@anaralabs/lector 3.13.0 → 3.13.2

package/dist/_tsup-dts-rollup.d.ts

@@ -168,6 +168,8 @@ export declare const cancellable: <T extends Promise<unknown>>(promise: T) => {
     cancel: () => void;
 };
 
+export declare const CANVAS_SUPERSAMPLE = 1.3;
+
 declare interface CanvasAndContext {
     canvas: HTMLCanvasElement | null;
     context: CanvasRenderingContext2D | null;
@@ -179,7 +181,7 @@ background?: string;
 
 export declare const clamp: (value: number, minimum: number, maximum: number) => number;
 
-export declare function clampScaleForPage(targetScale: number, pageWidth: number, pageHeight: number): number;
+export declare function clampScaleForPage(targetScale: number, pageWidth: number, pageHeight: number, maxPixels?: number): number;
 
 declare type CollapsibleSelection = {
     highlights: HighlightRect[];
@@ -208,6 +210,10 @@ declare type ColorScheme = "light" | "dark";
 export { ColorScheme }
 export { ColorScheme as ColorScheme_alias_1 }
 
+export declare function computeBaseScale(dpr: number, zoom: number, pageWidth: number, pageHeight: number): number;
+
+export declare function computeTargetScale(dpr: number, zoom: number): number;
+
 /**
  * Builds a memoized color map that flips perceived lightness onto the
  * background<->foreground ramp while preserving hue and chroma (OKLab).
@@ -272,6 +278,8 @@ export declare const ensureAnnotationLayerStyles: () => void;
 
 export declare const firstMemo: <T>(first: boolean, memo: unknown, initializer: () => T) => T;
 
+export declare function getCanvasPixelBudget(): number;
+
 export declare const getDefaultPdfJsAssetUrls: (version: string) => PdfJsAssetUrls;
 
 export declare const getEndOfHighlight: (selection: ColoredHighlight) => number;
@@ -321,6 +329,8 @@ export declare interface InitialPDFState {
     renderColorMapRef?: RenderColorMapRef;
 }
 
+export declare const IS_MOBILE_DEVICE: boolean;
+
 export declare class LinkService {
     _pdfDocumentProxy?: PDFDocumentProxy;
     externalLinkEnabled: boolean;

package/dist/index.js

@@ -1375,13 +1375,29 @@ AnnotationLayer.displayName = "AnnotationLayer";
 // src/lib/canvas-utils.ts
 var MAX_CANVAS_PIXELS = 16777216;
 var MAX_CANVAS_DIMENSION = 32767;
-function clampScaleForPage(targetScale, pageWidth, pageHeight) {
+var CANVAS_SUPERSAMPLE = 1.3;
+function computeTargetScale(dpr, zoom) {
+  const safeZoom = Math.max(Number.isFinite(zoom) ? zoom : 0, 0.01);
+  return dpr * safeZoom * (safeZoom > 1 ? CANVAS_SUPERSAMPLE : 1);
+}
+var IS_MOBILE_DEVICE = typeof navigator !== "undefined" && (/Android|iPhone|iPad|iPod/i.test(navigator.userAgent) || navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1);
+var CANVAS_AREA_FACTOR = IS_MOBILE_DEVICE ? 1.5 : 3;
+function getCanvasPixelBudget() {
+  if (typeof window === "undefined" || typeof screen === "undefined") {
+    return MAX_CANVAS_PIXELS;
+  }
+  const dpr = window.devicePixelRatio || 1;
+  const screenArea = (screen.width || 0) * (screen.height || 0) * dpr * dpr;
+  if (!Number.isFinite(screenArea) || screenArea <= 0) {
+    return MAX_CANVAS_PIXELS;
+  }
+  return Math.min(MAX_CANVAS_PIXELS, screenArea * CANVAS_AREA_FACTOR);
+}
+function clampScaleForPage(targetScale, pageWidth, pageHeight, maxPixels = MAX_CANVAS_PIXELS) {
   if (!targetScale) {
     return 0;
   }
-  const areaLimit = Math.sqrt(
-    MAX_CANVAS_PIXELS / Math.max(pageWidth * pageHeight, 1)
-  );
+  const areaLimit = Math.sqrt(maxPixels / Math.max(pageWidth * pageHeight, 1));
   const widthLimit = MAX_CANVAS_DIMENSION / Math.max(pageWidth, 1);
   const heightLimit = MAX_CANVAS_DIMENSION / Math.max(pageHeight, 1);
   const safeScale = Math.min(
@@ -1392,6 +1408,14 @@ function clampScaleForPage(targetScale, pageWidth, pageHeight) {
   );
   return Math.max(safeScale, 0);
 }
+function computeBaseScale(dpr, zoom, pageWidth, pageHeight) {
+  return clampScaleForPage(
+    computeTargetScale(dpr, zoom),
+    pageWidth,
+    pageHeight,
+    getCanvasPixelBudget()
+  );
+}
 
 // src/lib/recolor-context.ts
 var RECOLOR_CLEANUP = Symbol("lectorRecolorCleanup");
@@ -1515,47 +1539,89 @@ function applyContextRecolor(ctx, map) {
 function removeContextRecolor(ctx) {
   ctx[RECOLOR_CLEANUP]?.();
 }
+var DPR_CAP = 3;
+var readDpr = () => typeof window === "undefined" ? 1 : Math.min(window.devicePixelRatio || 1, DPR_CAP);
 var useDpr = () => {
-  const [dpr, setDPR] = useState(
-    typeof window === "undefined" ? 1 : Math.min(window.devicePixelRatio, 2)
-  );
+  const [dpr, setDpr] = useState(readDpr);
   useEffect(() => {
     if (typeof window === "undefined") {
       return;
     }
-    const handleDPRChange = () => {
-      setDPR(Math.min(window.devicePixelRatio, 2));
+    let mediaQuery = null;
+    let cancelled = false;
+    const handleChange = () => {
+      if (cancelled) {
+        return;
+      }
+      setDpr(readDpr());
+      subscribe();
     };
-    const windowMatch = window.matchMedia(
-      `screen and (min-resolution: ${dpr}dppx)`
-    );
-    windowMatch.addEventListener("change", handleDPRChange);
+    const unlisten = (mql) => {
+      if (!mql) return;
+      if (typeof mql.removeEventListener === "function") {
+        mql.removeEventListener("change", handleChange);
+      } else {
+        mql.removeListener(handleChange);
+      }
+    };
+    const subscribe = () => {
+      unlisten(mediaQuery);
+      const ratio = window.devicePixelRatio || 1;
+      mediaQuery = window.matchMedia(
+        `(resolution: ${ratio}dppx), (-webkit-device-pixel-ratio: ${ratio})`
+      );
+      if (typeof mediaQuery.addEventListener === "function") {
+        mediaQuery.addEventListener("change", handleChange, { once: true });
+      } else {
+        mediaQuery.addListener(handleChange);
+      }
+    };
+    setDpr(readDpr());
+    subscribe();
     return () => {
-      windowMatch.removeEventListener("change", handleDPRChange);
+      cancelled = true;
+      unlisten(mediaQuery);
     };
-  }, [dpr]);
+  }, []);
   return dpr;
 };
 
 // src/hooks/layers/useCanvasLayer.tsx
-var CACHE_MAX = 60;
+var CACHE_MAX_ENTRIES = 60;
+var CACHE_MAX_BYTES = (IS_MOBILE_DEVICE ? 64 : 192) * 1024 * 1024;
+var CACHE_MAX_ENTRY_BYTES = IS_MOBILE_DEVICE ? CACHE_MAX_BYTES / 3 : CACHE_MAX_BYTES / 4;
+var MAX_VARIANTS_PER_PROXY = 2;
 var cacheEntries = [];
 var canvasBitmapCache = /* @__PURE__ */ new WeakMap();
+var cacheBytes = 0;
+var documentIdFallbacks = /* @__PURE__ */ new WeakMap();
+var documentIdCounter = 0;
+function getDocumentCacheId(pdfDocumentProxy) {
+  const fingerprint = pdfDocumentProxy.fingerprints?.[0];
+  if (fingerprint) return fingerprint;
+  let id = documentIdFallbacks.get(pdfDocumentProxy);
+  if (!id) {
+    documentIdCounter += 1;
+    id = `anonymous-document-${documentIdCounter}`;
+    documentIdFallbacks.set(pdfDocumentProxy, id);
+  }
+  return id;
+}
+function evictEntryAt(index) {
+  const [entry] = cacheEntries.splice(index, 1);
+  if (!entry) return;
+  cacheBytes -= entry.bytes;
+  const map = canvasBitmapCache.get(entry.proxy);
+  if (map?.get(entry.key) === entry.bitmap) {
+    map.delete(entry.key);
+  }
+  entry.bitmap.close();
+}
 function clearBitmapCache(documentId) {
-  if (documentId === void 0) {
-    for (const entry of cacheEntries) {
-      entry.bitmap.close();
-      canvasBitmapCache.get(entry.proxy)?.delete(entry.key);
-    }
-    cacheEntries.length = 0;
-    return;
-  }
   for (let i = cacheEntries.length - 1; i >= 0; i--) {
-    const entry = cacheEntries[i];
-    if (entry.docId !== documentId) continue;
-    entry.bitmap.close();
-    canvasBitmapCache.get(entry.proxy)?.delete(entry.key);
-    cacheEntries.splice(i, 1);
+    if (documentId === void 0 || cacheEntries[i].docId === documentId) {
+      evictEntryAt(i);
+    }
   }
 }
 function cacheKey(scale, background, recolorKey) {
@@ -1578,40 +1644,49 @@ function getCachedBitmap(proxy, scale, background, recolorKey) {
   return bitmap;
 }
 function setCachedBitmap(docId, proxy, scale, background, recolorKey, bitmap) {
+  const bytes = bitmap.width * bitmap.height * 4;
+  if (bytes > CACHE_MAX_ENTRY_BYTES) {
+    bitmap.close();
+    return;
+  }
   const key = cacheKey(scale, background, recolorKey);
+  const existingIdx = cacheEntries.findIndex(
+    (e) => e.proxy === proxy && e.key === key
+  );
+  if (existingIdx !== -1) {
+    if (cacheEntries[existingIdx].bitmap === bitmap) return;
+    evictEntryAt(existingIdx);
+  }
   let map = canvasBitmapCache.get(proxy);
   if (!map) {
     map = /* @__PURE__ */ new Map();
     canvasBitmapCache.set(proxy, map);
   }
-  const existing = map.get(key);
-  if (existing && existing !== bitmap) {
-    existing.close();
-    const idx = cacheEntries.findIndex(
-      (e) => e.proxy === proxy && e.key === key
-    );
-    if (idx !== -1) cacheEntries.splice(idx, 1);
-  }
   map.set(key, bitmap);
-  cacheEntries.push({ docId, proxy, key, bitmap });
-  while (cacheEntries.length > CACHE_MAX) {
-    const evicted = cacheEntries.shift();
-    const evictedMap = canvasBitmapCache.get(evicted.proxy);
-    if (evictedMap?.get(evicted.key) === evicted.bitmap) {
-      evictedMap.delete(evicted.key);
-      evicted.bitmap.close();
+  cacheEntries.push({ docId, proxy, key, bitmap, bytes });
+  cacheBytes += bytes;
+  let variants = 0;
+  for (let i = cacheEntries.length - 1; i >= 0; i--) {
+    if (cacheEntries[i].proxy !== proxy) continue;
+    variants++;
+    if (variants > MAX_VARIANTS_PER_PROXY) {
+      evictEntryAt(i);
     }
   }
+  while (cacheEntries.length > 0 && (cacheEntries.length > CACHE_MAX_ENTRIES || cacheBytes > CACHE_MAX_BYTES)) {
+    evictEntryAt(0);
+  }
 }
 var useCanvasLayer = ({ background }) => {
   const canvasRef = useRef(null);
-  const paintedKeyRef = useRef(null);
+  const paintedRef = useRef(null);
   const pageNumber = usePDFPageNumber();
   const store = PDFStore.useContext();
   const dpr = useDpr();
   const bouncyZoom = usePdf((state) => state.zoom);
   const isResizing = usePdf((state) => state.isResizing);
-  const docId = usePdf((state) => state.pdfDocumentProxy.fingerprints[0] ?? "");
+  const isPinching = usePdf((state) => state.isPinching);
+  const docId = usePdf((state) => getDocumentCacheId(state.pdfDocumentProxy));
   const pdfPageProxy = usePdf((state) => state.getPdfPageProxy(pageNumber));
   const markPageRendered = usePdf((state) => state.markPageRendered);
   const unmarkPageRendered = usePdf((state) => state.unmarkPageRendered);
@@ -1627,29 +1702,52 @@ var useCanvasLayer = ({ background }) => {
     const pageWidth = baseViewport.width;
     const pageHeight = baseViewport.height;
     const contentKey = `${background ?? "white"}|${recolorKey ?? ""}`;
-    if (isResizing && paintedKeyRef.current === contentKey) {
+    const baseScale = computeBaseScale(dpr, zoom, pageWidth, pageHeight);
+    const hasCurrentFrame = paintedRef.current?.proxy === pdfPageProxy && paintedRef.current?.key === contentKey;
+    const geometryZoom = Math.max(Number.isFinite(zoom) ? zoom : 0, 0.01);
+    const applyGeometry = () => {
+      if (geometryZoom === 1) {
+        baseCanvas.style.width = `${pageWidth}px`;
+        baseCanvas.style.height = `${pageHeight}px`;
+        baseCanvas.style.transform = "translate(0px, 0px)";
+      } else {
+        baseCanvas.style.width = `${pageWidth * geometryZoom}px`;
+        baseCanvas.style.height = `${pageHeight * geometryZoom}px`;
+        baseCanvas.style.transform = `scale3d(${1 / geometryZoom},${1 / geometryZoom},1)`;
+        baseCanvas.style.transformOrigin = "0 0";
+      }
+    };
+    if (hasCurrentFrame && paintedRef.current?.scale === baseScale) {
+      applyGeometry();
+      return;
+    }
+    if ((isResizing || isPinching) && hasCurrentFrame) {
       baseCanvas.style.visibility = "";
-      baseCanvas.style.width = `${pageWidth}px`;
-      baseCanvas.style.height = `${pageHeight}px`;
       return;
     }
-    paintedKeyRef.current = null;
-    const targetBaseScale = dpr * Math.min(zoom, 1);
-    const baseScale = clampScaleForPage(targetBaseScale, pageWidth, pageHeight);
-    baseCanvas.width = Math.floor(pageWidth * baseScale);
-    baseCanvas.height = Math.floor(pageHeight * baseScale);
     baseCanvas.style.position = "absolute";
     baseCanvas.style.top = "0";
     baseCanvas.style.left = "0";
-    baseCanvas.style.width = `${pageWidth}px`;
-    baseCanvas.style.height = `${pageHeight}px`;
-    baseCanvas.style.transform = "translate(0px, 0px)";
+    applyGeometry();
     baseCanvas.style.zIndex = "0";
     baseCanvas.style.pointerEvents = "none";
     baseCanvas.style.backgroundColor = recolor ? recolor(background ?? "#ffffff") : background ?? "white";
-    baseCanvas.style.visibility = "";
+    const backingWidth = Math.floor(pageWidth * baseScale);
+    const backingHeight = Math.floor(pageHeight * baseScale);
     const context = baseCanvas.getContext("2d");
-    if (!context) return;
+    if (!context) {
+      if (!hasCurrentFrame) {
+        paintedRef.current = null;
+        baseCanvas.width = backingWidth;
+        baseCanvas.height = backingHeight;
+        baseCanvas.style.visibility = "hidden";
+      }
+      return;
+    }
+    const applyBackingSize = () => {
+      baseCanvas.width = backingWidth;
+      baseCanvas.height = backingHeight;
+    };
     const cached = getCachedBitmap(
       pdfPageProxy,
       baseScale,
@@ -1657,23 +1755,41 @@ var useCanvasLayer = ({ background }) => {
       recolorKey
     );
     if (cached) {
+      applyBackingSize();
       context.drawImage(cached, 0, 0);
+      baseCanvas.style.visibility = "";
       markPageRendered(pageNumber);
-      paintedKeyRef.current = contentKey;
+      paintedRef.current = {
+        proxy: pdfPageProxy,
+        key: contentKey,
+        scale: baseScale
+      };
       return;
     }
-    context.setTransform(1, 0, 0, 1, 0, 0);
-    context.clearRect(0, 0, baseCanvas.width, baseCanvas.height);
-    baseCanvas.style.visibility = "hidden";
+    const hideUntilPainted = () => {
+      paintedRef.current = null;
+      applyBackingSize();
+      baseCanvas.style.visibility = "hidden";
+    };
+    if (!hasCurrentFrame) {
+      hideUntilPainted();
+    }
     let cancelled = false;
     const viewport = pdfPageProxy.getViewport({ scale: baseScale });
     const buffer = document.createElement("canvas");
-    buffer.width = baseCanvas.width;
-    buffer.height = baseCanvas.height;
+    buffer.width = backingWidth;
+    buffer.height = backingHeight;
     const bufferCtx = buffer.getContext("2d");
     const useBuffer = bufferCtx !== null;
+    if (!useBuffer && hasCurrentFrame) {
+      hideUntilPainted();
+    }
     const renderCanvas = useBuffer ? buffer : baseCanvas;
     const renderCtx = bufferCtx ?? context;
+    const releaseBuffer = () => {
+      buffer.width = 0;
+      buffer.height = 0;
+    };
     let restoreRecolor = null;
     if (recolor) {
       restoreRecolor = applyContextRecolor(renderCtx, recolor);
@@ -1690,12 +1806,9 @@ var useCanvasLayer = ({ background }) => {
       });
     } catch (error) {
       restoreRecolor?.();
+      releaseBuffer();
       throw error;
     }
-    const releaseBuffer = () => {
-      buffer.width = 0;
-      buffer.height = 0;
-    };
     renderingTask.promise.finally(() => {
       restoreRecolor?.();
     }).then(() => {
@@ -1710,13 +1823,17 @@ var useCanvasLayer = ({ background }) => {
         return;
       }
       if (useBuffer) {
-        context.clearRect(0, 0, baseCanvas.width, baseCanvas.height);
+        applyBackingSize();
         context.drawImage(buffer, 0, 0);
       }
       baseCanvas.style.visibility = "";
       markPageRendered(pageNumber);
-      paintedKeyRef.current = contentKey;
-      if (typeof createImageBitmap !== "undefined") {
+      paintedRef.current = {
+        proxy: pdfPageProxy,
+        key: contentKey,
+        scale: baseScale
+      };
+      if (typeof createImageBitmap !== "undefined" && renderCanvas.width * renderCanvas.height * 4 <= CACHE_MAX_ENTRY_BYTES) {
         createImageBitmap(renderCanvas).then((bitmap) => {
           if (cancelled) {
             bitmap.close();
@@ -1752,6 +1869,7 @@ var useCanvasLayer = ({ background }) => {
     dpr,
     zoom,
     isResizing,
+    isPinching,
     pageNumber,
     markPageRendered,
     docId,
@@ -1767,6 +1885,7 @@ var useCanvasLayer = ({ background }) => {
         canvas.width = 0;
         canvas.height = 0;
       }
+      paintedRef.current = null;
     };
   }, [pageNumber, unmarkPageRendered]);
   return {
@@ -1839,6 +1958,12 @@ var subscribeToViewportInvalidation = (viewport, callback) => {
 
 // src/hooks/layers/useDetailCanvasLayer.tsx
 var DETAIL_RENDER_IDLE_MS = 80;
+var SCROLL_POLL_MS = 160;
+var ZOOM_DEBOUNCE_MS = 200;
+var ZOOM_SETTLE_MS = ZOOM_DEBOUNCE_MS + 50;
+var OVERSCAN_X = 0.25;
+var OVERSCAN_Y = 0.5;
+var RELEASE_HIDDEN_MS = 2e3;
 var useDetailCanvasLayer = ({
   background,
   baseCanvasRef
@@ -1849,15 +1974,23 @@ var useDetailCanvasLayer = ({
   const dpr = useDpr();
   const store = PDFStore.useContext();
   const bouncyZoom = usePdf((state) => state.zoom);
-  const isPinching = usePdf((state) => state.isPinching);
   const pdfPageProxy = usePdf((state) => state.getPdfPageProxy(pageNumber));
   const viewportRef = usePdf((state) => state.viewportRef);
   const colorScheme = usePdf((state) => state.colorScheme);
   const darkModeColors = usePdf((state) => state.darkModeColors);
   const recolor = colorScheme === "dark" ? createDarkModeColorMap(darkModeColors) : null;
   const recolorKey = recolor ? `dark:${darkModeColors.background},${darkModeColors.foreground}` : "light";
-  const paintedKeyRef = useRef(null);
-  const [zoom] = useDebounce(bouncyZoom, 200);
+  const paintedRef = useRef(null);
+  const releaseTimerRef = useRef(null);
+  const [zoom] = useDebounce(bouncyZoom, ZOOM_DEBOUNCE_MS);
+  const lastZoomChangeRef = useRef(
+    store.getState().isPinching ? performance.now() : 0
+  );
+  const prevBouncyZoomRef = useRef(bouncyZoom);
+  if (prevBouncyZoomRef.current !== bouncyZoom) {
+    prevBouncyZoomRef.current = bouncyZoom;
+    lastZoomChangeRef.current = performance.now();
+  }
   const pageDimsRef = useRef(null);
   if (!pageDimsRef.current || pageDimsRef.current.proxy !== pdfPageProxy) {
     const vp = pdfPageProxy.getViewport({ scale: 1 });
@@ -1879,35 +2012,52 @@ var useDetailCanvasLayer = ({
     }
     let renderingTask = null;
     let renderTimeoutId = null;
-    const bgColor = recolor ? recolor(background ?? "#ffffff") : background ?? "white";
     const contentKey = `${background ?? "white"}|${recolorKey}`;
-    const detailBaseStyle = `position:absolute;top:0;left:0;pointer-events:none;z-index:1;background-color:${bgColor}`;
+    const detailBaseStyle = "position:absolute;top:0;left:0;pointer-events:none;z-index:1";
     const hideDetailCanvas = () => {
       renderingTask?.cancel();
+      renderingTask = null;
       detailCanvas.style.cssText = `${detailBaseStyle};display:block;opacity:0`;
       container.style.cssText = "";
+      paintedRef.current = null;
+      if (releaseTimerRef.current === null) {
+        releaseTimerRef.current = setTimeout(() => {
+          releaseTimerRef.current = null;
+          detailCanvas.width = 1;
+          detailCanvas.height = 1;
+        }, RELEASE_HIDDEN_MS);
+      }
     };
+    const pageDims = pageDimsRef.current;
+    if (!pageDims) {
+      hideDetailCanvas();
+      return;
+    }
+    const { width: pageWidth, height: pageHeight } = pageDims;
+    const targetDetailScale = computeTargetScale(dpr, zoom);
+    const baseScale = computeBaseScale(dpr, zoom, pageWidth, pageHeight);
+    const needsDetail = targetDetailScale - baseScale > 1e-3;
     const renderDetailCanvas = () => {
+      if (targetDetailScale - computeBaseScale(dpr, zoom, pageWidth, pageHeight) <= 1e-3) {
+        hideDetailCanvas();
+        return;
+      }
       const virtualizer = store.getState().virtualizer;
       if (virtualizer?.isScrolling) {
-        scheduleRender(160);
+        scheduleRender(SCROLL_POLL_MS);
         return;
       }
-      const pageContainer = baseCanvasRef.current?.parentElement ?? null;
-      if (!pageContainer) {
-        hideDetailCanvas();
+      const settleElapsed = performance.now() - lastZoomChangeRef.current;
+      if (store.getState().isPinching || settleElapsed < ZOOM_SETTLE_MS) {
+        scheduleRender(Math.max(50, ZOOM_SETTLE_MS - settleElapsed + 10));
         return;
       }
-      const { width: pageWidth, height: pageHeight } = pageDimsRef.current;
-      const targetDetailScale = dpr * zoom * 1.3;
-      const baseTargetScale = dpr * Math.min(zoom, 1);
-      const baseScale = clampScaleForPage(
-        baseTargetScale,
-        pageWidth,
-        pageHeight
-      );
-      const needsDetail = zoom > 1 && targetDetailScale - baseScale > 1e-3;
-      if (isPinching || !needsDetail) {
+      if (store.getState().zoom !== zoom) {
+        scheduleRender(ZOOM_SETTLE_MS);
+        return;
+      }
+      const pageContainer = baseCanvasRef.current?.parentElement ?? null;
+      if (!pageContainer) {
         hideDetailCanvas();
         return;
       }
@@ -1935,17 +2085,72 @@ var useDetailCanvasLayer = ({
         hideDetailCanvas();
         return;
       }
+      const budget = getCanvasPixelBudget();
+      let effectiveScale = clampScaleForPage(
+        targetDetailScale,
+        visibleWidth,
+        visibleHeight,
+        budget
+      );
+      const padX = OVERSCAN_X * viewportWidth;
+      const padY = OVERSCAN_Y * viewportHeight;
+      const maxRectWidth = Math.min(pageWidth, visibleWidth + 2 * padX);
+      const maxRectHeight = Math.min(pageHeight, visibleHeight + 2 * padY);
+      effectiveScale = Math.min(
+        effectiveScale,
+        MAX_CANVAS_DIMENSION / Math.max(maxRectWidth, 1),
+        MAX_CANVAS_DIMENSION / Math.max(maxRectHeight, 1)
+      );
+      const eps = 1 / effectiveScale;
+      const painted = paintedRef.current;
+      if (painted && painted.proxy === pdfPageProxy && painted.key === contentKey && painted.scale === effectiveScale && visibleLeft >= painted.left - eps && visibleTop >= painted.top - eps && visibleRight <= painted.left + painted.width + eps && visibleBottom <= painted.top + painted.height + eps) {
+        renderingTask?.cancel();
+        renderingTask = null;
+        return;
+      }
+      const maxArea = budget / (effectiveScale * effectiveScale);
+      const a = 4 * padX * padY;
+      const b = 2 * (visibleWidth * padY + visibleHeight * padX);
+      const c = visibleWidth * visibleHeight - maxArea;
+      let padFactor = 1;
+      if (a > 0) {
+        padFactor = Math.min(
+          1,
+          Math.max(
+            0,
+            (-b + Math.sqrt(Math.max(b * b - 4 * a * c, 0))) / (2 * a)
+          )
+        );
+      } else if (b > 0) {
+        padFactor = Math.min(1, Math.max(0, -c / b));
+      }
+      const rectLeft = Math.max(0, visibleLeft - padX * padFactor);
+      const rectTop = Math.max(0, visibleTop - padY * padFactor);
+      const rectRight = Math.min(pageWidth, visibleRight + padX * padFactor);
+      const rectBottom = Math.min(pageHeight, visibleBottom + padY * padFactor);
+      const rectWidth = rectRight - rectLeft;
+      const rectHeight = rectBottom - rectTop;
       renderingTask?.cancel();
-      const pdfOffsetX = visibleLeft;
-      const pdfOffsetY = visibleTop;
-      const effectiveScale = targetDetailScale;
-      const actualWidth = visibleWidth * effectiveScale;
-      const actualHeight = visibleHeight * effectiveScale;
+      if (releaseTimerRef.current !== null) {
+        clearTimeout(releaseTimerRef.current);
+        releaseTimerRef.current = null;
+      }
+      const actualWidth = Math.max(1, Math.floor(rectWidth * effectiveScale));
+      const actualHeight = Math.max(1, Math.floor(rectHeight * effectiveScale));
       const buffer = document.createElement("canvas");
       buffer.width = actualWidth;
       buffer.height = actualHeight;
       const bufferCtx = buffer.getContext("2d");
       if (!bufferCtx) {
+        buffer.width = 0;
+        buffer.height = 0;
+        hideDetailCanvas();
+        if (releaseTimerRef.current !== null) {
+          clearTimeout(releaseTimerRef.current);
+          releaseTimerRef.current = null;
+        }
+        detailCanvas.width = 1;
+        detailCanvas.height = 1;
         return;
       }
       bufferCtx.setTransform(1, 0, 0, 1, 0, 0);
@@ -1954,21 +2159,35 @@ var useDetailCanvasLayer = ({
         0,
         0,
         1,
-        -pdfOffsetX * effectiveScale,
-        -pdfOffsetY * effectiveScale
+        -rectLeft * effectiveScale,
+        -rectTop * effectiveScale
       ];
       const detailViewport = pdfPageProxy.getViewport({
         scale: effectiveScale
       });
       if (recolor) applyContextRecolor(bufferCtx, recolor);
-      const currentRenderingTask = pdfPageProxy.render({
-        canvas: buffer,
-        canvasContext: bufferCtx,
-        viewport: detailViewport,
-        background,
-        transform
-      });
+      const releaseBuffer = () => {
+        buffer.width = 0;
+        buffer.height = 0;
+      };
+      let currentRenderingTask;
+      try {
+        currentRenderingTask = pdfPageProxy.render({
+          canvas: buffer,
+          canvasContext: bufferCtx,
+          viewport: detailViewport,
+          background,
+          transform
+        });
+      } catch (error) {
+        releaseBuffer();
+        hideDetailCanvas();
+        console.error("PDF detail render error:", error);
+        return;
+      }
       renderingTask = currentRenderingTask;
+      const cssWidth = actualWidth / effectiveScale * zoom;
+      const cssHeight = actualHeight / effectiveScale * zoom;
       currentRenderingTask.promise.then(() => {
         if (renderingTask !== currentRenderingTask) return;
         const state = store.getState();
@@ -1976,13 +2195,36 @@ var useDetailCanvasLayer = ({
         if (currentRecolorKey !== recolorKey) return;
         detailCanvas.width = actualWidth;
         detailCanvas.height = actualHeight;
-        detailCanvas.style.cssText = `${detailBaseStyle};display:block;opacity:1;width:${visibleWidth * zoom}px;height:${visibleHeight * zoom}px;transform-origin:center center;transform:translate(${visibleLeft * zoom}px,${visibleTop * zoom}px)`;
+        detailCanvas.style.cssText = `${detailBaseStyle};display:block;opacity:1;width:${cssWidth}px;height:${cssHeight}px;transform-origin:center center;transform:translate(${rectLeft * zoom}px,${rectTop * zoom}px)`;
         container.style.cssText = `transform:scale3d(${1 / zoom},${1 / zoom},1);transform-origin:0 0`;
         const ctx = detailCanvas.getContext("2d");
-        if (ctx) {
+        if (!ctx) {
+          hideDetailCanvas();
+          return;
+        }
+        try {
           ctx.drawImage(buffer, 0, 0);
+        } catch (error) {
+          hideDetailCanvas();
+          console.error("PDF detail canvas blit error:", error);
+          return;
+        }
+        paintedRef.current = {
+          proxy: pdfPageProxy,
+          key: contentKey,
+          scale: effectiveScale,
+          left: rectLeft,
+          top: rectTop,
+          // The truly painted extent comes from the floored backing,
+          // not the requested rect.
+          width: actualWidth / effectiveScale,
+          height: actualHeight / effectiveScale
+        };
+        if (releaseTimerRef.current !== null) {
+          clearTimeout(releaseTimerRef.current);
+          releaseTimerRef.current = null;
         }
-        paintedKeyRef.current = contentKey;
+        scheduleRender();
       }).catch((error) => {
         if (error.name === "RenderingCancelledException") {
           return;
@@ -1992,15 +2234,13 @@ var useDetailCanvasLayer = ({
         if (renderingTask === currentRenderingTask) {
           renderingTask = null;
         }
-        buffer.width = 0;
-        buffer.height = 0;
+        releaseBuffer();
       });
     };
     const scheduleRender = (delay = DETAIL_RENDER_IDLE_MS) => {
       if (renderTimeoutId !== null) {
         clearTimeout(renderTimeoutId);
       }
-      renderingTask?.cancel();
       renderTimeoutId = setTimeout(() => {
         renderTimeoutId = null;
         renderDetailCanvas();
@@ -2010,12 +2250,11 @@ var useDetailCanvasLayer = ({
       scrollContainer,
       scheduleRender
     );
-    if (zoom <= 1 || isPinching) {
+    if (!needsDetail) {
       hideDetailCanvas();
     } else {
-      if (paintedKeyRef.current !== null && paintedKeyRef.current !== contentKey) {
+      if (paintedRef.current !== null && (paintedRef.current.key !== contentKey || paintedRef.current.proxy !== pdfPageProxy)) {
         hideDetailCanvas();
-        paintedKeyRef.current = null;
       }
       scheduleRender(0);
     }
@@ -2029,7 +2268,6 @@ var useDetailCanvasLayer = ({
   }, [
     pdfPageProxy,
     zoom,
-    isPinching,
     background,
     dpr,
     viewportRef,
@@ -2041,10 +2279,15 @@ var useDetailCanvasLayer = ({
   useEffect(() => {
     const canvas = detailCanvasRef.current;
     return () => {
+      if (releaseTimerRef.current !== null) {
+        clearTimeout(releaseTimerRef.current);
+        releaseTimerRef.current = null;
+      }
       if (canvas) {
         canvas.width = 1;
         canvas.height = 1;
       }
+      paintedRef.current = null;
     };
   }, []);
   return {
@@ -3080,6 +3323,7 @@ var useTextLayer = () => {
   const pageNumber = usePDFPageNumber();
   const pdfPageProxy = usePdf((state) => state.getPdfPageProxy(pageNumber));
   const viewportRef = usePdf((state) => state.viewportRef);
+  const store = PDFStore.useContext();
   useEffect(() => {
     const textContainer = textContainerRef.current;
     if (!textContainer) {
@@ -3184,11 +3428,22 @@ var useTextLayer = () => {
     const show = () => {
       textContainer.style.visibility = "";
     };
-    const onScroll = () => {
+    const restoreWhenSettled = () => {
+      settleTimer = null;
+      if (store.getState().isPinching) {
+        settleTimer = setTimeout(restoreWhenSettled, TEXT_SCROLL_SETTLE_MS);
+        return;
+      }
+      show();
+    };
+    const hideAndDebounce = () => {
       if (selecting) return;
       textContainer.style.visibility = "hidden";
       if (settleTimer) clearTimeout(settleTimer);
-      settleTimer = setTimeout(show, TEXT_SCROLL_SETTLE_MS);
+      settleTimer = setTimeout(restoreWhenSettled, TEXT_SCROLL_SETTLE_MS);
+    };
+    const onScroll = () => {
+      hideAndDebounce();
     };
     const onPointerDown = () => {
       pointerDown = true;
@@ -3220,6 +3475,19 @@ var useTextLayer = () => {
       unsubscribe = subscribeToViewportInvalidation(scrollViewport, onScroll);
     };
     attachScrollSubscription();
+    const initialState = store.getState();
+    let prevZoom = initialState.zoom;
+    let prevPinching = initialState.isPinching;
+    if (prevPinching) hideAndDebounce();
+    const unsubscribeStore = store.subscribe(
+      (state) => {
+        const zoomChanged = state.zoom !== prevZoom;
+        const pinchStarted = state.isPinching && !prevPinching;
+        prevZoom = state.zoom;
+        prevPinching = state.isPinching;
+        if (zoomChanged || pinchStarted) hideAndDebounce();
+      }
+    );
     document.addEventListener("pointerdown", onPointerDown, true);
     document.addEventListener("pointerup", clearPointer, true);
     document.addEventListener("pointercancel", clearPointer, true);
@@ -3228,6 +3496,7 @@ var useTextLayer = () => {
     return () => {
       if (attachRaf !== null) cancelAnimationFrame(attachRaf);
       unsubscribe?.();
+      unsubscribeStore();
       document.removeEventListener("pointerdown", onPointerDown, true);
       document.removeEventListener("pointerup", clearPointer, true);
       document.removeEventListener("pointercancel", clearPointer, true);
@@ -3236,7 +3505,7 @@ var useTextLayer = () => {
       if (settleTimer) clearTimeout(settleTimer);
       show();
     };
-  }, [viewportRef]);
+  }, [viewportRef, store]);
   return {
     textContainerRef,
     pageNumber: pdfPageProxy.pageNumber
@@ -5600,10 +5869,10 @@ var useViewportContainer = ({
   const transformations = useRef({
     translateX: 0,
     translateY: 0,
-    zoom
+    zoom: 1
   });
   const zoomRafRef = useRef(null);
-  const lastPushedZoomRef = useRef(zoom);
+  const lastPushedZoomRef = useRef(null);
   const updateTransform = useCallback(
     (zoomUpdate) => {
       if (!elementRef.current || !containerRef.current || !elementWrapperRef.current) {
@@ -5640,8 +5909,14 @@ var useViewportContainer = ({
       return;
     }
     if (zoom === lastPushedZoomRef.current) {
+      lastPushedZoomRef.current = null;
       return;
     }
+    if (zoomRafRef.current !== null) {
+      cancelAnimationFrame(zoomRafRef.current);
+      zoomRafRef.current = null;
+    }
+    lastPushedZoomRef.current = null;
     const prevZoom = transformations.current.zoom;
     if (!prevZoom || !Number.isFinite(prevZoom)) {
       transformations.current = {
@@ -5871,7 +6146,13 @@ var Pages = ({
     overscan: virtualizerOptions?.overscan ?? 0,
     scrollToFn,
     gap,
-    initialOffset
+    initialOffset,
+    // Never trust scrollend alone to reset isScrolling: a single missed
+    // event (a documented browser flake — TanStack flipped this default to
+    // false in later 3.x) would pin isScrolling=true forever, and every
+    // consumer gated on it (text layer, detail canvas) would stop painting.
+    // false keeps the isScrollingResetDelay debounce active as a fallback.
+    useScrollendEvent: false
   });
   useEffect(() => {
     if (onOffsetChange && virtualizer.scrollOffset)
@@ -6298,7 +6579,8 @@ var Root = forwardRef(
     const linkService = useCreatePDFLinkService(
       initialState?.pdfDocumentProxy ?? null
     );
-    const documentId = initialState?.pdfDocumentProxy?.fingerprints?.[0];
+    const pdfDocumentProxy = initialState?.pdfDocumentProxy ?? null;
+    const documentId = pdfDocumentProxy ? getDocumentCacheId(pdfDocumentProxy) : null;
     useEffect(() => {
       if (!documentId) return;
       return () => {
@@ -6357,6 +6639,7 @@ var useThumbnail = (pageNumber, config = {}) => {
   const containerRef = useRef(null);
   const canvasRef = useRef(null);
   const renderTaskRef = useRef(null);
+  const renderedProxyRef = useRef(null);
   const pageProxy = usePdf((state) => state.getPdfPageProxy(pageNumber));
   const { visible } = useVisibility({ elementRef: containerRef });
   const [debouncedVisible] = useDebounce(visible, 50);
@@ -6366,6 +6649,8 @@ var useThumbnail = (pageNumber, config = {}) => {
   const recolor = colorScheme === "dark" ? createDarkModeColorMap(darkModeColors) : null;
   const isVisible = isFirstPage || debouncedVisible;
   useEffect(() => {
+    if (!isVisible && renderedProxyRef.current !== pageProxy) return;
+    renderedProxyRef.current = pageProxy;
     const renderThumbnail = async () => {
       const canvas2 = canvasRef.current;
       if (!canvas2 || !pageProxy) return;
@@ -6374,7 +6659,11 @@ var useThumbnail = (pageNumber, config = {}) => {
           renderTaskRef.current.cancel();
         }
         const viewport = pageProxy.getViewport({ scale: 1 });
-        const scale = Math.min(maxWidth / viewport.width, maxHeight / viewport.height) * (isVisible ? dpr : 0.5);
+        const scale = clampScaleForPage(
+          Math.min(maxWidth / viewport.width, maxHeight / viewport.height) * (isVisible ? dpr : 0.5),
+          viewport.width,
+          viewport.height
+        );
         const scaledViewport = pageProxy.getViewport({ scale });
         canvas2.width = scaledViewport.width;
         canvas2.height = scaledViewport.height;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anaralabs/lector",
-  "version": "3.13.0",
+  "version": "3.13.2",
   "description": "A headless PDF viewer for React",
   "author": "andrewdr (https://github.com/andrewdoro)",
   "license": "MIT",