pdfjs-reader-core 0.3.0 → 0.4.1

package/dist/index.cjs

@@ -140,8 +140,8 @@ async function loadDocument(options) {
     signal.addEventListener("abort", abortHandler);
   }
   if (onProgress) {
-    loadingTask.onProgress = ({ loaded, total }) => {
-      onProgress({ loaded, total });
+    loadingTask.onProgress = ({ loaded: loaded2, total }) => {
+      onProgress({ loaded: loaded2, total });
     };
   }
   let document2;
@@ -271,9 +271,9 @@ function loadDocumentWithCallbacks(options) {
     };
     abortController.signal.addEventListener("abort", abortHandler);
     if (onProgress) {
-      loadingTask.onProgress = ({ loaded, total }) => {
+      loadingTask.onProgress = ({ loaded: loaded2, total }) => {
         if (!abortController.signal.aborted) {
-          onProgress({ loaded, total });
+          onProgress({ loaded: loaded2, total });
         }
       };
     }
@@ -627,13 +627,13 @@ function createViewerStore(initialOverrides = {}) {
     },
     zoomIn: () => {
       const { scale } = get();
-      const currentIndex = ZOOM_LEVELS.findIndex((z) => z >= scale);
+      const currentIndex = ZOOM_LEVELS.findIndex((z2) => z2 >= scale);
       const nextIndex = Math.min(currentIndex + 1, ZOOM_LEVELS.length - 1);
       set({ scale: ZOOM_LEVELS[nextIndex] ?? MAX_SCALE });
     },
     zoomOut: () => {
       const { scale } = get();
-      const currentIndex = ZOOM_LEVELS.findIndex((z) => z >= scale);
+      const currentIndex = ZOOM_LEVELS.findIndex((z2) => z2 >= scale);
       const prevIndex = Math.max(currentIndex - 1, 0);
       set({ scale: ZOOM_LEVELS[prevIndex] ?? MIN_SCALE });
     },
@@ -1863,6 +1863,34 @@ var init_page_turn_sound = __esm({
   }
 });
 
+// src/utils/camera-math.ts
+function fitPageScale(page, viewport) {
+  const sx = viewport.width / page.width;
+  const sy = viewport.height / page.height;
+  return Math.min(sx, sy);
+}
+function computeCameraForBlock(bbox, page, viewport, opts = {}) {
+  const targetScale = opts.targetScale ?? 1.5;
+  const paddingPdf = opts.paddingPdf ?? 80;
+  const [x1, y1, x2, y2] = bbox;
+  const blockW = Math.max(1, x2 - x1 + paddingPdf * 2);
+  const blockH = Math.max(1, y2 - y1 + paddingPdf * 2);
+  const blockCX = (x1 + x2) / 2;
+  const blockCY = (y1 + y2) / 2;
+  const fitBlock = Math.min(viewport.width / blockW, viewport.height / blockH);
+  const scale = fitBlock * targetScale;
+  const pageCX = page.width / 2;
+  const pageCY = page.height / 2;
+  const x = (pageCX - blockCX) * scale;
+  const y = (pageCY - blockCY) * scale;
+  return { scale, x, y };
+}
+var init_camera_math = __esm({
+  "src/utils/camera-math.ts"() {
+    "use strict";
+  }
+});
+
 // src/utils/index.ts
 var init_utils = __esm({
   "src/utils/index.ts"() {
@@ -2281,6 +2309,78 @@ var init_student_store = __esm({
   }
 });
 
+// src/store/narration-store.ts
+function createNarrationStore(overrides = {}) {
+  return (0, import_vanilla6.createStore)()((set) => ({
+    ...initialState6,
+    ...overrides,
+    setCurrentChunk: (chunk) => set({ currentChunk: chunk }),
+    setCurrentPage: (page) => set({ currentPage: page }),
+    pushChunkHistory: (entry) => set((state) => ({
+      chunkHistory: [
+        ...state.chunkHistory.slice(-(MAX_HISTORY - 1)),
+        entry
+      ]
+    })),
+    setCamera: (camera) => set((state) => ({ camera: { ...state.camera, ...camera } })),
+    addOverlay: (overlay) => set((state) => ({ activeOverlays: [...state.activeOverlays, overlay] })),
+    removeOverlay: (id) => set((state) => ({
+      activeOverlays: state.activeOverlays.filter((o) => o.id !== id)
+    })),
+    clearOverlays: (predicate) => set((state) => ({
+      activeOverlays: predicate ? state.activeOverlays.filter((o) => !predicate(o)) : []
+    })),
+    setEngineStatus: (s) => set({ engineStatus: s }),
+    setLlmStatus: (s, error = null) => set({ llmStatus: s, lastError: error }),
+    setLastStoryboard: (sb) => set({ lastStoryboard: sb }),
+    setPaused: (paused) => set({ isPaused: paused }),
+    appendDebugEvent: (event) => set((state) => {
+      debugEventCounter += 1;
+      const next = {
+        ...event,
+        id: `dbg-${debugEventCounter}`,
+        timestamp: Date.now()
+      };
+      return {
+        debugEvents: [
+          ...state.debugEvents.slice(-(MAX_DEBUG_EVENTS - 1)),
+          next
+        ]
+      };
+    }),
+    clearDebugEvents: () => set({ debugEvents: [] }),
+    reset: () => set(initialState6)
+  }));
+}
+function makeOverlayId(action) {
+  overlayIdCounter += 1;
+  return `ov-${action.type}-${overlayIdCounter}-${Date.now()}`;
+}
+var import_vanilla6, MAX_HISTORY, initialState6, MAX_DEBUG_EVENTS, debugEventCounter, overlayIdCounter;
+var init_narration_store = __esm({
+  "src/store/narration-store.ts"() {
+    "use strict";
+    import_vanilla6 = require("zustand/vanilla");
+    MAX_HISTORY = 5;
+    initialState6 = {
+      currentChunk: null,
+      currentPage: 1,
+      chunkHistory: [],
+      camera: { scale: 1, x: 0, y: 0, easing: "ease-in-out" },
+      activeOverlays: [],
+      engineStatus: "idle",
+      llmStatus: "idle",
+      lastStoryboard: null,
+      lastError: null,
+      isPaused: false,
+      debugEvents: []
+    };
+    MAX_DEBUG_EVENTS = 50;
+    debugEventCounter = 0;
+    overlayIdCounter = 0;
+  }
+});
+
 // src/store/index.ts
 var init_store = __esm({
   "src/store/index.ts"() {
@@ -2290,13 +2390,14 @@ var init_store = __esm({
     init_search_store();
     init_agent_store();
     init_student_store();
+    init_narration_store();
   }
 });
 
 // src/hooks/PDFViewerContext.tsx
 function PDFViewerProvider({
   children,
-  initialState: initialState6,
+  initialState: initialState7,
   theme = "light",
   defaultSidebarPanel = "thumbnails",
   studentMode: _studentMode = false
@@ -2308,22 +2409,22 @@ function PDFViewerProvider({
   const studentStoreRef = (0, import_react2.useRef)(null);
   if (!viewerStoreRef.current) {
     viewerStoreRef.current = createViewerStore({
-      ...initialState6?.viewer,
+      ...initialState7?.viewer,
       theme,
       sidebarPanel: defaultSidebarPanel
     });
   }
   if (!annotationStoreRef.current) {
-    annotationStoreRef.current = createAnnotationStore(initialState6?.annotation);
+    annotationStoreRef.current = createAnnotationStore(initialState7?.annotation);
   }
   if (!searchStoreRef.current) {
-    searchStoreRef.current = createSearchStore(initialState6?.search);
+    searchStoreRef.current = createSearchStore(initialState7?.search);
   }
   if (!agentStoreRef.current) {
-    agentStoreRef.current = createAgentStore(initialState6?.agent);
+    agentStoreRef.current = createAgentStore(initialState7?.agent);
   }
   if (!studentStoreRef.current) {
-    studentStoreRef.current = createStudentStore(initialState6?.student);
+    studentStoreRef.current = createStudentStore(initialState7?.student);
   }
   (0, import_react2.useEffect)(() => {
     return () => {
@@ -3647,8 +3748,8 @@ var init_PluginManager = __esm({
       /**
        * Get toolbar items by position
        */
-      getToolbarItemsByPosition(position) {
-        return this.getToolbarItems().filter((item) => item.position === position);
+      getToolbarItemsByPosition(position2) {
+        return this.getToolbarItems().filter((item) => item.position === position2);
       }
       /**
        * Get all sidebar panels from all plugins
@@ -4761,7 +4862,7 @@ var init_MobileToolbar = __esm({
       sidebarOpen,
       theme,
       onThemeChange,
-      position = "bottom",
+      position: position2 = "bottom",
       className
     }) {
       const [showMoreMenu, setShowMoreMenu] = (0, import_react17.useState)(false);
@@ -4795,8 +4896,8 @@ var init_MobileToolbar = __esm({
             "bg-white dark:bg-gray-800",
             "border-gray-200 dark:border-gray-700",
             "px-2 py-1 safe-area-inset",
-            position === "top" && "top-0 border-b",
-            position === "bottom" && "bottom-0 border-t",
+            position2 === "top" && "top-0 border-b",
+            position2 === "bottom" && "bottom-0 border-t",
             className
           ),
           children: /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: "flex items-center justify-between gap-1", children: [
@@ -4922,7 +5023,7 @@ var init_MobileToolbar = __esm({
                       "bg-white dark:bg-gray-800",
                       "rounded-lg shadow-lg",
                       "border border-gray-200 dark:border-gray-700",
-                      position === "bottom" ? "bottom-full mb-2" : "top-full mt-2"
+                      position2 === "bottom" ? "bottom-full mb-2" : "top-full mt-2"
                     ),
                     children: [
                       /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { className: "px-2 py-1 text-xs text-gray-500 dark:text-gray-400 font-medium", children: "Theme" }),
@@ -6748,7 +6849,7 @@ var init_AnnotationToolbar = __esm({
       onShapeTypeChange: onShapeTypeChangeProp,
       onColorChange: onColorChangeProp,
       onStrokeWidthChange: onStrokeWidthChangeProp,
-      position = "top",
+      position: position2 = "top",
       className
     }) {
       const storeActiveTool = useAnnotationStore((s) => s.activeAnnotationTool);
@@ -6798,9 +6899,9 @@ var init_AnnotationToolbar = __esm({
         {
           className: cn(
             "annotation-toolbar flex items-center gap-1 p-2 bg-white dark:bg-gray-800 rounded-lg shadow-lg border border-gray-200 dark:border-gray-700",
-            position === "floating" && "fixed bottom-20 left-1/2 -translate-x-1/2 z-50",
-            position === "top" && "sticky top-0 z-40",
-            position === "bottom" && "sticky bottom-0 z-40",
+            position2 === "floating" && "fixed bottom-20 left-1/2 -translate-x-1/2 z-50",
+            position2 === "top" && "sticky top-0 z-40",
+            position2 === "bottom" && "sticky bottom-0 z-40",
             !isActive && "opacity-90",
             className
           ),
@@ -8449,7 +8550,7 @@ var init_SelectionToolbar = __esm({
       activeColor = "yellow",
       className
     }) {
-      const [position, setPosition] = (0, import_react35.useState)({ top: 0, left: 0, visible: false });
+      const [position2, setPosition] = (0, import_react35.useState)({ top: 0, left: 0, visible: false });
       const toolbarRef = (0, import_react35.useRef)(null);
       (0, import_react35.useEffect)(() => {
         if (selection && selection.text && selection.rects.length > 0) {
@@ -8488,7 +8589,7 @@ var init_SelectionToolbar = __esm({
       const handleCopy = (0, import_react35.useCallback)(() => {
         onCopy?.();
       }, [onCopy]);
-      if (!position.visible || !selection?.text) {
+      if (!position2.visible || !selection?.text) {
         return null;
       }
       return /* @__PURE__ */ (0, import_jsx_runtime21.jsxs)(
@@ -8506,8 +8607,8 @@ var init_SelectionToolbar = __esm({
             className
           ),
           style: {
-            top: position.top,
-            left: position.left,
+            top: position2.top,
+            left: position2.left,
             transform: "translateX(-50%)"
           },
           onMouseDown: (e) => {
@@ -8624,7 +8725,7 @@ var init_HighlightPopover = __esm({
     }) {
       const [isEditingComment, setIsEditingComment] = (0, import_react36.useState)(false);
       const [comment, setComment] = (0, import_react36.useState)(highlight?.comment ?? "");
-      const [position, setPosition] = (0, import_react36.useState)({ top: 0, left: 0, visible: false });
+      const [position2, setPosition] = (0, import_react36.useState)({ top: 0, left: 0, visible: false });
       const popoverRef = (0, import_react36.useRef)(null);
       const textareaRef = (0, import_react36.useRef)(null);
       (0, import_react36.useEffect)(() => {
@@ -8672,11 +8773,11 @@ var init_HighlightPopover = __esm({
             onClose();
           }
         }
-        if (position.visible) {
+        if (position2.visible) {
           document.addEventListener("mousedown", handleClickOutside);
           return () => document.removeEventListener("mousedown", handleClickOutside);
         }
-      }, [position.visible, onClose]);
+      }, [position2.visible, onClose]);
       (0, import_react36.useEffect)(() => {
         function handleKeyDown(event) {
           if (event.key === "Escape") {
@@ -8688,11 +8789,11 @@ var init_HighlightPopover = __esm({
             }
           }
         }
-        if (position.visible) {
+        if (position2.visible) {
           document.addEventListener("keydown", handleKeyDown);
           return () => document.removeEventListener("keydown", handleKeyDown);
         }
-      }, [position.visible, isEditingComment, highlight?.comment, onClose]);
+      }, [position2.visible, isEditingComment, highlight?.comment, onClose]);
       const handleColorClick = (0, import_react36.useCallback)(
         (color) => {
           if (highlight) {
@@ -8719,7 +8820,7 @@ var init_HighlightPopover = __esm({
           onCopy?.(highlight.text);
         }
       }, [highlight, onCopy]);
-      if (!highlight || !position.visible) {
+      if (!highlight || !position2.visible) {
         return null;
       }
       return /* @__PURE__ */ (0, import_jsx_runtime22.jsxs)(
@@ -8736,8 +8837,8 @@ var init_HighlightPopover = __esm({
             className
           ),
           style: {
-            top: position.top,
-            left: position.left,
+            top: position2.top,
+            left: position2.left,
             transform: "translate(-50%, -100%)",
             width: 280
           },
@@ -9964,10 +10065,23 @@ var init_BookModeContainer = __esm({
       const scrollToPageRequest = useViewerStore((s) => s.scrollToPageRequest);
       const { viewerStore } = usePDFViewerStores();
       const [pages, setPages] = (0, import_react41.useState)([]);
-      const [pageDims, setPageDims] = (0, import_react41.useState)({ width: 612, height: 792 });
+      const [rawPageDims, setRawPageDims] = (0, import_react41.useState)({ width: 612, height: 792 });
       const [isLoadingPages, setIsLoadingPages] = (0, import_react41.useState)(false);
+      const containerRef = (0, import_react41.useRef)(null);
+      const [containerSize, setContainerSize] = (0, import_react41.useState)({ width: 0, height: 0 });
       const flipBookRef = (0, import_react41.useRef)(null);
       const isSyncingRef = (0, import_react41.useRef)(false);
+      (0, import_react41.useEffect)(() => {
+        const el = containerRef.current;
+        if (!el) return;
+        const measure = () => {
+          setContainerSize({ width: el.clientWidth, height: el.clientHeight });
+        };
+        measure();
+        const ro = new ResizeObserver(measure);
+        ro.observe(el);
+        return () => ro.disconnect();
+      }, []);
       (0, import_react41.useEffect)(() => {
         if (!document2) {
           setPages([]);
@@ -9983,12 +10097,12 @@ var init_BookModeContainer = __esm({
             }
             const results = await Promise.allSettled(pagePromises);
             if (!cancelled) {
-              const loaded = results.map((r) => r.status === "fulfilled" ? r.value : null);
-              setPages(loaded);
-              const firstPage = loaded[0];
+              const loaded2 = results.map((r) => r.status === "fulfilled" ? r.value : null);
+              setPages(loaded2);
+              const firstPage = loaded2[0];
               if (firstPage) {
-                const vp = firstPage.getViewport({ scale, rotation });
-                setPageDims({ width: Math.floor(vp.width), height: Math.floor(vp.height) });
+                const vp = firstPage.getViewport({ scale: 1, rotation });
+                setRawPageDims({ width: vp.width, height: vp.height });
               }
             }
           } catch {
@@ -10000,13 +10114,27 @@ var init_BookModeContainer = __esm({
         return () => {
           cancelled = true;
         };
-      }, [document2, numPages, scale, rotation]);
+      }, [document2, numPages, rotation]);
       (0, import_react41.useEffect)(() => {
         if (pages[0]) {
-          const vp = pages[0].getViewport({ scale, rotation });
-          setPageDims({ width: Math.floor(vp.width), height: Math.floor(vp.height) });
-        }
-      }, [pages, scale, rotation]);
+          const vp = pages[0].getViewport({ scale: 1, rotation });
+          setRawPageDims({ width: vp.width, height: vp.height });
+        }
+      }, [pages, rotation]);
+      const padding = 8;
+      const fitWidth = Math.max(containerSize.width - padding * 2, 200);
+      const fitHeight = Math.max(containerSize.height - padding * 2, 300);
+      const pageAspect = rawPageDims.width / rawPageDims.height;
+      let displayWidth;
+      let displayHeight;
+      if (fitWidth / fitHeight > pageAspect) {
+        displayHeight = fitHeight;
+        displayWidth = Math.floor(fitHeight * pageAspect);
+      } else {
+        displayWidth = fitWidth;
+        displayHeight = Math.floor(fitWidth / pageAspect);
+      }
+      const renderScale = displayWidth / rawPageDims.width;
       (0, import_react41.useEffect)(() => {
         const pageFlip = flipBookRef.current?.pageFlip();
         if (!pageFlip) return;
@@ -10040,18 +10168,15 @@ var init_BookModeContainer = __esm({
         sepia: "bg-amber-50"
       };
       const themeClass = theme === "dark" ? "dark" : theme === "sepia" ? "sepia" : "";
-      if (!document2) {
-        return /* @__PURE__ */ (0, import_jsx_runtime27.jsx)("div", { className: cn("document-container", "flex-1", themeStyles[theme], className), children: /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(PDFLoadingScreen, { phase: isLoading ? "fetching" : "initializing" }) });
-      }
-      if (isLoadingPages || pages.length === 0) {
-        return /* @__PURE__ */ (0, import_jsx_runtime27.jsx)("div", { className: cn("document-container", "flex-1", themeStyles[theme], className), children: /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(PDFLoadingScreen, { phase: "rendering" }) });
-      }
+      const ready = !!document2 && !isLoadingPages && pages.length > 0;
+      const hasContainer = containerSize.width > 0 && containerSize.height > 0;
       return /* @__PURE__ */ (0, import_jsx_runtime27.jsxs)(
         "div",
         {
+          ref: containerRef,
           className: cn(
             "book-mode-container",
-            "flex-1 overflow-hidden",
+            "flex-1 h-full w-full overflow-hidden",
             "flex items-center justify-center",
             themeStyles[theme],
             themeClass,
@@ -10059,24 +10184,30 @@ var init_BookModeContainer = __esm({
           ),
           style: { userSelect: "none", WebkitUserSelect: "none" },
           children: [
-            /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(
+            !ready && /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(
+              PDFLoadingScreen,
+              {
+                phase: !document2 ? isLoading ? "fetching" : "initializing" : "rendering"
+              }
+            ),
+            ready && hasContainer && /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(
               import_react_pageflip.default,
               {
                 ref: flipBookRef,
-                width: pageDims.width,
-                height: pageDims.height,
-                size: "stretch",
-                minWidth: 300,
-                maxWidth: pageDims.width,
-                minHeight: 400,
-                maxHeight: pageDims.height,
+                width: displayWidth,
+                height: displayHeight,
+                size: "fixed",
+                minWidth: displayWidth,
+                maxWidth: displayWidth,
+                minHeight: displayHeight,
+                maxHeight: displayHeight,
                 drawShadow,
                 maxShadowOpacity,
                 flippingTime,
                 usePortrait: true,
                 startPage: currentPage - 1,
                 showCover: false,
-                mobileScrollSupport: false,
+                mobileScrollSupport: true,
                 swipeDistance: 30,
                 showPageCorners: true,
                 useMouseEvents: true,
@@ -10085,7 +10216,7 @@ var init_BookModeContainer = __esm({
                 className: "book-flipbook",
                 style: {},
                 startZIndex: 0,
-                autoSize: true,
+                autoSize: false,
                 renderOnlyPageLengthChange: false,
                 disableFlipByClick: false,
                 children: pages.map((page, index) => /* @__PURE__ */ (0, import_jsx_runtime27.jsx)(
@@ -10093,20 +10224,15 @@ var init_BookModeContainer = __esm({
                   {
                     pageNumber: index + 1,
                     page,
-                    scale,
+                    scale: renderScale,
                     rotation,
-                    width: pageDims.width,
-                    height: pageDims.height
+                    width: displayWidth,
+                    height: displayHeight
                   },
                   index
                 ))
               }
-            ),
-            /* @__PURE__ */ (0, import_jsx_runtime27.jsxs)("div", { className: "book-page-indicator", children: [
-              currentPage,
-              " / ",
-              numPages
-            ] })
+            )
           ]
         }
       );
@@ -10124,7 +10250,7 @@ var init_FloatingZoomControls = __esm({
     init_utils();
     import_jsx_runtime28 = require("react/jsx-runtime");
     FloatingZoomControls = (0, import_react42.memo)(function FloatingZoomControls2({
-      position = "bottom-right",
+      position: position2 = "bottom-right",
       className,
       showFitToWidth = true,
       showFitToPage = false,
@@ -10165,7 +10291,7 @@ var init_FloatingZoomControls = __esm({
             "bg-white dark:bg-gray-800 rounded-lg shadow-lg",
             "border border-gray-200 dark:border-gray-700",
             "p-1",
-            positionClasses[position],
+            positionClasses[position2],
             className
           ),
           children: [
@@ -10871,12 +10997,12 @@ var init_PDFViewerClient = __esm({
           src,
           workerSrc,
           signal: abortController.signal,
-          onProgress: ({ loaded, total }) => {
+          onProgress: ({ loaded: loaded2, total }) => {
             if (!mountedRef.current || srcIdRef.current !== loadId || abortController.signal.aborted) {
               return;
             }
             const now = Date.now();
-            const percent = total > 0 ? Math.round(loaded / total * 100) : 0;
+            const percent = total > 0 ? Math.round(loaded2 / total * 100) : 0;
             const timePassed = now - lastProgressUpdate >= PROGRESS_THROTTLE_MS;
             const percentChanged = Math.abs(percent - lastPercent) >= PROGRESS_MIN_CHANGE;
             const isComplete = percent >= 100;
@@ -10887,10 +11013,10 @@ var init_PDFViewerClient = __esm({
                 loadingProgress: {
                   phase: "fetching",
                   percent,
-                  bytesLoaded: loaded,
+                  bytesLoaded: loaded2,
                   totalBytes: total
                 },
-                streamingProgress: { loaded, total },
+                streamingProgress: { loaded: loaded2, total },
                 documentLoadingState: "loading"
               });
             }
@@ -11169,19 +11295,26 @@ var init_PDFViewer2 = __esm({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AnimatedHighlight: () => AnimatedHighlight,
+  AnimatedUnderline: () => AnimatedUnderline,
   AnnotationLayer: () => AnnotationLayer,
   AnnotationToolbar: () => AnnotationToolbar,
   AskAboutOverlay: () => AskAboutOverlay,
   AskAboutTrigger: () => AskAboutTrigger,
   BookModeContainer: () => BookModeContainer,
   BookmarksPanel: () => BookmarksPanel,
+  BoxOverlay: () => BoxOverlay,
+  CalloutArrow: () => CalloutArrow,
+  CameraView: () => CameraView,
   CanvasLayer: () => CanvasLayer,
+  CinemaLayer: () => CinemaLayer,
   ContinuousScrollContainer: () => ContinuousScrollContainer,
   DocumentContainer: () => DocumentContainer,
   DrawingCanvas: () => DrawingCanvas,
   DualPageContainer: () => DualPageContainer,
   FloatingZoomControls: () => FloatingZoomControls,
   FocusRegionLayer: () => FocusRegionLayer,
+  GhostReference: () => GhostReference,
   HighlightLayer: () => HighlightLayer,
   HighlightPopover: () => HighlightPopover,
   HighlightsPanel: () => HighlightsPanel,
@@ -11198,32 +11331,46 @@ __export(index_exports, {
   PDFViewerContext: () => PDFViewerContext,
   PDFViewerProvider: () => PDFViewerProvider,
   PluginManager: () => PluginManager,
+  PulseOverlay: () => PulseOverlay,
   QuickNoteButton: () => QuickNoteButton,
   QuickNotePopover: () => QuickNotePopover,
+  SYSTEM_PROMPT: () => SYSTEM_PROMPT,
   SearchPanel: () => SearchPanel,
   SelectionToolbar: () => SelectionToolbar,
   ShapePreview: () => ShapePreview,
   ShapeRenderer: () => ShapeRenderer,
   Sidebar: () => Sidebar,
+  SpotlightMask: () => SpotlightMask,
+  StickyLabel: () => StickyLabel,
   StickyNote: () => StickyNote,
+  StoryboardActionSchema: () => StoryboardActionSchema,
+  StoryboardEngine: () => StoryboardEngine,
+  StoryboardSchema: () => StoryboardSchema,
+  SubtitleBar: () => SubtitleBar,
   TakeawaysPanel: () => TakeawaysPanel,
   TextLayer: () => TextLayer,
   ThumbnailPanel: () => ThumbnailPanel,
   Toolbar: () => Toolbar,
+  TutorModeContainer: () => TutorModeContainer,
   VirtualizedDocumentContainer: () => VirtualizedDocumentContainer,
   applyRotation: () => applyRotation,
+  buildBBoxIndex: () => buildBBoxIndex,
+  buildUserPrompt: () => buildUserPrompt,
   clearHighlights: () => clearHighlights,
   clearStudentData: () => clearStudentData,
   cn: () => cn,
+  cosineSimilarity: () => cosineSimilarity,
   countTextOnPage: () => countTextOnPage,
   createAgentAPI: () => createAgentAPI,
   createAgentStore: () => createAgentStore,
   createAnnotationStore: () => createAnnotationStore,
+  createNarrationStore: () => createNarrationStore,
   createPDFViewer: () => createPDFViewer,
   createPluginManager: () => createPluginManager,
   createSearchStore: () => createSearchStore,
   createStudentStore: () => createStudentStore,
   createViewerStore: () => createViewerStore,
+  directStoryboard: () => directStoryboard,
   doRectsIntersect: () => doRectsIntersect,
   downloadAnnotationsAsJSON: () => downloadAnnotationsAsJSON,
   downloadAnnotationsAsMarkdown: () => downloadAnnotationsAsMarkdown,
@@ -11238,6 +11385,7 @@ __export(index_exports, {
   generateDocumentId: () => generateDocumentId,
   getAllDocumentIds: () => getAllDocumentIds,
   getAllStudentDataDocumentIds: () => getAllStudentDataDocumentIds,
+  getLocalMiniLM: () => getLocalMiniLM,
   getMetadata: () => getMetadata,
   getOutline: () => getOutline,
   getPage: () => getPage,
@@ -11255,6 +11403,8 @@ __export(index_exports, {
   loadDocumentWithCallbacks: () => loadDocumentWithCallbacks,
   loadHighlights: () => loadHighlights,
   loadStudentData: () => loadStudentData,
+  makeOverlayId: () => makeOverlayId,
+  matchChunkToBlock: () => matchChunkToBlock,
   mergeAdjacentRects: () => mergeAdjacentRects,
   pdfToPercent: () => pdfToPercent,
   pdfToViewport: () => pdfToViewport,
@@ -11267,6 +11417,9 @@ __export(index_exports, {
   saveHighlights: () => saveHighlights,
   saveStudentData: () => saveStudentData,
   scaleRect: () => scaleRect,
+  storyboardFromMatch: () => storyboardFromMatch,
+  storyboardJsonSchema: () => storyboardJsonSchema,
+  truncate: () => truncate,
   useAgentContext: () => useAgentContext,
   useAgentStore: () => useAgentStore,
   useAnnotationStore: () => useAnnotationStore,
@@ -11966,7 +12119,7 @@ var import_jsx_runtime34 = require("react/jsx-runtime");
 var QuickNoteButton = (0, import_react48.memo)(function QuickNoteButton2({
   pageNumber,
   scale,
-  position = "top-right",
+  position: position2 = "top-right",
   onClick,
   className,
   visible = true
@@ -11975,11 +12128,11 @@ var QuickNoteButton = (0, import_react48.memo)(function QuickNoteButton2({
   const handleClick = (0, import_react48.useCallback)(
     (e) => {
       e.stopPropagation();
-      const x = position === "top-right" ? 80 : 80;
-      const y = position === "top-right" ? 20 : 80;
+      const x = position2 === "top-right" ? 80 : 80;
+      const y = position2 === "top-right" ? 20 : 80;
       onClick(pageNumber, x / scale, y / scale);
     },
-    [pageNumber, onClick, position, scale]
+    [pageNumber, onClick, position2, scale]
   );
   if (!visible) {
     return null;
@@ -12000,8 +12153,8 @@ var QuickNoteButton = (0, import_react48.memo)(function QuickNoteButton2({
         "transition-all duration-200",
         "focus:outline-none focus:ring-2 focus:ring-yellow-500 focus:ring-offset-2",
         isHovered && "scale-110",
-        position === "top-right" && "top-3 right-3",
-        position === "bottom-right" && "bottom-3 right-3",
+        position2 === "top-right" && "top-3 right-3",
+        position2 === "bottom-right" && "bottom-3 right-3",
         className
       ),
       title: "Add quick note",
@@ -12027,7 +12180,7 @@ init_utils();
 var import_jsx_runtime35 = require("react/jsx-runtime");
 var QuickNotePopover = (0, import_react49.memo)(function QuickNotePopover2({
   visible,
-  position,
+  position: position2,
   initialContent = "",
   agentLastStatement,
   onSave,
@@ -12037,7 +12190,7 @@ var QuickNotePopover = (0, import_react49.memo)(function QuickNotePopover2({
   const [content, setContent] = (0, import_react49.useState)(initialContent);
   const textareaRef = (0, import_react49.useRef)(null);
   const popoverRef = (0, import_react49.useRef)(null);
-  const [adjustedPosition, setAdjustedPosition] = (0, import_react49.useState)(position);
+  const [adjustedPosition, setAdjustedPosition] = (0, import_react49.useState)(position2);
   (0, import_react49.useEffect)(() => {
     if (visible && textareaRef.current) {
       textareaRef.current.focus();
@@ -12052,7 +12205,7 @@ var QuickNotePopover = (0, import_react49.memo)(function QuickNotePopover2({
     if (!visible || !popoverRef.current) return;
     const rect = popoverRef.current.getBoundingClientRect();
     const padding = 10;
-    let { x, y } = position;
+    let { x, y } = position2;
     if (x + rect.width > window.innerWidth - padding) {
       x = window.innerWidth - rect.width - padding;
     }
@@ -12066,7 +12219,7 @@ var QuickNotePopover = (0, import_react49.memo)(function QuickNotePopover2({
       y = padding;
     }
     setAdjustedPosition({ x, y });
-  }, [position, visible]);
+  }, [position2, visible]);
   const handleSave = (0, import_react49.useCallback)(() => {
     if (content.trim()) {
       onSave(content.trim());
@@ -12183,11 +12336,11 @@ var import_jsx_runtime36 = require("react/jsx-runtime");
 var AskAboutOverlay = (0, import_react50.memo)(function AskAboutOverlay2({
   visible,
   progress,
-  position,
+  position: position2,
   size = 60,
   className
 }) {
-  if (!visible || !position) {
+  if (!visible || !position2) {
     return null;
   }
   const strokeWidth = 4;
@@ -12203,8 +12356,8 @@ var AskAboutOverlay = (0, import_react50.memo)(function AskAboutOverlay2({
         className
       ),
       style: {
-        left: position.x - size / 2,
-        top: position.y - size / 2
+        left: position2.x - size / 2,
+        top: position2.y - size / 2
       },
       children: [
         /* @__PURE__ */ (0, import_jsx_runtime36.jsxs)(
@@ -12292,20 +12445,20 @@ var import_react51 = require("react");
 init_utils();
 var import_jsx_runtime37 = require("react/jsx-runtime");
 var AskAboutTrigger = (0, import_react51.memo)(function AskAboutTrigger2({
-  position,
+  position: position2,
   onConfirm,
   onCancel,
   visible,
   autoHideDelay = 5e3,
   className
 }) {
-  const [adjustedPosition, setAdjustedPosition] = (0, import_react51.useState)(position);
+  const [adjustedPosition, setAdjustedPosition] = (0, import_react51.useState)(position2);
   const triggerRef = (0, import_react51.useRef)(null);
   (0, import_react51.useEffect)(() => {
     if (!visible || !triggerRef.current) return;
     const rect = triggerRef.current.getBoundingClientRect();
     const padding = 10;
-    let { x, y } = position;
+    let { x, y } = position2;
     if (x + rect.width / 2 > window.innerWidth - padding) {
       x = window.innerWidth - rect.width / 2 - padding;
     }
@@ -12313,10 +12466,10 @@ var AskAboutTrigger = (0, import_react51.memo)(function AskAboutTrigger2({
       x = rect.width / 2 + padding;
     }
     if (y + rect.height > window.innerHeight - padding) {
-      y = position.y - rect.height - 20;
+      y = position2.y - rect.height - 20;
     }
     setAdjustedPosition({ x, y });
-  }, [position, visible]);
+  }, [position2, visible]);
   (0, import_react51.useEffect)(() => {
     if (!visible || autoHideDelay === 0) return;
     const timer = setTimeout(onCancel, autoHideDelay);
@@ -12964,6 +13117,2258 @@ function withErrorBoundary({ component, ...props }) {
 // src/components/index.ts
 init_PDFLoadingScreen2();
 
+// src/components/TutorMode/TutorModeContainer.tsx
+var import_react56 = require("react");
+var import_zustand2 = require("zustand");
+init_PDFPage2();
+init_hooks();
+
+// src/components/TutorMode/CameraView.tsx
+var import_framer_motion = require("framer-motion");
+var import_jsx_runtime41 = require("react/jsx-runtime");
+function CameraView({
+  camera,
+  children,
+  durationMs = 700,
+  className
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime41.jsx)(
+    import_framer_motion.motion.div,
+    {
+      className,
+      style: {
+        transformOrigin: "50% 50%",
+        willChange: "transform",
+        width: "100%",
+        height: "100%",
+        position: "relative"
+      },
+      animate: {
+        scale: camera.scale,
+        x: camera.x,
+        y: camera.y
+      },
+      transition: {
+        duration: durationMs / 1e3,
+        ease: camera.easing === "linear" ? "linear" : camera.easing === "ease-in" ? [0.42, 0, 1, 1] : camera.easing === "ease-out" ? [0, 0, 0.58, 1] : [0.42, 0, 0.58, 1]
+      },
+      children
+    }
+  );
+}
+
+// src/components/TutorMode/CinemaLayer.tsx
+var import_framer_motion10 = require("framer-motion");
+
+// src/components/TutorMode/SpotlightMask.tsx
+var import_react55 = require("react");
+var import_framer_motion2 = require("framer-motion");
+var import_jsx_runtime42 = require("react/jsx-runtime");
+function SpotlightMask({
+  page,
+  bbox,
+  action,
+  durationMs = 400
+}) {
+  const maskId = (0, import_react55.useId)();
+  const filterId = `${maskId}-blur`;
+  const [x1, y1, x2, y2] = bbox;
+  const w = Math.max(0, x2 - x1);
+  const h = Math.max(0, y2 - y1);
+  const rx = action.shape === "rounded" ? 12 : action.shape === "ellipse" ? w / 2 : 0;
+  const ry = action.shape === "rounded" ? 12 : action.shape === "ellipse" ? h / 2 : 0;
+  const feather = action.feather_px;
+  return /* @__PURE__ */ (0, import_jsx_runtime42.jsxs)(
+    "svg",
+    {
+      viewBox: `0 0 ${page.width} ${page.height}`,
+      width: page.width,
+      height: page.height,
+      preserveAspectRatio: "none",
+      style: {
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        width: page.width,
+        height: page.height
+      },
+      "data-role": "spotlight-mask",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime42.jsxs)("defs", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime42.jsx)("filter", { id: filterId, x: "-20%", y: "-20%", width: "140%", height: "140%", children: /* @__PURE__ */ (0, import_jsx_runtime42.jsx)("feGaussianBlur", { in: "SourceGraphic", stdDeviation: feather / 4 }) }),
+          /* @__PURE__ */ (0, import_jsx_runtime42.jsxs)("mask", { id: maskId, children: [
+            /* @__PURE__ */ (0, import_jsx_runtime42.jsx)("rect", { x: 0, y: 0, width: page.width, height: page.height, fill: "white" }),
+            action.shape === "ellipse" ? /* @__PURE__ */ (0, import_jsx_runtime42.jsx)(
+              "ellipse",
+              {
+                cx: (x1 + x2) / 2,
+                cy: (y1 + y2) / 2,
+                rx: w / 2,
+                ry: h / 2,
+                fill: "black",
+                filter: `url(#${filterId})`
+              }
+            ) : /* @__PURE__ */ (0, import_jsx_runtime42.jsx)(
+              "rect",
+              {
+                x: x1,
+                y: y1,
+                width: w,
+                height: h,
+                rx,
+                ry,
+                fill: "black",
+                filter: `url(#${filterId})`
+              }
+            )
+          ] })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime42.jsx)(
+          import_framer_motion2.motion.rect,
+          {
+            x: 0,
+            y: 0,
+            width: page.width,
+            height: page.height,
+            fill: "black",
+            mask: `url(#${maskId})`,
+            initial: { fillOpacity: 0 },
+            animate: { fillOpacity: action.dim_opacity },
+            exit: { fillOpacity: 0 },
+            transition: { duration: durationMs / 1e3, ease: "easeOut" }
+          }
+        )
+      ]
+    }
+  );
+}
+
+// src/components/TutorMode/AnimatedUnderline.tsx
+var import_framer_motion3 = require("framer-motion");
+var import_jsx_runtime43 = require("react/jsx-runtime");
+function pathForStyle(x1, x2, y, style) {
+  if (style === "straight") return `M ${x1} ${y} L ${x2} ${y}`;
+  if (style === "double")
+    return `M ${x1} ${y - 3} L ${x2} ${y - 3} M ${x1} ${y + 3} L ${x2} ${y + 3}`;
+  if (style === "wavy") {
+    const steps = Math.max(8, Math.floor((x2 - x1) / 18));
+    let d2 = `M ${x1} ${y}`;
+    for (let i = 1; i <= steps; i++) {
+      const px = x1 + (x2 - x1) * i / steps;
+      const dy = i % 2 === 0 ? 4 : -4;
+      d2 += ` Q ${px - (x2 - x1) / (2 * steps)} ${y + dy} ${px} ${y}`;
+    }
+    return d2;
+  }
+  const segs = 6;
+  let d = `M ${x1} ${y}`;
+  for (let i = 1; i <= segs; i++) {
+    const px = x1 + (x2 - x1) * i / segs;
+    const jitter = (Math.random() - 0.5) * 4;
+    d += ` L ${px} ${y + jitter}`;
+  }
+  return d;
+}
+function AnimatedUnderline({ bbox, action }) {
+  const [x1, , x2, y2] = bbox;
+  const y = y2 + 6;
+  const d = pathForStyle(x1, x2, y, action.style);
+  const duration = action.draw_duration_ms / 1e3;
+  return /* @__PURE__ */ (0, import_jsx_runtime43.jsx)(
+    "svg",
+    {
+      style: {
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        overflow: "visible"
+      },
+      "data-role": "underline",
+      children: /* @__PURE__ */ (0, import_jsx_runtime43.jsx)(
+        import_framer_motion3.motion.path,
+        {
+          d,
+          fill: "none",
+          stroke: action.color,
+          strokeWidth: 4,
+          strokeLinecap: "round",
+          initial: { pathLength: 0, opacity: 0 },
+          animate: { pathLength: 1, opacity: 1 },
+          exit: { opacity: 0 },
+          transition: { duration, ease: "easeOut" }
+        }
+      )
+    }
+  );
+}
+
+// src/components/TutorMode/AnimatedHighlight.tsx
+var import_framer_motion4 = require("framer-motion");
+var import_jsx_runtime44 = require("react/jsx-runtime");
+function AnimatedHighlight({ bbox, action }) {
+  const [x1, y1, x2, y2] = bbox;
+  const w = x2 - x1;
+  const h = y2 - y1;
+  return /* @__PURE__ */ (0, import_jsx_runtime44.jsx)(
+    import_framer_motion4.motion.div,
+    {
+      style: {
+        position: "absolute",
+        left: x1,
+        top: y1,
+        height: h,
+        background: action.color,
+        borderRadius: 4,
+        mixBlendMode: "multiply",
+        transformOrigin: "0% 50%",
+        pointerEvents: "none"
+      },
+      initial: { width: 0, opacity: 0.9 },
+      animate: { width: w, opacity: 0.9 },
+      exit: { opacity: 0 },
+      transition: { duration: action.draw_duration_ms / 1e3, ease: "easeOut" },
+      "data-role": "highlight"
+    }
+  );
+}
+
+// src/components/TutorMode/PulseOverlay.tsx
+var import_framer_motion5 = require("framer-motion");
+var import_jsx_runtime45 = require("react/jsx-runtime");
+var INTENSITY = {
+  subtle: { scale: 1.02, border: "2px solid rgba(59,130,246,0.6)" },
+  normal: { scale: 1.05, border: "3px solid rgba(59,130,246,0.8)" },
+  strong: { scale: 1.1, border: "4px solid rgba(59,130,246,1.0)" }
+};
+function PulseOverlay({ bbox, action }) {
+  const [x1, y1, x2, y2] = bbox;
+  const { scale, border } = INTENSITY[action.intensity];
+  const repeat = action.count === 1 ? 0 : action.count - 1;
+  return /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(
+    import_framer_motion5.motion.div,
+    {
+      style: {
+        position: "absolute",
+        left: x1,
+        top: y1,
+        width: x2 - x1,
+        height: y2 - y1,
+        border,
+        borderRadius: 8,
+        pointerEvents: "none",
+        boxSizing: "border-box"
+      },
+      animate: { scale: [1, scale, 1] },
+      transition: {
+        duration: 1.2,
+        times: [0, 0.5, 1],
+        ease: "easeInOut",
+        repeat,
+        repeatType: "loop"
+      },
+      exit: { opacity: 0 },
+      "data-role": "pulse"
+    }
+  );
+}
+
+// src/components/TutorMode/CalloutArrow.tsx
+var import_framer_motion6 = require("framer-motion");
+var import_jsx_runtime46 = require("react/jsx-runtime");
+function centerOf(b) {
+  return { x: (b[0] + b[2]) / 2, y: (b[1] + b[3]) / 2 };
+}
+function arrowPath(fromBbox, toBbox, curve) {
+  const a = centerOf(fromBbox);
+  const b = centerOf(toBbox);
+  if (curve === "straight") return `M ${a.x} ${a.y} L ${b.x} ${b.y}`;
+  if (curve === "zigzag") {
+    const mx = (a.x + b.x) / 2;
+    return `M ${a.x} ${a.y} L ${mx} ${a.y} L ${mx} ${b.y} L ${b.x} ${b.y}`;
+  }
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const cx = (a.x + b.x) / 2 - dy * 0.25;
+  const cy = (a.y + b.y) / 2 + dx * 0.25;
+  return `M ${a.x} ${a.y} Q ${cx} ${cy} ${b.x} ${b.y}`;
+}
+function CalloutArrow({ fromBbox, toBbox, action }) {
+  const d = arrowPath(fromBbox, toBbox, action.curve);
+  const label = action.label;
+  const target = centerOf(toBbox);
+  return /* @__PURE__ */ (0, import_jsx_runtime46.jsxs)(
+    "svg",
+    {
+      style: {
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        overflow: "visible"
+      },
+      "data-role": "callout",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime46.jsx)("defs", { children: /* @__PURE__ */ (0, import_jsx_runtime46.jsx)(
+          "marker",
+          {
+            id: "arrowhead",
+            viewBox: "0 0 10 10",
+            refX: "8",
+            refY: "5",
+            markerWidth: "8",
+            markerHeight: "8",
+            orient: "auto",
+            children: /* @__PURE__ */ (0, import_jsx_runtime46.jsx)("path", { d: "M 0 0 L 10 5 L 0 10 z", fill: "#3B82F6" })
+          }
+        ) }),
+        /* @__PURE__ */ (0, import_jsx_runtime46.jsx)(
+          import_framer_motion6.motion.path,
+          {
+            d,
+            fill: "none",
+            stroke: "#3B82F6",
+            strokeWidth: 3,
+            strokeLinecap: "round",
+            markerEnd: "url(#arrowhead)",
+            initial: { pathLength: 0, opacity: 0 },
+            animate: { pathLength: 1, opacity: 1 },
+            exit: { opacity: 0 },
+            transition: { duration: 0.6, ease: "easeOut" }
+          }
+        ),
+        label ? /* @__PURE__ */ (0, import_jsx_runtime46.jsxs)(
+          import_framer_motion6.motion.g,
+          {
+            initial: { opacity: 0 },
+            animate: { opacity: 1 },
+            exit: { opacity: 0 },
+            transition: { delay: 0.3, duration: 0.3 },
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime46.jsx)(
+                "rect",
+                {
+                  x: target.x - 4,
+                  y: target.y - 28,
+                  width: label.length * 9 + 12,
+                  height: 22,
+                  rx: 4,
+                  fill: "#1F2937"
+                }
+              ),
+              /* @__PURE__ */ (0, import_jsx_runtime46.jsx)(
+                "text",
+                {
+                  x: target.x + 2,
+                  y: target.y - 12,
+                  fill: "white",
+                  fontSize: 14,
+                  fontFamily: "system-ui, sans-serif",
+                  children: label
+                }
+              )
+            ]
+          }
+        ) : null
+      ]
+    }
+  );
+}
+
+// src/components/TutorMode/GhostReference.tsx
+var import_framer_motion7 = require("framer-motion");
+var import_jsx_runtime47 = require("react/jsx-runtime");
+var POSITIONS = {
+  "top-right": { top: 40, right: 40 },
+  "top-left": { top: 40, left: 40 },
+  "bottom-right": { bottom: 40, right: 40 },
+  "bottom-left": { bottom: 40, left: 40 }
+};
+function GhostReference({
+  page,
+  sourceBbox,
+  sourceBlockText,
+  sourcePageNumber,
+  action
+}) {
+  const width = 360;
+  const [x1, y1, x2, y2] = sourceBbox;
+  return /* @__PURE__ */ (0, import_jsx_runtime47.jsxs)(
+    import_framer_motion7.motion.div,
+    {
+      initial: { opacity: 0, y: 20, scale: 0.95 },
+      animate: { opacity: 1, y: 0, scale: 1 },
+      exit: { opacity: 0, y: 20, scale: 0.95 },
+      transition: { duration: 0.4, ease: "easeOut" },
+      style: {
+        position: "absolute",
+        width,
+        background: "#111",
+        color: "white",
+        borderRadius: 12,
+        padding: 12,
+        boxShadow: "0 10px 40px rgba(0,0,0,0.5)",
+        pointerEvents: "none",
+        fontFamily: "system-ui, sans-serif",
+        fontSize: 13,
+        ...POSITIONS[action.position]
+      },
+      "data-role": "ghost-reference",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime47.jsxs)("div", { style: { opacity: 0.7, fontSize: 11, marginBottom: 6 }, children: [
+          "Page ",
+          sourcePageNumber,
+          " \u2014 ",
+          action.target_block
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime47.jsxs)(
+          "svg",
+          {
+            width: width - 24,
+            height: 160,
+            viewBox: `0 0 ${page.width} ${page.height}`,
+            style: { background: "#1F2937", borderRadius: 6, display: "block" },
+            preserveAspectRatio: "xMidYMid meet",
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime47.jsx)(
+                "rect",
+                {
+                  x: 0,
+                  y: 0,
+                  width: page.width,
+                  height: page.height,
+                  fill: "#1F2937"
+                }
+              ),
+              /* @__PURE__ */ (0, import_jsx_runtime47.jsx)(
+                "rect",
+                {
+                  x: x1,
+                  y: y1,
+                  width: x2 - x1,
+                  height: y2 - y1,
+                  fill: "rgba(250,204,21,0.45)",
+                  stroke: "#FBBF24",
+                  strokeWidth: 8
+                }
+              )
+            ]
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime47.jsx)(
+          "div",
+          {
+            style: {
+              marginTop: 8,
+              fontSize: 12,
+              lineHeight: 1.4,
+              opacity: 0.9
+            },
+            children: sourceBlockText ?? "(figure)"
+          }
+        )
+      ]
+    }
+  );
+}
+
+// src/components/TutorMode/BoxOverlay.tsx
+var import_framer_motion8 = require("framer-motion");
+var import_jsx_runtime48 = require("react/jsx-runtime");
+function BoxOverlay({ bbox, action }) {
+  const [x1, y1, x2, y2] = bbox;
+  return /* @__PURE__ */ (0, import_jsx_runtime48.jsx)(
+    import_framer_motion8.motion.div,
+    {
+      initial: { opacity: 0, scale: 0.97 },
+      animate: { opacity: 1, scale: 1 },
+      exit: { opacity: 0 },
+      transition: { duration: 0.35, ease: "easeOut" },
+      style: {
+        position: "absolute",
+        left: x1,
+        top: y1,
+        width: x2 - x1,
+        height: y2 - y1,
+        border: `${action.style === "dashed" ? "3px dashed" : "3px solid"} ${action.color}`,
+        borderRadius: 6,
+        pointerEvents: "none",
+        boxSizing: "border-box"
+      },
+      "data-role": "box"
+    }
+  );
+}
+
+// src/components/TutorMode/StickyLabel.tsx
+var import_framer_motion9 = require("framer-motion");
+var import_jsx_runtime49 = require("react/jsx-runtime");
+function position(bbox, where) {
+  const [x1, y1, x2, y2] = bbox;
+  const cx = (x1 + x2) / 2;
+  const cy = (y1 + y2) / 2;
+  const PAD = 16;
+  switch (where) {
+    case "top":
+      return { left: cx, top: y1 - PAD, transform: "translate(-50%, -100%)" };
+    case "bottom":
+      return { left: cx, top: y2 + PAD, transform: "translate(-50%, 0)" };
+    case "left":
+      return { left: x1 - PAD, top: cy, transform: "translate(-100%, -50%)" };
+    case "right":
+      return { left: x2 + PAD, top: cy, transform: "translate(0, -50%)" };
+    default:
+      return { left: cx, top: y1, transform: "translate(-50%, -100%)" };
+  }
+}
+function StickyLabel({ bbox, action }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime49.jsx)(
+    import_framer_motion9.motion.div,
+    {
+      initial: { opacity: 0, scale: 0.9 },
+      animate: { opacity: 1, scale: 1 },
+      exit: { opacity: 0 },
+      transition: { duration: 0.35, ease: "easeOut" },
+      style: {
+        position: "absolute",
+        padding: "6px 10px",
+        background: "#FEF3C7",
+        color: "#78350F",
+        borderRadius: 6,
+        boxShadow: "0 3px 10px rgba(0,0,0,0.2)",
+        fontSize: 14,
+        fontFamily: "system-ui, sans-serif",
+        maxWidth: 280,
+        pointerEvents: "none",
+        ...position(bbox, action.position)
+      },
+      "data-role": "label",
+      children: action.text
+    }
+  );
+}
+
+// src/components/TutorMode/CinemaLayer.tsx
+var import_jsx_runtime50 = require("react/jsx-runtime");
+function blockBbox(index, block_id) {
+  return index.blockById.get(block_id)?.block.bbox;
+}
+function CinemaLayer({
+  page,
+  index,
+  overlays,
+  scale
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(
+    "div",
+    {
+      "data-role": "cinema-layer",
+      style: {
+        position: "absolute",
+        inset: 0,
+        transformOrigin: "0 0",
+        transform: `scale(${scale})`,
+        width: page.page_dimensions.width,
+        height: page.page_dimensions.height,
+        pointerEvents: "none",
+        // PDFPage renders internal layers at z-index 10/20/40/45/50
+        // (canvas / text / highlight / focus / annotation). Without an
+        // explicit z-index here, every tutor overlay stacks UNDER the
+        // AnnotationLayer and becomes invisible. 100 puts us above all of
+        // them while still letting the Exit button (z-index 60) remain
+        // reachable because it sits OUTSIDE this stacking context.
+        zIndex: 100
+      },
+      children: /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(import_framer_motion10.AnimatePresence, { children: overlays.map((overlay) => {
+        switch (overlay.kind) {
+          case "spotlight": {
+            const a = overlay.action;
+            const b = blockBbox(index, a.target_block);
+            if (!b) return null;
+            return /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(
+              SpotlightMask,
+              {
+                page: page.page_dimensions,
+                bbox: b,
+                action: a
+              },
+              overlay.id
+            );
+          }
+          case "underline": {
+            const a = overlay.action;
+            const b = blockBbox(index, a.target_block);
+            if (!b) return null;
+            return /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(AnimatedUnderline, { bbox: b, action: a }, overlay.id);
+          }
+          case "highlight": {
+            const a = overlay.action;
+            const b = blockBbox(index, a.target_block);
+            if (!b) return null;
+            return /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(AnimatedHighlight, { bbox: b, action: a }, overlay.id);
+          }
+          case "pulse": {
+            const a = overlay.action;
+            const b = blockBbox(index, a.target_block);
+            if (!b) return null;
+            return /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(PulseOverlay, { bbox: b, action: a }, overlay.id);
+          }
+          case "callout": {
+            const a = overlay.action;
+            const from = blockBbox(index, a.from_block);
+            const to = blockBbox(index, a.to_block);
+            if (!from || !to) return null;
+            return /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(
+              CalloutArrow,
+              {
+                fromBbox: from,
+                toBbox: to,
+                action: a
+              },
+              overlay.id
+            );
+          }
+          case "ghost_reference": {
+            const a = overlay.action;
+            const hit = index.blockById.get(a.target_block);
+            if (!hit) return null;
+            const targetPage = index.byPage.get(a.target_page);
+            if (!targetPage) return null;
+            return /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(
+              GhostReference,
+              {
+                page: targetPage.page_dimensions,
+                sourceBbox: hit.block.bbox,
+                sourceBlockText: hit.block.text,
+                sourcePageNumber: hit.pageNumber,
+                action: a
+              },
+              overlay.id
+            );
+          }
+          case "box": {
+            const a = overlay.action;
+            const b = blockBbox(index, a.target_block);
+            if (!b) return null;
+            return /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(BoxOverlay, { bbox: b, action: a }, overlay.id);
+          }
+          case "label": {
+            const a = overlay.action;
+            const b = blockBbox(index, a.target_block);
+            if (!b) return null;
+            return /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(StickyLabel, { bbox: b, action: a }, overlay.id);
+          }
+          case "clear":
+          case "camera":
+            return null;
+        }
+      }) })
+    }
+  );
+}
+
+// src/components/TutorMode/SubtitleBar.tsx
+var import_framer_motion11 = require("framer-motion");
+var import_jsx_runtime51 = require("react/jsx-runtime");
+function SubtitleBar({ text }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime51.jsx)(import_framer_motion11.AnimatePresence, { children: text ? /* @__PURE__ */ (0, import_jsx_runtime51.jsx)(
+    import_framer_motion11.motion.div,
+    {
+      initial: { opacity: 0, y: 20 },
+      animate: { opacity: 1, y: 0 },
+      exit: { opacity: 0, y: 20 },
+      transition: { duration: 0.3 },
+      style: {
+        position: "absolute",
+        left: "50%",
+        bottom: 32,
+        transform: "translateX(-50%)",
+        background: "rgba(0,0,0,0.75)",
+        color: "white",
+        padding: "10px 18px",
+        borderRadius: 8,
+        maxWidth: "80%",
+        fontSize: 16,
+        lineHeight: 1.4,
+        fontFamily: "system-ui, sans-serif",
+        pointerEvents: "none",
+        zIndex: 50,
+        textAlign: "center"
+      },
+      "data-role": "subtitle-bar",
+      children: text
+    },
+    text
+  ) : null });
+}
+
+// src/director/storyboard-engine.ts
+init_narration_store();
+init_camera_math();
+var DEFAULT_MIN_OVERLAY_MS = 3500;
+var StoryboardEngine = class {
+  constructor(deps) {
+    /**
+     * Timers that schedule the START of a step (via `setTimeout(runStep, at_ms)`).
+     * These are storyboard-scoped: when a new storyboard arrives, anything still
+     * pending should be abandoned.
+     */
+    this.pendingStepTimers = /* @__PURE__ */ new Set();
+    /**
+     * Timers that auto-REMOVE an already-placed overlay after its visible
+     * duration. Keyed by overlay id so we can cancel one specifically. These are
+     * NOT cancelled when a new storyboard starts — otherwise the still-visible
+     * overlay from the previous beat would get stranded in the store forever
+     * (the "stuck spotlight" bug).
+     */
+    this.overlayRemovalTimers = /* @__PURE__ */ new Map();
+    this.currentStoryboardId = 0;
+    this.deps = deps;
+  }
+  /**
+   * Execute a new storyboard. Cancels in-flight steps from the previous storyboard
+   * and smoothly transitions the camera/overlays from the current state.
+   */
+  execute(storyboard) {
+    this.cancelPending();
+    this.currentStoryboardId += 1;
+    const storyboardId = this.currentStoryboardId;
+    const { narrationStore } = this.deps;
+    narrationStore.getState().setEngineStatus("transitioning");
+    narrationStore.getState().setLastStoryboard(storyboard);
+    let steps = [...storyboard.steps].sort((a, b) => a.at_ms - b.at_ms);
+    const hasCamera = steps.some((s) => s.action.type === "camera");
+    if (!hasCamera) {
+      const focus = steps.find(
+        (s) => s.action.type !== "clear" && "target_block" in s.action && s.action.target_block
+      );
+      if (focus && focus.action.type !== "clear" && "target_block" in focus.action) {
+        steps = [
+          {
+            at_ms: 0,
+            duration_ms: 700,
+            action: {
+              type: "camera",
+              target_block: focus.action.target_block,
+              scale: 1,
+              padding: 60,
+              easing: "ease-out"
+            }
+          },
+          ...steps
+        ];
+      }
+    }
+    for (const step of steps) {
+      const timer = setTimeout(() => {
+        if (storyboardId !== this.currentStoryboardId) return;
+        this.runStep(step);
+      }, step.at_ms);
+      this.pendingStepTimers.add(timer);
+    }
+    const markExecuting = setTimeout(() => {
+      if (storyboardId !== this.currentStoryboardId) return;
+      narrationStore.getState().setEngineStatus("executing");
+    }, 0);
+    this.pendingStepTimers.add(markExecuting);
+    const last = steps[steps.length - 1];
+    if (last) {
+      const totalMs = last.at_ms + last.duration_ms;
+      const markIdle = setTimeout(() => {
+        if (storyboardId !== this.currentStoryboardId) return;
+        narrationStore.getState().setEngineStatus("idle");
+      }, totalMs + 50);
+      this.pendingStepTimers.add(markIdle);
+    }
+  }
+  /**
+   * Abort pending STEP dispatches from the current storyboard. Overlay
+   * removal timers are left alone so already-visible overlays still auto-
+   * expire on their own schedule. To force-clear every overlay, call
+   * `resetVisuals()` instead.
+   */
+  cancelPending() {
+    for (const t of this.pendingStepTimers) clearTimeout(t);
+    this.pendingStepTimers.clear();
+    this.deps.narrationStore.getState().setEngineStatus("idle");
+  }
+  /** Cancel every removal timer (used by resetVisuals only). */
+  cancelAllRemovalTimers() {
+    for (const t of this.overlayRemovalTimers.values()) clearTimeout(t);
+    this.overlayRemovalTimers.clear();
+  }
+  /** Reset visuals: clear overlays, cancel every removal timer, fit camera. */
+  resetVisuals() {
+    this.cancelPending();
+    this.cancelAllRemovalTimers();
+    const { narrationStore, bboxIndex, getViewport } = this.deps;
+    narrationStore.getState().clearOverlays();
+    const viewport = getViewport();
+    const currentPage = narrationStore.getState().currentPage;
+    const pageDims = bboxIndex.byPage.get(currentPage);
+    const fit = pageDims && viewport.width > 0 && viewport.height > 0 ? fitPageScale(pageDims.page_dimensions, viewport) * 0.95 : 1;
+    narrationStore.getState().setCamera({ scale: fit, x: 0, y: 0, easing: "ease-in-out" });
+  }
+  /** Execute one step — dispatch to narrationStore. Returns true if applied. */
+  runStep(step) {
+    const action = step.action;
+    const { narrationStore, bboxIndex } = this.deps;
+    if ("target_block" in action && action.target_block) {
+      if (!bboxIndex.blockById.has(action.target_block)) {
+        narrationStore.getState().appendDebugEvent({
+          kind: "llm-error",
+          summary: `dropped ${action.type} step \u2192 unknown target_block "${action.target_block}"`,
+          payload: { action, validIds: [...bboxIndex.blockById.keys()] }
+        });
+        return false;
+      }
+    }
+    if ("from_block" in action && action.from_block) {
+      if (!bboxIndex.blockById.has(action.from_block)) {
+        narrationStore.getState().appendDebugEvent({
+          kind: "llm-error",
+          summary: `dropped ${action.type} step \u2192 unknown from_block "${action.from_block}"`,
+          payload: { action }
+        });
+        return false;
+      }
+    }
+    if ("to_block" in action && action.to_block) {
+      if (!bboxIndex.blockById.has(action.to_block)) {
+        narrationStore.getState().appendDebugEvent({
+          kind: "llm-error",
+          summary: `dropped ${action.type} step \u2192 unknown to_block "${action.to_block}"`,
+          payload: { action }
+        });
+        return false;
+      }
+    }
+    if (action.type === "camera") {
+      this.applyCamera(action, step.duration_ms);
+      return true;
+    }
+    if (action.type === "clear") {
+      const targets = action.targets;
+      if (targets === "all" || targets === "overlays") {
+        narrationStore.getState().clearOverlays();
+      } else if (targets === "spotlights") {
+        narrationStore.getState().clearOverlays((o) => o.kind === "spotlight");
+      } else if (Array.isArray(targets)) {
+        const ids = new Set(targets);
+        narrationStore.getState().clearOverlays((o) => ids.has(o.id));
+      }
+      return true;
+    }
+    const minMs = this.deps.minOverlayDurationMs ?? DEFAULT_MIN_OVERLAY_MS;
+    const visibleMs = Math.max(step.duration_ms, minMs);
+    const overlay = {
+      id: makeOverlayId(action),
+      kind: action.type,
+      action,
+      createdAt: Date.now(),
+      expiresAt: Date.now() + visibleMs
+    };
+    narrationStore.getState().addOverlay(overlay);
+    const timer = setTimeout(() => {
+      narrationStore.getState().removeOverlay(overlay.id);
+      this.overlayRemovalTimers.delete(overlay.id);
+    }, visibleMs);
+    this.overlayRemovalTimers.set(overlay.id, timer);
+    return true;
+  }
+  applyCamera(action, durationMs) {
+    const { narrationStore, bboxIndex, getViewport } = this.deps;
+    const viewport = getViewport();
+    let bbox = action.target_bbox;
+    let pageDims = void 0;
+    if (!bbox && action.target_block) {
+      const hit = bboxIndex.blockById.get(action.target_block);
+      if (!hit) return;
+      bbox = hit.block.bbox;
+      pageDims = bboxIndex.byPage.get(hit.pageNumber);
+    } else if (bbox) {
+      pageDims = bboxIndex.byPage.get(narrationStore.getState().currentPage);
+    }
+    if (!bbox || !pageDims) return;
+    const fit = fitPageScale(pageDims.page_dimensions, viewport);
+    const requested = Math.max(0.5, Math.min(3, action.scale ?? 1));
+    const finalScale = fit * requested;
+    const [x1, y1, x2, y2] = bbox;
+    const blockCX = (x1 + x2) / 2;
+    const blockCY = (y1 + y2) / 2;
+    const pageCX = pageDims.page_dimensions.width / 2;
+    const pageCY = pageDims.page_dimensions.height / 2;
+    const x = (pageCX - blockCX) * finalScale;
+    const y = (pageCY - blockCY) * finalScale;
+    const camera = {
+      scale: finalScale,
+      x,
+      y,
+      easing: action.easing
+    };
+    narrationStore.getState().setCamera(camera);
+    void durationMs;
+    void computeCameraForBlock;
+  }
+};
+
+// src/director/storyboard-schema.ts
+var import_zod = require("zod");
+var BBoxCoordsSchema = import_zod.z.tuple([import_zod.z.number(), import_zod.z.number(), import_zod.z.number(), import_zod.z.number()]);
+var CameraSchema = import_zod.z.object({
+  type: import_zod.z.literal("camera"),
+  target_block: import_zod.z.string().optional(),
+  target_bbox: BBoxCoordsSchema.optional(),
+  scale: import_zod.z.number().min(0.5).max(4).default(1),
+  padding: import_zod.z.number().min(0).max(400).default(80),
+  easing: import_zod.z.enum(["linear", "ease-in", "ease-out", "ease-in-out"]).default("ease-in-out")
+}).refine((a) => !!a.target_block || !!a.target_bbox, {
+  message: "camera requires target_block or target_bbox"
+});
+var SpotlightSchema = import_zod.z.object({
+  type: import_zod.z.literal("spotlight"),
+  target_block: import_zod.z.string(),
+  dim_opacity: import_zod.z.number().min(0).max(1).default(0.65),
+  feather_px: import_zod.z.number().min(0).max(200).default(40),
+  shape: import_zod.z.enum(["rect", "rounded", "ellipse"]).default("rounded")
+});
+var UnderlineSchema = import_zod.z.object({
+  type: import_zod.z.literal("underline"),
+  target_block: import_zod.z.string(),
+  color: import_zod.z.string().default("#FBBF24"),
+  style: import_zod.z.enum(["straight", "sketch", "double", "wavy"]).default("sketch"),
+  draw_duration_ms: import_zod.z.number().min(100).max(3e3).default(600)
+});
+var HighlightSchema = import_zod.z.object({
+  type: import_zod.z.literal("highlight"),
+  target_block: import_zod.z.string(),
+  color: import_zod.z.string().default("rgba(250, 204, 21, 0.35)"),
+  draw_duration_ms: import_zod.z.number().min(100).max(3e3).default(500)
+});
+var PulseSchema = import_zod.z.object({
+  type: import_zod.z.literal("pulse"),
+  target_block: import_zod.z.string(),
+  count: import_zod.z.number().int().min(1).max(5).default(2),
+  intensity: import_zod.z.enum(["subtle", "normal", "strong"]).default("normal")
+});
+var CalloutSchema = import_zod.z.object({
+  type: import_zod.z.literal("callout"),
+  from_block: import_zod.z.string(),
+  to_block: import_zod.z.string(),
+  label: import_zod.z.string().max(120).optional(),
+  curve: import_zod.z.enum(["straight", "curved", "zigzag"]).default("curved")
+});
+var GhostReferenceSchema = import_zod.z.object({
+  type: import_zod.z.literal("ghost_reference"),
+  target_page: import_zod.z.number().int().min(1),
+  target_block: import_zod.z.string(),
+  position: import_zod.z.enum(["top-right", "top-left", "bottom-right", "bottom-left"]).default("top-right")
+});
+var BoxSchema = import_zod.z.object({
+  type: import_zod.z.literal("box"),
+  target_block: import_zod.z.string(),
+  color: import_zod.z.string().default("#3B82F6"),
+  style: import_zod.z.enum(["solid", "dashed"]).default("solid")
+});
+var LabelSchema = import_zod.z.object({
+  type: import_zod.z.literal("label"),
+  target_block: import_zod.z.string(),
+  text: import_zod.z.string().min(1).max(120),
+  position: import_zod.z.enum(["top", "bottom", "left", "right"]).default("top")
+});
+var ClearSchema = import_zod.z.object({
+  type: import_zod.z.literal("clear"),
+  targets: import_zod.z.union([import_zod.z.enum(["all", "spotlights", "overlays"]), import_zod.z.array(import_zod.z.string())]).default("overlays")
+});
+var StoryboardActionSchema = import_zod.z.union([
+  CameraSchema,
+  SpotlightSchema,
+  UnderlineSchema,
+  HighlightSchema,
+  PulseSchema,
+  CalloutSchema,
+  GhostReferenceSchema,
+  BoxSchema,
+  LabelSchema,
+  ClearSchema
+]);
+var StoryboardStepSchema = import_zod.z.object({
+  at_ms: import_zod.z.number().min(0).max(5e3).default(0),
+  duration_ms: import_zod.z.number().min(100).max(5e3).default(800),
+  action: StoryboardActionSchema
+});
+var StoryboardSchema = import_zod.z.object({
+  version: import_zod.z.literal(1),
+  reasoning: import_zod.z.string().max(500).default(""),
+  steps: import_zod.z.array(StoryboardStepSchema).min(1).max(4)
+});
+function storyboardJsonSchema(opts = {}) {
+  const { validBlockIds, validCrossPageBlockIds } = opts;
+  const blockIdSchema = validBlockIds && validBlockIds.length > 0 ? { type: ["string", "null"], enum: [...validBlockIds, null] } : { type: ["string", "null"] };
+  const crossPageBlockIdSchema = validCrossPageBlockIds && validCrossPageBlockIds.length > 0 ? {
+    type: ["string", "null"],
+    enum: [...validCrossPageBlockIds, ...validBlockIds ?? [], null]
+  } : blockIdSchema;
+  const actionSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: [
+      "type",
+      "target_block",
+      "target_bbox",
+      "scale",
+      "padding",
+      "easing",
+      "dim_opacity",
+      "feather_px",
+      "shape",
+      "color",
+      "style",
+      "draw_duration_ms",
+      "count",
+      "intensity",
+      "from_block",
+      "to_block",
+      "label",
+      "curve",
+      "target_page",
+      "position",
+      "text",
+      "targets"
+    ],
+    properties: {
+      type: {
+        type: "string",
+        enum: [
+          "camera",
+          "spotlight",
+          "underline",
+          "highlight",
+          "pulse",
+          "callout",
+          "ghost_reference",
+          "box",
+          "label",
+          "clear"
+        ]
+      },
+      target_block: blockIdSchema,
+      target_bbox: {
+        type: ["array", "null"],
+        items: { type: "number" },
+        minItems: 4,
+        maxItems: 4
+      },
+      scale: { type: ["number", "null"] },
+      padding: { type: ["number", "null"] },
+      easing: {
+        type: ["string", "null"],
+        enum: ["linear", "ease-in", "ease-out", "ease-in-out", null]
+      },
+      dim_opacity: { type: ["number", "null"] },
+      feather_px: { type: ["number", "null"] },
+      shape: {
+        type: ["string", "null"],
+        enum: ["rect", "rounded", "ellipse", null]
+      },
+      color: { type: ["string", "null"] },
+      style: {
+        type: ["string", "null"],
+        enum: ["straight", "sketch", "double", "wavy", "solid", "dashed", null]
+      },
+      draw_duration_ms: { type: ["number", "null"] },
+      count: { type: ["integer", "null"] },
+      intensity: {
+        type: ["string", "null"],
+        enum: ["subtle", "normal", "strong", null]
+      },
+      from_block: blockIdSchema,
+      to_block: crossPageBlockIdSchema,
+      label: { type: ["string", "null"] },
+      curve: {
+        type: ["string", "null"],
+        enum: ["straight", "curved", "zigzag", null]
+      },
+      target_page: { type: ["integer", "null"] },
+      position: {
+        type: ["string", "null"],
+        enum: [
+          "top",
+          "bottom",
+          "left",
+          "right",
+          "top-right",
+          "top-left",
+          "bottom-right",
+          "bottom-left",
+          null
+        ]
+      },
+      text: { type: ["string", "null"] },
+      targets: {
+        type: ["string", "null"],
+        enum: ["all", "spotlights", "overlays", null]
+      }
+    }
+  };
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: ["version", "reasoning", "steps"],
+    properties: {
+      version: { type: "integer", enum: [1] },
+      reasoning: { type: "string" },
+      steps: {
+        type: "array",
+        minItems: 1,
+        maxItems: 4,
+        items: {
+          type: "object",
+          additionalProperties: false,
+          required: ["at_ms", "duration_ms", "action"],
+          properties: {
+            at_ms: { type: "number" },
+            duration_ms: { type: "number" },
+            action: actionSchema
+          }
+        }
+      }
+    }
+  };
+}
+
+// src/director/prompts.ts
+var 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.
+
+# Your primary task
+You 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.
+
+Anchoring rules:
+- 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.
+- 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.
+- 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.
+- If multiple blocks match, pick the most specific one, or use a \`callout\` from one to the other.
+
+# Output shape
+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> }, ... ]
+}
+
+# Action shapes \u2014 ALL fields shown are REQUIRED per action type
+- camera:          { "type":"camera", "target_block":"<id>", "scale":1.1, "padding":80, "easing":"ease-out" }
+- spotlight:       { "type":"spotlight", "target_block":"<id>", "dim_opacity":0.65, "feather_px":40, "shape":"rounded" }
+- underline:       { "type":"underline", "target_block":"<id>", "color":"#FBBF24", "style":"sketch", "draw_duration_ms":600 }
+- highlight:       { "type":"highlight", "target_block":"<id>", "color":"rgba(250,204,21,0.35)", "draw_duration_ms":500 }
+- pulse:           { "type":"pulse", "target_block":"<id>", "count":2, "intensity":"normal" }
+- callout:         { "type":"callout", "from_block":"<id>", "to_block":"<id>", "label":"<text>", "curve":"curved" }
+- ghost_reference: { "type":"ghost_reference", "target_page":<int>, "target_block":"<id>", "position":"top-right" }
+- box:             { "type":"box", "target_block":"<id>", "color":"#3B82F6", "style":"solid" }
+- label:           { "type":"label", "target_block":"<id>", "text":"<text>", "position":"top" }
+- clear:           { "type":"clear", "targets":"overlays" }
+
+# When to use each action (match the effect to the narration's intent, not just the block type)
+- 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.
+- spotlight       \u2014 when narration ISOLATES one idea, term, or sentence. Great for definitions, principles, and "the key insight is\u2026" moments.
+- 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.
+- highlight       \u2014 when narration FLAGS a keyword inline without full focus. Cheap, fast, great for list items, definitions-in-context, callback references.
+- 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.
+- 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.
+- 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.
+- 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.
+- 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.
+- clear           \u2014 rarely needed; the engine auto-expires overlays. Use only when you explicitly want to wipe prior state before a new beat.
+
+Respect 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.
+
+# Intent Taxonomy \u2014 canonical "recipes" you should use as your default vocabulary
+When 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.
+
+## define \u2014 the narration introduces or defines a term
+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 } },
+    { "at_ms":900, "duration_ms":1200, "action": { "type":"label", "target_block":"p1_para0", "text":"definition", "position":"top" } }
+  ]
+}
+
+## point_out \u2014 the narration directs the viewer's eye to a figure, diagram, or specific region
+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" } },
+    { "at_ms":900, "duration_ms":1200, "action": { "type":"pulse", "target_block":"p1_fig0", "count":2, "intensity":"normal" } }
+  ]
+}
+
+## compare \u2014 the narration contrasts two things on the page
+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" } },
+    { "at_ms":800, "duration_ms":1000, "action": { "type":"callout", "from_block":"p1_list5", "to_block":"p1_list12", "label":"vs", "curve":"curved" } }
+  ]
+}
+
+## emphasize \u2014 the narration stresses a keyword, warning, or takeaway
+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" } }
+  ]
+}
+
+# Choreography rules
+- 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.
+- 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.
+- 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.
+- 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.
+- 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.
+- 2\u20134 steps is typical; single-step overlays (no camera) are PREFERRED when the target is already visible.
+- 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).
+- 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\`.
+- Output ONLY valid JSON. No markdown, no code fences, no commentary, no trailing whitespace inside property values.
+
+# Forbidden outputs \u2014 these will be rejected:
+- A storyboard with only a camera step.
+- A camera step with scale < 0.5 or > 4.0.
+- target_block values not listed in "Page blocks" or "Cross-page figures index".
+- Tab characters, newlines, or explanatory text inside JSON string values.`;
+function truncate(text, max = 200) {
+  if (!text) return "";
+  if (text.length <= max) return text;
+  const slice = text.slice(0, max);
+  const last = slice.lastIndexOf(" ");
+  return (last > 40 ? slice.slice(0, last) : slice) + "\u2026";
+}
+function buildUserPrompt(input) {
+  const {
+    chunk,
+    pageNumber,
+    page,
+    index,
+    history,
+    camera,
+    activeOverlays,
+    maxSteps = 4
+  } = input;
+  const pageBlocks = page.blocks.map((b) => ({
+    block_id: b.block_id,
+    type: b.type,
+    text: truncate(b.text, 200),
+    bbox: b.bbox,
+    default_action: b.default_action
+  }));
+  const xPageFigures = index.crossPageFigures.filter((f) => f.page !== pageNumber).slice(0, 20).map((f) => ({
+    block_id: f.block_id,
+    page: f.page,
+    type: f.type,
+    text: truncate(f.text, 200)
+  }));
+  const recent = history.slice(-3).map((h) => h.text);
+  const overlaySummary = activeOverlays.map((o) => ({ id: o.id, kind: o.kind }));
+  const blockIdList = pageBlocks.map((b) => b.block_id);
+  return [
+    `Current page: ${pageNumber}`,
+    `Page blocks (${pageBlocks.length}) \u2014 you MUST pick target_block from this list:`,
+    JSON.stringify(pageBlocks),
+    "",
+    `Valid block_ids for this page: ${JSON.stringify(blockIdList)}`,
+    "",
+    `Cross-page figures index: ${JSON.stringify(xPageFigures)}`,
+    "",
+    `Current chunk (what the tutor just said): ${JSON.stringify(chunk)}`,
+    `Recent chunks: ${JSON.stringify(recent)}`,
+    `Current camera: ${JSON.stringify(camera)}`,
+    `Active overlays: ${JSON.stringify(overlaySummary)}`,
+    "",
+    `Max steps: ${maxSteps}`,
+    `Output JSON storyboard. Every target_block MUST be one of the ids above.`
+  ].join("\n");
+}
+
+// src/director/sse-parser.ts
+async function* parseSse(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buffer.indexOf("\n")) !== -1) {
+        const rawLine = buffer.slice(0, idx).trim();
+        buffer = buffer.slice(idx + 1);
+        if (!rawLine.startsWith("data:")) continue;
+        const payload = rawLine.slice(5).trim();
+        if (!payload || payload === "[DONE]") continue;
+        try {
+          yield JSON.parse(payload);
+        } catch {
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function extractDelta(chunk) {
+  if (!chunk || typeof chunk !== "object") return null;
+  const choices = chunk.choices;
+  if (!choices || !choices.length) return null;
+  return choices[0].delta?.content ?? null;
+}
+
+// src/director/llm-director.ts
+async function directStoryboard(config, input) {
+  const {
+    endpointUrl,
+    model,
+    authToken,
+    extraBody,
+    maxTokens = 1024,
+    temperature = 0.3,
+    useJsonSchema = true,
+    stream = false
+  } = config;
+  const userContent = buildUserPrompt(input);
+  const body = {
+    model,
+    stream,
+    temperature,
+    max_tokens: maxTokens,
+    messages: [
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user", content: userContent }
+    ],
+    ...extraBody ?? {}
+  };
+  if (useJsonSchema) {
+    const validBlockIds = input.page.blocks.map((b) => b.block_id);
+    const validCrossPageBlockIds = input.index.crossPageFigures.filter((f) => f.page !== input.pageNumber).map((f) => f.block_id);
+    body.response_format = {
+      type: "json_schema",
+      json_schema: {
+        name: "storyboard",
+        strict: true,
+        schema: storyboardJsonSchema({
+          validBlockIds,
+          validCrossPageBlockIds
+        })
+      }
+    };
+  }
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: stream ? "text/event-stream" : "application/json"
+  };
+  if (authToken) headers.Authorization = `Bearer ${authToken}`;
+  const timeoutController = new AbortController();
+  const timer = setTimeout(
+    () => timeoutController.abort(),
+    input.timeoutMs ?? 2500
+  );
+  const signal = mergeSignals(input.signal, timeoutController.signal);
+  try {
+    const response = await fetch(endpointUrl, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal
+    });
+    if (!response.ok || !response.body) {
+      return {
+        storyboard: null,
+        raw: "",
+        error: `HTTP ${response.status}`
+      };
+    }
+    let raw = "";
+    if (stream && response.body) {
+      for await (const chunk of parseSse(response.body)) {
+        const delta = extractDelta(chunk);
+        if (delta) raw += delta;
+      }
+    } else {
+      const json = await response.json();
+      raw = json.choices?.[0]?.message?.content ?? "";
+    }
+    const stripped = collapseWhitespaceRuns(stripCodeFences(raw).trim());
+    let parsed;
+    try {
+      parsed = JSON.parse(stripped);
+    } catch (e) {
+      return {
+        storyboard: null,
+        raw,
+        error: `parse error: ${e.message}`
+      };
+    }
+    const cleaned = clampNumericRanges(stripNullsDeep(parsed));
+    const validation = StoryboardSchema.safeParse(cleaned);
+    if (validation.success) {
+      return {
+        storyboard: enforceOverlayPresence(validation.data),
+        raw
+      };
+    }
+    const salvaged = salvageStoryboard(cleaned);
+    if (salvaged) {
+      return { storyboard: enforceOverlayPresence(salvaged), raw };
+    }
+    return {
+      storyboard: null,
+      raw,
+      error: `validation failed: ${validation.error.message}`
+    };
+  } catch (e) {
+    const name = e.name;
+    const msg = name === "AbortError" ? "aborted" : e.message;
+    return { storyboard: null, raw: "", error: msg };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function stripCodeFences(s) {
+  const m = s.match(/```(?:json)?\s*([\s\S]*?)```/);
+  return m ? m[1] : s;
+}
+function collapseWhitespaceRuns(src) {
+  let out = "";
+  let inString = false;
+  let escape = false;
+  let run = 0;
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (inString) {
+      out += c;
+      if (escape) {
+        escape = false;
+      } else if (c === "\\") {
+        escape = true;
+      } else if (c === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (c === '"') {
+      out += c;
+      inString = true;
+      run = 0;
+      continue;
+    }
+    if (c === " " || c === "	" || c === "\n" || c === "\r") {
+      run++;
+      if (run <= 1) out += " ";
+      continue;
+    }
+    run = 0;
+    out += c;
+  }
+  return out;
+}
+function clampNumericRanges(input) {
+  if (input === null || input === void 0) return input;
+  if (Array.isArray(input)) return input.map(clampNumericRanges);
+  if (typeof input !== "object") return input;
+  const obj = input;
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    out[k] = clampNumericRanges(v);
+  }
+  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.padding === "number") {
+      out.padding = clamp(out.padding, 0, 400);
+    }
+  }
+  if (typeof out.dim_opacity === "number") {
+    out.dim_opacity = clamp(out.dim_opacity, 0, 1);
+  }
+  if (typeof out.feather_px === "number") {
+    out.feather_px = clamp(out.feather_px, 0, 200);
+  }
+  if (typeof out.draw_duration_ms === "number") {
+    out.draw_duration_ms = clamp(out.draw_duration_ms, 100, 3e3);
+  }
+  if (typeof out.count === "number") {
+    out.count = Math.round(clamp(out.count, 1, 5));
+  }
+  if (typeof out.at_ms === "number") {
+    out.at_ms = clamp(out.at_ms, 0, 5e3);
+  }
+  if (typeof out.duration_ms === "number" && type === void 0) {
+    out.duration_ms = clamp(out.duration_ms, 100, 5e3);
+  }
+  return out;
+}
+function clamp(v, lo, hi) {
+  return Math.min(hi, Math.max(lo, v));
+}
+function enforceOverlayPresence(sb) {
+  if (sb.steps.length === 0) return sb;
+  const hasOverlay = sb.steps.some(
+    (s) => s.action.type !== "camera" && s.action.type !== "clear"
+  );
+  if (hasOverlay) return sb;
+  const cameraStep = sb.steps.find((s) => s.action.type === "camera");
+  if (!cameraStep || cameraStep.action.type !== "camera") return sb;
+  const target = cameraStep.action.target_block;
+  if (!target) return sb;
+  return {
+    ...sb,
+    reasoning: `${sb.reasoning} [auto-appended pulse: camera-only storyboards are forbidden]`,
+    steps: [
+      ...sb.steps,
+      {
+        at_ms: Math.min(4800, (cameraStep.at_ms ?? 0) + 200),
+        duration_ms: 900,
+        action: {
+          type: "pulse",
+          target_block: target,
+          count: 2,
+          intensity: "normal"
+        }
+      }
+    ]
+  };
+}
+function stripNullsDeep(input) {
+  if (input === null) return void 0;
+  if (Array.isArray(input)) {
+    return input.map(stripNullsDeep).filter((v) => v !== void 0);
+  }
+  if (input && typeof input === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+      const cleaned = stripNullsDeep(v);
+      if (cleaned !== void 0) out[k] = cleaned;
+    }
+    return out;
+  }
+  return input;
+}
+function salvageStoryboard(parsed) {
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed;
+  if (!Array.isArray(obj.steps)) return null;
+  const goodSteps = [];
+  for (const step of obj.steps) {
+    const r = StoryboardStepSchema.safeParse(step);
+    if (r.success) goodSteps.push(r.data);
+    if (goodSteps.length >= 4) break;
+  }
+  if (goodSteps.length === 0) return null;
+  return {
+    version: 1,
+    reasoning: typeof obj.reasoning === "string" ? obj.reasoning + " (salvaged)" : "salvaged",
+    steps: goodSteps
+  };
+}
+function mergeSignals(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  const ctrl = new AbortController();
+  const onAbort = () => ctrl.abort();
+  a.addEventListener("abort", onAbort);
+  b.addEventListener("abort", onAbort);
+  return ctrl.signal;
+}
+
+// src/director/embedding-fallback.ts
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom === 0 ? 0 : dot / denom;
+}
+async function matchChunkToBlock(chunk, page, provider) {
+  const textBlocks = page.blocks.filter(
+    (b) => typeof b.text === "string" && b.text.trim().length > 0
+  );
+  if (textBlocks.length === 0) return null;
+  const inputs = [chunk, ...textBlocks.map((b) => b.text)];
+  const embeds = await provider.embed(inputs);
+  if (embeds.length < 2) return null;
+  const chunkEmbed = embeds[0];
+  let best = null;
+  for (let i = 0; i < textBlocks.length; i++) {
+    const score = cosineSimilarity(chunkEmbed, embeds[i + 1]);
+    if (!best || score > best.score) best = { block: textBlocks[i], score };
+  }
+  return best;
+}
+function nearestFigureOnPage(caption, page) {
+  if (!page) return null;
+  const [cx1, cy1, cx2, cy2] = caption.bbox;
+  const ccx = (cx1 + cx2) / 2;
+  const ccy = (cy1 + cy2) / 2;
+  let best = null;
+  for (const b of page.blocks) {
+    if (b.block_id === caption.block_id) continue;
+    if (b.type !== "figure" && b.type !== "figure_region") continue;
+    const [x1, y1, x2, y2] = b.bbox;
+    const fx = (x1 + x2) / 2;
+    const fy = (y1 + y2) / 2;
+    const dist = Math.hypot(fx - ccx, fy - ccy);
+    if (!best || dist < best.dist) best = { block: b, dist };
+  }
+  return best?.block ?? null;
+}
+function truncateLabel(text, max) {
+  if (!text) return "";
+  const clean = text.replace(/\s+/g, " ").trim();
+  if (clean.length <= max) return clean;
+  return clean.slice(0, max - 1) + "\u2026";
+}
+function storyboardFromMatch(match, page) {
+  if (!match) {
+    return {
+      version: 1,
+      reasoning: "fallback: no match \u2014 clearing overlays",
+      steps: [
+        {
+          at_ms: 0,
+          duration_ms: 800,
+          action: { type: "clear", targets: "overlays" }
+        }
+      ]
+    };
+  }
+  const { block } = match;
+  const id = block.block_id;
+  const reason = `fallback (block.type=${block.type}): matched ${id} (${match.score.toFixed(2)})`;
+  switch (block.type) {
+    case "heading": {
+      return {
+        version: 1,
+        reasoning: reason,
+        steps: [
+          {
+            at_ms: 0,
+            duration_ms: 700,
+            action: {
+              type: "spotlight",
+              target_block: id,
+              dim_opacity: 0.6,
+              feather_px: 40,
+              shape: "rounded"
+            }
+          },
+          {
+            at_ms: 300,
+            duration_ms: 1200,
+            action: {
+              type: "label",
+              target_block: id,
+              text: truncateLabel(block.text, 32) || "section",
+              position: "top"
+            }
+          }
+        ]
+      };
+    }
+    case "paragraph": {
+      return {
+        version: 1,
+        reasoning: reason,
+        steps: [
+          {
+            at_ms: 0,
+            duration_ms: 600,
+            action: {
+              type: "camera",
+              target_block: id,
+              scale: 1.1,
+              padding: 80,
+              easing: "ease-out"
+            }
+          },
+          {
+            at_ms: 300,
+            duration_ms: 900,
+            action: {
+              type: "underline",
+              target_block: id,
+              color: "#FBBF24",
+              style: "sketch",
+              draw_duration_ms: 800
+            }
+          }
+        ]
+      };
+    }
+    case "list_item":
+    case "mcq_option": {
+      return {
+        version: 1,
+        reasoning: reason,
+        steps: [
+          {
+            at_ms: 0,
+            duration_ms: 500,
+            action: {
+              type: "highlight",
+              target_block: id,
+              color: "rgba(250, 204, 21, 0.35)",
+              draw_duration_ms: 450
+            }
+          }
+        ]
+      };
+    }
+    case "caption": {
+      const figure = nearestFigureOnPage(block, page);
+      if (figure) {
+        return {
+          version: 1,
+          reasoning: `${reason}; caption \u2192 figure ${figure.block_id}`,
+          steps: [
+            {
+              at_ms: 0,
+              duration_ms: 900,
+              action: {
+                type: "callout",
+                from_block: id,
+                to_block: figure.block_id,
+                label: "see",
+                curve: "curved"
+              }
+            },
+            {
+              at_ms: 600,
+              duration_ms: 1e3,
+              action: {
+                type: "pulse",
+                target_block: figure.block_id,
+                count: 2,
+                intensity: "normal"
+              }
+            }
+          ]
+        };
+      }
+      return {
+        version: 1,
+        reasoning: `${reason}; no figure on page, underlining caption`,
+        steps: [
+          {
+            at_ms: 0,
+            duration_ms: 800,
+            action: {
+              type: "underline",
+              target_block: id,
+              color: "#FBBF24",
+              style: "sketch",
+              draw_duration_ms: 700
+            }
+          }
+        ]
+      };
+    }
+    case "figure": {
+      return {
+        version: 1,
+        reasoning: reason,
+        steps: [
+          {
+            at_ms: 0,
+            duration_ms: 900,
+            action: {
+              type: "pulse",
+              target_block: id,
+              count: 2,
+              intensity: "strong"
+            }
+          },
+          {
+            at_ms: 400,
+            duration_ms: 1200,
+            action: {
+              type: "box",
+              target_block: id,
+              color: "#3B82F6",
+              style: "solid"
+            }
+          }
+        ]
+      };
+    }
+    case "figure_region": {
+      return {
+        version: 1,
+        reasoning: reason,
+        steps: [
+          {
+            at_ms: 0,
+            duration_ms: 900,
+            action: {
+              type: "pulse",
+              target_block: id,
+              count: 2,
+              intensity: "normal"
+            }
+          }
+        ]
+      };
+    }
+    case "table": {
+      return {
+        version: 1,
+        reasoning: reason,
+        steps: [
+          {
+            at_ms: 0,
+            duration_ms: 700,
+            action: {
+              type: "camera",
+              target_block: id,
+              scale: 1.2,
+              padding: 60,
+              easing: "ease-out"
+            }
+          },
+          {
+            at_ms: 300,
+            duration_ms: 1e3,
+            action: {
+              type: "box",
+              target_block: id,
+              color: "#3B82F6",
+              style: "dashed"
+            }
+          }
+        ]
+      };
+    }
+    default: {
+      return {
+        version: 1,
+        reasoning: `${reason}; unknown block.type, using highlight`,
+        steps: [
+          {
+            at_ms: 0,
+            duration_ms: 600,
+            action: {
+              type: "highlight",
+              target_block: id,
+              color: "rgba(250, 204, 21, 0.35)",
+              draw_duration_ms: 500
+            }
+          }
+        ]
+      };
+    }
+  }
+}
+
+// src/components/TutorMode/TutorModeContainer.tsx
+var import_jsx_runtime52 = require("react/jsx-runtime");
+function buildBBoxIndex(bboxData) {
+  const byPage = /* @__PURE__ */ new Map();
+  const blockById = /* @__PURE__ */ new Map();
+  const crossPageFigures = [];
+  for (const page of bboxData) {
+    byPage.set(page.page_number, page);
+    for (const block of page.blocks) {
+      blockById.set(block.block_id, { block, pageNumber: page.page_number });
+      if ((block.type === "figure" || block.type === "figure_region" || block.type === "caption") && typeof block.text === "string" && block.text.length > 0) {
+        crossPageFigures.push({
+          block_id: block.block_id,
+          page: page.page_number,
+          type: block.type,
+          text: block.text
+        });
+      }
+    }
+  }
+  return { byPage, blockById, crossPageFigures };
+}
+function TutorModeContainer({
+  pageNumber,
+  bboxData,
+  narrationStore,
+  scale,
+  rotation = 0,
+  currentChunk,
+  llm,
+  idleTimeoutMs = 5e3,
+  llmTimeoutMs = 3e4,
+  embeddingProvider,
+  showSubtitles = false,
+  showExitButton = true,
+  onExitTutorMode,
+  minOverlayDurationMs,
+  backgroundColor = "#ffffff",
+  loadingComponent,
+  className
+}) {
+  const containerRef = (0, import_react56.useRef)(null);
+  const index = (0, import_react56.useMemo)(() => buildBBoxIndex(bboxData), [bboxData]);
+  const { document: document2 } = usePDFViewer();
+  const [pageProxy, setPageProxy] = (0, import_react56.useState)(null);
+  const [viewport, setViewport] = (0, import_react56.useState)({ width: 800, height: 1e3 });
+  const camera = (0, import_zustand2.useStore)(narrationStore, (s) => s.camera);
+  const activeOverlays = (0, import_zustand2.useStore)(narrationStore, (s) => s.activeOverlays);
+  (0, import_react56.useEffect)(() => {
+    if (!containerRef.current) return;
+    const el = containerRef.current;
+    const update = () => setViewport({ width: el.clientWidth, height: el.clientHeight });
+    update();
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+  (0, import_react56.useEffect)(() => {
+    if (!document2) {
+      setPageProxy(null);
+      return;
+    }
+    let cancelled = false;
+    document2.getPage(pageNumber).then((p) => {
+      if (!cancelled) setPageProxy(p);
+    }).catch(() => {
+      if (!cancelled) setPageProxy(null);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [document2, pageNumber]);
+  (0, import_react56.useEffect)(() => {
+    narrationStore.getState().setCurrentPage(pageNumber);
+  }, [pageNumber, narrationStore]);
+  (0, import_react56.useEffect)(() => {
+    const page2 = index.byPage.get(pageNumber);
+    if (!page2) return;
+    if (viewport.width === 0 || viewport.height === 0) return;
+    if (narrationStore.getState().activeOverlays.length > 0) return;
+    const fit = Math.min(
+      viewport.width / page2.page_dimensions.width,
+      viewport.height / page2.page_dimensions.height
+    ) * 0.95;
+    narrationStore.getState().setCamera({ scale: fit, x: 0, y: 0 });
+  }, [pageNumber, viewport, index, narrationStore]);
+  const engineRef = (0, import_react56.useRef)(null);
+  (0, import_react56.useEffect)(() => {
+    engineRef.current = new StoryboardEngine({
+      narrationStore,
+      bboxIndex: index,
+      getViewport: () => viewport,
+      minOverlayDurationMs
+    });
+    return () => engineRef.current?.cancelPending();
+  }, [narrationStore, index, viewport, minOverlayDurationMs]);
+  const abortRef = (0, import_react56.useRef)(null);
+  const debounceRef = (0, import_react56.useRef)(null);
+  const lastChunkRef = (0, import_react56.useRef)(null);
+  (0, import_react56.useEffect)(() => {
+    if (!llm) return;
+    if (!currentChunk || currentChunk === lastChunkRef.current) return;
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+    debounceRef.current = setTimeout(async () => {
+      const chunk = currentChunk;
+      if (chunk === lastChunkRef.current) return;
+      lastChunkRef.current = chunk;
+      const page2 = index.byPage.get(pageNumber);
+      if (!page2) return;
+      narrationStore.getState().pushChunkHistory({
+        text: chunk,
+        pageNumber,
+        timestamp: Date.now()
+      });
+      narrationStore.getState().appendDebugEvent({
+        kind: "chunk",
+        summary: `chunk \u2192 ${chunk.slice(0, 80)}${chunk.length > 80 ? "\u2026" : ""}`,
+        payload: { chunk, pageNumber }
+      });
+      abortRef.current?.abort();
+      abortRef.current = new AbortController();
+      narrationStore.getState().setLlmStatus("in-flight");
+      narrationStore.getState().appendDebugEvent({
+        kind: "llm-request",
+        summary: `LLM ${llm.model} (page ${pageNumber}, ${page2.blocks.length} blocks)`,
+        payload: { model: llm.model, pageNumber, blockCount: page2.blocks.length }
+      });
+      const result = await directStoryboard(llm, {
+        chunk,
+        pageNumber,
+        page: page2,
+        index,
+        history: narrationStore.getState().chunkHistory,
+        camera: narrationStore.getState().camera,
+        activeOverlays: narrationStore.getState().activeOverlays,
+        signal: abortRef.current.signal,
+        timeoutMs: llmTimeoutMs
+      });
+      if (result.storyboard) {
+        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)}`,
+          payload: { raw: result.raw, storyboard: result.storyboard }
+        });
+        engineRef.current?.execute(result.storyboard);
+        narrationStore.getState().appendDebugEvent({
+          kind: "storyboard-execute",
+          summary: `engine executing ${result.storyboard.steps.length} steps`,
+          payload: result.storyboard.steps.map((s) => ({
+            at_ms: s.at_ms,
+            type: s.action.type,
+            target: "target_block" in s.action ? s.action.target_block : "target" in s.action ? s.action.target : void 0
+          }))
+        });
+      } else {
+        narrationStore.getState().setLlmStatus("failed", result.error ?? "unknown");
+        narrationStore.getState().appendDebugEvent({
+          kind: "llm-error",
+          summary: `LLM failed: ${(result.error ?? "unknown").slice(0, 80)}`,
+          payload: { error: result.error, raw: result.raw }
+        });
+        if (embeddingProvider) {
+          try {
+            const match = await matchChunkToBlock(chunk, page2, embeddingProvider);
+            const fallbackSb = storyboardFromMatch(match, page2);
+            narrationStore.getState().appendDebugEvent({
+              kind: "fallback-fired",
+              summary: `embedding fallback \u2192 ${match?.block.block_id ?? "no match"}`,
+              payload: { match, storyboard: fallbackSb }
+            });
+            engineRef.current?.execute(fallbackSb);
+          } catch (e) {
+            narrationStore.getState().appendDebugEvent({
+              kind: "llm-error",
+              summary: `fallback also failed: ${e.message}`,
+              payload: e
+            });
+          }
+        }
+      }
+    }, 200);
+    return () => {
+      if (debounceRef.current) clearTimeout(debounceRef.current);
+    };
+  }, [currentChunk, llm, index, pageNumber, narrationStore, embeddingProvider, llmTimeoutMs]);
+  (0, import_react56.useEffect)(() => {
+    if (!currentChunk) return;
+    const t = setTimeout(() => {
+      if (!engineRef.current) return;
+      const hist = narrationStore.getState().chunkHistory;
+      const latest = hist.length > 0 ? hist[hist.length - 1] : null;
+      if (!latest) return;
+      if (Date.now() - latest.timestamp < idleTimeoutMs) return;
+      engineRef.current.resetVisuals();
+    }, idleTimeoutMs + 100);
+    return () => clearTimeout(t);
+  }, [currentChunk, idleTimeoutMs, narrationStore]);
+  const page = index.byPage.get(pageNumber);
+  const dpiScale = page ? page.page_dimensions.dpi / 72 : 1;
+  const rasterScale = dpiScale * (scale || 1);
+  const baseW = page ? page.page_dimensions.width * (scale || 1) : 0;
+  const baseH = page ? page.page_dimensions.height * (scale || 1) : 0;
+  const isReady = !!page && !!pageProxy;
+  return /* @__PURE__ */ (0, import_jsx_runtime52.jsxs)(
+    "div",
+    {
+      ref: containerRef,
+      className,
+      style: {
+        position: "relative",
+        width: "100%",
+        height: "100%",
+        overflow: "hidden",
+        background: backgroundColor
+      },
+      "data-role": "tutor-mode-container",
+      "data-page-loaded": isReady ? "true" : "false",
+      children: [
+        showExitButton && isReady ? /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(
+          "button",
+          {
+            onClick: () => {
+              engineRef.current?.resetVisuals();
+              onExitTutorMode?.();
+            },
+            style: {
+              position: "absolute",
+              top: 12,
+              right: 12,
+              zIndex: 60,
+              minHeight: 40,
+              minWidth: 40,
+              padding: "8px 14px",
+              border: "none",
+              borderRadius: 8,
+              // Dark translucent pill with white text reads cleanly on both
+              // light and dark container backgrounds.
+              background: "rgba(17,24,39,0.72)",
+              color: "white",
+              cursor: "pointer",
+              fontFamily: "system-ui, sans-serif",
+              fontSize: 14,
+              touchAction: "manipulation"
+            },
+            "aria-label": "Reset view \u2014 clear overlays and fit the page",
+            "data-role": "exit-tutor",
+            children: "Reset view"
+          }
+        ) : null,
+        isReady ? /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(CameraView, { camera, children: /* @__PURE__ */ (0, import_jsx_runtime52.jsxs)(
+          "div",
+          {
+            style: {
+              position: "absolute",
+              top: "50%",
+              left: "50%",
+              width: baseW,
+              height: baseH,
+              transform: "translate(-50%, -50%)"
+            },
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(
+                PDFPage,
+                {
+                  pageNumber,
+                  page: pageProxy,
+                  scale: rasterScale,
+                  rotation,
+                  showTextLayer: false,
+                  showHighlightLayer: false,
+                  showAnnotationLayer: false
+                }
+              ),
+              /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(
+                CinemaLayer,
+                {
+                  page,
+                  index,
+                  overlays: activeOverlays,
+                  scale: scale || 1
+                }
+              )
+            ]
+          }
+        ) }) : /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(TutorLoadingState, { custom: loadingComponent }),
+        showSubtitles ? /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(SubtitleBar, { text: currentChunk ?? null }) : null
+      ]
+    }
+  );
+}
+function TutorLoadingState({
+  custom
+}) {
+  if (custom) {
+    return /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(
+      "div",
+      {
+        style: {
+          position: "absolute",
+          inset: 0,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center"
+        },
+        "data-role": "tutor-loading",
+        children: custom
+      }
+    );
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime52.jsxs)(
+    "div",
+    {
+      style: {
+        position: "absolute",
+        inset: 0,
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "center",
+        gap: 12,
+        color: "rgba(0,0,0,0.55)",
+        fontFamily: "system-ui, sans-serif",
+        fontSize: 13
+      },
+      "data-role": "tutor-loading",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(
+          "div",
+          {
+            "aria-hidden": true,
+            style: {
+              width: 36,
+              height: 36,
+              borderRadius: "50%",
+              border: "3px solid rgba(0,0,0,0.1)",
+              borderTopColor: "rgba(0,0,0,0.45)",
+              animation: "pdf-tutor-spin 0.9s linear infinite"
+            }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime52.jsx)("span", { children: "Loading document\u2026" }),
+        /* @__PURE__ */ (0, import_jsx_runtime52.jsx)("style", { children: `
+        @keyframes pdf-tutor-spin {
+          from { transform: rotate(0deg); }
+          to { transform: rotate(360deg); }
+        }
+      ` })
+      ]
+    }
+  );
+}
+
+// src/director/transformers-embedding.ts
+var loaded = null;
+function getLocalMiniLM() {
+  if (loaded) return loaded;
+  loaded = (async () => {
+    const mod = await import(
+      /* webpackIgnore: true */
+      "@xenova/transformers"
+    );
+    const { pipeline } = mod;
+    const extractor = await pipeline(
+      "feature-extraction",
+      "Xenova/all-MiniLM-L6-v2"
+    );
+    return {
+      async embed(texts) {
+        const out = [];
+        for (const t of texts) {
+          const result = await extractor(t, {
+            pooling: "mean",
+            normalize: true
+          });
+          out.push(new Float32Array(result.data.slice()));
+        }
+        return out;
+      }
+    };
+  })();
+  return loaded;
+}
+
 // src/index.ts
 init_hooks();
 init_store();
@@ -12975,19 +15380,26 @@ init_PluginManager();
 init_utils();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AnimatedHighlight,
+  AnimatedUnderline,
   AnnotationLayer,
   AnnotationToolbar,
   AskAboutOverlay,
   AskAboutTrigger,
   BookModeContainer,
   BookmarksPanel,
+  BoxOverlay,
+  CalloutArrow,
+  CameraView,
   CanvasLayer,
+  CinemaLayer,
   ContinuousScrollContainer,
   DocumentContainer,
   DrawingCanvas,
   DualPageContainer,
   FloatingZoomControls,
   FocusRegionLayer,
+  GhostReference,
   HighlightLayer,
   HighlightPopover,
   HighlightsPanel,
@@ -13004,32 +15416,46 @@ init_utils();
   PDFViewerContext,
   PDFViewerProvider,
   PluginManager,
+  PulseOverlay,
   QuickNoteButton,
   QuickNotePopover,
+  SYSTEM_PROMPT,
   SearchPanel,
   SelectionToolbar,
   ShapePreview,
   ShapeRenderer,
   Sidebar,
+  SpotlightMask,
+  StickyLabel,
   StickyNote,
+  StoryboardActionSchema,
+  StoryboardEngine,
+  StoryboardSchema,
+  SubtitleBar,
   TakeawaysPanel,
   TextLayer,
   ThumbnailPanel,
   Toolbar,
+  TutorModeContainer,
   VirtualizedDocumentContainer,
   applyRotation,
+  buildBBoxIndex,
+  buildUserPrompt,
   clearHighlights,
   clearStudentData,
   cn,
+  cosineSimilarity,
   countTextOnPage,
   createAgentAPI,
   createAgentStore,
   createAnnotationStore,
+  createNarrationStore,
   createPDFViewer,
   createPluginManager,
   createSearchStore,
   createStudentStore,
   createViewerStore,
+  directStoryboard,
   doRectsIntersect,
   downloadAnnotationsAsJSON,
   downloadAnnotationsAsMarkdown,
@@ -13044,6 +15470,7 @@ init_utils();
   generateDocumentId,
   getAllDocumentIds,
   getAllStudentDataDocumentIds,
+  getLocalMiniLM,
   getMetadata,
   getOutline,
   getPage,
@@ -13061,6 +15488,8 @@ init_utils();
   loadDocumentWithCallbacks,
   loadHighlights,
   loadStudentData,
+  makeOverlayId,
+  matchChunkToBlock,
   mergeAdjacentRects,
   pdfToPercent,
   pdfToViewport,
@@ -13073,6 +15502,9 @@ init_utils();
   saveHighlights,
   saveStudentData,
   scaleRect,
+  storyboardFromMatch,
+  storyboardJsonSchema,
+  truncate,
   useAgentContext,
   useAgentStore,
   useAnnotationStore,