@vue-pdf-viewer/viewer 3.5.2-rc.0 → 3.6.0-beta.0

package/dist/types/components/LayerCanvas.vue.d.ts

@@ -1,12 +1,11 @@
 import type { PDFPageProxy } from 'pdfjs-dist';
-import type { CanvasLoadedCallback } from '@/utils/types';
+import type { CanvasLoadedCallback, VisibleArea } from '@/utils/types';
 interface OwnProps {
     page: PDFPageProxy;
-    width: number;
-    height: number;
     pageIndex: number;
     intersecting: boolean;
     afterCanvasLoaded?: CanvasLoadedCallback;
+    visibleArea?: VisibleArea;
 }
 declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<OwnProps>>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     rendered: (canvasWrapperElement: HTMLDivElement) => void;

package/dist/types/components/LayerCanvasDetail.vue.d.ts

@@ -0,0 +1,23 @@
+import type { PDFPageProxy } from 'pdfjs-dist';
+import type { VisibleArea } from '@/utils/types';
+interface OwnProps {
+    page: PDFPageProxy;
+    pageIndex: number;
+    visibleArea: VisibleArea;
+    viewport: any;
+    maxCanvasPixels: number;
+    capAreaFactor: number;
+    queueRenderTask: any;
+    annotationMode: number;
+}
+declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<OwnProps>>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<OwnProps>>> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;
+type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+type __VLS_TypePropsToRuntimeProps<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};

package/dist/types/components/ToolZoom.vue.d.ts

@@ -1,9 +1,7 @@
-import { ViewerPdfPage } from '../utils/types';
 import { ZoomLevel } from '@/utils/enumerators';
 declare const _default: {
     new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<{
         scale: number;
-        focusedPage?: Omit<ViewerPdfPage, "page"> | undefined;
         pagesContainer?: HTMLDivElement | undefined;
     }>>> & Readonly<{
         onZoom?: ((nextScale: number | ZoomLevel) => any) | undefined;
@@ -18,7 +16,6 @@ declare const _default: {
         Defaults: {};
     }, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<{
         scale: number;
-        focusedPage?: Omit<ViewerPdfPage, "page"> | undefined;
         pagesContainer?: HTMLDivElement | undefined;
     }>>> & Readonly<{
         onZoom?: ((nextScale: number | ZoomLevel) => any) | undefined;
@@ -28,7 +25,6 @@ declare const _default: {
     __isSuspense?: undefined;
 } & import("vue").ComponentOptionsBase<Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<{
     scale: number;
-    focusedPage?: Omit<ViewerPdfPage, "page"> | undefined;
     pagesContainer?: HTMLDivElement | undefined;
 }>>> & Readonly<{
     onZoom?: ((nextScale: number | ZoomLevel) => any) | undefined;

package/dist/types/components/ToolZoomPercentageMenu.vue.d.ts

@@ -1,14 +1,11 @@
-import { ViewerPdfPage } from '../utils/types';
 import { ZoomLevel } from '@/utils/enumerators';
 declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<{
     currentPercentage: string;
-    currentPage?: Omit<ViewerPdfPage, "page"> | undefined;
     container?: HTMLDivElement | undefined;
 }>>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     select: (scale: number | ZoomLevel) => void;
 }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<__VLS_TypePropsToRuntimeProps<{
     currentPercentage: string;
-    currentPage?: Omit<ViewerPdfPage, "page"> | undefined;
     container?: HTMLDivElement | undefined;
 }>>> & Readonly<{
     onSelect?: ((scale: number | ZoomLevel) => any) | undefined;

package/dist/types/components/VPdfPage.vue.d.ts

@@ -1,6 +1,6 @@
 import type { PageViewport, PDFPageProxy } from 'pdfjs-dist/types/web/interfaces';
 import type { PDFDocumentProxy } from 'pdfjs-dist';
-import type { CanvasLoadedCallback, AnnotationEventPayload, HighlightEventPayload, HighlightOptions, MatchValue, TextLayerLoadedEventPayload, VisibilityInfo, TextHighlight } from '../utils/types';
+import type { CanvasLoadedCallback, AnnotationEventPayload, HighlightEventPayload, HighlightOptions, MatchValue, TextLayerLoadedEventPayload, TextHighlight, CanvasRenderedEventPayload, VisibleArea } from '../utils/types';
 interface BaseProps {
     pageIndex: number;
     page: PDFPageProxy;
@@ -8,6 +8,7 @@ interface BaseProps {
     document: PDFDocumentProxy;
     afterCanvasLoaded?: CanvasLoadedCallback;
     annoImageResourcesPath?: string;
+    visibleArea?: VisibleArea;
 }
 type TextProps = {
     initialTextLayer: boolean;
@@ -23,7 +24,7 @@ declare const _default: {
         onHighlight?: ((payload: HighlightEventPayload) => any) | undefined;
         onTextLoaded?: ((payload: TextLayerLoadedEventPayload) => any) | undefined;
         onAnnotated?: ((payload: AnnotationEventPayload) => any) | undefined;
-        onIntersected?: ((args: VisibilityInfo) => any) | undefined;
+        onCanvasRendered?: ((payload: CanvasRenderedEventPayload) => any) | undefined;
     }>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
         highlight: (payload: HighlightEventPayload) => void;
     } & {
@@ -31,7 +32,7 @@ declare const _default: {
     } & {
         annotated: (payload: AnnotationEventPayload) => void;
     } & {
-        intersected: (args: VisibilityInfo) => void;
+        canvasRendered: (payload: CanvasRenderedEventPayload) => void;
     }, import("vue").PublicProps, {}, true, {}, {}, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, {}, any, import("vue").ComponentProvideOptions, {
         P: {};
         B: {};
@@ -43,7 +44,7 @@ declare const _default: {
         onHighlight?: ((payload: HighlightEventPayload) => any) | undefined;
         onTextLoaded?: ((payload: TextLayerLoadedEventPayload) => any) | undefined;
         onAnnotated?: ((payload: AnnotationEventPayload) => any) | undefined;
-        onIntersected?: ((args: VisibilityInfo) => any) | undefined;
+        onCanvasRendered?: ((payload: CanvasRenderedEventPayload) => any) | undefined;
     }>, {}, {}, {}, {}, {}>;
     __isFragment?: undefined;
     __isTeleport?: undefined;
@@ -52,7 +53,7 @@ declare const _default: {
     onHighlight?: ((payload: HighlightEventPayload) => any) | undefined;
     onTextLoaded?: ((payload: TextLayerLoadedEventPayload) => any) | undefined;
     onAnnotated?: ((payload: AnnotationEventPayload) => any) | undefined;
-    onIntersected?: ((args: VisibilityInfo) => any) | undefined;
+    onCanvasRendered?: ((payload: CanvasRenderedEventPayload) => any) | undefined;
 }>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     highlight: (payload: HighlightEventPayload) => void;
 } & {
@@ -60,7 +61,7 @@ declare const _default: {
 } & {
     annotated: (payload: AnnotationEventPayload) => void;
 } & {
-    intersected: (args: VisibilityInfo) => void;
+    canvasRendered: (payload: CanvasRenderedEventPayload) => void;
 }, string, {}, {}, string, {}, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & (new () => {
     $slots: {
         pageOverlay: (_: {

package/dist/types/components/VPdfViewer.vue.d.ts

@@ -148,7 +148,10 @@ declare const _default: {
         };
         zoomControl: {
             scale: number;
-            zoom: (scale: number | ZoomLevel) => void;
+            zoom: (scale: number | ZoomLevel, options?: {
+                immediate?: boolean | undefined;
+                origin?: [number, number] | undefined;
+            } | undefined) => void;
         };
     }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
         annotation: (data: AnnotationEventPayload) => void;
@@ -344,7 +347,10 @@ declare const _default: {
         };
         zoomControl: {
             scale: number;
-            zoom: (scale: number | ZoomLevel) => void;
+            zoom: (scale: number | ZoomLevel, options?: {
+                immediate?: boolean | undefined;
+                origin?: [number, number] | undefined;
+            } | undefined) => void;
         };
     }, {}, {}, {}, {
         readonly initialViewMode: ViewMode;
@@ -513,7 +519,10 @@ declare const _default: {
     };
     zoomControl: {
         scale: number;
-        zoom: (scale: number | ZoomLevel) => void;
+        zoom: (scale: number | ZoomLevel, options?: {
+            immediate?: boolean | undefined;
+            origin?: [number, number] | undefined;
+        } | undefined) => void;
     };
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     annotation: (data: AnnotationEventPayload) => void;

package/dist/types/components/utils/helpers.d.ts

@@ -1,2 +1 @@
 export declare const roundDownToNearestMultiple: (num: number, divisor: number) => number;
-export declare const floatToRatio: (x: number, limit: number) => [number, number];

package/dist/types/composables/usePdfActualPages.d.ts

@@ -0,0 +1,21 @@
+import { UnwrapRef } from 'vue';
+import { ViewerPdfPage, ViewerState } from '@/utils/types';
+/**
+ * Composable for managing PDF pages at base scale (100%).
+ *
+ * Returns pages with viewports at scale=1. Components that need the viewport
+ * at current scale should use: `page.getViewport({ scale: currentScale, rotation })`
+ *
+ * This pattern follows pdf.js approach where base viewport is stored and
+ * scale is applied at render time.
+ *
+ * @param props - The viewer state containing PDF document and rotation settings
+ * @returns Object containing pdfPages (all pages) and filteredPages (view-mode filtered)
+ */
+declare function usePdfActualPages(props: UnwrapRef<ViewerState>): {
+    /** All pages at base scale (100%) */
+    pdfPages: import("vue").ShallowRef<ViewerPdfPage[], ViewerPdfPage[]>;
+    /** Pages filtered by view mode (for page scroll mode) */
+    filteredPages: import("vue").ComputedRef<ViewerPdfPage[]>;
+};
+export default usePdfActualPages;

package/dist/types/composables/usePdfCanvas.d.ts

@@ -0,0 +1,13 @@
+import { Ref } from 'vue';
+export interface UsePdfCanvasReturn {
+    renderedPages: Ref<Set<number>>;
+    hasPageBeenRendered: (pageIndex: number) => boolean;
+    markPageAsRendered: (pageIndex: number) => void;
+    clearRenderedPages: () => void;
+}
+/**
+ * Composable to track canvas rendering state across page component remounts.
+ * This prevents loaders from appearing again during zoom/rotation operations
+ * when pages are re-rendered.
+ */
+export declare function usePdfCanvas(): UsePdfCanvasReturn;

package/dist/types/composables/usePinch.d.ts

@@ -1,3 +1,6 @@
 import { Ref } from 'vue';
-declare const usePinch: (container: Ref<HTMLDivElement | undefined>, currentScale: Ref<number | undefined>) => void;
+declare const usePinch: (container: Ref<HTMLDivElement | undefined>, currentScale: Ref<number | undefined>, zoom?: ((scale: number, options?: {
+    immediate?: boolean;
+    origin?: [number, number];
+}) => void) | undefined) => void;
 export default usePinch;

package/dist/types/composables/useRenderQueue.d.ts

@@ -1,4 +1,8 @@
 import { Queue } from '@/utils/Queue';
 import { RenderQueueItem } from '@/utils/types';
 import { MaybeRef } from 'vue';
-export declare const useRenderQueue: (focusedPage: MaybeRef<number>) => Queue<RenderQueueItem>;
+export declare const useRenderQueue: (focusedPage: MaybeRef<number>) => {
+    queue: Queue<RenderQueueItem>;
+    cancelAllRenders: () => void;
+    reprioritizeCurrentPage: () => void;
+};

package/dist/types/composables/useScale.d.ts

@@ -6,20 +6,32 @@ interface UseScaleProps {
     pdfDocument: ShallowRef<PDFDocumentProxy | undefined>;
     pagesContainerRef: ShallowRef<HTMLDivElement | undefined>;
     viewMode: Ref<ViewMode>;
-    initialScale: MaybeRef<number | ZoomLevel>;
     focusedPage: MaybeRef<ViewerPdfPage | undefined>;
-    leftToolbar?: Ref<boolean>;
+    currentScale: Ref<number>;
+    onScaleRequest?: (newScale: number, options?: {
+        immediate?: boolean;
+        origin?: [number, number];
+    }) => Promise<void>;
 }
+/**
+ * Composable for handling zoom operations.
+ * Calculates scale for ZoomLevel presets and delegates actual scaling to useVirtualPages.
+ *
+ * @param props - Scale-related props including PDF document, container, and callbacks
+ * @param scaleCallback - Optional callback for external scale change listeners
+ */
 declare const useScale: (props: UnwrapRef<UseScaleProps>, scaleCallback?: ((event: UseScaleCallback) => void) | undefined) => {
     currentScale: Ref<number, number>;
-    targetScale: Ref<number, number>;
-    isScaling: Ref<boolean, boolean>;
     zoom: (scale: number | ZoomLevel, options?: {
         immediate?: boolean;
+        origin?: [number, number];
     }) => void;
     zoomControl: {
         scale: number;
-        zoom: (scale: number | ZoomLevel) => void;
+        zoom: (scale: number | ZoomLevel, options?: {
+            immediate?: boolean | undefined;
+            origin?: [number, number] | undefined;
+        } | undefined) => void;
     };
 };
 export default useScale;

package/dist/types/composables/useVirtualPages.d.ts

@@ -1,6 +1,7 @@
-import { ComputedRef, CSSProperties, Ref, StyleValue, UnwrapRef } from 'vue';
-import type { ViewerPdfPage, VirtualRange, ElementRect } from '@/utils/types';
-import { ScrollMode, ViewMode } from '@/utils/enumerators';
+import { ComputedRef, CSSProperties, MaybeRef, Ref, StyleValue, UnwrapRef } from 'vue';
+import type { ViewerPdfPage, ElementRect, VisibleArea } from '@/utils/types';
+import { ScrollMode, ViewMode, ZoomLevel } from '@/utils/enumerators';
+import type { PDFDocumentProxy } from 'pdfjs-dist';
 interface UseVirtualListItem<T> {
     data: T;
     index: number;
@@ -17,16 +18,46 @@ export interface UseVirtualListReturn {
     wrapperProps: ComputedRef<{
         style: CSSProperties;
     }>;
-    range: Ref<VirtualRange>;
     pagesPerRow: Ref<number>;
+    targetScale: Ref<number>;
+    isScaling: Ref<boolean>;
+    onScaleRequest: (newScale: number, options?: {
+        immediate?: boolean;
+        origin?: [number, number];
+    }) => Promise<void>;
+    pageVisibleAreas: Ref<Map<number, VisibleArea>>;
+    currentPageIndex: Ref<number>;
 }
 interface UseVirtualPagesProps {
     pages: Ref<ViewerPdfPage[]>;
+    actualPdfPages: Ref<ViewerPdfPage[]>;
     viewerRef: Ref<HTMLElement | undefined>;
     scrollMode: Ref<ScrollMode>;
     viewMode: Ref<ViewMode>;
     isRtl: boolean;
     smoothScroll: Ref<boolean>;
+    currentScale: Ref<number>;
+    pdfDocument: Ref<PDFDocumentProxy | undefined>;
+    initialScale: MaybeRef<number | ZoomLevel>;
+    cancelAllRenders?: () => void;
+    reprioritizeCurrentPage?: () => void;
 }
+/**
+ * Composable for virtual scrolling of PDF pages with support for multiple view modes.
+ *
+ * Implements efficient virtual scrolling by only rendering pages in the viewport plus overscan.
+ * Supports smooth CSS-based zooming with atomic canvas swapping to prevent flashing.
+ *
+ * Features:
+ * - Virtual scrolling with configurable overscan
+ * - Multiple scroll modes: vertical, horizontal, wrapped, page
+ * - Multiple view modes: single, dual page, dual page with cover
+ * - Smooth zoom with CSS transform bridge and debounced re-render
+ * - Maintains scroll position during zoom operations
+ * - Dual page grouping for proper layout
+ *
+ * @param props - Configuration for virtual pages including pages, scroll mode, view mode
+ * @returns Virtual list utilities including list, scrollTo, containerProps, wrapperProps, and zoom controls
+ */
 declare function useVirtualPages(props: UnwrapRef<UseVirtualPagesProps>): UseVirtualListReturn;
 export default useVirtualPages;

package/dist/types/const.d.ts

@@ -33,6 +33,7 @@ export declare const DEFAULT_VIEWER_HEIGHT = 768;
 export declare const PERCENTAGE = 100;
 export declare const MIN_ZOOM_SCALE = 0.25;
 export declare const MAX_ZOOM_SCALE = 10;
+export declare const DEFAULT_SCALE_DELTA = 1.1;
 export declare const SCROLL_BAR_WIDTH = 20;
 export declare const PAGE_PADDING = 1;
 export declare const PAGE_OFFSET = 0;
@@ -75,6 +76,10 @@ export declare const VIEWER_STATE: InjectionKey<{
     isEditing: boolean;
     updateViewerState: (state: Partial<ViewerState>) => void;
 }>;
+export declare const SCALE_ROUND_VALUES: InjectionKey<ComputedRef<{
+    scaleRoundX: string;
+    scaleRoundY: string;
+}>>;
 export declare const VIEWER_PAGES_PER_ROW: InjectionKey<Ref<number, number>>;
 export declare const TOOLBAR_OPTIONS: InjectionKey<Ref<ToolbarOptions | undefined, ToolbarOptions | undefined>>;
 export declare const TOTAL_TOOL_OTHERS_MENU: InjectionKey<Ref<number, number>>;
@@ -397,7 +402,7 @@ export declare const QUEUE_RENDER_TASK: InjectionKey<{
                 } | undefined;
                 isEditing?: boolean | undefined;
             };
-            onLoaded?: (() => void) | undefined;
+            onLoaded?: ((renderTask: import("pdfjs-dist/types/src/display/api").RenderTask) => void) | undefined;
             onError?: ((error: Error) => void) | undefined;
             onComplete?: (() => void) | undefined;
         };
@@ -407,6 +412,10 @@ export declare const QUEUE_RENDER_TASK: InjectionKey<{
     size: () => number;
     clear: () => void;
 }>;
+export declare const PDF_CANVAS_TRACKER: InjectionKey<{
+    hasPageBeenRendered: (pageIndex: number) => boolean;
+    markPageAsRendered: (pageIndex: number) => void;
+}>;
 export declare const DEFAULT_VIEWER_STATE: Reactive<ViewerState>;
 export declare const SUPPORTED_IMAGE_MIME_TYPES: readonly ["image/apng", "image/avif", "image/bmp", "image/gif", "image/jpeg", "image/png", "image/svg+xml", "image/webp", "image/x-icon"];
 export declare const PIXELS_PER_INCH: {

package/dist/types/utils/CanvasRender.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared canvas rendering utilities for LayerCanvas and LayerCanvasDetail.
+ * Consolidates common patterns to reduce code duplication and memory usage.
+ *
+ * Following pdf.js patterns:
+ * - Dynamic canvas creation (no template canvases)
+ * - Atomic swap with opacity transitions (iOS Safari compositor-friendly)
+ * - Immediate cleanup via width=0, height=0 (releases GPU texture)
+ * - Lifecycle guards to prevent DOM manipulation after unmount
+ */
+/// <reference types="node" />
+import { type Ref } from 'vue';
+/**
+ * Canvas context options optimized for PDF rendering.
+ * Matches pdf.js quality settings.
+ */
+export declare const CANVAS_CONTEXT_OPTIONS: CanvasRenderingContext2DSettings;
+/**
+ * Create a new canvas element with standard settings.
+ * All canvases are created dynamically (pdf.js pattern) to prevent
+ * dual-canvas confusion that causes visual overlap on iPad Safari.
+ *
+ * @param className - CSS class name for the canvas
+ * @param ariaHidden - Whether to hide from accessibility tree (default: false)
+ * @returns New canvas element configured for off-screen rendering
+ */
+export declare function createCanvas(className: string, ariaHidden?: boolean): HTMLCanvasElement;
+/**
+ * Get 2D rendering context with optimized settings for PDF rendering.
+ * Disables image smoothing for pixel-perfect rendering (pdf.js pattern).
+ *
+ * @param canvas - Canvas element to get context from
+ * @returns Canvas 2D context or null if failed
+ */
+export declare function getCanvasContext(canvas: HTMLCanvasElement): CanvasRenderingContext2D | null;
+/**
+ * Show a canvas by setting opacity to 1.
+ * Uses opacity instead of hidden attribute for iOS Safari compositor compatibility.
+ *
+ * @param canvas - Canvas element to show
+ */
+export declare function showCanvas(canvas: HTMLCanvasElement): void;
+/**
+ * Clean up a canvas by zeroing its dimensions.
+ * This immediately releases the GPU texture (pdf.js pattern).
+ *
+ * @param canvas - Canvas element to clean up
+ * @param removeFromDom - Whether to also remove from DOM (default: false)
+ */
+export declare function cleanupCanvas(canvas: HTMLCanvasElement | null, removeFromDom?: boolean): void;
+/**
+ * Perform atomic canvas swap with proper cleanup.
+ * Following pdf.js pattern: replaceWith for atomic swap, then show via opacity.
+ *
+ * @param oldCanvas - Existing canvas to replace (can be null for first render)
+ * @param newCanvas - New canvas to insert
+ * @param containerRef - Fallback container if oldCanvas has no parent
+ * @param isMounted - Ref to check if component is still mounted
+ * @param canvasRef - Ref to update with new canvas
+ * @param prepend - If true, prepend instead of append (for base canvas under detail)
+ * @returns true if swap was successful, false otherwise
+ */
+export declare function performAtomicSwap(oldCanvas: HTMLCanvasElement | null | undefined, newCanvas: HTMLCanvasElement, containerRef: Ref<HTMLDivElement | null | undefined>, isMounted: Ref<boolean>, canvasRef: Ref<HTMLCanvasElement | null | undefined>, prepend?: boolean): boolean;
+/**
+ * Options for creating a render task.
+ */
+export interface RenderTaskOptions {
+    page: any;
+    canvas: HTMLCanvasElement;
+    renderParameters: any;
+    queueRenderTask: any;
+    queueId: string;
+    priority: number;
+    isMounted: Ref<boolean>;
+    canvasRef: Ref<HTMLCanvasElement | null>;
+    containerRef: Ref<HTMLDivElement | null>;
+    prepend?: boolean;
+    onSuccess?: (canvas: HTMLCanvasElement) => void;
+    onError?: (error: any) => void;
+}
+/**
+ * Create and enqueue a render task with standard callback handling.
+ * Consolidates the common render task pattern used by both LayerCanvas and LayerCanvasDetail.
+ *
+ * @param options - Render task configuration
+ * @returns Timeout ID for the safety timeout (call clearTimeout on cleanup)
+ */
+export declare function createRenderTask(options: RenderTaskOptions): NodeJS.Timeout;
+/**
+ * Clear a debounce timeout safely.
+ *
+ * @param timeout - Timeout to clear (can be null)
+ * @returns null (for easy assignment: timeout = clearDebounceTimeout(timeout))
+ */
+export declare function clearDebounceTimeout(timeout: NodeJS.Timeout | null): null;
+/**
+ * Standard cleanup for canvas components.
+ * Call this in onBeforeUnmount and onUnmounted.
+ *
+ * @param options - Cleanup configuration
+ */
+export interface CleanupOptions {
+    canvasRef: Ref<HTMLCanvasElement | null>;
+    containerRef: Ref<HTMLDivElement | null>;
+    newCanvasElement: HTMLCanvasElement | null;
+    renderDebounceTimeout: NodeJS.Timeout | null;
+    renderTimeout?: NodeJS.Timeout | null;
+    queueRenderTask?: any;
+    queueId?: string;
+    removeFromDom?: boolean;
+    clearContainer?: boolean;
+}
+export declare function cleanupCanvasComponent(options: CleanupOptions): void;

package/dist/types/utils/scaleUtils.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Scale utilities for CSS round() based dimension calculations
+ * Based on pdf.js implementation for pixel-perfect layer alignment
+ */
+/**
+ * Detect iOS devices (following pdf.js pattern)
+ * Used for platform-specific canvas memory limits and optimizations
+ */
+export declare const isIOS: boolean;
+/**
+ * Detect Safari browser (following pdf.js pattern from app_options.js)
+ * Safari has stricter canvas memory limits than other browsers
+ */
+export declare const isSafari: boolean;
+/**
+ * Maximum canvas pixels for different browsers (following pdf.js pattern)
+ * Safari: 16,777,216 pixels (~16 megapixels) - to stay within ~128MB per-canvas limit
+ * Others: 33,554,432 pixels (2^25, ~32 megapixels)
+ *
+ * Note: iOS Safari uses even lower limits (5.2M) via platform-specific checks
+ */
+export declare const maxCanvasPixels: number;
+/**
+ * Maximum canvas dimension (width or height) - following pdf.js app_options.js default
+ * This is the browser canvas size limit (32767 on most browsers)
+ * Corresponds to pdf.js maxCanvasDim option
+ */
+export declare const MAX_CANVAS_DIM = 32767;
+/**
+ * Maximum canvas area (4096×4096) - used for initial scale calculation
+ * This is a conservative limit to prevent memory issues during setup
+ */
+export declare const MAX_CANVAS_SIZE: number;
+/**
+ * Approximate a float scale value as a fraction using Farey sequence.
+ * This ensures CSS and canvas dimensions round to the same pixel boundaries.
+ *
+ * @param x - The scale value to approximate
+ * @returns [numerator, denominator] array
+ */
+export declare function approximateFraction(x: number): [number, number];
+/**
+ * Canvas area factor for viewport-based capping (following pdf.js default)
+ * Limits canvas to viewportArea × factor pixels
+ * Default: 200 (allows ~14x zoom on small viewports, since √200 ≈ 14.14)
+ */
+export declare const DEFAULT_CAP_CANVAS_AREA_FACTOR = 200;
+/**
+ * Calculate effective max pixels based on viewport size and area factor.
+ * Following pdf.js OutputScale.capPixels() pattern.
+ *
+ * This function prevents over-allocation of canvas memory for small viewports
+ * by capping maxCanvasPixels based on the viewport area. For example, a tiny
+ * 400×300 viewport would be capped at 24M pixels instead of the default 33.5M.
+ *
+ * @param viewportWidth - Viewport width in CSS pixels
+ * @param viewportHeight - Viewport height in CSS pixels
+ * @param maxPixels - Static maximum canvas pixels limit
+ * @param capAreaFactor - Multiplier for viewport area (default: 200, ≤0 = disabled)
+ * @returns Effective maximum canvas pixels (minimum of static limit and capped limit)
+ *
+ * @example
+ * // Small viewport: 400×300 = 120,000 px²
+ * capPixels(400, 300, 33554432, 200)
+ * // Returns: min(33554432, 120000 × 200) = 24,000,000 pixels
+ *
+ * @example
+ * // Large viewport: 1920×1080 = 2,073,600 px²
+ * capPixels(1920, 1080, 33554432, 200)
+ * // Returns: min(33554432, 414720000) = 33,554,432 pixels (static limit wins)
+ */
+export declare function capPixels(viewportWidth: number, viewportHeight: number, maxPixels: number, capAreaFactor?: number): number;
+/**
+ * Browser-specific precision rounding.
+ * Firefox uses f32 precision for CSS calc, so we need to match it.
+ */
+export declare const calcRound: (x: number) => number;
+/**
+ * Floor a value to the nearest multiple of divisor.
+ * Used for canvas dimension calculations.
+ *
+ * @param value - The value to floor
+ * @param divisor - The divisor to floor to
+ * @returns Floored value
+ */
+export declare function floorToDivide(value: number, divisor: number): number;
+/**
+ * Check if the browser supports CSS round() function.
+ * Falls back to calc() if not supported.
+ */
+export declare function isCSSRoundSupported(): boolean;
+/**
+ * Generate CSS dimension string using round() or calc() based on browser support.
+ *
+ * @param baseVar - The base CSS variable name (e.g., '--page-width')
+ * @param scaleVar - The scale CSS variable name (e.g., '--scale-factor')
+ * @param roundVar - The rounding CSS variable name (e.g., '--scale-round-x')
+ * @returns CSS calc/round string
+ */
+export declare function generateDimensionCSS(baseVar: string, scaleVar?: string, roundVar?: string | null): string;
+/**
+ * Calculate scale rounding values for CSS variables.
+ *
+ * @param scale - The current scale value
+ * @returns Object with scaleRoundX and scaleRoundY in pixels
+ */
+export declare function calculateScaleRound(scale: number): {
+    scaleRoundX: string;
+    scaleRoundY: string;
+};
+/**
+ * Calculate safe output scale considering all canvas constraints.
+ * Following pdf.js OutputScale.limitCanvas() pattern from display_utils.js
+ *
+ * This function applies four types of constraints:
+ * 1. Viewport-based area capping (viewportArea × capAreaFactor, pdf.js pattern)
+ * 2. Total pixel area (width × height ≤ effectiveMaxPixels)
+ * 3. Maximum width dimension (width ≤ maxDim)
+ * 4. Maximum height dimension (height ≤ maxDim)
+ *
+ * Takes the most restrictive constraint and scales down if needed.
+ *
+ * @param width - Canvas width at scale 1
+ * @param height - Canvas height at scale 1
+ * @param requestedScale - Desired output scale (typically devicePixelRatio)
+ * @param viewportWidth - Viewport width for area capping (default: width)
+ * @param viewportHeight - Viewport height for area capping (default: height)
+ * @param maxPixels - Maximum total canvas pixels (platform-specific, default from maxCanvasPixels)
+ * @param maxDim - Maximum canvas dimension for width or height (default 32767)
+ * @param capAreaFactor - Viewport area multiplier for capping (default: 200, ≤0 = disabled)
+ * @returns Object with scale, needsRestriction flag, and reason for restriction
+ *
+ * @example
+ * // Normal case: 800×600 page at 2x scale
+ * limitCanvasScale(800, 600, 2.0)
+ * // Returns: { scale: 2.0, needsRestriction: false }
+ *
+ * @example
+ * // Wide page: 40000×1000 page at 1x scale
+ * limitCanvasScale(40000, 1000, 1.0)
+ * // Returns: { scale: 0.819, needsRestriction: true, reason: 'width' }
+ * // Actual canvas: 32767×819 pixels
+ *
+ * @example
+ * // Small viewport: 400×300 viewport with area capping
+ * limitCanvasScale(800, 600, 2.0, 400, 300)
+ * // Viewport area: 120,000 → capped limit: 24M pixels
+ * // Returns: { scale: 1.414, needsRestriction: true, reason: 'area-capped' }
+ */
+export declare function limitCanvasScale(width: number, height: number, requestedScale: number, viewportWidth?: number, viewportHeight?: number, maxPixels?: number, maxDim?: number, capAreaFactor?: number): {
+    scale: number;
+    needsRestriction: boolean;
+    reason?: 'area' | 'area-capped' | 'width' | 'height';
+};