pdfjs-reader-core 0.4.2 → 0.5.1

package/README.md

@@ -1278,6 +1278,7 @@ default. Clicking it clears every overlay and returns the camera to fit-page.
 | `backgroundColor` | `string` | `'#ffffff'` | Surround colour visible around the PDF when the viewport is larger than the page fit. v0.4.1+ |
 | `loadingComponent` | `ReactNode` | default spinner | Custom loading state shown while the PDF document/page is still fetching. v0.4.1+ |
 | `onPageChange` | `(page: number) => void` | — | Called when the viewer's page changes from any source (agent API, sidebar, programmatic). Pair with the `pageNumber` prop for bidirectional sync. **Required** when agents call `goToPage`/`nextPage`/`previousPage`. v0.4.2+ |
+| `storyboardProvider` | `(input) => Promise<Storyboard \| null>` | — | Consumer-owned director — when provided, called per chunk INSTEAD of the built-in LLM director. Your backend owns the system prompt + bbox context and returns the storyboard JSON. v0.5.0+ |
 | `className` | `string` | — | Passes through to the root container for custom theming |
 
 ### LlmConfig
@@ -1299,6 +1300,56 @@ interface LlmConfig {
 multiple consumers and each owns its own inference endpoint. Pass the URL as
 a prop at the call site, sourced from an env var or runtime config.
 
+### Alternative: `storyboardProvider` (v0.5.0+)
+
+When your backend owns the system prompt and bbox context, use
+`storyboardProvider` instead of `llm`. The library will call your provider per
+chunk, validate its return value against `StoryboardSchema`, and execute the
+result.
+
+```tsx
+<TutorModeContainer
+  pageNumber={currentPage}
+  bboxData={bboxData}
+  narrationStore={storeRef.current}
+  currentChunk={currentChunk}
+  storyboardProvider={async ({ chunk, pageNumber, signal }) => {
+    // Your director endpoint already has bbox server-side. Send just
+    // the chunk + page number and get the storyboard back.
+    const res = await fetch('/director', {
+      method: 'POST',
+      body: JSON.stringify({ chunk, pageNumber }),
+      signal,
+    });
+    if (!res.ok) return null;   // library skips this chunk gracefully
+    return res.json();           // must match StoryboardSchema
+  }}
+/>
+```
+
+**Why use this instead of `llm`?**
+- You iterate on the system prompt without a library upgrade.
+- You choose the model (fine-tuned, OSS, hosted, local) without vendor lock.
+- You cache bbox server-side; the browser sends only the chunk + page number.
+- Works great with KV-cache / prefix caching on the director model.
+
+**What the library still handles regardless of path:**
+- `StoryboardSchema` validation of the returned JSON
+- Range clamping of out-of-bounds numeric fields
+- `enforceOverlayPresence` auto-pulse if the storyboard is camera-only
+- Engine scheduling (per-step `setTimeout` at `at_ms`)
+- All overlay rendering (spotlight / underline / highlight / pulse / callout /
+  ghost reference / box / label), plus viewport-space overlays and camera math
+- Debug events (`llm-request` / `llm-response` / `storyboard-execute`) so the
+  DebugLog telemetry works identically to the built-in path
+
+**Priority:** if both `storyboardProvider` and `llm` are set, the provider
+wins and `llm` is ignored.
+
+**Return `null` to skip:** the provider may decide a given chunk shouldn't
+trigger visuals (e.g. filler words, acknowledgements). Returning `null`
+emits a `note` debug event and no storyboard fires.
+
 ### The integration contract in one picture
 
 ```

package/dist/index.cjs

@@ -13181,8 +13181,6 @@ var PAPER = "#faf6ec";
 var ACCENT = "#b04a1a";
 var ACCENT_SOFT = "rgba(176, 74, 26, 0.18)";
 var ACCENT_GLOW = "rgba(176, 74, 26, 0.35)";
-var MARKER = "#e6b422";
-var MARKER_SOFT = "rgba(230, 180, 34, 0.38)";
 var SERIF = "'Iowan Old Style', 'Palatino Linotype', Palatino, 'Book Antiqua', 'EB Garamond', 'Hoefler Text', Georgia, serif";
 var EASE_OUT_EXPO = [0.22, 1, 0.36, 1];
 
@@ -13470,17 +13468,17 @@ function AnimatedUnderline({ bbox, action }) {
 var import_react56 = require("react");
 var import_framer_motion4 = require("framer-motion");
 var import_jsx_runtime44 = require("react/jsx-runtime");
+var WASH = "rgba(230, 180, 34, 0.22)";
 function AnimatedHighlight({ bbox, action }) {
   const [x1, y1, x2, y2] = bbox;
   const h = Math.max(1, y2 - y1);
   const bleed = Math.min(4, h * 0.12);
   const yTop = y1 - bleed;
   const yBot = y2 + bleed;
-  const height = yBot - yTop;
   const duration = action.draw_duration_ms / 1e3;
   const filterId = (0, import_react56.useId)();
-  const fill = action.color && action.color !== "rgba(250, 204, 21, 0.35)" && action.color !== "rgba(250,204,21,0.35)" ? action.color : MARKER_SOFT;
-  const inner = action.color && action.color !== "rgba(250, 204, 21, 0.35)" && action.color !== "rgba(250,204,21,0.35)" ? action.color : MARKER;
+  const isDefaultColour = !action.color || action.color === "rgba(250, 204, 21, 0.35)" || action.color === "rgba(250,204,21,0.35)";
+  const fill = isDefaultColour ? WASH : action.color;
   const taper = Math.min(6, h * 0.2);
   const pathD = `
     M ${x1 - 2} ${yTop + taper}
@@ -13510,44 +13508,24 @@ function AnimatedHighlight({ bbox, action }) {
             "feTurbulence",
             {
               type: "fractalNoise",
-              baseFrequency: "1.6",
+              baseFrequency: "1.8",
               numOctaves: "1",
               seed: 3,
               result: "noise"
             }
           ),
-          /* @__PURE__ */ (0, import_jsx_runtime44.jsx)("feDisplacementMap", { in: "SourceGraphic", in2: "noise", scale: 1.4 })
+          /* @__PURE__ */ (0, import_jsx_runtime44.jsx)("feDisplacementMap", { in: "SourceGraphic", in2: "noise", scale: 1 })
         ] }) }),
-        /* @__PURE__ */ (0, import_jsx_runtime44.jsxs)(
-          import_framer_motion4.motion.g,
+        /* @__PURE__ */ (0, import_jsx_runtime44.jsx)(
+          import_framer_motion4.motion.path,
           {
+            d: pathD,
+            fill,
             initial: { clipPath: `inset(0 100% 0 0)` },
             animate: { clipPath: `inset(0 0% 0 0)` },
             exit: { opacity: 0 },
-            transition: { duration, ease: EASE_OUT_EXPO },
-            children: [
-              /* @__PURE__ */ (0, import_jsx_runtime44.jsx)(
-                "path",
-                {
-                  d: pathD,
-                  fill,
-                  opacity: 0.85,
-                  filter: `url(#${filterId})`
-                }
-              ),
-              /* @__PURE__ */ (0, import_jsx_runtime44.jsx)(
-                "rect",
-                {
-                  x: x1 - 1,
-                  y: y1 - bleed * 0.4,
-                  width: x2 - x1 + 2,
-                  height: height - bleed * 0.8,
-                  fill: inner,
-                  opacity: 0.5,
-                  filter: `url(#${filterId})`
-                }
-              )
-            ]
+            filter: `url(#${filterId})`,
+            transition: { duration, ease: EASE_OUT_EXPO }
           }
         )
       ]
@@ -15110,7 +15088,12 @@ var StoryboardStepSchema = import_zod.z.object({
 });
 var StoryboardSchema = import_zod.z.object({
   version: import_zod.z.literal(1),
-  reasoning: import_zod.z.string().max(500).default(""),
+  // `reasoning` was required in 0.4.x as a model-generated explanation used
+  // by DebugLog. It carries no visual effect and costs 50–150 output tokens
+  // per call, so from 0.5.1 it's optional (default empty). Consumers who
+  // still send it (from cached prompts or older directors) keep working —
+  // the field is still accepted, just not required.
+  reasoning: import_zod.z.string().max(500).optional().default(""),
   steps: import_zod.z.array(StoryboardStepSchema).min(1).max(4)
 });
 function storyboardJsonSchema(opts = {}) {
@@ -15225,7 +15208,10 @@ function storyboardJsonSchema(opts = {}) {
   return {
     type: "object",
     additionalProperties: false,
-    required: ["version", "reasoning", "steps"],
+    // `reasoning` intentionally omitted from `required` — the field is still
+    // accepted when present but the model doesn't need to generate it,
+    // which saves 50–150 output tokens per call. See zod schema above.
+    required: ["version", "steps"],
     properties: {
       version: { type: "integer", enum: [1] },
       reasoning: { type: "string" },
@@ -15264,7 +15250,6 @@ Anchoring rules:
 Output ONLY this JSON, nothing else:
 {
   "version": 1,
-  "reasoning": "<which block(s) you picked, which intent you used, and why \u2014 name the block_id>",
   "steps": [ { "at_ms": <int>, "duration_ms": <int>, "action": <action> }, ... ]
 }
 
@@ -15301,7 +15286,6 @@ When narration fits one of these patterns, emit the corresponding storyboard sha
 Shape: spotlight the term + underline it + drop a label tag. No camera move if the block is already on-screen.
 {
   "version": 1,
-  "reasoning": "define recipe: spotlighting and underlining the term, labeling as 'definition'",
   "steps": [
     { "at_ms":0,   "duration_ms":700, "action": { "type":"spotlight", "target_block":"p1_para0", "dim_opacity":0.6, "feather_px":40, "shape":"rounded" } },
     { "at_ms":200, "duration_ms":800, "action": { "type":"underline", "target_block":"p1_para0", "color":"#FBBF24", "style":"sketch", "draw_duration_ms":700 } },
@@ -15313,7 +15297,6 @@ Shape: spotlight the term + underline it + drop a label tag. No camera move if t
 Shape: gentle camera move + callout arrow from caption to figure + pulse the figure.
 {
   "version": 1,
-  "reasoning": "point_out recipe: drawing attention from caption p1_cap1 to figure p1_fig0",
   "steps": [
     { "at_ms":0,   "duration_ms":600, "action": { "type":"camera", "target_block":"p1_fig0", "scale":1.3, "padding":80, "easing":"ease-out" } },
     { "at_ms":400, "duration_ms":900, "action": { "type":"callout", "from_block":"p1_cap1", "to_block":"p1_fig0", "label":"see here", "curve":"curved" } },
@@ -15325,7 +15308,6 @@ Shape: gentle camera move + callout arrow from caption to figure + pulse the fig
 Shape: box A + box B + callout between them with a relational label.
 {
   "version": 1,
-  "reasoning": "compare recipe: framing fibrous vs synovial joints",
   "steps": [
     { "at_ms":0,   "duration_ms":600, "action": { "type":"box", "target_block":"p1_list5", "color":"#3B82F6", "style":"solid" } },
     { "at_ms":300, "duration_ms":600, "action": { "type":"box", "target_block":"p1_list12", "color":"#F472B6", "style":"solid" } },
@@ -15337,7 +15319,6 @@ Shape: box A + box B + callout between them with a relational label.
 Shape: highlight + pulse. Fast, punchy, no camera.
 {
   "version": 1,
-  "reasoning": "emphasize recipe: highlighting key keyword and pulsing for stress",
   "steps": [
     { "at_ms":0,   "duration_ms":500, "action": { "type":"highlight", "target_block":"p1_list0", "color":"rgba(250,204,21,0.35)", "draw_duration_ms":450 } },
     { "at_ms":350, "duration_ms":800, "action": { "type":"pulse", "target_block":"p1_list0", "count":2, "intensity":"strong" } }
@@ -15644,9 +15625,10 @@ function enforceOverlayPresence(sb) {
   if (!cameraStep || cameraStep.action.type !== "camera") return sb;
   const target = cameraStep.action.target_block;
   if (!target) return sb;
+  const prefix = sb.reasoning ? `${sb.reasoning} ` : "";
   return {
     ...sb,
-    reasoning: `${sb.reasoning} [auto-appended pulse: camera-only storyboards are forbidden]`,
+    reasoning: `${prefix}[auto-appended pulse: camera-only storyboards are forbidden]`,
     steps: [
       ...sb.steps,
       {
@@ -16038,6 +16020,7 @@ function TutorModeContainer({
   backgroundColor = "#ffffff",
   loadingComponent,
   onPageChange,
+  storyboardProvider,
   className
 }) {
   const containerRef = (0, import_react58.useRef)(null);
@@ -16116,7 +16099,7 @@ function TutorModeContainer({
   const debounceRef = (0, import_react58.useRef)(null);
   const lastChunkRef = (0, import_react58.useRef)(null);
   (0, import_react58.useEffect)(() => {
-    if (!llm) return;
+    if (!storyboardProvider && !llm) return;
     if (!currentChunk || currentChunk === lastChunkRef.current) return;
     if (debounceRef.current) clearTimeout(debounceRef.current);
     debounceRef.current = setTimeout(async () => {
@@ -16137,6 +16120,75 @@ function TutorModeContainer({
       });
       abortRef.current?.abort();
       abortRef.current = new AbortController();
+      if (storyboardProvider) {
+        narrationStore.getState().setLlmStatus("in-flight");
+        narrationStore.getState().appendDebugEvent({
+          kind: "llm-request",
+          summary: `provider (page ${pageNumber}, ${page2.blocks.length} blocks)`,
+          payload: {
+            via: "storyboardProvider",
+            pageNumber,
+            blockCount: page2.blocks.length
+          }
+        });
+        try {
+          const raw = await storyboardProvider({
+            chunk,
+            pageNumber,
+            page: page2,
+            history: narrationStore.getState().chunkHistory,
+            signal: abortRef.current.signal
+          });
+          if (!raw) {
+            narrationStore.getState().setLlmStatus("idle");
+            narrationStore.getState().appendDebugEvent({
+              kind: "note",
+              summary: "provider returned null \u2014 no storyboard for this chunk"
+            });
+            return;
+          }
+          const parsed = StoryboardSchema.safeParse(raw);
+          if (!parsed.success) {
+            narrationStore.getState().setLlmStatus(
+              "failed",
+              parsed.error.message
+            );
+            narrationStore.getState().appendDebugEvent({
+              kind: "llm-error",
+              summary: `provider storyboard rejected by schema: ${parsed.error.issues[0]?.message ?? "unknown"}`,
+              payload: { raw, error: parsed.error.message }
+            });
+            return;
+          }
+          const storyboard = parsed.data;
+          narrationStore.getState().setLlmStatus("idle");
+          narrationStore.getState().appendDebugEvent({
+            kind: "llm-response",
+            summary: summariseStoryboard(storyboard),
+            payload: { via: "storyboardProvider", storyboard }
+          });
+          engineRef.current?.execute(storyboard);
+          narrationStore.getState().appendDebugEvent({
+            kind: "storyboard-execute",
+            summary: `engine executing ${storyboard.steps.length} steps`,
+            payload: storyboard.steps.map((s) => ({
+              at_ms: s.at_ms,
+              type: s.action.type,
+              target: "target_block" in s.action ? s.action.target_block : void 0
+            }))
+          });
+        } catch (e) {
+          if (e.name === "AbortError") return;
+          narrationStore.getState().setLlmStatus("failed", e.message);
+          narrationStore.getState().appendDebugEvent({
+            kind: "llm-error",
+            summary: `provider threw: ${e.message.slice(0, 80)}`,
+            payload: e
+          });
+        }
+        return;
+      }
+      if (!llm) return;
       narrationStore.getState().setLlmStatus("in-flight");
       narrationStore.getState().appendDebugEvent({
         kind: "llm-request",
@@ -16158,7 +16210,7 @@ function TutorModeContainer({
         narrationStore.getState().setLlmStatus("idle");
         narrationStore.getState().appendDebugEvent({
           kind: "llm-response",
-          summary: `storyboard \u2713 ${result.storyboard.steps.length} steps \u2014 ${result.storyboard.reasoning.slice(0, 60)}`,
+          summary: summariseStoryboard(result.storyboard),
           payload: { raw: result.raw, storyboard: result.storyboard }
         });
         engineRef.current?.execute(result.storyboard);
@@ -16201,7 +16253,16 @@ function TutorModeContainer({
     return () => {
       if (debounceRef.current) clearTimeout(debounceRef.current);
     };
-  }, [currentChunk, llm, index, pageNumber, narrationStore, embeddingProvider, llmTimeoutMs]);
+  }, [
+    currentChunk,
+    llm,
+    storyboardProvider,
+    index,
+    pageNumber,
+    narrationStore,
+    embeddingProvider,
+    llmTimeoutMs
+  ]);
   (0, import_react58.useEffect)(() => {
     if (!currentChunk) return;
     const t = setTimeout(() => {
@@ -16391,6 +16452,15 @@ function TutorLoadingState({
     }
   );
 }
+function summariseStoryboard(sb) {
+  const stepCount = sb.steps.length;
+  const trimmedReasoning = (sb.reasoning ?? "").trim();
+  if (trimmedReasoning) {
+    return `storyboard \u2713 ${stepCount} steps \u2014 ${trimmedReasoning.slice(0, 60)}`;
+  }
+  const kinds = sb.steps.map((s) => s.action.type).join(" \u2192 ");
+  return `storyboard \u2713 ${stepCount} steps \u2014 ${kinds}`;
+}
 
 // src/director/transformers-embedding.ts
 var loaded = null;