pdfjs-reader-core 0.4.1 → 0.4.3

package/dist/index.cjs

@@ -1885,6 +1885,17 @@ function computeCameraForBlock(bbox, page, viewport, opts = {}) {
   const y = (pageCY - blockCY) * scale;
   return { scale, x, y };
 }
+function clampCamera(target, page, viewport) {
+  const pageWScreen = page.width * target.scale;
+  const pageHScreen = page.height * target.scale;
+  const maxOffsetX = Math.max(0, (pageWScreen - viewport.width) / 2);
+  const maxOffsetY = Math.max(0, (pageHScreen - viewport.height) / 2);
+  return {
+    scale: target.scale,
+    x: Math.max(-maxOffsetX, Math.min(maxOffsetX, target.x)),
+    y: Math.max(-maxOffsetY, Math.min(maxOffsetY, target.y))
+  };
+}
 var init_camera_math = __esm({
   "src/utils/camera-math.ts"() {
     "use strict";
@@ -3748,8 +3759,8 @@ var init_PluginManager = __esm({
       /**
        * Get toolbar items by position
        */
-      getToolbarItemsByPosition(position2) {
-        return this.getToolbarItems().filter((item) => item.position === position2);
+      getToolbarItemsByPosition(position) {
+        return this.getToolbarItems().filter((item) => item.position === position);
       }
       /**
        * Get all sidebar panels from all plugins
@@ -4862,7 +4873,7 @@ var init_MobileToolbar = __esm({
       sidebarOpen,
       theme,
       onThemeChange,
-      position: position2 = "bottom",
+      position = "bottom",
       className
     }) {
       const [showMoreMenu, setShowMoreMenu] = (0, import_react17.useState)(false);
@@ -4896,8 +4907,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",
-            position2 === "top" && "top-0 border-b",
-            position2 === "bottom" && "bottom-0 border-t",
+            position === "top" && "top-0 border-b",
+            position === "bottom" && "bottom-0 border-t",
             className
           ),
           children: /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("div", { className: "flex items-center justify-between gap-1", children: [
@@ -5023,7 +5034,7 @@ var init_MobileToolbar = __esm({
                       "bg-white dark:bg-gray-800",
                       "rounded-lg shadow-lg",
                       "border border-gray-200 dark:border-gray-700",
-                      position2 === "bottom" ? "bottom-full mb-2" : "top-full mt-2"
+                      position === "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" }),
@@ -6849,7 +6860,7 @@ var init_AnnotationToolbar = __esm({
       onShapeTypeChange: onShapeTypeChangeProp,
       onColorChange: onColorChangeProp,
       onStrokeWidthChange: onStrokeWidthChangeProp,
-      position: position2 = "top",
+      position = "top",
       className
     }) {
       const storeActiveTool = useAnnotationStore((s) => s.activeAnnotationTool);
@@ -6899,9 +6910,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",
-            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",
+            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",
             !isActive && "opacity-90",
             className
           ),
@@ -8550,7 +8561,7 @@ var init_SelectionToolbar = __esm({
       activeColor = "yellow",
       className
     }) {
-      const [position2, setPosition] = (0, import_react35.useState)({ top: 0, left: 0, visible: false });
+      const [position, 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) {
@@ -8589,7 +8600,7 @@ var init_SelectionToolbar = __esm({
       const handleCopy = (0, import_react35.useCallback)(() => {
         onCopy?.();
       }, [onCopy]);
-      if (!position2.visible || !selection?.text) {
+      if (!position.visible || !selection?.text) {
         return null;
       }
       return /* @__PURE__ */ (0, import_jsx_runtime21.jsxs)(
@@ -8607,8 +8618,8 @@ var init_SelectionToolbar = __esm({
             className
           ),
           style: {
-            top: position2.top,
-            left: position2.left,
+            top: position.top,
+            left: position.left,
             transform: "translateX(-50%)"
           },
           onMouseDown: (e) => {
@@ -8725,7 +8736,7 @@ var init_HighlightPopover = __esm({
     }) {
       const [isEditingComment, setIsEditingComment] = (0, import_react36.useState)(false);
       const [comment, setComment] = (0, import_react36.useState)(highlight?.comment ?? "");
-      const [position2, setPosition] = (0, import_react36.useState)({ top: 0, left: 0, visible: false });
+      const [position, 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)(() => {
@@ -8773,11 +8784,11 @@ var init_HighlightPopover = __esm({
             onClose();
           }
         }
-        if (position2.visible) {
+        if (position.visible) {
           document.addEventListener("mousedown", handleClickOutside);
           return () => document.removeEventListener("mousedown", handleClickOutside);
         }
-      }, [position2.visible, onClose]);
+      }, [position.visible, onClose]);
       (0, import_react36.useEffect)(() => {
         function handleKeyDown(event) {
           if (event.key === "Escape") {
@@ -8789,11 +8800,11 @@ var init_HighlightPopover = __esm({
             }
           }
         }
-        if (position2.visible) {
+        if (position.visible) {
           document.addEventListener("keydown", handleKeyDown);
           return () => document.removeEventListener("keydown", handleKeyDown);
         }
-      }, [position2.visible, isEditingComment, highlight?.comment, onClose]);
+      }, [position.visible, isEditingComment, highlight?.comment, onClose]);
       const handleColorClick = (0, import_react36.useCallback)(
         (color) => {
           if (highlight) {
@@ -8820,7 +8831,7 @@ var init_HighlightPopover = __esm({
           onCopy?.(highlight.text);
         }
       }, [highlight, onCopy]);
-      if (!highlight || !position2.visible) {
+      if (!highlight || !position.visible) {
         return null;
       }
       return /* @__PURE__ */ (0, import_jsx_runtime22.jsxs)(
@@ -8837,8 +8848,8 @@ var init_HighlightPopover = __esm({
             className
           ),
           style: {
-            top: position2.top,
-            left: position2.left,
+            top: position.top,
+            left: position.left,
             transform: "translate(-50%, -100%)",
             width: 280
           },
@@ -10250,7 +10261,7 @@ var init_FloatingZoomControls = __esm({
     init_utils();
     import_jsx_runtime28 = require("react/jsx-runtime");
     FloatingZoomControls = (0, import_react42.memo)(function FloatingZoomControls2({
-      position: position2 = "bottom-right",
+      position = "bottom-right",
       className,
       showFitToWidth = true,
       showFitToPage = false,
@@ -10291,7 +10302,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[position2],
+            positionClasses[position],
             className
           ),
           children: [
@@ -12119,7 +12130,7 @@ var import_jsx_runtime34 = require("react/jsx-runtime");
 var QuickNoteButton = (0, import_react48.memo)(function QuickNoteButton2({
   pageNumber,
   scale,
-  position: position2 = "top-right",
+  position = "top-right",
   onClick,
   className,
   visible = true
@@ -12128,11 +12139,11 @@ var QuickNoteButton = (0, import_react48.memo)(function QuickNoteButton2({
   const handleClick = (0, import_react48.useCallback)(
     (e) => {
       e.stopPropagation();
-      const x = position2 === "top-right" ? 80 : 80;
-      const y = position2 === "top-right" ? 20 : 80;
+      const x = position === "top-right" ? 80 : 80;
+      const y = position === "top-right" ? 20 : 80;
       onClick(pageNumber, x / scale, y / scale);
     },
-    [pageNumber, onClick, position2, scale]
+    [pageNumber, onClick, position, scale]
   );
   if (!visible) {
     return null;
@@ -12153,8 +12164,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",
-        position2 === "top-right" && "top-3 right-3",
-        position2 === "bottom-right" && "bottom-3 right-3",
+        position === "top-right" && "top-3 right-3",
+        position === "bottom-right" && "bottom-3 right-3",
         className
       ),
       title: "Add quick note",
@@ -12180,7 +12191,7 @@ init_utils();
 var import_jsx_runtime35 = require("react/jsx-runtime");
 var QuickNotePopover = (0, import_react49.memo)(function QuickNotePopover2({
   visible,
-  position: position2,
+  position,
   initialContent = "",
   agentLastStatement,
   onSave,
@@ -12190,7 +12201,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)(position2);
+  const [adjustedPosition, setAdjustedPosition] = (0, import_react49.useState)(position);
   (0, import_react49.useEffect)(() => {
     if (visible && textareaRef.current) {
       textareaRef.current.focus();
@@ -12205,7 +12216,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 } = position2;
+    let { x, y } = position;
     if (x + rect.width > window.innerWidth - padding) {
       x = window.innerWidth - rect.width - padding;
     }
@@ -12219,7 +12230,7 @@ var QuickNotePopover = (0, import_react49.memo)(function QuickNotePopover2({
       y = padding;
     }
     setAdjustedPosition({ x, y });
-  }, [position2, visible]);
+  }, [position, visible]);
   const handleSave = (0, import_react49.useCallback)(() => {
     if (content.trim()) {
       onSave(content.trim());
@@ -12336,11 +12347,11 @@ var import_jsx_runtime36 = require("react/jsx-runtime");
 var AskAboutOverlay = (0, import_react50.memo)(function AskAboutOverlay2({
   visible,
   progress,
-  position: position2,
+  position,
   size = 60,
   className
 }) {
-  if (!visible || !position2) {
+  if (!visible || !position) {
     return null;
   }
   const strokeWidth = 4;
@@ -12356,8 +12367,8 @@ var AskAboutOverlay = (0, import_react50.memo)(function AskAboutOverlay2({
         className
       ),
       style: {
-        left: position2.x - size / 2,
-        top: position2.y - size / 2
+        left: position.x - size / 2,
+        top: position.y - size / 2
       },
       children: [
         /* @__PURE__ */ (0, import_jsx_runtime36.jsxs)(
@@ -12445,20 +12456,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: position2,
+  position,
   onConfirm,
   onCancel,
   visible,
   autoHideDelay = 5e3,
   className
 }) {
-  const [adjustedPosition, setAdjustedPosition] = (0, import_react51.useState)(position2);
+  const [adjustedPosition, setAdjustedPosition] = (0, import_react51.useState)(position);
   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 } = position2;
+    let { x, y } = position;
     if (x + rect.width / 2 > window.innerWidth - padding) {
       x = window.innerWidth - rect.width / 2 - padding;
     }
@@ -12466,10 +12477,10 @@ var AskAboutTrigger = (0, import_react51.memo)(function AskAboutTrigger2({
       x = rect.width / 2 + padding;
     }
     if (y + rect.height > window.innerHeight - padding) {
-      y = position2.y - rect.height - 20;
+      y = position.y - rect.height - 20;
     }
     setAdjustedPosition({ x, y });
-  }, [position2, visible]);
+  }, [position, visible]);
   (0, import_react51.useEffect)(() => {
     if (!visible || autoHideDelay === 0) return;
     const timer = setTimeout(onCancel, autoHideDelay);
@@ -13118,7 +13129,7 @@ function withErrorBoundary({ component, ...props }) {
 init_PDFLoadingScreen2();
 
 // src/components/TutorMode/TutorModeContainer.tsx
-var import_react56 = require("react");
+var import_react58 = require("react");
 var import_zustand2 = require("zustand");
 init_PDFPage2();
 init_hooks();
@@ -13158,26 +13169,48 @@ function CameraView({
 }
 
 // src/components/TutorMode/CinemaLayer.tsx
-var import_framer_motion10 = require("framer-motion");
+var import_framer_motion8 = require("framer-motion");
 
 // src/components/TutorMode/SpotlightMask.tsx
 var import_react55 = require("react");
 var import_framer_motion2 = require("framer-motion");
+
+// src/components/TutorMode/tokens.ts
+var INK = "#2a2420";
+var PAPER = "#faf6ec";
+var ACCENT = "#b04a1a";
+var ACCENT_SOFT = "rgba(176, 74, 26, 0.18)";
+var ACCENT_GLOW = "rgba(176, 74, 26, 0.35)";
+var MARKER = "#e6b422";
+var MARKER_SOFT = "rgba(230, 180, 34, 0.38)";
+var SERIF = "'Iowan Old Style', 'Palatino Linotype', Palatino, 'Book Antiqua', 'EB Garamond', 'Hoefler Text', Georgia, serif";
+var EASE_OUT_EXPO = [0.22, 1, 0.36, 1];
+
+// src/components/TutorMode/SpotlightMask.tsx
 var import_jsx_runtime42 = require("react/jsx-runtime");
 function SpotlightMask({
   page,
   bbox,
   action,
-  durationMs = 400
+  durationMs = 500
 }) {
   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;
+  const [rawX1, rawY1, rawX2, rawY2] = bbox;
+  const rawW = Math.max(0, rawX2 - rawX1);
+  const rawH = Math.max(0, rawY2 - rawY1);
+  const pad = Math.min(28, Math.max(10, Math.min(rawW, rawH) * 0.06));
+  const x1 = rawX1 - pad;
+  const y1 = rawY1 - pad;
+  const x2 = rawX2 + pad;
+  const y2 = rawY2 + pad;
+  const w = x2 - x1;
+  const h = y2 - y1;
+  const rx = action.shape === "rounded" ? 14 : action.shape === "ellipse" ? w / 2 : 0;
+  const ry = action.shape === "rounded" ? 14 : action.shape === "ellipse" ? h / 2 : 0;
+  const feather = Math.max(16, action.feather_px);
+  const cx = (x1 + x2) / 2;
+  const cy = (y1 + y2) / 2;
   return /* @__PURE__ */ (0, import_jsx_runtime42.jsxs)(
     "svg",
     {
@@ -13190,7 +13223,8 @@ function SpotlightMask({
         inset: 0,
         pointerEvents: "none",
         width: page.width,
-        height: page.height
+        height: page.height,
+        overflow: "visible"
       },
       "data-role": "spotlight-mask",
       children: [
@@ -13201,8 +13235,8 @@ function SpotlightMask({
             action.shape === "ellipse" ? /* @__PURE__ */ (0, import_jsx_runtime42.jsx)(
               "ellipse",
               {
-                cx: (x1 + x2) / 2,
-                cy: (y1 + y2) / 2,
+                cx,
+                cy,
                 rx: w / 2,
                 ry: h / 2,
                 fill: "black",
@@ -13230,14 +13264,82 @@ function SpotlightMask({
             y: 0,
             width: page.width,
             height: page.height,
-            fill: "black",
+            fill: INK,
             mask: `url(#${maskId})`,
             initial: { fillOpacity: 0 },
             animate: { fillOpacity: action.dim_opacity },
             exit: { fillOpacity: 0 },
-            transition: { duration: durationMs / 1e3, ease: "easeOut" }
+            transition: { duration: durationMs / 1e3, ease: EASE_OUT_EXPO }
           }
-        )
+        ),
+        action.shape === "ellipse" ? /* @__PURE__ */ (0, import_jsx_runtime42.jsx)(
+          import_framer_motion2.motion.ellipse,
+          {
+            cx,
+            cy,
+            rx: w / 2,
+            ry: h / 2,
+            fill: "none",
+            stroke: ACCENT,
+            strokeWidth: 3,
+            initial: { opacity: 0, scale: 1.08 },
+            animate: { opacity: 0.9, scale: 1 },
+            exit: { opacity: 0 },
+            style: { transformOrigin: `${cx}px ${cy}px`, transformBox: "fill-box" },
+            transition: {
+              duration: durationMs / 1e3,
+              delay: 0.15,
+              ease: EASE_OUT_EXPO
+            }
+          }
+        ) : /* @__PURE__ */ (0, import_jsx_runtime42.jsx)(
+          import_framer_motion2.motion.rect,
+          {
+            x: x1,
+            y: y1,
+            width: w,
+            height: h,
+            rx,
+            ry,
+            fill: "none",
+            stroke: ACCENT,
+            strokeWidth: 3,
+            initial: { opacity: 0, scale: 1.04 },
+            animate: { opacity: 0.9, scale: 1 },
+            exit: { opacity: 0 },
+            style: {
+              transformOrigin: `${cx}px ${cy}px`,
+              transformBox: "fill-box"
+            },
+            transition: {
+              duration: durationMs / 1e3,
+              delay: 0.15,
+              ease: EASE_OUT_EXPO
+            }
+          }
+        ),
+        action.shape !== "ellipse" ? /* @__PURE__ */ (0, import_jsx_runtime42.jsx)(
+          import_framer_motion2.motion.rect,
+          {
+            x: x1 - 2,
+            y: y1 - 2,
+            width: w + 4,
+            height: h + 4,
+            rx: rx + 2,
+            ry: ry + 2,
+            fill: "none",
+            stroke: ACCENT_GLOW,
+            strokeWidth: 8,
+            initial: { opacity: 0 },
+            animate: { opacity: 0.6 },
+            exit: { opacity: 0 },
+            transition: {
+              duration: durationMs / 1e3,
+              delay: 0.2,
+              ease: EASE_OUT_EXPO
+            }
+          }
+        ) : null
       ]
     }
   );
@@ -13246,35 +13348,58 @@ function SpotlightMask({
 // src/components/TutorMode/AnimatedUnderline.tsx
 var import_framer_motion3 = require("framer-motion");
 var import_jsx_runtime43 = require("react/jsx-runtime");
+function jitterAt(i) {
+  const h = Math.sin(i * 12.9898) * 43758.5453;
+  return (h - Math.floor(h) - 0.5) * 4;
+}
 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}`;
+  const x1e = x1 - 4;
+  const x2e = x2 + 4;
+  if (style === "straight") {
+    return { primary: `M ${x1e} ${y} L ${x2e} ${y}` };
+  }
+  if (style === "double") {
+    return {
+      primary: `M ${x1e} ${y - 3} L ${x2e} ${y - 3}`,
+      ghost: `M ${x1e} ${y + 3} L ${x2e} ${y + 3}`
+    };
+  }
   if (style === "wavy") {
-    const steps = Math.max(8, Math.floor((x2 - x1) / 18));
-    let d2 = `M ${x1} ${y}`;
+    const len = x2e - x1e;
+    const steps = Math.max(12, Math.floor(len / 10));
+    const amp = 3.2;
+    let d = `M ${x1e} ${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}`;
+      const t = i / steps;
+      const px = x1e + len * t;
+      const py = y + Math.sin(t * Math.PI * 4) * amp;
+      const prevT = (i - 1) / steps;
+      const cpx = x1e + len * (prevT + (t - prevT) / 2);
+      const cpy = y + Math.sin((prevT + (t - prevT) / 2) * Math.PI * 4) * amp;
+      d += ` Q ${cpx} ${cpy} ${px} ${py}`;
     }
-    return d2;
+    return { primary: d };
   }
-  const segs = 6;
-  let d = `M ${x1} ${y}`;
+  const segs = 8;
+  let primary = `M ${x1e} ${y + jitterAt(0)}`;
+  let ghost = `M ${x1e} ${y + jitterAt(100) + 1.5}`;
   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}`;
+    const px = x1e + (x2e - x1e) * i / segs;
+    primary += ` L ${px} ${y + jitterAt(i)}`;
+    ghost += ` L ${px} ${y + jitterAt(i + 100) + 1.5}`;
   }
-  return d;
+  return { primary, ghost };
 }
 function AnimatedUnderline({ bbox, action }) {
   const [x1, , x2, y2] = bbox;
   const y = y2 + 6;
-  const d = pathForStyle(x1, x2, y, action.style);
+  const { primary, ghost } = pathForStyle(x1, x2, y, action.style);
   const duration = action.draw_duration_ms / 1e3;
-  return /* @__PURE__ */ (0, import_jsx_runtime43.jsx)(
+  const stroke = action.color && action.color !== "#FBBF24" ? action.color : ACCENT;
+  const blotX = x2 + 4;
+  const blotY = y;
+  const strokeWeight = action.style === "wavy" ? 3 : 4;
+  return /* @__PURE__ */ (0, import_jsx_runtime43.jsxs)(
     "svg",
     {
       style: {
@@ -13284,50 +13409,148 @@ function AnimatedUnderline({ bbox, action }) {
         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" }
-        }
-      )
+      children: [
+        ghost ? /* @__PURE__ */ (0, import_jsx_runtime43.jsx)(
+          import_framer_motion3.motion.path,
+          {
+            d: ghost,
+            fill: "none",
+            stroke,
+            strokeWidth: strokeWeight - 1.5,
+            strokeLinecap: "round",
+            strokeOpacity: 0.35,
+            initial: { pathLength: 0, opacity: 0 },
+            animate: { pathLength: 1, opacity: 0.55 },
+            exit: { opacity: 0 },
+            transition: { duration, ease: EASE_OUT_EXPO }
+          }
+        ) : null,
+        /* @__PURE__ */ (0, import_jsx_runtime43.jsx)(
+          import_framer_motion3.motion.path,
+          {
+            d: primary,
+            fill: "none",
+            stroke,
+            strokeWidth: strokeWeight,
+            strokeLinecap: "round",
+            strokeLinejoin: "round",
+            initial: { pathLength: 0, opacity: 0 },
+            animate: { pathLength: 1, opacity: 1 },
+            exit: { opacity: 0 },
+            transition: { duration, ease: EASE_OUT_EXPO }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime43.jsx)(
+          import_framer_motion3.motion.circle,
+          {
+            cx: blotX,
+            cy: blotY,
+            r: strokeWeight / 2 + 0.5,
+            fill: stroke,
+            initial: { scale: 0, opacity: 0 },
+            animate: { scale: 1, opacity: 0.9 },
+            exit: { opacity: 0 },
+            style: {
+              transformOrigin: `${blotX}px ${blotY}px`,
+              transformBox: "fill-box"
+            },
+            transition: {
+              duration: 0.25,
+              delay: duration - 0.1,
+              ease: EASE_OUT_EXPO
+            }
+          }
+        )
+      ]
     }
   );
 }
 
 // src/components/TutorMode/AnimatedHighlight.tsx
+var import_react56 = require("react");
 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,
+  const h = Math.max(1, y2 - y1);
+  const bleed = Math.min(4, h * 0.12);
+  const yTop = y1 - bleed;
+  const yBot = y2 + bleed;
+  const height = yBot - yTop;
+  const duration = action.draw_duration_ms / 1e3;
+  const filterId = (0, import_react56.useId)();
+  const fill = action.color && action.color !== "rgba(250, 204, 21, 0.35)" && action.color !== "rgba(250,204,21,0.35)" ? action.color : MARKER_SOFT;
+  const inner = action.color && action.color !== "rgba(250, 204, 21, 0.35)" && action.color !== "rgba(250,204,21,0.35)" ? action.color : MARKER;
+  const taper = Math.min(6, h * 0.2);
+  const pathD = `
+    M ${x1 - 2} ${yTop + taper}
+    L ${x1 + 2} ${yTop}
+    L ${x2 - 2} ${yTop}
+    L ${x2 + 2} ${yTop + taper}
+    L ${x2 + 2} ${yBot - taper}
+    L ${x2 - 2} ${yBot}
+    L ${x1 + 2} ${yBot}
+    L ${x1 - 2} ${yBot - taper}
+    Z
+  `;
+  return /* @__PURE__ */ (0, import_jsx_runtime44.jsxs)(
+    "svg",
     {
       style: {
         position: "absolute",
-        left: x1,
-        top: y1,
-        height: h,
-        background: action.color,
-        borderRadius: 4,
-        mixBlendMode: "multiply",
-        transformOrigin: "0% 50%",
-        pointerEvents: "none"
+        inset: 0,
+        pointerEvents: "none",
+        overflow: "visible",
+        mixBlendMode: "multiply"
       },
-      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"
+      "data-role": "highlight",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime44.jsx)("defs", { children: /* @__PURE__ */ (0, import_jsx_runtime44.jsxs)("filter", { id: filterId, children: [
+          /* @__PURE__ */ (0, import_jsx_runtime44.jsx)(
+            "feTurbulence",
+            {
+              type: "fractalNoise",
+              baseFrequency: "1.6",
+              numOctaves: "1",
+              seed: 3,
+              result: "noise"
+            }
+          ),
+          /* @__PURE__ */ (0, import_jsx_runtime44.jsx)("feDisplacementMap", { in: "SourceGraphic", in2: "noise", scale: 1.4 })
+        ] }) }),
+        /* @__PURE__ */ (0, import_jsx_runtime44.jsxs)(
+          import_framer_motion4.motion.g,
+          {
+            initial: { clipPath: `inset(0 100% 0 0)` },
+            animate: { clipPath: `inset(0 0% 0 0)` },
+            exit: { opacity: 0 },
+            transition: { duration, ease: EASE_OUT_EXPO },
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime44.jsx)(
+                "path",
+                {
+                  d: pathD,
+                  fill,
+                  opacity: 0.85,
+                  filter: `url(#${filterId})`
+                }
+              ),
+              /* @__PURE__ */ (0, import_jsx_runtime44.jsx)(
+                "rect",
+                {
+                  x: x1 - 1,
+                  y: y1 - bleed * 0.4,
+                  width: x2 - x1 + 2,
+                  height: height - bleed * 0.8,
+                  fill: inner,
+                  opacity: 0.5,
+                  filter: `url(#${filterId})`
+                }
+              )
+            ]
+          }
+        )
+      ]
     }
   );
 }
@@ -13336,66 +13559,214 @@ function AnimatedHighlight({ bbox, action }) {
 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)" }
+  subtle: { bracketLen: 14, strokeWeight: 2, coreOpacity: 0.5, ringScale: 1.08 },
+  normal: { bracketLen: 20, strokeWeight: 2.5, coreOpacity: 0.75, ringScale: 1.14 },
+  strong: { bracketLen: 26, strokeWeight: 3, coreOpacity: 1, ringScale: 1.22 }
 };
 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,
+  const w = Math.max(1, x2 - x1);
+  const h = Math.max(1, y2 - y1);
+  const cx = (x1 + x2) / 2;
+  const cy = (y1 + y2) / 2;
+  const spec = INTENSITY[action.intensity] ?? INTENSITY.normal;
+  const L = Math.min(spec.bracketLen, Math.min(w, h) / 2.5);
+  const PAD = 6;
+  return /* @__PURE__ */ (0, import_jsx_runtime45.jsxs)(
+    "svg",
     {
       style: {
         position: "absolute",
-        left: x1,
-        top: y1,
-        width: x2 - x1,
-        height: y2 - y1,
-        border,
-        borderRadius: 8,
+        inset: 0,
         pointerEvents: "none",
-        boxSizing: "border-box"
-      },
-      animate: { scale: [1, scale, 1] },
-      transition: {
-        duration: 1.2,
-        times: [0, 0.5, 1],
-        ease: "easeInOut",
-        repeat,
-        repeatType: "loop"
+        overflow: "visible"
       },
+      "data-role": "pulse",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(
+          import_framer_motion5.motion.ellipse,
+          {
+            cx,
+            cy,
+            rx: w / 2 + 10,
+            ry: h / 2 + 10,
+            fill: ACCENT_GLOW,
+            style: {
+              transformOrigin: `${cx}px ${cy}px`,
+              transformBox: "fill-box",
+              filter: "blur(16px)"
+            },
+            initial: { opacity: 0, scale: 0.95 },
+            animate: {
+              opacity: [0, spec.coreOpacity * 0.45, 0.15],
+              scale: [0.95, spec.ringScale, 1]
+            },
+            exit: { opacity: 0 },
+            transition: {
+              duration: 1.3,
+              times: [0, 0.5, 1],
+              ease: EASE_OUT_EXPO
+            }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(
+          Bracket,
+          {
+            originX: x1 - PAD,
+            originY: y1 - PAD,
+            direction: "tl",
+            length: L,
+            weight: spec.strokeWeight,
+            delay: 0
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(
+          Bracket,
+          {
+            originX: x2 + PAD,
+            originY: y1 - PAD,
+            direction: "tr",
+            length: L,
+            weight: spec.strokeWeight,
+            delay: 0.04
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(
+          Bracket,
+          {
+            originX: x1 - PAD,
+            originY: y2 + PAD,
+            direction: "bl",
+            length: L,
+            weight: spec.strokeWeight,
+            delay: 0.08
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(
+          Bracket,
+          {
+            originX: x2 + PAD,
+            originY: y2 + PAD,
+            direction: "br",
+            length: L,
+            weight: spec.strokeWeight,
+            delay: 0.12
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(
+          import_framer_motion5.motion.rect,
+          {
+            x: x1 - PAD,
+            y: y1 - PAD,
+            width: w + PAD * 2,
+            height: h + PAD * 2,
+            fill: "none",
+            stroke: ACCENT,
+            strokeWidth: 1,
+            rx: 4,
+            style: {
+              transformOrigin: `${cx}px ${cy}px`,
+              transformBox: "fill-box"
+            },
+            initial: { scale: 1, opacity: 0 },
+            animate: {
+              scale: [1, spec.ringScale, 1],
+              opacity: [0, spec.coreOpacity * 0.5, 0]
+            },
+            exit: { opacity: 0 },
+            transition: {
+              duration: 1.3,
+              times: [0, 0.5, 1],
+              ease: EASE_OUT_EXPO,
+              delay: 0.2
+            }
+          }
+        )
+      ]
+    }
+  );
+}
+function Bracket({
+  originX,
+  originY,
+  direction,
+  length,
+  weight,
+  delay
+}) {
+  const xSign = direction === "tl" || direction === "bl" ? 1 : -1;
+  const ySign = direction === "tl" || direction === "tr" ? 1 : -1;
+  const d = `
+    M ${originX + xSign * length} ${originY}
+    L ${originX} ${originY}
+    L ${originX} ${originY + ySign * length}
+  `;
+  const slideX = -xSign * 8;
+  const slideY = -ySign * 8;
+  return /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(
+    import_framer_motion5.motion.path,
+    {
+      d,
+      fill: "none",
+      stroke: ACCENT,
+      strokeWidth: weight,
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      initial: { opacity: 0, x: slideX, y: slideY },
+      animate: { opacity: 1, x: 0, y: 0 },
       exit: { opacity: 0 },
-      "data-role": "pulse"
+      transition: {
+        duration: 0.4,
+        delay,
+        ease: EASE_OUT_EXPO
+      }
     }
   );
 }
 
 // src/components/TutorMode/CalloutArrow.tsx
+var import_react57 = require("react");
 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) {
+function edgePoints(fromBbox, toBbox) {
   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}`;
+  const len = Math.hypot(dx, dy) || 1;
+  const ux = dx / len;
+  const uy = dy / len;
+  const aHalfW = (fromBbox[2] - fromBbox[0]) / 2;
+  const aHalfH = (fromBbox[3] - fromBbox[1]) / 2;
+  const bHalfW = (toBbox[2] - toBbox[0]) / 2;
+  const bHalfH = (toBbox[3] - toBbox[1]) / 2;
+  const aOff = Math.min(Math.max(aHalfW, aHalfH), 60);
+  const bOff = Math.min(Math.max(bHalfW, bHalfH), 60);
+  return {
+    from: { x: a.x + ux * aOff, y: a.y + uy * aOff },
+    to: { x: b.x - ux * bOff, y: b.y - uy * bOff }
+  };
+}
+function arrowPath(from, to, curve) {
+  if (curve === "straight") return `M ${from.x} ${from.y} L ${to.x} ${to.y}`;
+  if (curve === "zigzag") {
+    const mx = (from.x + to.x) / 2;
+    return `M ${from.x} ${from.y} L ${mx} ${from.y} L ${mx} ${to.y} L ${to.x} ${to.y}`;
+  }
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const cx = (from.x + to.x) / 2 - dy * 0.22;
+  const cy = (from.y + to.y) / 2 + dx * 0.22;
+  return `M ${from.x} ${from.y} Q ${cx} ${cy} ${to.x} ${to.y}`;
 }
 function CalloutArrow({ fromBbox, toBbox, action }) {
-  const d = arrowPath(fromBbox, toBbox, action.curve);
-  const label = action.label;
-  const target = centerOf(toBbox);
+  const markerId = (0, import_react57.useId)();
+  const glowId = `${markerId}-glow`;
+  const { from, to } = edgePoints(fromBbox, toBbox);
+  const d = arrowPath(from, to, action.curve);
   return /* @__PURE__ */ (0, import_jsx_runtime46.jsxs)(
     "svg",
     {
@@ -13407,247 +13778,142 @@ function CalloutArrow({ fromBbox, toBbox, action }) {
       },
       "data-role": "callout",
       children: [
-        /* @__PURE__ */ (0, import_jsx_runtime46.jsx)("defs", { children: /* @__PURE__ */ (0, import_jsx_runtime46.jsx)(
-          "marker",
+        /* @__PURE__ */ (0, import_jsx_runtime46.jsxs)("defs", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime46.jsx)(
+            "marker",
+            {
+              id: markerId,
+              viewBox: "0 0 12 10",
+              refX: 10,
+              refY: 5,
+              markerWidth: 10,
+              markerHeight: 10,
+              orient: "auto",
+              children: /* @__PURE__ */ (0, import_jsx_runtime46.jsx)(
+                "path",
+                {
+                  d: "M 1 1 L 10 5 L 1 9",
+                  fill: "none",
+                  stroke: ACCENT,
+                  strokeWidth: 1.8,
+                  strokeLinecap: "round",
+                  strokeLinejoin: "round"
+                }
+              )
+            }
+          ),
+          /* @__PURE__ */ (0, import_jsx_runtime46.jsx)("filter", { id: glowId, x: "-20%", y: "-20%", width: "140%", height: "140%", children: /* @__PURE__ */ (0, import_jsx_runtime46.jsx)("feGaussianBlur", { stdDeviation: "2.5" }) })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime46.jsx)(
+          import_framer_motion6.motion.circle,
+          {
+            cx: from.x,
+            cy: from.y,
+            r: 4,
+            fill: ACCENT,
+            initial: { scale: 0, opacity: 0 },
+            animate: { scale: 1, opacity: 1 },
+            exit: { opacity: 0 },
+            style: {
+              transformOrigin: `${from.x}px ${from.y}px`,
+              transformBox: "fill-box"
+            },
+            transition: { duration: 0.3, ease: EASE_OUT_EXPO }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime46.jsx)(
+          import_framer_motion6.motion.circle,
           {
-            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" })
+            cx: from.x,
+            cy: from.y,
+            r: 7,
+            fill: "none",
+            stroke: ACCENT,
+            strokeWidth: 1.2,
+            strokeOpacity: 0.4,
+            initial: { scale: 0, opacity: 0 },
+            animate: { scale: 1, opacity: 0.5 },
+            exit: { opacity: 0 },
+            style: {
+              transformOrigin: `${from.x}px ${from.y}px`,
+              transformBox: "fill-box"
+            },
+            transition: { duration: 0.4, delay: 0.08, ease: EASE_OUT_EXPO }
           }
-        ) }),
+        ),
         /* @__PURE__ */ (0, import_jsx_runtime46.jsx)(
           import_framer_motion6.motion.path,
           {
             d,
             fill: "none",
-            stroke: "#3B82F6",
-            strokeWidth: 3,
+            stroke: ACCENT,
+            strokeWidth: 6,
+            strokeOpacity: 0.18,
             strokeLinecap: "round",
-            markerEnd: "url(#arrowhead)",
+            filter: `url(#${glowId})`,
             initial: { pathLength: 0, opacity: 0 },
-            animate: { pathLength: 1, opacity: 1 },
+            animate: { pathLength: 1, opacity: 0.8 },
             exit: { opacity: 0 },
-            transition: { duration: 0.6, ease: "easeOut" }
+            transition: { duration: 0.7, delay: 0.12, ease: EASE_OUT_EXPO }
           }
         ),
-        label ? /* @__PURE__ */ (0, import_jsx_runtime46.jsxs)(
-          import_framer_motion6.motion.g,
+        /* @__PURE__ */ (0, import_jsx_runtime46.jsx)(
+          import_framer_motion6.motion.path,
           {
-            initial: { opacity: 0 },
-            animate: { opacity: 1 },
+            d,
+            fill: "none",
+            stroke: ACCENT,
+            strokeWidth: 2.4,
+            strokeLinecap: "round",
+            strokeLinejoin: "round",
+            markerEnd: `url(#${markerId})`,
+            initial: { pathLength: 0, opacity: 0 },
+            animate: { pathLength: 1, 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
-                }
-              )
-            ]
+            transition: { duration: 0.7, delay: 0.15, ease: EASE_OUT_EXPO }
           }
-        ) : null
+        )
       ]
     }
   );
 }
 
-// src/components/TutorMode/GhostReference.tsx
+// src/components/TutorMode/BoxOverlay.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)(
+function BoxOverlay({ bbox, action }) {
+  const [x1, y1, x2, y2] = bbox;
+  const useSystem = !action.color || action.color === "#3B82F6" || action.color === "#3b82f6";
+  const borderColor = useSystem ? ACCENT : action.color;
+  const washColor = useSystem ? ACCENT_SOFT : void 0;
+  return /* @__PURE__ */ (0, import_jsx_runtime47.jsx)(
     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" },
+      initial: { opacity: 0, scale: 0.98 },
+      animate: { opacity: 1, scale: 1 },
+      exit: { opacity: 0 },
+      transition: { duration: 0.45, ease: EASE_OUT_EXPO },
       style: {
         position: "absolute",
-        width,
-        background: "#111",
-        color: "white",
-        borderRadius: 12,
-        padding: 12,
-        boxShadow: "0 10px 40px rgba(0,0,0,0.5)",
+        left: x1 - 3,
+        top: y1 - 3,
+        width: x2 - x1 + 6,
+        height: y2 - y1 + 6,
+        border: `${action.style === "dashed" ? "2px dashed" : "2px solid"} ${borderColor}`,
+        borderRadius: 4,
+        background: washColor,
         pointerEvents: "none",
-        fontFamily: "system-ui, sans-serif",
-        fontSize: 13,
-        ...POSITIONS[action.position]
+        boxSizing: "border-box",
+        // Subtle outer glow for the accent version, tinted to match.
+        boxShadow: useSystem ? `0 0 0 1px rgba(176, 74, 26, 0.10), 0 8px 24px -10px rgba(176, 74, 26, 0.35)` : void 0
       },
-      "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
+      "data-role": "box"
     }
   );
 }
 
 // src/components/TutorMode/CinemaLayer.tsx
-var import_jsx_runtime50 = require("react/jsx-runtime");
+var import_jsx_runtime48 = require("react/jsx-runtime");
 function blockBbox(index, block_id) {
   return index.blockById.get(block_id)?.block.bbox;
 }
@@ -13657,7 +13923,7 @@ function CinemaLayer({
   overlays,
   scale
 }) {
-  return /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime48.jsx)(
     "div",
     {
       "data-role": "cinema-layer",
@@ -13677,13 +13943,13 @@ function CinemaLayer({
         // 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) => {
+      children: /* @__PURE__ */ (0, import_jsx_runtime48.jsx)(import_framer_motion8.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)(
+            return /* @__PURE__ */ (0, import_jsx_runtime48.jsx)(
               SpotlightMask,
               {
                 page: page.page_dimensions,
@@ -13697,26 +13963,26 @@ function CinemaLayer({
             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);
+            return /* @__PURE__ */ (0, import_jsx_runtime48.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);
+            return /* @__PURE__ */ (0, import_jsx_runtime48.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);
+            return /* @__PURE__ */ (0, import_jsx_runtime48.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)(
+            return /* @__PURE__ */ (0, import_jsx_runtime48.jsx)(
               CalloutArrow,
               {
                 fromBbox: from,
@@ -13726,36 +13992,16 @@ function CinemaLayer({
               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 "ghost_reference":
+            return null;
           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);
+            return /* @__PURE__ */ (0, import_jsx_runtime48.jsx)(BoxOverlay, { bbox: b, action: a }, overlay.id);
           }
+          case "label":
+            return null;
           case "clear":
           case "camera":
             return null;
@@ -13765,12 +14011,774 @@ function CinemaLayer({
   );
 }
 
-// src/components/TutorMode/SubtitleBar.tsx
+// src/components/TutorMode/GhostReferenceOverlay.tsx
+var import_framer_motion10 = require("framer-motion");
+
+// src/components/TutorMode/GhostReference.tsx
+var import_framer_motion9 = require("framer-motion");
+var import_jsx_runtime49 = require("react/jsx-runtime");
+var POSITIONS = {
+  "top-right": {
+    top: "clamp(12px, 4vw, 40px)",
+    right: "clamp(12px, 4vw, 40px)"
+  },
+  "top-left": {
+    top: "clamp(12px, 4vw, 40px)",
+    left: "clamp(12px, 4vw, 40px)"
+  },
+  "bottom-right": {
+    bottom: "clamp(12px, 4vw, 40px)",
+    right: "clamp(12px, 4vw, 40px)"
+  },
+  "bottom-left": {
+    bottom: "clamp(12px, 4vw, 40px)",
+    left: "clamp(12px, 4vw, 40px)"
+  }
+};
+var INK2 = "#2a2420";
+var PAPER2 = "#faf6ec";
+var PAPER_DEEP = "#f3ece0";
+var ACCENT2 = "#b04a1a";
+var RULE = "rgba(42, 36, 32, 0.10)";
+var SERIF2 = "'Iowan Old Style', 'Palatino Linotype', Palatino, 'Book Antiqua', 'EB Garamond', 'Hoefler Text', Georgia, serif";
+function GhostReference({
+  page,
+  sourceBbox,
+  sourceBlockText,
+  action
+}) {
+  const [x1, y1, x2, y2] = sourceBbox;
+  const text = sourceBlockText ?? "(figure)";
+  return /* @__PURE__ */ (0, import_jsx_runtime49.jsxs)(
+    import_framer_motion9.motion.div,
+    {
+      initial: { opacity: 0, y: 24, scale: 0.97 },
+      animate: { opacity: 1, y: 0, scale: 1 },
+      exit: { opacity: 0, y: 20, scale: 0.97 },
+      transition: {
+        duration: 0.55,
+        ease: [0.22, 1, 0.36, 1]
+        // custom out-expo for an unhurried settle
+      },
+      style: {
+        position: "absolute",
+        width: "min(420px, calc(100vw - clamp(24px, 8vw, 80px)))",
+        background: PAPER2,
+        color: INK2,
+        border: `1px solid ${RULE}`,
+        // Barely-there corner radius — square-ish corners feel editorial,
+        // 12px+ radius feels SaaS-notification. 3px is the sweet spot.
+        borderRadius: 3,
+        overflow: "hidden",
+        // Warm, two-layer shadow: a tight contact shadow for definition,
+        // a wider diffuse one tinted toward ink rather than pure grey.
+        boxShadow: "0 1px 2px rgba(42, 36, 32, 0.10), 0 20px 44px -14px rgba(42, 36, 32, 0.22), 0 8px 20px -10px rgba(42, 36, 32, 0.14)",
+        pointerEvents: "none",
+        ...POSITIONS[action.position]
+      },
+      "data-role": "ghost-reference",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime49.jsx)(
+          import_framer_motion9.motion.span,
+          {
+            "aria-hidden": true,
+            initial: { scaleY: 0 },
+            animate: { scaleY: 1 },
+            exit: { scaleY: 0 },
+            transition: { duration: 0.55, delay: 0.06, ease: [0.22, 1, 0.36, 1] },
+            style: {
+              position: "absolute",
+              left: 0,
+              top: 0,
+              bottom: 0,
+              width: 3,
+              background: ACCENT2,
+              transformOrigin: "top"
+            }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime49.jsx)(
+          "span",
+          {
+            "aria-hidden": true,
+            style: {
+              position: "absolute",
+              inset: 0,
+              pointerEvents: "none",
+              background: `
+            radial-gradient(120% 80% at 0% 0%, rgba(255, 244, 220, 0.5) 0%, transparent 55%),
+            radial-gradient(100% 80% at 100% 100%, rgba(243, 229, 200, 0.35) 0%, transparent 60%)
+          `
+            }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime49.jsxs)(
+          "div",
+          {
+            style: {
+              position: "relative",
+              padding: "20px 22px 20px 26px",
+              display: "flex",
+              gap: 16,
+              alignItems: "flex-start"
+            },
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime49.jsx)(
+                import_framer_motion9.motion.div,
+                {
+                  "aria-hidden": true,
+                  initial: { opacity: 0, scale: 0.92 },
+                  animate: { opacity: 1, scale: 1 },
+                  exit: { opacity: 0, scale: 0.92 },
+                  transition: { duration: 0.45, delay: 0.18, ease: [0.22, 1, 0.36, 1] },
+                  style: {
+                    flexShrink: 0,
+                    width: 46,
+                    aspectRatio: `${page.width} / ${page.height}`,
+                    background: PAPER_DEEP,
+                    borderRadius: 2,
+                    overflow: "hidden",
+                    boxShadow: "inset 0 0 0 1px rgba(42, 36, 32, 0.12), 0 1px 3px rgba(42, 36, 32, 0.10)"
+                  },
+                  children: /* @__PURE__ */ (0, import_jsx_runtime49.jsxs)(
+                    "svg",
+                    {
+                      width: "100%",
+                      height: "100%",
+                      viewBox: `0 0 ${page.width} ${page.height}`,
+                      preserveAspectRatio: "xMidYMid meet",
+                      style: { display: "block" },
+                      children: [
+                        /* @__PURE__ */ (0, import_jsx_runtime49.jsx)(
+                          "rect",
+                          {
+                            x: 0,
+                            y: 0,
+                            width: page.width,
+                            height: page.height,
+                            fill: PAPER_DEEP
+                          }
+                        ),
+                        TEXT_LINES.map((ln, i) => /* @__PURE__ */ (0, import_jsx_runtime49.jsx)(
+                          "rect",
+                          {
+                            x: page.width * ln.x,
+                            y: page.height * ln.y,
+                            width: page.width * ln.w,
+                            height: page.height * 0.012,
+                            fill: "rgba(42, 36, 32, 0.18)"
+                          },
+                          i
+                        )),
+                        /* @__PURE__ */ (0, import_jsx_runtime49.jsx)(
+                          "rect",
+                          {
+                            x: x1,
+                            y: y1,
+                            width: x2 - x1,
+                            height: y2 - y1,
+                            fill: "rgba(176, 74, 26, 0.28)",
+                            stroke: ACCENT2,
+                            strokeWidth: 18
+                          }
+                        )
+                      ]
+                    }
+                  )
+                }
+              ),
+              /* @__PURE__ */ (0, import_jsx_runtime49.jsxs)(
+                import_framer_motion9.motion.div,
+                {
+                  initial: { opacity: 0, y: 6 },
+                  animate: { opacity: 1, y: 0 },
+                  exit: { opacity: 0 },
+                  transition: { duration: 0.5, delay: 0.26, ease: [0.22, 1, 0.36, 1] },
+                  style: {
+                    flex: 1,
+                    minWidth: 0,
+                    fontFamily: SERIF2,
+                    fontSize: 15.5,
+                    lineHeight: 1.55,
+                    color: INK2,
+                    fontFeatureSettings: "'liga' 1, 'kern' 1, 'onum' 1",
+                    textRendering: "optimizeLegibility",
+                    letterSpacing: 0.05,
+                    // Hang an ornamental opening glyph outside the text column
+                    // so the reader's eye falls into the paragraph as if into a
+                    // well-set pull quote.
+                    position: "relative",
+                    paddingLeft: 2
+                  },
+                  children: [
+                    /* @__PURE__ */ (0, import_jsx_runtime49.jsx)(
+                      "span",
+                      {
+                        "aria-hidden": true,
+                        style: {
+                          position: "absolute",
+                          left: -14,
+                          top: -2,
+                          color: ACCENT2,
+                          fontSize: 22,
+                          lineHeight: 1,
+                          fontWeight: 500
+                          // ornamental flourish anchoring the paragraph
+                        },
+                        children: "\u2767"
+                      }
+                    ),
+                    /* @__PURE__ */ (0, import_jsx_runtime49.jsx)(
+                      "span",
+                      {
+                        style: {
+                          display: "-webkit-box",
+                          WebkitLineClamp: 8,
+                          WebkitBoxOrient: "vertical",
+                          overflow: "hidden"
+                        },
+                        children: text
+                      }
+                    )
+                  ]
+                }
+              )
+            ]
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime49.jsx)(
+          import_framer_motion9.motion.span,
+          {
+            "aria-hidden": true,
+            initial: { scaleX: 0, opacity: 0 },
+            animate: { scaleX: 1, opacity: 0.6 },
+            exit: { opacity: 0 },
+            transition: { duration: 0.5, delay: 0.42, ease: [0.22, 1, 0.36, 1] },
+            style: {
+              position: "absolute",
+              right: 22,
+              bottom: 10,
+              height: 1,
+              width: 28,
+              background: ACCENT2,
+              transformOrigin: "right"
+            }
+          }
+        )
+      ]
+    }
+  );
+}
+var TEXT_LINES = [
+  { x: 0.1, y: 0.12, w: 0.54 },
+  { x: 0.1, y: 0.18, w: 0.68 },
+  { x: 0.1, y: 0.24, w: 0.48 },
+  { x: 0.1, y: 0.34, w: 0.72 },
+  { x: 0.1, y: 0.4, w: 0.62 },
+  { x: 0.1, y: 0.46, w: 0.66 },
+  { x: 0.1, y: 0.56, w: 0.56 },
+  { x: 0.1, y: 0.62, w: 0.7 },
+  { x: 0.1, y: 0.68, w: 0.44 },
+  { x: 0.1, y: 0.78, w: 0.64 },
+  { x: 0.1, y: 0.84, w: 0.58 }
+];
+
+// src/components/TutorMode/GhostReferenceOverlay.tsx
+var import_jsx_runtime50 = require("react/jsx-runtime");
+function GhostReferenceOverlay({
+  overlays,
+  index
+}) {
+  const ghosts = overlays.filter((o) => o.kind === "ghost_reference");
+  return /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(
+    "div",
+    {
+      "data-role": "ghost-reference-overlay",
+      style: {
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        // Sits above the Reset view button (z-60) so a ghost card doesn't
+        // disappear behind it if the host also renders the Reset button.
+        zIndex: 70
+      },
+      children: /* @__PURE__ */ (0, import_jsx_runtime50.jsx)(import_framer_motion10.AnimatePresence, { children: ghosts.map((overlay) => {
+        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
+        );
+      }) })
+    }
+  );
+}
+
+// src/components/TutorMode/LabelOverlay.tsx
+var import_framer_motion12 = require("framer-motion");
+
+// src/components/TutorMode/StickyLabel.tsx
 var import_framer_motion11 = require("framer-motion");
 var import_jsx_runtime51 = require("react/jsx-runtime");
-function SubtitleBar({ text }) {
-  return /* @__PURE__ */ (0, import_jsx_runtime51.jsx)(import_framer_motion11.AnimatePresence, { children: text ? /* @__PURE__ */ (0, import_jsx_runtime51.jsx)(
+var INK3 = "#2a2420";
+var PAPER3 = "#faf6ec";
+var ACCENT3 = "#b04a1a";
+var SERIF3 = "'Iowan Old Style', 'Palatino Linotype', Palatino, 'Book Antiqua', 'EB Garamond', 'Hoefler Text', Georgia, serif";
+var STEM = 18;
+function StickyLabel({ screenAnchor, action }) {
+  const { x, y } = screenAnchor;
+  const layout = LAYOUTS[action.position] ?? LAYOUTS.top;
+  return /* @__PURE__ */ (0, import_jsx_runtime51.jsxs)(
     import_framer_motion11.motion.div,
+    {
+      initial: { opacity: 0, scale: 0.88 },
+      animate: { opacity: 1, scale: 1 },
+      exit: { opacity: 0, scale: 0.92 },
+      transition: {
+        duration: 0.4,
+        ease: [0.22, 1, 0.36, 1]
+      },
+      style: {
+        position: "absolute",
+        left: x,
+        top: y,
+        // Wrapper positions at the anchor; the body's transform places
+        // it on the correct side via `layout.containerTransform`.
+        transform: layout.containerTransform,
+        pointerEvents: "none",
+        // Compose transform-origin toward the anchor so scale-in feels
+        // tethered to the block rather than free-floating.
+        transformOrigin: layout.origin
+      },
+      "data-role": "label",
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime51.jsx)(
+          import_framer_motion11.motion.span,
+          {
+            "aria-hidden": true,
+            initial: { scaleX: 0, scaleY: 0, opacity: 0 },
+            animate: { scaleX: 1, scaleY: 1, opacity: 1 },
+            exit: { opacity: 0 },
+            transition: { duration: 0.35, ease: [0.22, 1, 0.36, 1] },
+            style: {
+              position: "absolute",
+              background: ACCENT3,
+              transformOrigin: layout.stemOrigin,
+              ...layout.stem
+            }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime51.jsx)(
+          import_framer_motion11.motion.span,
+          {
+            "aria-hidden": true,
+            initial: { scale: 0 },
+            animate: { scale: 1 },
+            exit: { scale: 0 },
+            transition: { duration: 0.3, delay: 0.15, ease: [0.22, 1, 0.36, 1] },
+            style: {
+              position: "absolute",
+              width: 6,
+              height: 6,
+              borderRadius: "50%",
+              background: ACCENT3,
+              boxShadow: `0 0 0 2px ${PAPER3}, 0 0 0 3px rgba(176, 74, 26, 0.25)`,
+              ...layout.dot
+            }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime51.jsx)(
+          import_framer_motion11.motion.div,
+          {
+            initial: { y: layout.bodyIn.y, x: layout.bodyIn.x, opacity: 0 },
+            animate: { y: 0, x: 0, opacity: 1 },
+            exit: { opacity: 0 },
+            transition: { duration: 0.4, delay: 0.08, ease: [0.22, 1, 0.36, 1] },
+            style: {
+              position: "absolute",
+              ...layout.bodyAnchor,
+              background: PAPER3,
+              color: INK3,
+              border: "1px solid rgba(42, 36, 32, 0.10)",
+              borderRadius: 3,
+              padding: "6px 12px 6px 14px",
+              fontFamily: SERIF3,
+              fontSize: 12.5,
+              lineHeight: 1.25,
+              letterSpacing: 0.6,
+              textTransform: "uppercase",
+              fontWeight: 500,
+              whiteSpace: "nowrap",
+              maxWidth: 240,
+              overflow: "hidden",
+              textOverflow: "ellipsis",
+              // Warm two-layer shadow (matches GhostReference's palette).
+              boxShadow: "0 1px 2px rgba(42, 36, 32, 0.12), 0 8px 18px -6px rgba(42, 36, 32, 0.22)",
+              // Internal left accent rule — a 2px terracotta stripe.
+              backgroundImage: `linear-gradient(to right, ${ACCENT3} 0, ${ACCENT3} 2px, transparent 2px)`,
+              backgroundRepeat: "no-repeat",
+              backgroundSize: "2px 100%",
+              backgroundPosition: "left top"
+            },
+            children: action.text
+          }
+        )
+      ]
+    }
+  );
+}
+var LAYOUTS = {
+  top: {
+    containerTransform: "translate(-50%, -100%)",
+    origin: "50% 100%",
+    stem: {
+      left: "50%",
+      bottom: -STEM,
+      width: 1,
+      height: STEM - 4,
+      transform: "translateX(-50%)"
+    },
+    stemOrigin: "bottom",
+    dot: {
+      left: "50%",
+      bottom: -STEM + 1,
+      transform: "translate(-50%, 100%)"
+    },
+    bodyAnchor: { bottom: 0, left: "50%", transform: "translateX(-50%)" },
+    bodyIn: { x: 0, y: -4 }
+  },
+  bottom: {
+    containerTransform: "translate(-50%, 0%)",
+    origin: "50% 0%",
+    stem: {
+      left: "50%",
+      top: STEM - (STEM - 4),
+      width: 1,
+      height: STEM - 4,
+      transform: "translateX(-50%)"
+    },
+    stemOrigin: "top",
+    dot: {
+      left: "50%",
+      top: -1,
+      transform: "translate(-50%, -100%)"
+    },
+    bodyAnchor: { top: STEM, left: "50%", transform: "translateX(-50%)" },
+    bodyIn: { x: 0, y: 4 }
+  },
+  left: {
+    containerTransform: "translate(-100%, -50%)",
+    origin: "100% 50%",
+    stem: {
+      top: "50%",
+      right: -STEM,
+      width: STEM - 4,
+      height: 1,
+      transform: "translateY(-50%)"
+    },
+    stemOrigin: "right",
+    dot: {
+      right: -STEM + 1,
+      top: "50%",
+      transform: "translate(100%, -50%)"
+    },
+    bodyAnchor: { right: 0, top: "50%", transform: "translateY(-50%)" },
+    bodyIn: { x: -4, y: 0 }
+  },
+  right: {
+    containerTransform: "translate(0%, -50%)",
+    origin: "0% 50%",
+    stem: {
+      top: "50%",
+      left: STEM - (STEM - 4),
+      width: STEM - 4,
+      height: 1,
+      transform: "translateY(-50%)"
+    },
+    stemOrigin: "left",
+    dot: {
+      left: -1,
+      top: "50%",
+      transform: "translate(-100%, -50%)"
+    },
+    bodyAnchor: { left: STEM, top: "50%", transform: "translateY(-50%)" },
+    bodyIn: { x: 4, y: 0 }
+  }
+};
+
+// src/components/TutorMode/LabelOverlay.tsx
+var import_jsx_runtime52 = require("react/jsx-runtime");
+function LabelOverlay({
+  overlays,
+  index,
+  currentPage,
+  camera,
+  viewport
+}) {
+  const labels = overlays.filter((o) => o.kind === "label");
+  const page = index.byPage.get(currentPage);
+  return /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(
+    "div",
+    {
+      "data-role": "label-overlay",
+      style: {
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        overflow: "hidden",
+        // Above CameraView and the Reset button but not above
+        // GhostReferenceOverlay (z:70) — labels are block-attached and
+        // should not cover a cross-page reference card.
+        zIndex: 65
+      },
+      children: /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(import_framer_motion12.AnimatePresence, { children: page ? labels.map((overlay) => {
+        const a = overlay.action;
+        const hit = index.blockById.get(a.target_block);
+        if (!hit) return null;
+        const anchor = computeScreenAnchor(
+          hit.block.bbox,
+          a.position,
+          page,
+          camera,
+          viewport
+        );
+        return /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(
+          StickyLabel,
+          {
+            screenAnchor: anchor,
+            action: a
+          },
+          overlay.id
+        );
+      }) : null })
+    }
+  );
+}
+function computeScreenAnchor(bbox, where, page, camera, viewport) {
+  const [x1, y1, x2, y2] = bbox;
+  const pageCX = page.page_dimensions.width / 2;
+  const pageCY = page.page_dimensions.height / 2;
+  let px, py;
+  switch (where) {
+    case "top":
+      px = (x1 + x2) / 2;
+      py = y1;
+      break;
+    case "bottom":
+      px = (x1 + x2) / 2;
+      py = y2;
+      break;
+    case "left":
+      px = x1;
+      py = (y1 + y2) / 2;
+      break;
+    case "right":
+      px = x2;
+      py = (y1 + y2) / 2;
+      break;
+    default:
+      px = (x1 + x2) / 2;
+      py = y1;
+  }
+  const screenX = viewport.width / 2 + camera.x + (px - pageCX) * camera.scale;
+  const screenY = viewport.height / 2 + camera.y + (py - pageCY) * camera.scale;
+  return { x: screenX, y: screenY };
+}
+
+// src/components/TutorMode/CalloutLabelOverlay.tsx
+var import_framer_motion13 = require("framer-motion");
+var import_jsx_runtime53 = require("react/jsx-runtime");
+function CalloutLabelOverlay({
+  overlays,
+  index,
+  currentPage,
+  camera,
+  viewport
+}) {
+  const callouts = overlays.filter(
+    (o) => o.kind === "callout" && o.action.label
+  );
+  const page = index.byPage.get(currentPage);
+  return /* @__PURE__ */ (0, import_jsx_runtime53.jsx)(
+    "div",
+    {
+      "data-role": "callout-label-overlay",
+      style: {
+        position: "absolute",
+        inset: 0,
+        pointerEvents: "none",
+        overflow: "hidden",
+        // Above the arrow stroke (which is inside CameraView) and the
+        // reset button, below the ghost card.
+        zIndex: 68
+      },
+      children: /* @__PURE__ */ (0, import_jsx_runtime53.jsx)(import_framer_motion13.AnimatePresence, { children: page ? callouts.map((overlay) => {
+        const a = overlay.action;
+        const fromHit = index.blockById.get(a.from_block);
+        const toHit = index.blockById.get(a.to_block);
+        if (!fromHit || !toHit || !a.label) return null;
+        const pos = computePillAnchor(
+          fromHit.block.bbox,
+          toHit.block.bbox,
+          page,
+          camera,
+          viewport
+        );
+        return /* @__PURE__ */ (0, import_jsx_runtime53.jsx)(
+          CalloutLabelPill,
+          {
+            label: a.label,
+            anchor: pos,
+            side: pos.side
+          },
+          overlay.id
+        );
+      }) : null })
+    }
+  );
+}
+function computePillAnchor(fromBbox, toBbox, page, camera, viewport) {
+  const aCX = (fromBbox[0] + fromBbox[2]) / 2;
+  const aCY = (fromBbox[1] + fromBbox[3]) / 2;
+  const bCX = (toBbox[0] + toBbox[2]) / 2;
+  const bCY = (toBbox[1] + toBbox[3]) / 2;
+  const dx = bCX - aCX;
+  const dy = bCY - aCY;
+  const len = Math.hypot(dx, dy) || 1;
+  const ux = dx / len;
+  const uy = dy / len;
+  const bHalfW = (toBbox[2] - toBbox[0]) / 2;
+  const bHalfH = (toBbox[3] - toBbox[1]) / 2;
+  const bOff = Math.min(Math.max(bHalfW, bHalfH), 60);
+  const toX = bCX - ux * bOff;
+  const toY = bCY - uy * bOff;
+  const pageCX = page.page_dimensions.width / 2;
+  const pageCY = page.page_dimensions.height / 2;
+  const tipScreenX = viewport.width / 2 + camera.x + (toX - pageCX) * camera.scale;
+  const tipScreenY = viewport.height / 2 + camera.y + (toY - pageCY) * camera.scale;
+  const isVertical = Math.abs(dy) >= Math.abs(dx);
+  const OFFSET = 32;
+  const MAX_PILL_W = 220;
+  const MAX_PILL_H = 30;
+  const SAFE = 16;
+  if (isVertical) {
+    const canFitRight = tipScreenX + OFFSET + MAX_PILL_W < viewport.width - SAFE;
+    const side2 = canFitRight ? "right" : "left";
+    return {
+      x: tipScreenX + (side2 === "right" ? OFFSET : -OFFSET),
+      y: tipScreenY,
+      side: side2
+    };
+  }
+  const canFitBelow = tipScreenY + OFFSET + MAX_PILL_H < viewport.height - SAFE;
+  const side = canFitBelow ? "below" : "above";
+  return {
+    x: tipScreenX,
+    y: tipScreenY + (side === "below" ? OFFSET : -OFFSET),
+    side
+  };
+}
+function CalloutLabelPill({
+  label,
+  anchor,
+  side
+}) {
+  const spec = PILL_SIDE_SPECS[side];
+  return /* @__PURE__ */ (0, import_jsx_runtime53.jsx)(
+    import_framer_motion13.motion.div,
+    {
+      initial: { opacity: 0, scale: 0.92, ...spec.slideIn },
+      animate: { opacity: 1, scale: 1, x: 0, y: 0 },
+      exit: { opacity: 0, scale: 0.94 },
+      transition: { duration: 0.45, delay: 0.5, ease: EASE_OUT_EXPO },
+      style: {
+        position: "absolute",
+        left: anchor.x,
+        top: anchor.y,
+        transform: spec.transform,
+        pointerEvents: "none",
+        background: PAPER,
+        color: INK,
+        border: "1px solid rgba(42, 36, 32, 0.10)",
+        borderRadius: 3,
+        padding: spec.padding,
+        fontFamily: SERIF,
+        fontSize: 11.5,
+        lineHeight: 1.2,
+        letterSpacing: 0.6,
+        textTransform: "uppercase",
+        fontWeight: 500,
+        whiteSpace: "nowrap",
+        maxWidth: 220,
+        overflow: "hidden",
+        textOverflow: "ellipsis",
+        boxShadow: "0 1px 2px rgba(42, 36, 32, 0.12), 0 8px 18px -6px rgba(42, 36, 32, 0.22)",
+        // Accent rule on the "inward" edge (the one closest to the arrow).
+        backgroundImage: spec.accentGradient,
+        backgroundRepeat: "no-repeat",
+        backgroundSize: spec.accentSize,
+        backgroundPosition: spec.accentPosition
+      },
+      "data-role": "callout-label",
+      children: label
+    }
+  );
+}
+var PILL_SIDE_SPECS = {
+  // Pill sits to the RIGHT of a vertical arrow → left edge anchors at
+  // offset point, accent rule on the left (pointing back toward arrow).
+  right: {
+    transform: "translate(0, -50%)",
+    slideIn: { x: -6 },
+    padding: "5px 12px 5px 14px",
+    accentGradient: `linear-gradient(to right, ${ACCENT} 0, ${ACCENT} 2px, transparent 2px)`,
+    accentSize: "2px 100%",
+    accentPosition: "left top"
+  },
+  left: {
+    transform: "translate(-100%, -50%)",
+    slideIn: { x: 6 },
+    padding: "5px 14px 5px 12px",
+    accentGradient: `linear-gradient(to left, ${ACCENT} 0, ${ACCENT} 2px, transparent 2px)`,
+    accentSize: "2px 100%",
+    accentPosition: "right top"
+  },
+  // Pill sits BELOW a horizontal arrow → top edge anchors at offset
+  // point, accent rule on the top (pointing back up toward arrow).
+  below: {
+    transform: "translate(-50%, 0)",
+    slideIn: { y: -6 },
+    padding: "7px 12px 5px 12px",
+    accentGradient: `linear-gradient(to bottom, ${ACCENT} 0, ${ACCENT} 2px, transparent 2px)`,
+    accentSize: "100% 2px",
+    accentPosition: "left top"
+  },
+  above: {
+    transform: "translate(-50%, -100%)",
+    slideIn: { y: 6 },
+    padding: "5px 12px 7px 12px",
+    accentGradient: `linear-gradient(to top, ${ACCENT} 0, ${ACCENT} 2px, transparent 2px)`,
+    accentSize: "100% 2px",
+    accentPosition: "left bottom"
+  }
+};
+
+// src/components/TutorMode/SubtitleBar.tsx
+var import_framer_motion14 = require("framer-motion");
+var import_jsx_runtime54 = require("react/jsx-runtime");
+function SubtitleBar({ text }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime54.jsx)(import_framer_motion14.AnimatePresence, { children: text ? /* @__PURE__ */ (0, import_jsx_runtime54.jsx)(
+    import_framer_motion14.motion.div,
     {
       initial: { opacity: 0, y: 20 },
       animate: { opacity: 1, y: 0 },
@@ -13996,12 +15004,17 @@ var StoryboardEngine = class {
     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 rawX = (pageCX - blockCX) * finalScale;
+    const rawY = (pageCY - blockCY) * finalScale;
+    const clamped = clampCamera(
+      { scale: finalScale, x: rawX, y: rawY },
+      pageDims.page_dimensions,
+      viewport
+    );
     const camera = {
-      scale: finalScale,
-      x,
-      y,
+      scale: clamped.scale,
+      x: clamped.x,
+      y: clamped.y,
       easing: action.easing
     };
     narrationStore.getState().setCamera(camera);
@@ -14986,7 +15999,7 @@ function storyboardFromMatch(match, page) {
 }
 
 // src/components/TutorMode/TutorModeContainer.tsx
-var import_jsx_runtime52 = require("react/jsx-runtime");
+var import_jsx_runtime55 = require("react/jsx-runtime");
 function buildBBoxIndex(bboxData) {
   const byPage = /* @__PURE__ */ new Map();
   const blockById = /* @__PURE__ */ new Map();
@@ -15024,16 +16037,34 @@ function TutorModeContainer({
   minOverlayDurationMs,
   backgroundColor = "#ffffff",
   loadingComponent,
+  onPageChange,
   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 containerRef = (0, import_react58.useRef)(null);
+  const index = (0, import_react58.useMemo)(() => buildBBoxIndex(bboxData), [bboxData]);
+  const {
+    document: document2,
+    currentPage: viewerCurrentPage,
+    numPages,
+    goToPage: viewerGoToPage
+  } = usePDFViewer();
+  const [pageProxy, setPageProxy] = (0, import_react58.useState)(null);
+  const [viewport, setViewport] = (0, import_react58.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)(() => {
+  (0, import_react58.useEffect)(() => {
+    if (numPages <= 0) return;
+    if (pageNumber < 1 || pageNumber > numPages) return;
+    if (viewerCurrentPage === pageNumber) return;
+    viewerGoToPage(pageNumber);
+  }, [pageNumber, numPages, viewerCurrentPage, viewerGoToPage]);
+  (0, import_react58.useEffect)(() => {
+    if (!onPageChange) return;
+    if (viewerCurrentPage === pageNumber) return;
+    if (viewerCurrentPage < 1) return;
+    onPageChange(viewerCurrentPage);
+  }, [viewerCurrentPage, pageNumber, onPageChange]);
+  (0, import_react58.useEffect)(() => {
     if (!containerRef.current) return;
     const el = containerRef.current;
     const update = () => setViewport({ width: el.clientWidth, height: el.clientHeight });
@@ -15042,7 +16073,7 @@ function TutorModeContainer({
     ro.observe(el);
     return () => ro.disconnect();
   }, []);
-  (0, import_react56.useEffect)(() => {
+  (0, import_react58.useEffect)(() => {
     if (!document2) {
       setPageProxy(null);
       return;
@@ -15057,10 +16088,10 @@ function TutorModeContainer({
       cancelled = true;
     };
   }, [document2, pageNumber]);
-  (0, import_react56.useEffect)(() => {
+  (0, import_react58.useEffect)(() => {
     narrationStore.getState().setCurrentPage(pageNumber);
   }, [pageNumber, narrationStore]);
-  (0, import_react56.useEffect)(() => {
+  (0, import_react58.useEffect)(() => {
     const page2 = index.byPage.get(pageNumber);
     if (!page2) return;
     if (viewport.width === 0 || viewport.height === 0) return;
@@ -15071,8 +16102,8 @@ function TutorModeContainer({
     ) * 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)(() => {
+  const engineRef = (0, import_react58.useRef)(null);
+  (0, import_react58.useEffect)(() => {
     engineRef.current = new StoryboardEngine({
       narrationStore,
       bboxIndex: index,
@@ -15081,10 +16112,10 @@ function TutorModeContainer({
     });
     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)(() => {
+  const abortRef = (0, import_react58.useRef)(null);
+  const debounceRef = (0, import_react58.useRef)(null);
+  const lastChunkRef = (0, import_react58.useRef)(null);
+  (0, import_react58.useEffect)(() => {
     if (!llm) return;
     if (!currentChunk || currentChunk === lastChunkRef.current) return;
     if (debounceRef.current) clearTimeout(debounceRef.current);
@@ -15171,7 +16202,7 @@ function TutorModeContainer({
       if (debounceRef.current) clearTimeout(debounceRef.current);
     };
   }, [currentChunk, llm, index, pageNumber, narrationStore, embeddingProvider, llmTimeoutMs]);
-  (0, import_react56.useEffect)(() => {
+  (0, import_react58.useEffect)(() => {
     if (!currentChunk) return;
     const t = setTimeout(() => {
       if (!engineRef.current) return;
@@ -15189,7 +16220,7 @@ function TutorModeContainer({
   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)(
+  return /* @__PURE__ */ (0, import_jsx_runtime55.jsxs)(
     "div",
     {
       ref: containerRef,
@@ -15204,7 +16235,7 @@ function TutorModeContainer({
       "data-role": "tutor-mode-container",
       "data-page-loaded": isReady ? "true" : "false",
       children: [
-        showExitButton && isReady ? /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(
+        showExitButton && isReady ? /* @__PURE__ */ (0, import_jsx_runtime55.jsx)(
           "button",
           {
             onClick: () => {
@@ -15235,43 +16266,66 @@ function TutorModeContainer({
             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
+        isReady ? /* @__PURE__ */ (0, import_jsx_runtime55.jsxs)(import_jsx_runtime55.Fragment, { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime55.jsx)(CameraView, { camera, children: /* @__PURE__ */ (0, import_jsx_runtime55.jsxs)(
+            "div",
+            {
+              style: {
+                position: "absolute",
+                top: "50%",
+                left: "50%",
+                width: baseW,
+                height: baseH,
+                transform: "translate(-50%, -50%)"
+              },
+              children: [
+                /* @__PURE__ */ (0, import_jsx_runtime55.jsx)(
+                  PDFPage,
+                  {
+                    pageNumber,
+                    page: pageProxy,
+                    scale: rasterScale,
+                    rotation,
+                    showTextLayer: false,
+                    showHighlightLayer: false,
+                    showAnnotationLayer: false
+                  }
+                ),
+                /* @__PURE__ */ (0, import_jsx_runtime55.jsx)(
+                  CinemaLayer,
+                  {
+                    page,
+                    index,
+                    overlays: activeOverlays,
+                    scale: scale || 1
+                  }
+                )
+              ]
+            }
+          ) }),
+          /* @__PURE__ */ (0, import_jsx_runtime55.jsx)(
+            LabelOverlay,
+            {
+              overlays: activeOverlays,
+              index,
+              currentPage: pageNumber,
+              camera,
+              viewport
+            }
+          ),
+          /* @__PURE__ */ (0, import_jsx_runtime55.jsx)(
+            CalloutLabelOverlay,
+            {
+              overlays: activeOverlays,
+              index,
+              currentPage: pageNumber,
+              camera,
+              viewport
+            }
+          ),
+          /* @__PURE__ */ (0, import_jsx_runtime55.jsx)(GhostReferenceOverlay, { overlays: activeOverlays, index })
+        ] }) : /* @__PURE__ */ (0, import_jsx_runtime55.jsx)(TutorLoadingState, { custom: loadingComponent }),
+        showSubtitles ? /* @__PURE__ */ (0, import_jsx_runtime55.jsx)(SubtitleBar, { text: currentChunk ?? null }) : null
       ]
     }
   );
@@ -15280,7 +16334,7 @@ function TutorLoadingState({
   custom
 }) {
   if (custom) {
-    return /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(
+    return /* @__PURE__ */ (0, import_jsx_runtime55.jsx)(
       "div",
       {
         style: {
@@ -15295,7 +16349,7 @@ function TutorLoadingState({
       }
     );
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime52.jsxs)(
+  return /* @__PURE__ */ (0, import_jsx_runtime55.jsxs)(
     "div",
     {
       style: {
@@ -15312,7 +16366,7 @@ function TutorLoadingState({
       },
       "data-role": "tutor-loading",
       children: [
-        /* @__PURE__ */ (0, import_jsx_runtime52.jsx)(
+        /* @__PURE__ */ (0, import_jsx_runtime55.jsx)(
           "div",
           {
             "aria-hidden": true,
@@ -15326,8 +16380,8 @@ function TutorLoadingState({
             }
           }
         ),
-        /* @__PURE__ */ (0, import_jsx_runtime52.jsx)("span", { children: "Loading document\u2026" }),
-        /* @__PURE__ */ (0, import_jsx_runtime52.jsx)("style", { children: `
+        /* @__PURE__ */ (0, import_jsx_runtime55.jsx)("span", { children: "Loading document\u2026" }),
+        /* @__PURE__ */ (0, import_jsx_runtime55.jsx)("style", { children: `
         @keyframes pdf-tutor-spin {
           from { transform: rotate(0deg); }
           to { transform: rotate(360deg); }