@hamster-note/reader 0.2.0-beta.1

package/dist/components/IntermediateDocumentViewer/IntermediateDocumentViewer.d.ts

@@ -0,0 +1,356 @@
+import { IntermediateDocument, type IntermediateDocumentSerialized, type IntermediateText } from '@hamster-note/types';
+import { type IntermediateDocumentRenderTimingCallback } from './renderTiming';
+import React from 'react';
+import { type ReaderSelectedTextSegment } from '../selection/selectionPayloadSerializer';
+import type { ReaderMousePosition, ReaderLinkedSelectionData, ReaderSelectionOverlayRectType, ReaderSelectionRange, ReaderSelectionRef } from '../../types/selection';
+export { getNearestTextElementForPoint, getPageElementByPageNumber, getPageElementForPoint, resolveCaret } from '../selection/caretResolver';
+export { composeSelection, createOrderedRange } from '../selection/selectionComposer';
+export { buildSelectionPayload, getClosestTextElement, type ReaderSelectedTextSegment, type ReaderSelectionPayload, textElementRecords } from '../selection/selectionPayloadSerializer';
+export { buildSavedSelection, denormalizePageRects, normalizePageRects, resolveSavedSelection, textHash, type NormalizedRect, type TextElementInfo } from '../selection/savedSelection';
+export type ReaderTextSelectionDetail = {
+    text: IntermediateText;
+    texts: IntermediateText[];
+    selectedText: string;
+    pageNumber: number;
+    selection: Selection;
+};
+export type { ReaderLinkedSelectionData, ReaderLinkedSelectionRange, ReaderMousePosition, ReaderSelectionEndpoint, ReaderSelectionOverlayRectType, ReaderSelectionRange, ReaderSelectionRect, ReaderSelectionRef } from '../../types/selection';
+export type ReaderPageRange = {
+    start: number;
+    end: number;
+};
+/**
+ * 选择覆盖层矩形区域。
+ *
+ * 坐标原由可选 `origin` 字段标识：
+ * - `'viewport'`    — 来自 Range.getClientRects / getBoundingClientRect 的浏览器视口坐标，
+ *                      viewer 边界需调用 convertSavedSelectionRectToPageRect 转为页面相对坐标。
+ * - `'page-relative'` — 已是页面像素相对坐标（来自归一化 bbox 反归一化或 visual fallback），
+ *                      viewer 边界不应再做 viewport→page-relative 转换，否则会双重偏移。
+ * - `undefined`     — 历史调用方未显式标注，按 viewport 坐标处理（向后兼容）。
+ */
+export type ReaderSelectionOverlayRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    pageNumber: number;
+    /** 坐标原点标识，用于 viewer 边界区分 viewport / page-relative */
+    origin?: 'viewport' | 'page-relative';
+};
+/**
+ * 已保存选择的文本锚点信息。
+ * 用于精确定位选择在文档中的起始/结束位置。
+ * bbox 使用归一化坐标（0-1），相对于页面尺寸。
+ */
+export type ReaderSavedSelectionAnchor = {
+    /** 锚点所在页码 */
+    pageNumber: number;
+    /** 文本元素的唯一标识符（可选，用于精确匹配） */
+    textId?: string;
+    /** 文本内容的哈希值（可选，用于文本变化后的模糊匹配） */
+    textHash?: string;
+    /** 锚点在文本元素中的字符索引（可选） */
+    charIndex?: number;
+    /** 锚点前的上下文文本（可选，用于上下文匹配回退） */
+    contextBefore?: string;
+    /** 锚点后的上下文文本（可选，用于上下文匹配回退） */
+    contextAfter?: string;
+    /** 归一化的边界框坐标（可选，0-1 范围，相对于页面尺寸） */
+    bbox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+};
+/**
+ * 已保存选择中的一个文本段落。
+ * 描述选择在单页内的一段连续文本及其位置信息。
+ */
+export type ReaderSavedSelectionSegment = {
+    /** 段落所在页码 */
+    pageNumber: number;
+    /** 文本元素的唯一标识符（可选） */
+    textId?: string;
+    /** 文本内容的哈希值（可选） */
+    textHash?: string;
+    /** 段落起始字符索引（可选） */
+    startCharIndex?: number;
+    /** 段落结束字符索引（可选） */
+    endCharIndex?: number;
+    /** 段落中的已选文本内容（可选） */
+    selectedText?: string;
+    /** 段落前的上下文文本（可选） */
+    contextBefore?: string;
+    /** 段落后的上下文文本（可选） */
+    contextAfter?: string;
+    /** 归一化的边界框坐标（可选，0-1 范围，相对于页面尺寸） */
+    bbox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+};
+/**
+ * 已保存选择的视觉回退数据（单页）。
+ * 当文本锚点无法解析时，使用归一化矩形区域进行视觉渲染。
+ */
+export type ReaderSavedSelectionVisualPage = {
+    /** 页码 */
+    pageNumber: number;
+    /** 页面尺寸（像素） */
+    pageSize: {
+        width: number;
+        height: number;
+    };
+    /** 归一化的矩形区域列表（0-1 范围，相对于页面尺寸） */
+    rects: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+};
+/** 已保存选择的恢复状态 */
+export type ReaderSavedSelectionRestoreStatus = 'resolved' | 'visual-fallback' | 'unresolved';
+/**
+ * 已保存选择的恢复结果。
+ * 包含恢复状态、覆盖层矩形、段落信息和提取的文本。
+ */
+export type ReaderSavedSelectionRestoreResult = {
+    /** 已保存选择的唯一标识符 */
+    id: string;
+    /** 原始的已保存选择数据 */
+    selection: ReaderSavedSelection;
+    /** 恢复状态 */
+    status: ReaderSavedSelectionRestoreStatus;
+    /** 可编辑的恢复 Range；视觉回退和未解析状态为空 */
+    range?: Range;
+    /** 恢复后的覆盖层矩形，坐标原点由 rectsOrigin 标识 */
+    rects: ReaderSelectionOverlayRect[];
+    /**
+     * rects 的坐标原点：
+     * - `'viewport'`      — 浏览器视口坐标，viewer 需转为 page-relative
+     * - `'page-relative'` — 已是页面相对像素坐标，viewer 不应二次转换
+     * - `'mixed'`         — 混合来源，需逐 rect 检查 origin 字段
+     * - `undefined`       — 历史行为，按 viewport 处理（向后兼容）
+     */
+    rectsOrigin?: 'viewport' | 'page-relative' | 'mixed';
+    /** 恢复后的段落信息，未解析时为空数组 */
+    segments: ReaderSavedSelectionSegment[];
+    /** 提取的文本内容，未解析时为空字符串 */
+    extractedText: string;
+    /** 未完全解析的原因说明（可选） */
+    reason?: string;
+};
+/**
+ * 已保存选择编辑事件的详细信息。
+ * 当用户通过拖动手柄编辑已保存选择时触发。
+ */
+export type ReaderSavedSelectionEditDetail = {
+    /** 已保存选择的唯一标识符 */
+    id: string;
+    /** 编辑后的选择数据 */
+    selection: ReaderSavedSelection;
+    /** 编辑前的选择数据 */
+    previousSelection: ReaderSavedSelection;
+    /** 恢复状态 */
+    status: ReaderSavedSelectionRestoreStatus;
+    /** 编辑后的段落信息 */
+    segments: ReaderSavedSelectionSegment[];
+    /** 编辑后提取的文本内容 */
+    extractedText: string;
+    /** 状态说明（可选） */
+    reason?: string;
+};
+/**
+ * 已保存选择的公共数据模型（v1 版本）。
+ *
+ * 设计原则：
+ * - **版本化**：`version` 字段为字面量 `1`，未来 schema 变更时递增。
+ * - **归一化坐标**：所有 bbox 和 visual rects 使用 0-1 归一化坐标，
+ *   相对于页面尺寸，确保跨分辨率一致性。
+ * - **调用方持久化**：Reader 和 IntermediateDocumentViewer 不实现持久化逻辑；
+ *   调用方负责保存/加载 savedSelections 数据。
+ * - **只读回退**：当文本锚点无法解析时，使用 visual 数据渲染只读覆盖层；
+ *   回退选择不可编辑，不显示拖动手柄。
+ */
+/**
+ * 已保存选择上的评论。评论数据由调用方维护，库本身只负责透传与
+ * 在编辑选区时保留这些数据，不会主动渲染或修改评论内容。
+ */
+export type ReaderSavedSelectionComment = {
+    /** 评论唯一标识符（由调用方生成） */
+    id: string;
+    /** 评论文本内容 */
+    text: string;
+    /** 评论创建时间戳（毫秒） */
+    createdAt: number;
+    /** 评论作者（可选） */
+    author?: string;
+};
+export type ReaderSavedSelection = {
+    /** 数据格式版本，当前固定为 1 */
+    version: 1;
+    /** 已保存选择的唯一标识符（由调用方生成和管理） */
+    id: string;
+    /** 文档标识符（可选，用于区分不同文档的选择） */
+    document?: string;
+    /** 选择的完整文本内容 */
+    text: string;
+    /** 选择起始锚点 */
+    start: ReaderSavedSelectionAnchor;
+    /** 选择结束锚点 */
+    end: ReaderSavedSelectionAnchor;
+    /** 选择包含的文本段落列表（支持跨页选择） */
+    segments: ReaderSavedSelectionSegment[];
+    /** 视觉回退数据（按页分组，用于无法解析文本时的只读渲染） */
+    visual: ReaderSavedSelectionVisualPage[];
+    /**
+     * 选区上的评论（可选）。库不解释这些数据，仅在 rebuildSavedSelectionFromEdit
+     * 等内部流程中保留它们，避免编辑手柄拖动时评论被意外丢弃。
+     */
+    comments?: ReaderSavedSelectionComment[];
+};
+export declare const isNonSpaceBlankText: (content: string) => boolean;
+/** 交互模式：'default' 为默认触摸/鼠标模式，'stylus' 为手写笔优化模式 */
+export type ReaderInteractionMode = 'default' | 'stylus';
+export type IntermediateDocumentViewerProps = {
+    document?: IntermediateDocument | IntermediateDocumentSerialized | null;
+    serializedDocument?: IntermediateDocumentSerialized | null;
+    className?: string;
+    overscan?: number;
+    pageRange?: ReaderPageRange;
+    ocr?: boolean | {
+        enabled?: boolean;
+    };
+    onOcrError?: (error: unknown, detail: {
+        pageNumber: number;
+    }) => void;
+    onTextSelectionChange?: (text: IntermediateText, detail: ReaderTextSelectionDetail) => void;
+    onTextSelectionEnd?: (text: IntermediateText, detail: ReaderTextSelectionDetail) => void;
+    onSelectText?: (selection: Selection, segments: ReaderSelectedTextSegment[], extractedText: string) => void;
+    /**
+     * Controlled zoom scale. When provided, internal wheel/pinch gestures do not
+     * mutate scale state; they call `onScaleChange` with the next clamped value
+     * and wait for the caller to pass that value back. Invalid/non-positive values
+     * are treated as the safe default scale of `1`, then clamped to the active
+     * bounds.
+     */
+    scale?: number;
+    /**
+     * Initial zoom scale for uncontrolled mode. Defaults to `1`, is clamped to the
+     * effective `minScale`/`maxScale` range, and is read only during initial state
+     * creation so later `defaultScale` prop changes do not reset user zoom.
+     */
+    defaultScale?: number;
+    /**
+     * Fires only when a wheel or pinch gesture produces a changed, clamped scale.
+     * The detail object reports `source: 'wheel' | 'pinch'` and may include the
+     * viewport focal point used to preserve scroll anchoring.
+     */
+    onScaleChange?: (scale: number, detail: {
+        source: 'wheel' | 'pinch';
+        focalPoint?: {
+            x: number;
+            y: number;
+        };
+    }) => void;
+    /**
+     * Lower zoom bound. Defaults to `0.25`; invalid or non-positive values fall
+     * back to the default. If the normalized minimum is greater than the maximum,
+     * the maximum is raised to the minimum to keep clamping deterministic.
+     */
+    minScale?: number;
+    /**
+     * Upper zoom bound. Defaults to `4`; invalid or non-positive values fall back
+     * to the default before the final range is normalized.
+     */
+    maxScale?: number;
+    /**
+     * Maximum number of concurrently loaded pages before lazy eviction. Defaults
+     * to `max(5, overscan * 2 + 5)`. Only `Infinity` disables eviction entirely;
+     * `0`, negative, `NaN`, or other invalid values fall back to the default cap.
+     * Finite values are floored by protected pages (visible pages, overscan,
+     * in-flight work, active selection/drag/pinch state, and saved-selection
+     * anchors), so more pages may remain loaded than the raw value. With
+     */
+    maxLoadedPages?: number;
+    /** 交互模式，影响手势处理行为 */
+    interactionMode?: ReaderInteractionMode;
+    /** 受控的已高亮 range 列表；传入时组件不内部 mutation，缺失则用内部 state 从 defaultRanges 初始化 */
+    ranges?: ReaderSelectionRange[];
+    /** 非受控模式下 ranges 的初始值，默认空数组 */
+    defaultRanges?: ReaderSelectionRange[];
+    /** 受控的当前选中 range ID；null 表示未选中；缺失则用内部 state 从 defaultSelectedRangeId 初始化 */
+    selectedRangeId?: string | null;
+    /** 非受控模式下 selectedRangeId 的初始值，默认 null */
+    defaultSelectedRangeId?: string | null;
+    /** 用户确认高亮时触发；非受控 ranges 模式下内部先 append range 再回调 */
+    onSelect?: (range: ReaderSelectionRange) => void;
+    onLinkedDataChange?: (next: ReaderLinkedSelectionData) => void;
+    onLinkedSelect?: (range: ReaderSelectionRange) => void;
+    onLinkedUpdateRange?: (range: ReaderSelectionRange) => void;
+    onLinkedSelectRange?: (id: string | null) => void;
+    /** 用户点击或取消选中某个已高亮 range 时触发 */
+    onSelectRange?: (id: string | null) => void;
+    /** 用户拖动已高亮 range 的首尾手柄调整范围时触发；非受控 ranges 模式下内部先替换对应 range */
+    onUpdateRange?: (range: ReaderSelectionRange) => void;
+    /** 用户开始选择时触发（容器内 mousedown），mousePos 为 viewport 坐标 */
+    onSelectionStart?: (mousePos: ReaderMousePosition, selection: Selection) => void;
+    /** 用户结束选择时触发（容器内 mouseup 且有有效选区）；注意 Selection 库此回调基于 mouseup，touch 选择可能不触发 */
+    onSelectionEnd?: (mousePos: ReaderMousePosition, selection: Selection) => void;
+    /** 执行高亮操作时额外触发（在 onSelect 之后） */
+    onHighlight?: (range: ReaderSelectionRange) => void;
+    /** 已确认高亮的 Overlay 颜色（CSS color），默认半透明黄 */
+    highlightColor?: string;
+    /** 正在选择中的临时 Overlay 颜色（CSS color），默认半透明粉 */
+    selectionColor?: string;
+    /** 当某个高亮被选中时，在其上方弹出的 Popover 内容（ReactNode），由调用方完全控制 */
+    selectionPopover?: React.ReactNode;
+    /** 被高亮的片段上方弹出的 Popover 内容，未提供时 fallback 到 selectionPopover */
+    highlightPopover?: React.ReactNode;
+    /** 是否在选区结束时自动触发高亮，默认为 false */
+    autoHighlight?: boolean;
+    /** Selection 组件的命令式 ref，暴露 highlight()/clear() 方法 */
+    selectionRef?: React.Ref<ReaderSelectionRef>;
+    /** 选区 Overlay 矩形坐标类型；默认 'percent' */
+    overlayRectType?: ReaderSelectionOverlayRectType;
+    /**
+     * 初始立即加载的页数。省略时默认 `1`。
+     */
+    initialLoadedPages?: number;
+    /**
+     * 同时并发加载的页数上限。省略时默认 `3`。
+     */
+    pageLoadConcurrency?: number;
+    /**
+     * 页面进入可加载窗口后、真正发起加载前的延迟（毫秒）。省略时默认 `500`。
+     */
+    pageLoadEnterDelayMs?: number;
+    /**
+     * 页面离开可加载窗口后、卸载其内容的延迟（毫秒）。省略时默认 `5000`。
+     */
+    pageUnloadDelayMs?: number;
+    /** intermediate-document 渲染阶段计时回调 */
+    onIntermediateDocumentRenderTiming?: IntermediateDocumentRenderTimingCallback;
+};
+/**
+ * Merge overlapping or adjacent rectangles on the same line.
+ * Uses a tolerance of 2px to handle minor gaps between text spans.
+ */
+export declare const mergeSelectionRects: (rects: Array<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>) => Array<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+export declare function IntermediateDocumentViewer({ document, serializedDocument, className, overscan, pageRange, ocr, onOcrError, onTextSelectionChange, onTextSelectionEnd, onSelectText, scale, defaultScale, onScaleChange, minScale, maxScale, maxLoadedPages, interactionMode, ranges, defaultRanges, selectedRangeId, defaultSelectedRangeId, onSelect, onLinkedDataChange, onLinkedSelect, onLinkedUpdateRange, onLinkedSelectRange, onSelectRange, onUpdateRange, onSelectionStart: onSelectionStartProp, onSelectionEnd: onSelectionEndProp, onHighlight, highlightColor, selectionColor, selectionPopover, highlightPopover, autoHighlight, selectionRef, overlayRectType, initialLoadedPages, pageLoadConcurrency, pageLoadEnterDelayMs, pageUnloadDelayMs, onIntermediateDocumentRenderTiming }: IntermediateDocumentViewerProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=IntermediateDocumentViewer.d.ts.map

package/dist/components/IntermediateDocumentViewer/IntermediateDocumentViewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntermediateDocumentViewer.d.ts","sourceRoot":"","sources":["../../../src/components/IntermediateDocumentViewer/IntermediateDocumentViewer.tsx"],"names":[],"mappings":"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"}

package/dist/components/IntermediateDocumentViewer/index.d.ts

@@ -0,0 +1,7 @@
+export { IntermediateDocumentViewer, isNonSpaceBlankText, mergeSelectionRects, type IntermediateDocumentViewerProps, type ReaderInteractionMode, type ReaderPageRange, type ReaderSavedSelection, type ReaderSavedSelectionAnchor, type ReaderSavedSelectionComment, type ReaderSavedSelectionEditDetail, type ReaderSavedSelectionRestoreResult, type ReaderSavedSelectionRestoreStatus, type ReaderSavedSelectionSegment, type ReaderSavedSelectionVisualPage, type ReaderSelectionOverlayRect, type ReaderTextSelectionDetail } from './IntermediateDocumentViewer';
+export { getNearestTextElementForPoint, getPageElementByPageNumber, getPageElementForPoint, resolveCaret } from '../selection/caretResolver';
+export { composeSelection, createOrderedRange } from '../selection/selectionComposer';
+export { buildSelectionPayload, getClosestTextElement, textElementRecords, type ReaderSelectedTextSegment, type ReaderSelectionPayload } from '../selection/selectionPayloadSerializer';
+export { buildSavedSelection, denormalizePageRects, normalizePageRects, resolveSavedSelection, textHash, type NormalizedRect, type TextElementInfo } from '../selection/savedSelection';
+export { createIntermediateDocumentRenderTiming, type CreateIntermediateDocumentRenderTimingOptions, type IntermediateDocumentRenderTiming, type IntermediateDocumentRenderTimingCallback, type IntermediateDocumentRenderTimingClock, type IntermediateDocumentRenderTimingEntry, type IntermediateDocumentRenderTimingStage } from './renderTiming';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/IntermediateDocumentViewer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/IntermediateDocumentViewer/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,+BAA+B,EACpC,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,EAChC,KAAK,8BAA8B,EACnC,KAAK,iCAAiC,EACtC,KAAK,iCAAiC,EACtC,KAAK,2BAA2B,EAChC,KAAK,8BAA8B,EACnC,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC/B,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,sBAAsB,EACtB,YAAY,EACb,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC5B,MAAM,yCAAyC,CAAA;AAChD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,QAAQ,EACR,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,sCAAsC,EACtC,KAAK,6CAA6C,EAClD,KAAK,gCAAgC,EACrC,KAAK,wCAAwC,EAC7C,KAAK,qCAAqC,EAC1C,KAAK,qCAAqC,EAC1C,KAAK,qCAAqC,EAC3C,MAAM,gBAAgB,CAAA"}

package/dist/components/IntermediateDocumentViewer/pageContentGeometry.d.ts

@@ -0,0 +1,84 @@
+import type { IntermediateImage, IntermediateText } from '@hamster-note/types';
+import type { CSSProperties } from 'react';
+/**
+ * intermediate-document 渲染器使用的
+ * 纯几何与样式辅助函数。
+ *
+ * 这些函数从 `IntermediateDocumentViewer.tsx` 中抽取出来，供新的
+ * `IntermediateDocumentPageContent` 渲染器复用，避免在
+ * 巨大的 viewer 文件中继续膨胀。所有函数均为纯函数，无闭包依赖，
+ * 由现有 intermediate-document 测试覆盖验证行为一致性。
+ */
+/**
+ * 几何计算用的单个点（[x, y]）。声明为 readonly tuple，既兼容运行期
+ * 解析器/OCR 提供的可变 `[number, number][]`，也兼容 `@hamster-note/types`
+ * 中 `IntermediateImage.polygon` / `IntermediateText.polygon` 的只读四点
+ * 多边形（`Polygon`），从而无需 `as unknown` 逃逸即可统一处理。
+ */
+export type GeometryPoint = readonly [number, number];
+/**
+ * 几何计算用的多边形：任意数量的 {@link GeometryPoint} 只读数组。
+ * `IntermediateImage.polygon`（4 点 `Polygon`）与运行期文本的
+ * `[number, number][]` 均可直接赋值给该类型。
+ */
+export type GeometryPolygon = readonly GeometryPoint[];
+/**
+ * 渲染时可用的 IntermediateText —— 序列化字段之外，运行期可能附带
+ * 解析器/OCR 提供的 x/y/width/height/polygon/rotate/skew 几何信息。
+ */
+export type RenderableIntermediateText = IntermediateText & Partial<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    polygon: GeometryPolygon;
+    rotate: number;
+    skew: number;
+}>;
+/** 多边形几何计算结果 */
+export type PolygonGeometry = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+};
+/**
+ * 合并多边形顶点为一个轴对齐包围盒（适用于少于 4 个有效顶点或非标准四边形）。
+ */
+export declare const getTextBoundingBox: (polygon: GeometryPolygon) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * 从标准四边形多边形（4 个顶点）推导精确的位置、尺寸与旋转角。
+ * 返回 null 表示多边形不规范，调用方应回退到轴对齐包围盒。
+ */
+export declare const getPolygonTextGeometry: (polygon: GeometryPolygon | undefined) => PolygonGeometry | null;
+/**
+ * 计算单个文本 span 的包围盒（优先使用四边形精确几何，回退到轴对齐包围盒，
+ * 最后回退到 x/y/width/height 字段）。
+ */
+export declare const getTextBbox: (text: RenderableIntermediateText) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+};
+/**
+ * 从 IntermediateImage 的四边形 polygon 计算位置、尺寸与旋转角。
+ * 复用与文本相同的四边形几何逻辑；polygon 缺失或非法时回退到 0 尺寸。
+ */
+export declare const getImageGeometry: (image: IntermediateImage) => PolygonGeometry;
+/**
+ * 根据 IntermediateImage 的几何与透明度/裁剪属性构建 `<img>` 的内联样式。
+ *
+ * - 位置与尺寸由 polygon 几何决定（绝对定位在页面内容层内）。
+ * - opacity 直接透传。
+ * - clip（如果存在）转换为 CSS `clip-path: inset(...)`，以图片自身盒子为参考。
+ */
+export declare const buildImageStyle: (image: IntermediateImage, geometry: PolygonGeometry) => CSSProperties;
+//# sourceMappingURL=pageContentGeometry.d.ts.map

package/dist/components/IntermediateDocumentViewer/pageContentGeometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pageContentGeometry.d.ts","sourceRoot":"","sources":["../../../src/components/IntermediateDocumentViewer/pageContentGeometry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAErD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,aAAa,EAAE,CAAA;AAEtD;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,gBAAgB,GACvD,OAAO,CAAC;IACN,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,eAAe,CAAA;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,CAAC,CAAA;AAEJ,gBAAgB;AAChB,MAAM,MAAM,eAAe,GAAG;IAC5B,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,eAAe;;;;;CAc1D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,eAAe,GAAG,SAAS,KACnC,eAAe,GAAG,IAqCpB,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,0BAA0B;;;;;;CA4B3D,CAAA;AAMD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,iBAAiB,KAAG,eAc3D,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,iBAAiB,EACxB,UAAU,eAAe,KACxB,aA6BF,CAAA"}

package/dist/components/IntermediateDocumentViewer/rangeJumpHelpers.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Pure range-jump helpers for public page ids and rect units.
+ *
+ * Given a range id and the public ReaderSelectionRange[],
+ * these helpers return a jump target { pageNumber, centerX, centerY }
+ * or null for no-op.  No React hooks or DOM access.
+ */
+import type { ReaderSelectionRange, ReaderSelectionRect } from '../../types/selection';
+export type RangeJumpTarget = {
+    /** 1-based public page number parsed from the page-N id. */
+    readonly pageNumber: number;
+    /** Horizontal center in page-local pixels. */
+    readonly centerX: number;
+    /** Vertical center in page-local pixels. */
+    readonly centerY: number;
+};
+/** Parse a public `page-N` id → 1-based page number, or null for malformed ids. */
+export declare function parsePublicPageId(pageId: string): number | null;
+/**
+ * Find a range by its public `id` in the ranges array.
+ * Returns null when no range matches.
+ */
+export declare function findRangeById(ranges: readonly ReaderSelectionRange[], rangeId: string): ReaderSelectionRange | null;
+type SelectedRect = {
+    readonly rect: ReaderSelectionRect;
+    /** Page id that owns this rect (e.g. "page-3"). */
+    readonly pageId: string;
+};
+/**
+ * Choose the best rect for jumping.
+ *
+ * Strategy (deterministic):
+ *  1. First rect under `range.start.selectionId` when that key exists.
+ *  2. Otherwise first rect from the first key in sorted key order.
+ *
+ * Returns null when rectsBySelectionId is empty or contains only empty arrays.
+ */
+export declare function selectTargetRect(range: ReaderSelectionRange): SelectedRect | null;
+/**
+ * Convert a rect's center from either percent (0-100) or px units
+ * to page-local pixel coordinates.
+ *
+ * @param rect       The overlay rect (x, y, width, height).
+ * @param rectType   'percent' treats x/y/width/height as 0-100;
+ *                   'px' treats them as page-local pixels.
+ * @param pageWidth  Page width in pixels.
+ * @param pageHeight Page height in pixels.
+ */
+export declare function rectCenterToPagePixels(rect: ReaderSelectionRect, rectType: 'percent' | 'px', pageWidth: number, pageHeight: number): {
+    centerX: number;
+    centerY: number;
+};
+export type ResolveRangeJumpTargetParams = {
+    readonly ranges: readonly ReaderSelectionRange[];
+    readonly rangeId: string;
+    /** Rect unit type to apply; falls back to range.overlayRectType then 'percent'. */
+    readonly rectType?: 'percent' | 'px';
+    readonly pageWidth: number;
+    readonly pageHeight: number;
+};
+/**
+ * Resolve a range id to a concrete page-local jump target.
+ *
+ * Flow:
+ *  1. Find the range by id → null if not found.
+ *  2. Select the best rect (start page → fallback) → null if no rects.
+ *  3. Parse the page id to a 1-based page number → null if malformed.
+ *  4. Convert the rect center to page-local pixels.
+ */
+export declare function resolveRangeJumpTarget(params: ResolveRangeJumpTargetParams): RangeJumpTarget | null;
+/**
+ * A VirtualPaper transform: `{ x, y, scale }`.
+ * Applied as `translate3d(x, y, 0) scale(scale)` on the content container.
+ */
+export type VirtualPaperTransform = {
+    readonly x: number;
+    readonly y: number;
+    readonly scale: number;
+};
+/**
+ * Compute the content-space origin (top-left) of a page by summing the
+ * heights of preceding pages and inter-page gaps.  X is 0 because the
+ * `.hamster-note-document` flex-column centers pages horizontally
+ * relative to the widest page (content coordinate 0 = left edge of the
+ * widest page, not necessarily the target page — but for transform
+ * clamping we only need the vertical origin; horizontal centering is
+ * handled by the page-local `targetCenterX`).
+ *
+ * This is the deterministic fallback for jsdom and zero-layout cases
+ * where real DOM measurement is unavailable.
+ */
+export declare function computePageOriginY(pageNumber: number, pageNumbers: readonly number[], pageSizesByPageNumber: ReadonlyMap<number, {
+    width: number;
+    height: number;
+}>): number;
+export type ComputeTransformParams = {
+    /** Viewport width in CSS pixels (the VirtualPaper wrapper element). */
+    readonly viewportWidth: number;
+    /** Viewport height in CSS pixels. */
+    readonly viewportHeight: number;
+    /** Content element total width in CSS pixels (pre-scale). */
+    readonly contentWidth: number;
+    /** Content element total height in CSS pixels (pre-scale). */
+    readonly contentHeight: number;
+    /** Content-space X coordinate to center on. */
+    readonly targetContentX: number;
+    /** Content-space Y coordinate to center on. */
+    readonly targetContentY: number;
+    /** Scale to apply. */
+    readonly scale: number;
+};
+/**
+ * Compute a VirtualPaper transform that centers `(targetContentX,
+ * targetContentY)` in the viewport, clamped to VirtualPaper contain
+ * semantics.
+ *
+ * Math:
+ *   screen = content * scale + translate
+ *   → translate = viewportCenter - targetContent * scale
+ *
+ * Contain clamping per axis:
+ *   - If scaledContentSize ≤ viewportSize → center the content:
+ *       translate = (viewportSize - scaledContentSize) / 2
+ *   - Otherwise → clamp so content edges stay visible:
+ *       translate ∈ [viewportSize - scaledContentSize, 0]
+ *
+ * Returns `null` when inputs are invalid (zero, negative, non-finite).
+ */
+export declare function computeTransform(params: ComputeTransformParams): VirtualPaperTransform | null;
+export {};
+//# sourceMappingURL=rangeJumpHelpers.d.ts.map

package/dist/components/IntermediateDocumentViewer/rangeJumpHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rangeJumpHelpers.d.ts","sourceRoot":"","sources":["../../../src/components/IntermediateDocumentViewer/rangeJumpHelpers.ts"],"names":[],"mappings":"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"}

package/dist/components/IntermediateDocumentViewer/renderTiming.d.ts

@@ -0,0 +1,44 @@
+/** 渲染计时阶段枚举 */
+export type IntermediateDocumentRenderTimingStage = 'document-resolution' | 'shell-rendering' | 'initial-page-loading' | 'content-extraction' | 'page-content-rendering' | 'visibility-lazy-loading' | 'offscreen-unload' | 'ocr-processing';
+/** 渲染计时记录条目 */
+export type DetailValue = string | number | boolean | null;
+export interface IntermediateDocumentRenderTimingEntry {
+    stage: IntermediateDocumentRenderTimingStage;
+    startedAt: number;
+    endedAt: number;
+    durationMs: number;
+    pageNumber?: number;
+    detail?: Readonly<Record<string, DetailValue>>;
+}
+/** 渲染计时回调 */
+export type IntermediateDocumentRenderTimingCallback = (entry: IntermediateDocumentRenderTimingEntry) => void;
+/** 时钟抽象，便于测试注入 */
+export interface IntermediateDocumentRenderTimingClock {
+    now: () => number;
+}
+/** 工厂函数选项 */
+export interface CreateIntermediateDocumentRenderTimingOptions {
+    callback?: IntermediateDocumentRenderTimingCallback;
+    clock?: IntermediateDocumentRenderTimingClock;
+    /** 显式覆盖环境变量检测结果；未提供时读取 import.meta.env */
+    envEnabled?: boolean;
+}
+/** 工厂函数返回的计时实例 */
+export interface IntermediateDocumentRenderTiming {
+    readonly enabled: boolean;
+    /** 开始计时，返回结束函数（disabled 时返回 no-op） */
+    start: (stage: IntermediateDocumentRenderTimingStage, context?: {
+        pageNumber?: number;
+        detail?: Record<string, DetailValue>;
+    }) => () => void;
+    /** 同步测量 fn 执行耗时并返回 fn 结果 */
+    measure: <T>(stage: IntermediateDocumentRenderTimingStage, context: {
+        pageNumber?: number;
+        detail?: Record<string, DetailValue>;
+    } | undefined, fn: () => T) => T;
+    /** 直接记录一条已构造的 entry */
+    record: (entry: IntermediateDocumentRenderTimingEntry) => void;
+}
+/** 创建 intermediate-document 渲染计时器 */
+export declare function createIntermediateDocumentRenderTiming(options?: CreateIntermediateDocumentRenderTimingOptions): IntermediateDocumentRenderTiming;
+//# sourceMappingURL=renderTiming.d.ts.map