pdfjs-reader-core 0.5.5 → 0.5.7

package/dist/index.d.cts

@@ -1858,19 +1858,40 @@ interface TutorModeContainerProps {
      * Added in v0.4.2.
      */
     onPageChange?: (page: number) => void;
+    /**
+     * PDF-points → CSS-pixels scale factor. Direct override: when set, the
+     * tutor renders the PDF at exactly this scale regardless of source DPI.
+     * Takes precedence over `scale` when both are passed.
+     *
+     * If neither `renderScale` nor `scale` is passed:
+     *   - Desktop (`pointer: fine`): defaults to `page.dpi / 72` — identical
+     *     to pre-v0.6 behavior.
+     *   - Touch (`pointer: coarse`): defaults to fit-to-viewport — much
+     *     smaller canvas on mobile, sidesteps the iOS Safari crash root
+     *     cause even when bbox data ships at very high source DPI.
+     *
+     * Added in v0.6.0.
+     */
+    renderScale?: number;
     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, backgroundColor, loadingComponent, onPageChange, storyboardProvider, 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, onPageChange, storyboardProvider, renderScale, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
 
 interface CinemaLayerProps {
     page: PageBBoxData;
     index: BBoxIndex;
     overlays: ActiveOverlay[];
-    scale: number;
+    /**
+     * Factor converting source-DPI pixel coords (the bbox space every
+     * overlay primitive uses internally) into CSS-pixel coords. Applied
+     * as `transform: scale(coordScale)` on the outer element so individual
+     * overlay components don't need to know about CSS vs DPI space.
+     */
+    coordScale: number;
 }
-declare function CinemaLayer({ page, index, overlays, scale, }: CinemaLayerProps): react_jsx_runtime.JSX.Element;
+declare function CinemaLayer({ page, index, overlays, coordScale, }: CinemaLayerProps): react_jsx_runtime.JSX.Element | null;
 
 interface CameraViewProps {
     camera: CameraState;
@@ -2062,8 +2083,24 @@ declare class StoryboardEngine {
      * `resetVisuals()` instead.
      */
     cancelPending(): void;
-    /** Cancel every removal timer (used by resetVisuals only). */
+    /** Cancel every removal timer (used by resetVisuals and destroy). */
     private cancelAllRemovalTimers;
+    /**
+     * Full destructor — cancels both pending step timers AND overlay removal
+     * timers. Use this in component unmount/cleanup. The per-storyboard
+     * `cancelPending()` deliberately leaves overlay removal timers alone so a
+     * mid-flight overlay doesn't get stranded (see `overlayRemovalTimers` doc),
+     * but at destruction time we must release every timer or their closures
+     * keep `deps` (narrationStore, the full bboxIndex) alive beyond the
+     * lifetime of this engine. On iOS Safari with many engine recreations
+     * this causes cumulative memory pressure and eventual tab reload.
+     */
+    destroy(): void;
+    /** Test-only — exposes internal queue sizes for regression tests. */
+    _queueSizesForTest(): {
+        pending: number;
+        removals: number;
+    };
     /** Reset visuals: clear overlays, cancel every removal timer, fit camera. */
     resetVisuals(): void;
     /** Execute one step — dispatch to narrationStore. Returns true if applied. */

package/dist/index.d.ts

@@ -1858,19 +1858,40 @@ interface TutorModeContainerProps {
      * Added in v0.4.2.
      */
     onPageChange?: (page: number) => void;
+    /**
+     * PDF-points → CSS-pixels scale factor. Direct override: when set, the
+     * tutor renders the PDF at exactly this scale regardless of source DPI.
+     * Takes precedence over `scale` when both are passed.
+     *
+     * If neither `renderScale` nor `scale` is passed:
+     *   - Desktop (`pointer: fine`): defaults to `page.dpi / 72` — identical
+     *     to pre-v0.6 behavior.
+     *   - Touch (`pointer: coarse`): defaults to fit-to-viewport — much
+     *     smaller canvas on mobile, sidesteps the iOS Safari crash root
+     *     cause even when bbox data ships at very high source DPI.
+     *
+     * Added in v0.6.0.
+     */
+    renderScale?: number;
     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, backgroundColor, loadingComponent, onPageChange, storyboardProvider, 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, onPageChange, storyboardProvider, renderScale, className, }: TutorModeContainerProps): react_jsx_runtime.JSX.Element;
 
 interface CinemaLayerProps {
     page: PageBBoxData;
     index: BBoxIndex;
     overlays: ActiveOverlay[];
-    scale: number;
+    /**
+     * Factor converting source-DPI pixel coords (the bbox space every
+     * overlay primitive uses internally) into CSS-pixel coords. Applied
+     * as `transform: scale(coordScale)` on the outer element so individual
+     * overlay components don't need to know about CSS vs DPI space.
+     */
+    coordScale: number;
 }
-declare function CinemaLayer({ page, index, overlays, scale, }: CinemaLayerProps): react_jsx_runtime.JSX.Element;
+declare function CinemaLayer({ page, index, overlays, coordScale, }: CinemaLayerProps): react_jsx_runtime.JSX.Element | null;
 
 interface CameraViewProps {
     camera: CameraState;
@@ -2062,8 +2083,24 @@ declare class StoryboardEngine {
      * `resetVisuals()` instead.
      */
     cancelPending(): void;
-    /** Cancel every removal timer (used by resetVisuals only). */
+    /** Cancel every removal timer (used by resetVisuals and destroy). */
     private cancelAllRemovalTimers;
+    /**
+     * Full destructor — cancels both pending step timers AND overlay removal
+     * timers. Use this in component unmount/cleanup. The per-storyboard
+     * `cancelPending()` deliberately leaves overlay removal timers alone so a
+     * mid-flight overlay doesn't get stranded (see `overlayRemovalTimers` doc),
+     * but at destruction time we must release every timer or their closures
+     * keep `deps` (narrationStore, the full bboxIndex) alive beyond the
+     * lifetime of this engine. On iOS Safari with many engine recreations
+     * this causes cumulative memory pressure and eventual tab reload.
+     */
+    destroy(): void;
+    /** Test-only — exposes internal queue sizes for regression tests. */
+    _queueSizesForTest(): {
+        pending: number;
+        removals: number;
+    };
     /** Reset visuals: clear overlays, cancel every removal timer, fit camera. */
     resetVisuals(): void;
     /** Execute one step — dispatch to narrationStore. Returns true if applied. */