pdf-h5-react 0.0.0-stage → 0.3.1

package/dist/components/PdfH5Reader.d.ts

@@ -0,0 +1,101 @@
+import { PDFDocumentProxy } from 'pdfjs-dist';
+import { ZoomEventPayload } from '../core/readerEvents';
+import { Annotation, AnnotationStyle } from '../core/annotations';
+import { PdfH5ReaderHandle, PdfSource, ThemeMode, ViewerMode, FitMode } from '../types';
+export interface PdfH5ReaderProps {
+    /** PDF 来源：URL / 二进制 / 参数对象 */
+    src: PdfSource | null | undefined;
+    /** 连续滚动 / 单页翻页 */
+    mode?: ViewerMode;
+    /** 适配方式，默认 width */
+    fitMode?: FitMode;
+    initialPage?: number;
+    /** 初始缩放倍率（相对适配尺寸），默认 1 */
+    initialZoom?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    /** 双击 / 双指点击的放大目标倍率，默认 2.5 */
+    doubleTapZoom?: number;
+    /** 缩放动画时长（ms），默认 300；设为 0 立即跳变 */
+    animationDuration?: number;
+    /** 是否允许缩放手势，默认 true */
+    zoomEnable?: boolean;
+    /** 是否允许滚动，默认 true */
+    scrollEnable?: boolean;
+    rotation?: number;
+    theme?: ThemeMode;
+    gap?: number;
+    padding?: number;
+    /** 文本层（可选中 / 可复制），默认开启 */
+    textLayer?: boolean;
+    /** 链接层，默认开启 */
+    links?: boolean;
+    /** 是否显示内置工具栏，默认 true */
+    toolbar?: boolean;
+    /** 是否显示页码 / 缩放浮层，默认 true */
+    showControls?: boolean;
+    /** 是否显示「回到顶部」悬浮按钮，默认 true */
+    backTop?: boolean;
+    /** 是否显示顶部加载进度条，默认 true */
+    loadingBar?: boolean;
+    /** 是否启用注释功能（工具栏出现批注按钮），默认 false */
+    annotation?: boolean;
+    /** 受控注释列表；不传则由组件内部维护 */
+    annotations?: Annotation[];
+    /** 注释样式覆盖 */
+    annotationStyle?: Partial<AnnotationStyle>;
+    /** 注释变化回调（新增 / 删除 / 清空） */
+    onAnnotationsChange?: (annotations: Annotation[]) => void;
+    /** 位图缓存上限（字节），默认 96MB */
+    bitmapCacheBytes?: number;
+    /** 文本层缓存条目上限，默认 24 */
+    textLayerCacheEntries?: number;
+    maxCanvasPixels?: number;
+    maxCanvasDimension?: number;
+    className?: string;
+    style?: React.CSSProperties;
+    onDocumentLoad?: (doc: PDFDocumentProxy) => void;
+    onPageChange?: (page: number, total: number) => void;
+    onProgress?: (loaded: number, total: number) => void;
+    onError?: (error: Error) => void;
+    onZoomChange?: (zoom: number) => void;
+    onInternalLink?: (dest: string | unknown[] | null) => void;
+    onExternalLink?: (url: string) => void;
+    /** 自定义空状态 / 加载失败渲染 */
+    renderError?: (error: Error, retry: () => void) => React.ReactNode;
+    /** 文档就绪，可拿到总页数 */
+    onReady?: (payload: {
+        doc: PDFDocumentProxy;
+        total: number;
+    }) => void;
+    /** 某一页渲染完成 */
+    onRender?: (payload: {
+        pageNumber: number;
+        pageTime: number;
+        totalTime: number;
+    }) => void;
+    /** 滚动（已节流） */
+    onScroll?: (payload: {
+        scrollTop: number;
+        scrollLeft: number;
+        currentPage: number;
+        progress: number;
+    }) => void;
+    /** 缩放结束 */
+    onZoomEnd?: (payload: ZoomEventPayload) => void;
+    /** 加载流程结束（成功或失败都会触发） */
+    onComplete?: (payload: {
+        status: 'success' | 'error';
+        message: string;
+        time: number;
+    }) => void;
+}
+/**
+ * 移动端优先的 PDF 阅读器。
+ *
+ * 三层性能结构：
+ *  文档层  usePdfDocument   —— 加载 / 密码 / 进度（进度事件节流）
+ *  度量层  usePageMetrics   —— 首屏 N 页真实尺寸 + 其余页渐进解析（rAF 批量校正）
+ *  视图层  useVirtualPages  —— 只挂载可视区内的页面 DOM，位图走 LRU，渲染走双并发队列
+ */
+export declare const PdfH5Reader: import('react').ForwardRefExoticComponent<PdfH5ReaderProps & import('react').RefAttributes<PdfH5ReaderHandle>>;

package/dist/components/SearchPanel.d.ts

@@ -0,0 +1,18 @@
+import { SearchHit, CacheStatsSnapshot } from '../types';
+export interface SearchPanelProps {
+    hits: readonly SearchHit[];
+    index: number;
+    onSearch(query: string): Promise<SearchHit[]>;
+    onSelect(index: number): void;
+    onClose(): void;
+    /** 缓存统计（用于「性能」诊断区） */
+    stats?: CacheStatsSnapshot | null;
+    onClearCaches?(): void;
+}
+/**
+ * 搜索面板。
+ *
+ * 输入用防抖（260ms）避免逐字触发全文档扫描；
+ * 扫描本身在 lib/search 里逐页让出主线程，不会阻塞滚动。
+ */
+export declare function SearchPanel({ hits, index, onSearch, onSelect, onClose, stats, onClearCaches }: SearchPanelProps): import("react").JSX.Element;

package/dist/components/StatusOverlay.d.ts

@@ -0,0 +1,15 @@
+export interface StatusOverlayProps {
+    loading: boolean;
+    needPassword: boolean;
+    passwordReason: number;
+    error: Error | null;
+    progress: {
+        loaded: number;
+        total: number;
+    } | null;
+    onSubmitPassword(password: string): void;
+    onCancelPassword(): void;
+    renderError?: (error: Error, retry: () => void) => React.ReactNode;
+}
+/** 加载 / 密码 / 错误三态覆盖层 */
+export declare function StatusOverlay({ loading, needPassword, passwordReason, error, progress, onSubmitPassword, onCancelPassword, renderError, }: StatusOverlayProps): import("react").JSX.Element | null;

package/dist/components/TextLayer.d.ts

@@ -0,0 +1,26 @@
+import { PDFPageProxy } from 'pdfjs-dist';
+import { TextLayerCache } from '../core/cache';
+import { RenderQueue } from '../core/renderQueue';
+export interface TextLayerProps {
+    page: PDFPageProxy | null;
+    pageNumber: number;
+    /** 与画布一致的显示尺寸 */
+    width: number;
+    height: number;
+    displayScale: number;
+    rotation: number;
+    textLayerCache: TextLayerCache;
+    renderQueue: RenderQueue;
+    /** 关闭时完全不构建文本层（省内存，代价是不可选中/搜索仍可用） */
+    enabled: boolean;
+    shouldBuild: boolean;
+}
+/**
+ * 文本层。
+ *
+ * 性能要点：
+ * 1. 文本层构建成本高（几百个 span + 字体测量），按页缓存在 LRU 里；
+ * 2. 缩放时优先走 TextLayer.update({ viewport }) 重排，而不是重建 DOM；
+ * 3. 一旦缓存里没有可用节点，才重新 streamTextContent 构建。
+ */
+export declare function TextLayer({ page, pageNumber, width, height, displayScale, rotation, textLayerCache, renderQueue, enabled, shouldBuild, }: TextLayerProps): import("react").JSX.Element;

package/dist/components/ThumbnailPanel.d.ts

@@ -0,0 +1,18 @@
+import { PDFDocumentProxy } from 'pdfjs-dist';
+import { ThumbnailCache } from '../core/cache';
+export interface ThumbnailPanelProps {
+    doc: PDFDocumentProxy;
+    cache: ThumbnailCache;
+    currentPage: number;
+    rotation: number;
+    onSelect(pageNumber: number): void;
+    onClose(): void;
+}
+/**
+ * 缩略图面板。
+ *
+ * 上百张缩略图不能一次性渲染：按容器滚动位置算出「可见行区间」，
+ * 只渲染该区间（±2 屏），配合 ThumbnailCache，回滚时命中 dataURL 零成本。
+ * 这里用位置区间而不是 IntersectionObserver —— 网格均质，算区间更稳且无观察者开销。
+ */
+export declare function ThumbnailPanel({ doc, cache, currentPage, rotation, onSelect, onClose }: ThumbnailPanelProps): import("react").JSX.Element;

package/dist/components/Toolbar.d.ts

@@ -0,0 +1,36 @@
+export type PanelKind = 'outline' | 'thumbnails' | 'search' | null;
+export interface ToolbarProps {
+    mode: 'scroll' | 'page';
+    page: number;
+    total: number;
+    zoom: number;
+    minZoom: number;
+    maxZoom: number;
+    panel: PanelKind;
+    panelSupported: Record<'search' | 'outline' | 'thumbnails', boolean>;
+    /** 是否显示批注按钮 */
+    annotation?: boolean;
+    /** 当前批注模式 */
+    annotationMode?: 'none' | 'highlight' | 'freetext' | 'ink';
+    /** 当前页的批注数量（显示角标） */
+    annotationCount?: number;
+    onPrev(): void;
+    onNext(): void;
+    onJump(page: number): void;
+    onZoomIn(): void;
+    onZoomOut(): void;
+    onResetZoom(): void;
+    onTogglePanel(panel: PanelKind): void;
+    onLocate(): void;
+    onToggleAnnotation?(mode: 'highlight' | 'freetext' | 'ink'): void;
+    onClearAnnotations?(): void;
+}
+/**
+ * 底部工具栏（移动端优先）。
+ *
+ * 交互细节：
+ * - 页码输入框在移动端用 inputMode="numeric"，聚焦时自动全选，输入完回车跳转；
+ * - 工具栏可折叠：滚动阅读时点中间区域收起，把屏幕让给正文；
+ * - 所有按钮 ≥ 40px 命中区，符合手指操作。
+ */
+export declare function Toolbar({ mode, page, total, zoom, minZoom, maxZoom, panel, panelSupported, annotation, annotationMode, annotationCount, onPrev, onNext, onJump, onZoomIn, onZoomOut, onResetZoom, onTogglePanel, onLocate, onToggleAnnotation, onClearAnnotations, }: ToolbarProps): import("react").JSX.Element;

package/dist/core/annotations.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 注释数据模型与坐标换算。
+ *
+ * 设计要点（这是注释功能最容易做错的地方）：
+ *
+ * 1. **存储用归一化坐标**（0-1，相对页面宽高），而不是 CSS 像素。
+ *    否则缩放 / 旋转屏幕 / 切换 fitMode 之后，所有注释都会错位。
+ *
+ * 2. **不写回 PDF 字节**（默认）。把注释存在独立的数据层，导出时才考虑落盘。
+ *    改 PDF 需要 pdf-lib 之类的重量级依赖，且会破坏原文件的签名与增量更新语义。
+ *
+ * 3. 坐标以「页面显示盒」为参照系（即 .pdfh5-page 的左上角），
+ *    与 viewport 的旋转无关 —— 旋转在渲染层处理，注释层始终贴合最终显示区域。
+ */
+/** 归一化点：x/y ∈ [0, 1]，相对页面显示区域的左上角 */
+export interface NormPoint {
+    x: number;
+    y: number;
+}
+/** 归一化矩形 */
+export interface NormRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type AnnotationKind = 'highlight' | 'freetext' | 'ink';
+interface AnnotationBase {
+    id: string;
+    kind: AnnotationKind;
+    pageNumber: number;
+    /** 创建时间戳（ms） */
+    createdAt: number;
+    /** 作者标记，便于多人协作时区分 */
+    author?: string;
+    /** 任意业务附加数据（不会渲染） */
+    meta?: Record<string, unknown>;
+}
+/** 文本高亮：一个或多个矩形（跨行时会有多段） */
+export interface HighlightAnnotation extends AnnotationBase {
+    kind: 'highlight';
+    rects: NormRect[];
+    /** 高亮到的文字（便于做批注列表 / 导出） */
+    text?: string;
+    color: string;
+    opacity: number;
+}
+/** 自由文本：一个锚点 + 字号（归一化到页面宽度，保证缩放后视觉比例一致） */
+export interface FreetextAnnotation extends AnnotationBase {
+    kind: 'freetext';
+    anchor: NormPoint;
+    text: string;
+    /** 字号相对页面宽度的比例（例如 0.02 表示页面宽度的 2%） */
+    fontSize: number;
+    color: string;
+}
+/** 手写笔迹：归一化点序列 */
+export interface InkAnnotation extends AnnotationBase {
+    kind: 'ink';
+    points: NormPoint[];
+    /** 线宽相对页面宽度的比例 */
+    thickness: number;
+    color: string;
+}
+export type Annotation = HighlightAnnotation | FreetextAnnotation | InkAnnotation;
+export type AnnotationMode = 'none' | 'highlight' | 'freetext' | 'ink';
+export interface AnnotationStyle {
+    highlightColor: string;
+    highlightOpacity: number;
+    textColor: string;
+    inkColor: string;
+    /** 相对页面宽度的比例 */
+    fontSize: number;
+    thickness: number;
+}
+export declare const DEFAULT_ANNOTATION_STYLE: AnnotationStyle;
+/** 视口像素（相对页面盒左上角）→ 归一化 */
+export declare function toNormalized(px: number, py: number, boxWidth: number, boxHeight: number): NormPoint;
+/** 归一化 → 视口像素 */
+export declare function toPixel(point: NormPoint, boxWidth: number, boxHeight: number): NormPoint;
+export declare function rectToPixel(rect: NormRect, boxWidth: number, boxHeight: number): NormRect;
+/** 由两个对角点构造归一化矩形（自动处理反向拖拽） */
+export declare function rectFromPoints(a: NormPoint, b: NormPoint): NormRect;
+export declare function createAnnotationId(prefix?: string): string;
+/** 判断注释是否「有效」：空高亮、空文本、单击点都不入库 */
+export declare function isAnnotationValid(annotation: Annotation): boolean;
+/** 归一化坐标是否落在页面内（含少量容差） */
+export declare function isPointInPage(point: NormPoint, tolerance?: number): boolean;
+/** 按页分组，便于渲染时 O(1) 取用 */
+export declare function groupByPage(annotations: readonly Annotation[]): Map<number, Annotation[]>;
+export {};

package/dist/core/cache.d.ts

@@ -0,0 +1,96 @@
+import { PDFPageProxy } from 'pdfjs-dist';
+import { LruCacheStats } from './lru';
+export interface SizedCanvas {
+    canvas: HTMLCanvasElement | OffscreenCanvas;
+    width: number;
+    height: number;
+    bytes: number;
+}
+export declare function createCacheCanvas(width: number, height: number): HTMLCanvasElement;
+export declare function disposeCanvas(canvas: HTMLCanvasElement | OffscreenCanvas | null | undefined): void;
+export interface BitmapEntry extends SizedCanvas {
+    key: string;
+    pageNumber: number;
+    scale: number;
+    canvas: HTMLCanvasElement;
+}
+export interface BitmapCacheOptions {
+    maxBytes?: number;
+    onEvict?: (entry: BitmapEntry) => void;
+}
+/**
+ * 位图缓存。key = `${pageNumber}@${scaleBucket}`。
+ * 缩放时量化到固定档位，来回捏合不会反复触发渲染。
+ */
+export declare class BitmapCache {
+    private readonly cache;
+    constructor(options?: BitmapCacheOptions);
+    static key(pageNumber: number, scale: number): string;
+    get(pageNumber: number, scale: number): BitmapEntry | undefined;
+    take(pageNumber: number, scale: number): BitmapEntry | undefined;
+    release(entry: BitmapEntry | undefined): void;
+    put(pageNumber: number, scale: number, canvas: HTMLCanvasElement): BitmapEntry;
+    has(pageNumber: number, scale: number): boolean;
+    /** 丢掉某一页的所有档位（例如页面被移出远区） */
+    dropPage(pageNumber: number): void;
+    clear(): void;
+    stats(): LruCacheStats;
+}
+export interface TextLayerEntry {
+    pageNumber: number;
+    /** 已构建好的 .textLayer 节点，可 detach / re-attach */
+    node: HTMLDivElement;
+    scale: number;
+    viewportScale: number;
+    bytes: number;
+    /** pdf.js TextLayer 实例，用于 update({viewport}) */
+    update: (viewport: unknown) => void;
+    destroy: () => void;
+}
+export interface TextLayerCacheOptions {
+    maxEntries?: number;
+    maxBytes?: number;
+}
+/**
+ * 文本层 DOM 缓存。构建一次成本高（几百个 span + 字体测量），
+ * 滚动离开视口后保留，回来后直接挂回 DOM。
+ */
+export declare class TextLayerCache {
+    private readonly cache;
+    constructor(options?: TextLayerCacheOptions);
+    get(pageNumber: number): TextLayerEntry | undefined;
+    take(pageNumber: number): TextLayerEntry | undefined;
+    release(pageNumber: number): void;
+    put(entry: TextLayerEntry): void;
+    delete(pageNumber: number): void;
+    clear(): void;
+    stats(): LruCacheStats;
+}
+/** 页面代理缓存：避免反复调用 doc.getPage() */
+export declare class PageProxyCache {
+    private readonly cache;
+    private readonly inflight;
+    private doc;
+    constructor(doc: {
+        getPage(n: number): Promise<PDFPageProxy>;
+    } | null, maxEntries?: number);
+    /** 同步读取（命中即返回，不发起请求） */
+    peek(pageNumber: number): PDFPageProxy | undefined;
+    get(pageNumber: number): Promise<PDFPageProxy>;
+    clear(): void;
+    stats(): LruCacheStats;
+}
+export interface ThumbnailEntry {
+    pageNumber: number;
+    dataUrl: string;
+    bytes: number;
+}
+/** 缩略图缓存（dataURL，体积小但数量多） */
+export declare class ThumbnailCache {
+    private readonly cache;
+    constructor(maxEntries?: number);
+    get(pageNumber: number): ThumbnailEntry | undefined;
+    put(pageNumber: number, dataUrl: string): void;
+    clear(): void;
+    stats(): LruCacheStats;
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class PdfH5Error extends Error {
+    readonly cause?: unknown | undefined;
+    readonly code: 'load' | 'password' | 'render' | 'unknown';
+    readonly name = "PdfH5Error";
+    constructor(message: string, cause?: unknown | undefined, code?: 'load' | 'password' | 'render' | 'unknown');
+}
+/** 渲染任务被主动取消（离开视口 / 缩放变化），不应作为错误上报 */
+export declare class RenderCancelledError extends Error {
+    readonly name = "RenderCancelledError";
+    constructor(message?: string);
+}
+export declare function isCancelledError(error: unknown): boolean;

package/dist/core/eventEmitter.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 轻量事件总线。
+ *
+ * 设计参考 pdfh5 的 `on / off / trigger`：命令式 API 对「非 React 心智」的使用者更自然，
+ * 也便于在 ref 上挂载（无需把每个事件都写成一个 prop）。
+ * 同时保留 React 的 props 回调：两种风格各自可用，互不干扰。
+ *
+ * 与 pdfh5 的差异（都是踩过坑之后的选择）：
+ * 1. 回调抛错不会中断其它监听者 —— 一个监听器写错不该让整个阅读器的事件链断掉；
+ * 2. `off` 支持只移除指定回调（pdfh5 只能按事件名全清，容易误伤）；
+ * 3. 提供 `once`，且事件分发时对监听器数组做快照，避免回调里增删监听导致漏发。
+ */
+export type Listener<T> = (payload: T) => void;
+/**
+ * 事件表约束。
+ *
+ * 用 `Record<PropertyKey, unknown>` 而不是 `Record<string, unknown>`：
+ * 后者的索引签名隐含「所有 string key 都得有值」，与 `{ destroy: {} }` 这类
+ * 具体对象类型不兼容（会报 Type 'X' does not satisfy Record<string, unknown>）。
+ */
+export declare class EventEmitter<Events extends object> {
+    private readonly listeners;
+    /** 注册监听，返回取消订阅函数 */
+    on<K extends keyof Events>(type: K, listener: Listener<Events[K]>): () => void;
+    /** 只触发一次 */
+    once<K extends keyof Events>(type: K, listener: Listener<Events[K]>): () => void;
+    /**
+     * 移除监听。
+     * 不传 listener 时清空该事件的全部监听（兼容 pdfh5 的用法）。
+     */
+    off<K extends keyof Events>(type: K, listener?: Listener<Events[K]>): void;
+    /**
+     * 触发事件。
+     *
+     * 对数组做快照再遍历：回调内部调用 `off` 不会影响本轮分发（否则会漏发后续监听者）。
+     * 单个监听器抛错时打印告警并继续 —— 避免一个写错的回调导致别的功能静默失效。
+     */
+    emit<K extends keyof Events>(type: K, payload: Events[K]): void;
+    /** 某个事件当前的监听数量（调试用） */
+    listenerCount(type: keyof Events): number;
+    /** 清空全部监听（组件卸载时调用） */
+    clear(): void;
+}

package/dist/core/gestures.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 捏合 / 双击 / 滚轮缩放的纯数学部分（可单测，不碰 DOM）。
+ *
+ * 关键点：内容（页面 + 间距 + 内边距）对 zoom 严格线性，
+ * 因此捏合过程中可以用 CSS transform 做「预演」，松手后一次性提交真实 zoom，
+ * 两者在同一坐标系下等价，不会出现跳变。
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface ViewportMetrics {
+    /** 容器左上角在视口中的位置（getBoundingClientRect） */
+    left: number;
+    top: number;
+    /** 当前滚动位置 */
+    scrollLeft: number;
+    scrollTop: number;
+}
+export interface PinchGeometry {
+    /** 预演用的缩放比（相对手势开始时） */
+    k: number;
+    /** 预演用平移（px），配合 transform-origin: 0 0，作用在滚动容器内的内容元素上 */
+    tx: number;
+    ty: number;
+}
+/**
+ * 计算捏合预演 transform。
+ *
+ * 坐标系：transform 作用在「滚动容器内的内容元素」上（transform-origin: 0 0），
+ * 因此它以内容坐标系为基准；屏幕位置 = 内容坐标 - scroll。
+ *
+ * 约束：手势开始时手指中点下方的内容点 c0，必须始终落在当前两指中点处：
+ *   k * c0 + t - scroll = v   →   t = v + scroll - k * c0
+ * 这样预演与「松手后提交 zoom + scroll」在数学上完全等价，松手不会跳变。
+ */
+export declare function pinchTransform(startMidpoint: Point, currentMidpoint: Point, startViewport: ViewportMetrics, k: number): PinchGeometry;
+export interface PinchCommit {
+    zoom: number;
+    scrollLeft: number;
+    scrollTop: number;
+}
+/**
+ * 松手后提交：给定新的 zoom，算出保持同一内容点位于当前中点所需的滚动位置。
+ */
+export declare function pinchCommit(startMidpoint: Point, currentMidpoint: Point, startViewport: ViewportMetrics, ratio: number, options: {
+    minZoom: number;
+    maxZoom: number;
+    baseZoom: number;
+    maxScrollLeft: number;
+    maxScrollTop: number;
+}): PinchCommit;
+/**
+ * 双击 / 双指点击快速放大：以点击点为中心在 fit 与 targetZoom 之间切换。
+ */
+export declare function doubleTapTarget(currentZoom: number, options: {
+    targetZoom: number;
+    minZoom: number;
+    maxZoom: number;
+}): number;
+/** 以某个视口点为中心缩放（滚轮 / 按钮 / 快捷键共用） */
+export declare function zoomAtPoint(anchor: Point, viewport: ViewportMetrics, ratio: number, options: {
+    minZoom: number;
+    maxZoom: number;
+    baseZoom: number;
+    maxScrollLeft: number;
+    maxScrollTop: number;
+}): PinchCommit;
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function distance(a: Point, b: Point): number;
+export declare function midpoint(a: Point, b: Point): Point;

package/dist/core/layout.d.ts

@@ -0,0 +1,109 @@
+import { FitMode, PageMetric, ViewerMode } from '../types';
+export interface PageSize {
+    width: number;
+    height: number;
+}
+export interface PageBox extends PageSize {
+    pageNumber: number;
+    top: number;
+    left: number;
+    /** 该页实际使用的缩放（翻页模式下每页独立适配） */
+    scale: number;
+}
+export interface ViewerLayout {
+    boxes: PageBox[];
+    contentWidth: number;
+    contentHeight: number;
+    /** 连续模式下页面宽度上限（用于把内容容器撑开） */
+    widest: number;
+    mode: ViewerMode;
+}
+export interface LayoutInput {
+    mode: ViewerMode;
+    /** 每页的度量，index 0 对应第 1 页；缺省用 fallback 顶替 */
+    metrics: ReadonlyArray<PageMetric | undefined>;
+    fallback: PageSize;
+    /** 连续模式下的统一缩放 */
+    scale: number;
+    /** 用户缩放倍率（1 = 适配），用于缩放间距，保证捏合锚点数学精确 */
+    zoom: number;
+    containerWidth: number;
+    containerHeight: number;
+    /** 基础间距（未乘 zoom） */
+    gap: number;
+    padding: number;
+    rotation: number;
+    fitMode: FitMode;
+}
+/** 旋转后的显示尺寸（未缩放） */
+export declare function rotatedSize(metric: PageMetric, extraRotation: number): PageSize;
+/** 适配缩放：fit-width 按宽度铺满，fit-page 整页可见 */
+export declare function fitScale(size: PageSize, container: PageSize, fitMode: FitMode): number;
+export declare function computeLayout(input: LayoutInput): ViewerLayout;
+/**
+ * 二分查找「当前阅读页」：返回覆盖 offset 的页面；落在间隙里则取最近的一页。
+ */
+export declare function pageAtOffset(boxes: ReadonlyArray<PageBox>, offset: number, axis?: 'y' | 'x'): number;
+/** 滚动到指定页所需的 scrollTop / scrollLeft（让页面顶部对齐容器顶部） */
+export declare function offsetForPage(layout: ViewerLayout, pageNumber: number, axis?: 'y' | 'x', align?: 'start' | 'center'): number;
+/**
+ * 缩放锚点换算：保持 anchor 处的「内容坐标」不动。
+ *
+ * 因为内容（含间距 / 内边距）整体按 zoom 同比缩放，内容坐标可线性映射：
+ *   content' = content * k,  k = newZoom / oldZoom
+ * 于是新的滚动位置 = content' - anchor。
+ */
+export declare function anchoredScroll(scroll: number, anchorViewportOffset: number, ratio: number): number;
+/**
+ * 把渲染分辨率量化到固定档位，命中缓存（缩放来回时不重复渲染）。
+ * 返回「不小于 value 的最小档位」，没有更大档位时返回最后一档与 value 的较大者。
+ */
+export declare const DEFAULT_SCALE_STEPS: readonly [0.25, 0.35, 0.5, 0.7, 0.85, 1, 1.25, 1.5, 1.75, 2, 2.5, 3, 3.5, 4, 5, 6, 8, 10, 12, 16];
+export declare function quantizeScale(value: number, steps?: ReadonlyArray<number>): number;
+/**
+ * 量化「设备像素比」，用于决定画布分辨率。
+ *
+ * 注意这里只处理 DPR —— 不掺任何页面缩放。
+ * 画布像素 = CSS 尺寸 × 本函数返回值，viewport scale 见 viewportScaleFor。
+ *
+ * 量化到固定档位是为了让缩放来回时能命中同一份位图缓存；
+ * 误差控制在 6% 内（视觉不可辨），超过则直接用精确值，宁可少一次命中也不牺牲画质。
+ */
+export declare function quantizePixelRatio(devicePixelRatio: number, maxDpr?: number): number;
+export interface CanvasLimitOptions {
+    /** 总像素上限，iOS 上建议 <= 16.7M */
+    maxPixels?: number;
+    /** 单边上限，iOS 上建议 <= 4096~8192 */
+    maxDimension?: number;
+}
+export interface CanvasSize {
+    width: number;
+    height: number;
+    /** 实际生效的缩放（可能因限幅而小于请求值） */
+    scale: number;
+    clamped: boolean;
+}
+/**
+ * 计算 canvas 的像素尺寸并在必要时限幅。
+ *
+ * 注意 scale 的语义：**画布像素 / CSS 像素**（不是 pdf.js 的 viewport scale）。
+ * 它不能直接传给 getViewport —— 中间还差一个「CSS 像素 / PDF 单位」的换算，
+ * 见 viewportScaleFor。
+ *
+ * 移动端 canvas 有硬上限（iOS Safari 约 16.7M 像素、单边 8192），超限会得到空白画布，
+ * 所以宁可降分辨率也要限幅。
+ */
+export declare function clampCanvasSize(cssWidth: number, cssHeight: number, pixelRatio: number, options?: CanvasLimitOptions): CanvasSize;
+/**
+ * 计算应当传给 `page.getViewport({ scale })` 的值。
+ *
+ * pdf.js 用「PDF 单位 × scale」算渲染尺寸，因此必须把
+ * 「画布像素 / CSS 像素」再乘上「CSS 像素 / PDF 单位」。
+ *
+ * 若直接把 clampCanvasSize 返回的 scale 传给 getViewport，
+ * 渲染内容会比画布大 1/displayScale 倍（窄屏 A4 约 1.63 倍），右侧被画布边界切掉，
+ * 表现就是「文字被截断」。
+ */
+export declare function viewportScaleFor(cssWidth: number, pdfWidth: number, canvasPixelRatio: number): number;
+/** 位图内存估算（RGBA） */
+export declare function bitmapBytes(width: number, height: number): number;