pdfjs-reader-core 0.4.0 → 0.4.1

package/dist/index.d.cts

@@ -1782,11 +1782,24 @@ interface TutorModeContainerProps {
      * Default: 3500ms.
      */
     minOverlayDurationMs?: number;
+    /**
+     * Background colour of the container surround (visible around the PDF when
+     * the viewport is larger than the page fit). Default: `#ffffff`. Pass a
+     * dark value for dark-themed hosts.
+     */
+    backgroundColor?: string;
+    /**
+     * Optional content to render while the PDF document/page is still loading.
+     * Receives the loading stage so the host can show a spinner, a skeleton,
+     * or a custom brand. If omitted, a minimal default spinner is rendered on
+     * the `backgroundColor` surround.
+     */
+    loadingComponent?: react__default.ReactNode;
     className?: string;
 }
 /** Build a cross-page/block index from the raw bbox list. */
 declare function buildBBoxIndex(bboxData: PageBBoxData[]): BBoxIndex;
-declare function TutorModeContainer({ pageNumber, bboxData, narrationStore, scale, rotation, currentChunk, llm, idleTimeoutMs, llmTimeoutMs, embeddingProvider, showSubtitles, showExitButton, onExitTutorMode, minOverlayDurationMs, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
+declare function TutorModeContainer({ pageNumber, bboxData, narrationStore, scale, rotation, currentChunk, llm, idleTimeoutMs, llmTimeoutMs, embeddingProvider, showSubtitles, showExitButton, onExitTutorMode, minOverlayDurationMs, backgroundColor, loadingComponent, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
 
 interface CinemaLayerProps {
     page: PageBBoxData;
@@ -1902,7 +1915,20 @@ interface EngineDeps {
 }
 declare class StoryboardEngine {
     private deps;
-    private pendingTimers;
+    /**
+     * 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.
+     */
+    private pendingStepTimers;
+    /**
+     * 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).
+     */
+    private overlayRemovalTimers;
     private currentStoryboardId;
     constructor(deps: EngineDeps);
     /**
@@ -1910,9 +1936,16 @@ declare class StoryboardEngine {
      * and smoothly transitions the camera/overlays from the current state.
      */
     execute(storyboard: Storyboard): void;
-    /** Abort all pending steps and set engine status to idle. */
+    /**
+     * 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(): void;
-    /** Reset visuals: clear overlays, fit camera back to page. */
+    /** Cancel every removal timer (used by resetVisuals only). */
+    private cancelAllRemovalTimers;
+    /** Reset visuals: clear overlays, cancel every removal timer, fit camera. */
     resetVisuals(): void;
     /** Execute one step — dispatch to narrationStore. Returns true if applied. */
     private runStep;

package/dist/index.d.ts

@@ -1782,11 +1782,24 @@ interface TutorModeContainerProps {
      * Default: 3500ms.
      */
     minOverlayDurationMs?: number;
+    /**
+     * Background colour of the container surround (visible around the PDF when
+     * the viewport is larger than the page fit). Default: `#ffffff`. Pass a
+     * dark value for dark-themed hosts.
+     */
+    backgroundColor?: string;
+    /**
+     * Optional content to render while the PDF document/page is still loading.
+     * Receives the loading stage so the host can show a spinner, a skeleton,
+     * or a custom brand. If omitted, a minimal default spinner is rendered on
+     * the `backgroundColor` surround.
+     */
+    loadingComponent?: react__default.ReactNode;
     className?: string;
 }
 /** Build a cross-page/block index from the raw bbox list. */
 declare function buildBBoxIndex(bboxData: PageBBoxData[]): BBoxIndex;
-declare function TutorModeContainer({ pageNumber, bboxData, narrationStore, scale, rotation, currentChunk, llm, idleTimeoutMs, llmTimeoutMs, embeddingProvider, showSubtitles, showExitButton, onExitTutorMode, minOverlayDurationMs, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
+declare function TutorModeContainer({ pageNumber, bboxData, narrationStore, scale, rotation, currentChunk, llm, idleTimeoutMs, llmTimeoutMs, embeddingProvider, showSubtitles, showExitButton, onExitTutorMode, minOverlayDurationMs, backgroundColor, loadingComponent, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
 
 interface CinemaLayerProps {
     page: PageBBoxData;
@@ -1902,7 +1915,20 @@ interface EngineDeps {
 }
 declare class StoryboardEngine {
     private deps;
-    private pendingTimers;
+    /**
+     * 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.
+     */
+    private pendingStepTimers;
+    /**
+     * 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).
+     */
+    private overlayRemovalTimers;
     private currentStoryboardId;
     constructor(deps: EngineDeps);
     /**
@@ -1910,9 +1936,16 @@ declare class StoryboardEngine {
      * and smoothly transitions the camera/overlays from the current state.
      */
     execute(storyboard: Storyboard): void;
-    /** Abort all pending steps and set engine status to idle. */
+    /**
+     * 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(): void;
-    /** Reset visuals: clear overlays, fit camera back to page. */
+    /** Cancel every removal timer (used by resetVisuals only). */
+    private cancelAllRemovalTimers;
+    /** Reset visuals: clear overlays, cancel every removal timer, fit camera. */
     resetVisuals(): void;
     /** Execute one step — dispatch to narrationStore. Returns true if applied. */
     private runStep;

package/dist/index.js

@@ -13621,7 +13621,20 @@ init_camera_math();
 var DEFAULT_MIN_OVERLAY_MS = 3500;
 var StoryboardEngine = class {
   constructor(deps) {
-    this.pendingTimers = /* @__PURE__ */ new Set();
+    /**
+     * 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;
   }
@@ -13664,13 +13677,13 @@ var StoryboardEngine = class {
         if (storyboardId !== this.currentStoryboardId) return;
         this.runStep(step);
       }, step.at_ms);
-      this.pendingTimers.add(timer);
+      this.pendingStepTimers.add(timer);
     }
     const markExecuting = setTimeout(() => {
       if (storyboardId !== this.currentStoryboardId) return;
       narrationStore.getState().setEngineStatus("executing");
     }, 0);
-    this.pendingTimers.add(markExecuting);
+    this.pendingStepTimers.add(markExecuting);
     const last = steps[steps.length - 1];
     if (last) {
       const totalMs = last.at_ms + last.duration_ms;
@@ -13678,18 +13691,29 @@ var StoryboardEngine = class {
         if (storyboardId !== this.currentStoryboardId) return;
         narrationStore.getState().setEngineStatus("idle");
       }, totalMs + 50);
-      this.pendingTimers.add(markIdle);
+      this.pendingStepTimers.add(markIdle);
     }
   }
-  /** Abort all pending steps and set engine status to idle. */
+  /**
+   * 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.pendingTimers) clearTimeout(t);
-    this.pendingTimers.clear();
+    for (const t of this.pendingStepTimers) clearTimeout(t);
+    this.pendingStepTimers.clear();
     this.deps.narrationStore.getState().setEngineStatus("idle");
   }
-  /** Reset visuals: clear overlays, fit camera back to page. */
+  /** 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();
@@ -13760,8 +13784,9 @@ var StoryboardEngine = class {
     narrationStore.getState().addOverlay(overlay);
     const timer = setTimeout(() => {
       narrationStore.getState().removeOverlay(overlay.id);
+      this.overlayRemovalTimers.delete(overlay.id);
     }, visibleMs);
-    this.pendingTimers.add(timer);
+    this.overlayRemovalTimers.set(overlay.id, timer);
     return true;
   }
   applyCamera(action, durationMs) {
@@ -14812,6 +14837,8 @@ function TutorModeContainer({
   showExitButton = true,
   onExitTutorMode,
   minOverlayDurationMs,
+  backgroundColor = "#ffffff",
+  loadingComponent,
   className
 }) {
   const containerRef = useRef27(null);
@@ -14976,6 +15003,7 @@ function TutorModeContainer({
   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__ */ jsxs38(
     "div",
     {
@@ -14986,12 +15014,12 @@ function TutorModeContainer({
         width: "100%",
         height: "100%",
         overflow: "hidden",
-        background: "#111"
+        background: backgroundColor
       },
       "data-role": "tutor-mode-container",
-      "data-page-loaded": page ? "true" : "false",
+      "data-page-loaded": isReady ? "true" : "false",
       children: [
-        showExitButton ? /* @__PURE__ */ jsx52(
+        showExitButton && isReady ? /* @__PURE__ */ jsx52(
           "button",
           {
             onClick: () => {
@@ -15008,7 +15036,9 @@ function TutorModeContainer({
               padding: "8px 14px",
               border: "none",
               borderRadius: 8,
-              background: "rgba(255,255,255,0.12)",
+              // 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",
@@ -15020,7 +15050,7 @@ function TutorModeContainer({
             children: "Reset view"
           }
         ) : null,
-        page ? /* @__PURE__ */ jsx52(CameraView, { camera, children: /* @__PURE__ */ jsxs38(
+        isReady ? /* @__PURE__ */ jsx52(CameraView, { camera, children: /* @__PURE__ */ jsxs38(
           "div",
           {
             style: {
@@ -15055,12 +15085,73 @@ function TutorModeContainer({
               )
             ]
           }
-        ) }) : null,
+        ) }) : /* @__PURE__ */ jsx52(TutorLoadingState, { custom: loadingComponent }),
         showSubtitles ? /* @__PURE__ */ jsx52(SubtitleBar, { text: currentChunk ?? null }) : null
       ]
     }
   );
 }
+function TutorLoadingState({
+  custom
+}) {
+  if (custom) {
+    return /* @__PURE__ */ jsx52(
+      "div",
+      {
+        style: {
+          position: "absolute",
+          inset: 0,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center"
+        },
+        "data-role": "tutor-loading",
+        children: custom
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxs38(
+    "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__ */ jsx52(
+          "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__ */ jsx52("span", { children: "Loading document\u2026" }),
+        /* @__PURE__ */ jsx52("style", { children: `
+        @keyframes pdf-tutor-spin {
+          from { transform: rotate(0deg); }
+          to { transform: rotate(360deg); }
+        }
+      ` })
+      ]
+    }
+  );
+}
 
 // src/director/transformers-embedding.ts
 var loaded = null;