pdfjs-reader-core 0.4.3 → 0.5.2

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,10 +13181,26 @@ 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];
+var PILL_FONT_CAPS = "clamp(10.5px, 0.55vw + 8.5px, 14.5px)";
+var PILL_FONT_BODY = "clamp(12px, 0.6vw + 10px, 16.5px)";
+var PILL_FONT_DISPLAY = "clamp(14px, 0.75vw + 12px, 19px)";
+var PILL_MAX_W_CAPS = "clamp(180px, 26vw, 380px)";
+var PILL_MAX_W_BODY = "clamp(200px, 28vw, 440px)";
+function resolvePillOffset(viewportWidthPx) {
+  return clamp(0.022 * viewportWidthPx + 12, 20, 44);
+}
+function resolveMaxPillW(viewportWidthPx) {
+  return clamp(0.26 * viewportWidthPx, 180, 380);
+}
+function resolveMaxPillH(viewportWidthPx) {
+  const font = clamp(55e-4 * viewportWidthPx + 8.5, 10.5, 14.5);
+  return clamp(font * 2.6, 28, 42);
+}
+function clamp(v, lo, hi) {
+  return Math.min(hi, Math.max(lo, v));
+}
 
 // src/components/TutorMode/SpotlightMask.tsx
 var import_jsx_runtime42 = require("react/jsx-runtime");
@@ -13470,17 +13486,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 +13526,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 }
           }
         )
       ]
@@ -14117,9 +14113,11 @@ function GhostReference({
           {
             style: {
               position: "relative",
-              padding: "20px 22px 20px 26px",
+              // Padding scales with viewport: compact on phones, breathing on
+              // desktop. Extra 4px on the left preserves the footnote-rule gap.
+              padding: "clamp(14px, 1.4vw + 10px, 26px) clamp(14px, 1.4vw + 10px, 26px) clamp(14px, 1.4vw + 10px, 26px) clamp(18px, 1.4vw + 14px, 30px)",
               display: "flex",
-              gap: 16,
+              gap: "clamp(12px, 1.1vw + 8px, 20px)",
               alignItems: "flex-start"
             },
             children: [
@@ -14133,7 +14131,7 @@ function GhostReference({
                   transition: { duration: 0.45, delay: 0.18, ease: [0.22, 1, 0.36, 1] },
                   style: {
                     flexShrink: 0,
-                    width: 46,
+                    width: "clamp(40px, 4vw + 20px, 64px)",
                     aspectRatio: `${page.width} / ${page.height}`,
                     background: PAPER_DEEP,
                     borderRadius: 2,
@@ -14198,7 +14196,7 @@ function GhostReference({
                     flex: 1,
                     minWidth: 0,
                     fontFamily: SERIF2,
-                    fontSize: 15.5,
+                    fontSize: PILL_FONT_DISPLAY,
                     lineHeight: 1.55,
                     color: INK2,
                     fontFeatureSettings: "'liga' 1, 'kern' 1, 'onum' 1",
@@ -14220,7 +14218,7 @@ function GhostReference({
                           left: -14,
                           top: -2,
                           color: ACCENT2,
-                          fontSize: 22,
+                          fontSize: "clamp(18px, 1vw + 14px, 28px)",
                           lineHeight: 1,
                           fontWeight: 500
                           // ornamental flourish anchoring the paragraph
@@ -14330,10 +14328,6 @@ var import_framer_motion12 = require("framer-motion");
 // src/components/TutorMode/StickyLabel.tsx
 var import_framer_motion11 = require("framer-motion");
 var import_jsx_runtime51 = require("react/jsx-runtime");
-var INK3 = "#2a2420";
-var PAPER3 = "#faf6ec";
-var ACCENT3 = "#b04a1a";
-var SERIF3 = "'Iowan Old Style', 'Palatino Linotype', Palatino, 'Book Antiqua', 'EB Garamond', 'Hoefler Text', Georgia, serif";
 var STEM = 18;
 function StickyLabel({ screenAnchor, action }) {
   const { x, y } = screenAnchor;
@@ -14372,7 +14366,7 @@ function StickyLabel({ screenAnchor, action }) {
             transition: { duration: 0.35, ease: [0.22, 1, 0.36, 1] },
             style: {
               position: "absolute",
-              background: ACCENT3,
+              background: ACCENT,
               transformOrigin: layout.stemOrigin,
               ...layout.stem
             }
@@ -14391,8 +14385,8 @@ function StickyLabel({ screenAnchor, action }) {
               width: 6,
               height: 6,
               borderRadius: "50%",
-              background: ACCENT3,
-              boxShadow: `0 0 0 2px ${PAPER3}, 0 0 0 3px rgba(176, 74, 26, 0.25)`,
+              background: ACCENT,
+              boxShadow: `0 0 0 2px ${PAPER}, 0 0 0 3px rgba(176, 74, 26, 0.25)`,
               ...layout.dot
             }
           }
@@ -14407,25 +14401,25 @@ function StickyLabel({ screenAnchor, action }) {
             style: {
               position: "absolute",
               ...layout.bodyAnchor,
-              background: PAPER3,
-              color: INK3,
+              background: PAPER,
+              color: INK,
               border: "1px solid rgba(42, 36, 32, 0.10)",
               borderRadius: 3,
               padding: "6px 12px 6px 14px",
-              fontFamily: SERIF3,
-              fontSize: 12.5,
+              fontFamily: SERIF,
+              fontSize: PILL_FONT_BODY,
               lineHeight: 1.25,
               letterSpacing: 0.6,
               textTransform: "uppercase",
               fontWeight: 500,
               whiteSpace: "nowrap",
-              maxWidth: 240,
+              maxWidth: PILL_MAX_W_BODY,
               overflow: "hidden",
               textOverflow: "ellipsis",
               // Warm two-layer shadow (matches GhostReference's palette).
               boxShadow: "0 1px 2px rgba(42, 36, 32, 0.12), 0 8px 18px -6px rgba(42, 36, 32, 0.22)",
               // Internal left accent rule — a 2px terracotta stripe.
-              backgroundImage: `linear-gradient(to right, ${ACCENT3} 0, ${ACCENT3} 2px, transparent 2px)`,
+              backgroundImage: `linear-gradient(to right, ${ACCENT} 0, ${ACCENT} 2px, transparent 2px)`,
               backgroundRepeat: "no-repeat",
               backgroundSize: "2px 100%",
               backgroundPosition: "left top"
@@ -14667,9 +14661,9 @@ function computePillAnchor(fromBbox, toBbox, page, camera, viewport) {
   const tipScreenX = viewport.width / 2 + camera.x + (toX - pageCX) * camera.scale;
   const tipScreenY = viewport.height / 2 + camera.y + (toY - pageCY) * camera.scale;
   const isVertical = Math.abs(dy) >= Math.abs(dx);
-  const OFFSET = 32;
-  const MAX_PILL_W = 220;
-  const MAX_PILL_H = 30;
+  const OFFSET = resolvePillOffset(viewport.width);
+  const MAX_PILL_W = resolveMaxPillW(viewport.width);
+  const MAX_PILL_H = resolveMaxPillH(viewport.width);
   const SAFE = 16;
   if (isVertical) {
     const canFitRight = tipScreenX + OFFSET + MAX_PILL_W < viewport.width - SAFE;
@@ -14713,13 +14707,13 @@ function CalloutLabelPill({
         borderRadius: 3,
         padding: spec.padding,
         fontFamily: SERIF,
-        fontSize: 11.5,
+        fontSize: PILL_FONT_CAPS,
         lineHeight: 1.2,
         letterSpacing: 0.6,
         textTransform: "uppercase",
         fontWeight: 500,
         whiteSpace: "nowrap",
-        maxWidth: 220,
+        maxWidth: PILL_MAX_W_CAPS,
         overflow: "hidden",
         textOverflow: "ellipsis",
         boxShadow: "0 1px 2px rgba(42, 36, 32, 0.12), 0 8px 18px -6px rgba(42, 36, 32, 0.22)",
@@ -15110,7 +15104,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 +15224,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 +15266,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 +15302,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 +15313,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 +15324,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 +15335,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" } }
@@ -15606,32 +15603,32 @@ function clampNumericRanges(input) {
   }
   const type = typeof out.type === "string" ? out.type : void 0;
   if (type === "camera") {
-    if (typeof out.scale === "number") out.scale = clamp(out.scale, 0.5, 4);
+    if (typeof out.scale === "number") out.scale = clamp2(out.scale, 0.5, 4);
     if (typeof out.padding === "number") {
-      out.padding = clamp(out.padding, 0, 400);
+      out.padding = clamp2(out.padding, 0, 400);
     }
   }
   if (typeof out.dim_opacity === "number") {
-    out.dim_opacity = clamp(out.dim_opacity, 0, 1);
+    out.dim_opacity = clamp2(out.dim_opacity, 0, 1);
   }
   if (typeof out.feather_px === "number") {
-    out.feather_px = clamp(out.feather_px, 0, 200);
+    out.feather_px = clamp2(out.feather_px, 0, 200);
   }
   if (typeof out.draw_duration_ms === "number") {
-    out.draw_duration_ms = clamp(out.draw_duration_ms, 100, 3e3);
+    out.draw_duration_ms = clamp2(out.draw_duration_ms, 100, 3e3);
   }
   if (typeof out.count === "number") {
-    out.count = Math.round(clamp(out.count, 1, 5));
+    out.count = Math.round(clamp2(out.count, 1, 5));
   }
   if (typeof out.at_ms === "number") {
-    out.at_ms = clamp(out.at_ms, 0, 5e3);
+    out.at_ms = clamp2(out.at_ms, 0, 5e3);
   }
   if (typeof out.duration_ms === "number" && type === void 0) {
-    out.duration_ms = clamp(out.duration_ms, 100, 5e3);
+    out.duration_ms = clamp2(out.duration_ms, 100, 5e3);
   }
   return out;
 }
-function clamp(v, lo, hi) {
+function clamp2(v, lo, hi) {
   return Math.min(hi, Math.max(lo, v));
 }
 function enforceOverlayPresence(sb) {
@@ -15644,9 +15641,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 +16036,7 @@ function TutorModeContainer({
   backgroundColor = "#ffffff",
   loadingComponent,
   onPageChange,
+  storyboardProvider,
   className
 }) {
   const containerRef = (0, import_react58.useRef)(null);
@@ -16116,7 +16115,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 +16136,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 +16226,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 +16269,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 +16468,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;