@embedpdf-editor/react-chapter-viewer 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,803 @@
+import { AnnotationCapability } from '@embedpdf/plugin-annotation';
+import { BasePlugin } from '@embedpdf/core';
+import { BasePluginConfig } from '@embedpdf/core';
+import { ChapterPdfViewer } from '../chapter-pdf-viewer';
+import { ChapterPdfViewerProps } from '../chapter-pdf-viewer';
+import { Command } from '@embedpdf/plugin-commands';
+import { EmbedPDF } from '@embedpdf/core/react';
+import { EventHook } from '@embedpdf/core';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { PdfChapterViewport } from '../pdf-chapter-viewport';
+import { PdfChapterViewportProps } from '../pdf-chapter-viewport';
+import { PluginBatchRegistration } from '@embedpdf/core';
+import { PluginRegistry } from '@embedpdf/core';
+import { ReactNode } from 'react';
+import { Rect } from '@embedpdf/models';
+import { SelectionCapability } from '@embedpdf/plugin-selection';
+import { ToolbarSchema } from '@embedpdf/plugin-ui';
+import { UISchema } from '@embedpdf/plugin-ui';
+import { useCapability } from '@embedpdf/core/react';
+import { usePdfiumEngine } from '@embedpdf/engines/react';
+
+/** 对当前选区应用 PDF 划线/高亮，支持按类型自定义颜色、粗细与偏移 */
+export declare function applySelectionMarkup(documentId: string, kind: SelectionMarkupKind, annotation: AnnotationCapability, selection: SelectionCapability, styles?: MarkupStylesConfig): boolean;
+
+declare interface BookmarkMarkerUiConfig {
+    /** 自定义图标；提供时仅渲染图标，无默认蓝色背景按钮 */
+    renderIcon?: (ctx: {
+        bookmark: ParagraphBookmark;
+    }) => ReactNode;
+    iconSize?: number;
+}
+
+declare interface BookmarkMarkerUiConfig_2 {
+    /** 自定义图标；提供时仅渲染图标，无默认蓝色圆角背景 */
+    renderIcon?: (ctx: {
+        bookmark: ParagraphBookmark;
+    }) => unknown;
+    iconSize?: number;
+}
+
+export declare function buildParagraphBookmarkAnchor(chapterId: string, localPageIndex: number, rectsPdfCoord: Rect[], virtualPage?: {
+    globalPageIndex: number;
+    globalPageNumber: number;
+}): ParagraphBookmark['anchor'];
+
+/** 选区浮窗 card 内置操作 */
+declare type BuiltinSelectionToolbarAction = 'highlight' | 'underline' | 'squiggly' | 'strikeout' | 'note';
+
+/**
+ * 回调型：把决策交给业务侧异步函数（最常用）。
+ */
+export declare class CallbackPasswordProvider implements IPasswordProvider {
+    private readonly cb;
+    constructor(cb: (chapter: ChapterDescriptor, attempt: number) => Promise<string | null>);
+    resolvePassword(chapter: ChapterDescriptor, attempt: number): Promise<string | null>;
+}
+
+export declare interface ChapterDescriptor {
+    /** 业务唯一 ID；同时复用作 documentManager 的 documentId */
+    chapterId: string;
+    title: string;
+    /**
+     * 该章节在「整本」中的全局页范围（闭区间，业务页码，可 1-based 也可 0-based，
+     * 只要全局一致即可）。允许相邻章节重叠：`[a, b]` ∩ `[c, d]` ≠ ∅。
+     */
+    globalPageRange: [number, number];
+    /**
+     * 该章节 PDF 文件内部的本地页范围（0-based 闭区间）。
+     * 必须满足：`localPageRange[1] - localPageRange[0] === globalPageRange[1] - globalPageRange[0]`
+     */
+    localPageRange: [number, number];
+    /**
+     * PDF 来源。可省略：须在 ChapterManager 配置 `chapterPdfLoader` 中统一加载。
+     */
+    source?: ChapterSource;
+    encrypted?: boolean;
+    /**
+     * 仅当 OverlapOwnerStrategy = 'explicit' 时使用：
+     * 该章节"声明拥有"的全局页号集合。
+     */
+    ownedGlobalPages?: number[];
+}
+
+/**
+ * 章节级加载状态。区别于 `@embedpdf/core` 的 DocumentState：
+ * - `idle` = manifest 已注册但尚未触发 open
+ * - `password-required` = 用户取消/密码错误后停在等密码态
+ */
+export declare type ChapterLoadStatus = 'idle' | 'loading' | 'loaded' | 'error' | 'password-required' | 'closed';
+
+declare interface ChapterManagerCapability {
+    /** 替换 manifest（会触发已不存在章节的卸载） */
+    setManifest(manifest: ChapterManifest, strategy?: OverlapOwnerStrategy): void;
+    getManifest(): ChapterManifest;
+    getVirtualPageMap(): VirtualPageMap;
+    /** ChapterScrollPlugin 在可见页位变化时调用，用以驱动按需加载 */
+    setVisibleGlobalPages(visiblePageIndices: number[]): void;
+    /** 显式触发某章节加载（如点击章节标题跳转时） */
+    ensureChapterLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    /** 状态查询 */
+    getChapterStatus(chapterId: string): ChapterLoadStatus;
+    getChapter(chapterId: string): ChapterDescriptor | null;
+    /** 事件 */
+    onChapterStatusChange: EventHook<ChapterStatusEvent>;
+    onManifestChange: EventHook<{
+        manifest: ChapterManifest;
+        map: VirtualPageMap;
+    }>;
+}
+
+/**
+ * 章节生命周期管理：以章节为粒度懒加载/预取/卸载 PDF 文件，并屏蔽密码协议细节。
+ *
+ * 关键不变量：
+ * - 每个章节对 DocumentManager 用 `documentId === chapterId`，从而保持 1:1 缓存。
+ * - 视觉上的「activeDocumentId」由本插件根据当前可见页位维护；上层无须感知。
+ * - 渲染层最终始终通过 `(chapterId, localPageIndex)` 索引到 owner 章节的 PDF 文档。
+ */
+export declare class ChapterManagerPlugin extends BasePlugin<ChapterManagerPluginConfig, ChapterManagerCapability> {
+    static readonly id: "chapter-manager";
+    private readonly statusChange$;
+    private readonly manifestChange$;
+    private config;
+    private documentManager;
+    private passwordProvider?;
+    private manifest;
+    private overlapStrategy;
+    private virtualPageMap;
+    /** 每个章节当前状态（in-memory；不需要 redux 同步） */
+    private readonly chapterStatus;
+    /** 章节最近一次进入视口或被显式请求的时间戳，用于卸载判断 */
+    private readonly chapterLastUsed;
+    /** 章节密码累计尝试次数 */
+    private readonly passwordAttempts;
+    /** 等待 ensureChapterLoaded 完成的 Promise 列表（按章节去重） */
+    private readonly pendingLoadPromises;
+    /** unload tick 句柄 */
+    private unloadTimer;
+    private documentManagerUnsubs;
+    constructor(id: string, registry: PluginRegistry);
+    initialize(config: ChapterManagerPluginConfig): Promise<void>;
+    protected buildCapability(): ChapterManagerCapability;
+    destroy(): void;
+    private setManifestInternal;
+    /** manifest 就绪后预取前 N 章（不依赖滚动视口是否已算出可见页） */
+    private eagerPrefetchFromManifest;
+    private findChapter;
+    private isOwnedChapter;
+    private handleVisibleChange;
+    private collectIdleChapters;
+    ensureChapterLoaded(chapterId: string): Promise<ChapterLoadStatus>;
+    private resolvePdfPayload;
+    private startLoad;
+    /** 阻塞等待该章节状态进入 loaded / error / password-required / closed */
+    private waitForTerminalStatus;
+    private handleDocumentError;
+    private closeChapter;
+    private updateStatus;
+}
+
+declare interface ChapterManagerPluginConfig extends BasePluginConfig {
+    manifest: ChapterManifest;
+    overlapStrategy?: OverlapOwnerStrategy;
+    passwordProvider?: IPasswordProvider;
+    /** 未在 descriptor.source 中指定 PDF 时，由此统一加载 */
+    chapterPdfLoader?: IChapterPdfLoader;
+    /** 视口前后预取多少章节，默认 1 */
+    prefetchChapters?: number;
+    /** 章节空闲多久后卸载（毫秒），默认 60s。设为 0 关闭卸载 */
+    unloadTimeoutMs?: number;
+    /** 第一个加载的章节是否自动设为 active，默认 true */
+    autoActivateOnLoad?: boolean;
+}
+
+export declare interface ChapterManifest {
+    chapters: ChapterDescriptor[];
+    /**
+     * 整本去重后的总页数。当未提供时由 VirtualPageMap 自动推导
+     * （取所有章节 globalPageRange 的并集大小）。
+     */
+    totalGlobalPages?: number;
+}
+
+/** 单页布局（用于 ChapterScroller 渲染） */
+declare interface ChapterPageItem {
+    /** 0-based 紧凑虚拟索引 */
+    globalPageIndex: number;
+    /** 后端业务页号 */
+    globalPageNumber: number;
+    chapterId: string;
+    localPageIndex: number;
+    /** 渲染尺寸（CSS 像素，含 scale） */
+    width: number;
+    height: number;
+    /** 在内容容器内的纵向偏移（CSS 像素） */
+    offsetTop: number;
+    /** owner 章节尚未加载完成；UI 通常画一个 skeleton */
+    isPlaceholder: boolean;
+}
+
+/**
+ * Backend-supplied chapter contract.
+ *
+ * 一个 PDF 整体被后端按章节切成若干独立 PDF 文件；前端将它们组装成一条
+ * 连续滚动流。相邻章节在 `globalPageRange` 上**允许重叠**（业务上下章
+ * 经常各含一个过渡页），由 OverlapResolver 决定每个全局页归属的「owner
+ * chapter」，渲染与标注都落在 owner 上以保持唯一性。
+ */
+/** 章节 PDF 解析结果 */
+export declare type ChapterPdfPayload = {
+    url: string;
+} | {
+    buffer: ArrayBuffer;
+};
+
+export { ChapterPdfViewer }
+
+export { ChapterPdfViewerProps }
+
+declare interface ChapterScrollCapability {
+    /** 绑定/解绑滚动容器（由 ChapterScroller 内部调用） */
+    registerViewport(el: HTMLElement | null): void;
+    /** 当某章节 PDF 加载完成时，由 ChapterRenderLayer 等汇报真实页尺寸 */
+    reportChapterPageSizes(chapterId: string, sizes: Array<{
+        localPageIndex: number;
+        width: number;
+        height: number;
+    }>): void;
+    /** 当前布局 */
+    getLayout(): ChapterScrollLayout;
+    getCurrentGlobalPageIndex(): number;
+    getVisibleGlobalPageIndices(): number[];
+    /** 跳转 */
+    scrollToGlobalPageIndex(idx: number, options?: ChapterScrollScrollToOptions): void;
+    scrollToChapter(chapterId: string, options?: ChapterScrollScrollToOptions): void;
+    scrollToGlobalPageNumber(globalPageNumber: number, options?: ChapterScrollScrollToOptions): void;
+    /**
+     * 滚动到虚拟页内某 PDF 坐标点（y 为 PDF 坐标，原点在页左下）。
+     * 比 topOffset 更直观，附注/书签定位应优先使用。
+     */
+    scrollToGlobalPdfPoint(globalPageIndex: number, pdfY: number, options?: ChapterScrollScrollToPdfPointOptions): void;
+    /** 事件 */
+    onLayoutChange: EventHook<ChapterScrollLayout>;
+    onVisibleChange: EventHook<VisibleChangeEvent>;
+}
+
+declare interface ChapterScrollLayout {
+    totalHeight: number;
+    totalWidth: number;
+    items: ChapterPageItem[];
+    pageGap: number;
+}
+
+/**
+ * 跨章节虚拟滚动。
+ *
+ * 设计：
+ * - 维护一个「整本」页位序列（来自 `chapter-manager.getVirtualPageMap()`，已 dedup）。
+ * - 每个页位先用占位尺寸；当章节加载完成后由 ChapterRenderLayer 上报真实尺寸 → 重排。
+ * - 监听容器 scroll/resize，计算 visible + buffer 范围 → 输出 `ChapterScrollLayout`。
+ * - 把 `visibleGlobalPageIndices` 反向回传给 chapter-manager 驱动按需加载/卸载。
+ *
+ * 不直接持有 @embedpdf/plugin-viewport / plugin-scroll —— 它在 `ChapterScroller`
+ * 组件内部自己挂滚动监听，避免与单文档版本冲突。
+ */
+export declare class ChapterScrollPlugin extends BasePlugin<ChapterScrollPluginConfig, ChapterScrollCapability> {
+    static readonly id: "chapter-scroll";
+    private readonly layoutChange$;
+    private readonly visibleChange$;
+    private config;
+    private chapterManager;
+    private documentManager;
+    private virtualPageMap;
+    /** 每个页位的真实尺寸（key = globalPageIndex），未上报前用占位 */
+    private readonly pageSizes;
+    /** 累计后的纵向偏移缓存（key = globalPageIndex） */
+    private offsets;
+    private totalHeight;
+    private totalWidth;
+    private viewportEl;
+    private viewportObservers;
+    private currentVisible;
+    private currentGlobalPageIndex;
+    private chapterManagerUnsubs;
+    constructor(id: string, registry: PluginRegistry);
+    initialize(config: ChapterScrollPluginConfig): Promise<void>;
+    /** 章节 PDF 在 document-manager 中是否已可渲染（不依赖 chapter-manager.status，避免事件丢失） */
+    private isChapterDocumentReady;
+    private refreshLayout;
+    /** 对已打开且可渲染的章节补采页尺寸 */
+    private syncReadyChapterSizes;
+    protected onDocumentLoaded(documentId: string): void;
+    protected onDocumentClosed(documentId: string): void;
+    protected buildCapability(): ChapterScrollCapability;
+    destroy(): void;
+    private getPageSize;
+    private rebuildOffsets;
+    private applyChapterPageSizes;
+    /** 章节 document 在 core store 中的缩放（与 RenderLayer / Annotation 一致） */
+    private getChapterDocumentScale;
+    /** 从已加载的 PdfDocumentObject 拉取章节内所有页尺寸并上报 */
+    private harvestChapterSizes;
+    /** core SET_SCALE 后重算布局，使滚动占位与 PDF 渲染尺寸一致 */
+    protected onScaleChanged(documentId: string): void;
+    private dropChapterSizes;
+    private bindViewport;
+    private recomputeVisible;
+    private findFirstVisibleIndex;
+    private computeLayout;
+    private scrollToIndex;
+    private scrollToGlobalPdfPoint;
+    private scrollToChapter;
+    private scrollToGlobalNumber;
+}
+
+declare interface ChapterScrollPluginConfig extends BasePluginConfig {
+    /** 章节尚未加载时占位页高度（CSS 像素），默认 1200 */
+    placeholderPageHeight?: number;
+    /** 占位页宽度（CSS 像素），默认 900 */
+    placeholderPageWidth?: number;
+    /** 上下 buffer 页数，默认 2 */
+    bufferSize?: number;
+    /** 页间距，默认 20 */
+    pageGap?: number;
+}
+
+declare interface ChapterScrollScrollToOptions {
+    /** behavior 默认 'auto' */
+    behavior?: ScrollBehavior;
+    /** 距离顶部的偏移（CSS 像素），默认 0 */
+    topOffset?: number;
+}
+
+declare interface ChapterScrollScrollToPdfPointOptions {
+    behavior?: ScrollBehavior;
+    /** 目标点距视口顶部的留白（CSS 像素），默认 80 */
+    marginTop?: number;
+}
+
+/**
+ * 章节 PDF 来源（由业务在 manifest 中提供）：
+ * - `url`：直接打开该地址
+ * - `buffer`：已取回的 PDF 二进制
+ * - `load`：按章节自定义拉取（鉴权、本地 FS 等）
+ */
+export declare type ChapterSource = {
+    url: string;
+} | {
+    buffer: ArrayBuffer;
+} | {
+    load: () => Promise<ChapterPdfPayload>;
+};
+
+declare interface ChapterStatusEvent {
+    chapterId: string;
+    status: ChapterLoadStatus;
+    /** 仅在 status === 'error' 时有意义 */
+    error?: {
+        message: string;
+        code?: number;
+    };
+}
+
+/** 章节目录树节点（仅 UI；内容由业务构造） */
+export declare type ChapterTreeNode = {
+    id: string;
+    title: string;
+    startPage: number;
+    endPage: number;
+    children?: ChapterTreeNode[];
+};
+
+export declare function ChapterTreePanel({ tree, activeChapterId, onActiveChapterChange, }: ChapterTreePanelProps): JSX_2.Element;
+
+export declare type ChapterTreePanelProps = {
+    tree: ChapterTreeNode[];
+    activeChapterId: string;
+    onActiveChapterChange?: (chapterId: string) => void;
+};
+
+/** 目录树 + 章节 manifest，由业务组装后传入阅读器 */
+export declare type ChapterViewerCatalog = {
+    tree: ChapterTreeNode[];
+    manifest: ChapterManifest;
+};
+
+/** 章节渲染器集成功能开关（与 demo 默认样式对齐） */
+export declare interface ChapterViewerFeaturesConfig {
+    /** 划线/高亮 */
+    markup?: {
+        enabled?: boolean;
+        styles?: MarkupStylesConfig;
+    };
+    /** 段落书签（含悬停添加） */
+    bookmarks?: {
+        enabled?: boolean;
+        marker?: BookmarkMarkerUiConfig_2;
+        hover?: HoverBookmarkUiConfig_2;
+    };
+    /** 笔记 */
+    notes?: {
+        enabled?: boolean;
+        marker?: NoteMarkerUiConfig;
+    };
+    /** 选区浮窗 */
+    selectionToolbar?: SelectionToolbarConfig;
+    /** 缩放 */
+    zoom?: ChapterViewerZoomConfig;
+}
+
+declare interface ChapterViewerZoomConfig {
+    /** 是否启用 pinch/滑块缩放容器，默认 true */
+    enabled?: boolean;
+    min?: number;
+    max?: number;
+    initial?: number;
+}
+
+/**
+ * 创建带默认划线/笔记/书签/选区 card 的章节编辑器插件包。
+ * 传入的 `features` 与默认值浅合并。
+ */
+export declare function createChapterViewerEditor(options: CreatePdfChapterEditorOptions): PdfChapterEditorBundle;
+
+export declare function createChapterViewerEditorOptions(input: CreateChapterViewerEditorOptionsInput): Omit<CreatePdfChapterEditorOptions, 'features'>;
+
+export declare type CreateChapterViewerEditorOptionsInput = {
+    manifest: ChapterManifest;
+    chapterPdfLoader?: IChapterPdfLoader;
+    bookmarks: PdfChapterEditorBookmarksConfig;
+    notes: PdfChapterEditorNotesConfig;
+};
+
+declare interface CreateEditorUiSchemaOptions {
+    /** 默认全开 */
+    enabledModes?: EditorModeId[];
+    customOperations?: OperationSpec[];
+    /** 合并进最终 schema 的额外 toolbars / menus 等 */
+    extend?: Partial<Pick<UISchema, 'toolbars' | 'menus' | 'sidebars' | 'modals' | 'selectionMenus'>>;
+}
+
+/**
+ * 组装章节 PDF 编辑器所需的插件注册列表与 UI Schema。
+ * 不挂载 `@embedpdf/plugin-scroll`；滚动由 `ChapterScrollPlugin` + `ChapterScroller` 负责。
+ */
+export declare function createPdfChapterEditor(options: CreatePdfChapterEditorOptions): PdfChapterEditorBundle;
+
+export declare interface CreatePdfChapterEditorOptions {
+    manifest: ChapterManifest;
+    overlapStrategy?: OverlapOwnerStrategy;
+    passwordProvider?: IPasswordProvider;
+    /** 章节未在 manifest 中写 source 时，由此加载 PDF */
+    chapterPdfLoader?: IChapterPdfLoader;
+    notes?: PdfChapterEditorNotesConfig;
+    bookmarks?: PdfChapterEditorBookmarksConfig;
+    toolbar?: PdfChapterEditorToolbarConfig;
+    /** 传给 chapter-manager；manifest 就绪后预取前 N 章 */
+    prefetchChapters?: number;
+    /** 为 false 时不拉取 CDN 默认图章库（@embedpdf/default-stamps） */
+    loadDefaultStampLibrary?: boolean;
+    unloadTimeoutMs?: number;
+    /** 传给 chapter-scroll */
+    placeholderPageHeight?: number;
+    placeholderPageWidth?: number;
+    /** 合并进 Commands 插件（如 mode / annotation / form 等） */
+    commands?: Record<string, Command>;
+    /**
+     * 章节阅读器集成功能（划线/笔记/书签/选区 card / 缩放）。
+     * 默认 demo 样式；各子项可单独关闭或扩展。
+     */
+    features?: ChapterViewerFeaturesConfig;
+}
+
+/** 与 demo 对齐的默认集成功能 */
+export declare const DEFAULT_CHAPTER_VIEWER_FEATURES: ChapterViewerFeaturesConfig;
+
+/** 与 snippet 主工具栏 mode tabs 对齐的编辑模式 */
+declare type EditorModeId = 'view' | 'annotate' | 'shapes' | 'insert' | 'form' | 'redact';
+
+/** Snippet-derived secondary toolbars for Annotate / Shapes / Insert / Form / Redact */
+declare const editorSecondaryToolbars: Record<string, ToolbarSchema>;
+
+export { EmbedPDF }
+
+declare interface HoverBookmarkUiConfig {
+    renderAddIcon?: () => ReactNode;
+    iconSize?: number;
+}
+
+declare interface HoverBookmarkUiConfig_2 {
+    /** 悬停行末「添加书签」自定义图标；无背景 */
+    renderAddIcon?: () => unknown;
+    iconSize?: number;
+}
+
+/**
+ * 全局章节 PDF 加载器：当 `ChapterDescriptor.source` 未提供 url/buffer/load 时使用。
+ * 适合统一走业务 API、鉴权下载等场景。
+ */
+export declare interface IChapterPdfLoader {
+    loadPdf(chapter: ChapterDescriptor): Promise<ChapterPdfPayload>;
+}
+
+/**
+ * 章节加密的抽象接口：当某章节首次或重试加载因密码失败时，
+ * `ChapterManagerPlugin` 会向 provider 询问密码。
+ *
+ * 返回 `null` 表示用户/系统放弃，对应章节进入 `password-required` 状态。
+ */
+declare interface IPasswordProvider {
+    /**
+     * @param chapter 失败章节描述
+     * @param attempt 已经尝试次数（0 = 首次），可用于实现"输错三次锁定"等策略
+     */
+    resolvePassword(chapter: ChapterDescriptor, attempt: number): Promise<string | null>;
+    /** 可选：同步快查缓存，避免显式 await */
+    getCachedPassword?(chapterId: string): string | null;
+}
+
+/** 单种划线的样式（颜色、粗细、垂直偏移，PDF 点） */
+export declare interface MarkupKindStyle {
+    /** 描边/填充色，如 #facc15 */
+    color?: string;
+    /** 线宽（下划线/删除线等），PDF 点 */
+    thickness?: number;
+    /** 相对字形底边的垂直偏移，正值向下（PDF 点） */
+    offsetY?: number;
+    opacity?: number;
+}
+
+export declare type MarkupStylesConfig = Partial<Record<SelectionMarkupKind, MarkupKindStyle>>;
+
+/**
+ * 一条附注（note）的位置锚点。
+ * - `rectsPdfCoord` 来自 selection.getHighlightRectsForPage 的 PDF 坐标系
+ * - `endAnchor` 用于"末尾图标"渲染：取选区最后一行 right 边缘
+ * - `noteId` 由开发者回调返回（服务端 ID），插件本身不生成
+ */
+export declare interface NoteAnchor {
+    noteId: string;
+    chapterId: string;
+    globalPageIndex: number;
+    globalPageNumber: number;
+    localPageIndex: number;
+    rectsPdfCoord: Rect[];
+    endAnchor: {
+        x: number;
+        y: number;
+    };
+    selectedText: string;
+    /** 用户填写的笔记正文（由业务持久化） */
+    content?: string;
+}
+
+export declare interface NoteCallbacks {
+    /** 初次加载已有附注 */
+    loadNotes?: () => Promise<NoteAnchor[]>;
+    /**
+     * 内置创建：持久化后返回 noteId。
+     * 与 onRequestCreateNote 二选一（至少配置其一）。
+     */
+    onCreateNote?: (draft: NoteDraft) => Promise<{
+        noteId: string;
+    } | null>;
+    /**
+     * 自定义创建弹窗：仅发出事件，由宿主 complete(noteId)。
+     * 配置后划词/默认流程不再调用 onCreateNote。
+     */
+    onRequestCreateNote?: (payload: NoteCreateRequestPayload_2) => void;
+    /** 自定义编辑：传出 noteId */
+    onRequestEditNote?: (noteId: string, anchor: NoteAnchor) => void;
+    onUpdateNote?: (note: NoteAnchor) => Promise<void>;
+    onDeleteNote?: (noteId: string) => Promise<void>;
+    /** 点击编辑且未配置 onRequestEditNote 时回退 */
+    onActivateNote?: (noteId: string, anchor: NoteAnchor) => void;
+}
+
+/** 笔记创建请求（划词选「笔记」或宿主触发） */
+export declare interface NoteCreateRequestPayload {
+    draft: NoteDraft;
+    /** 用户完成创建后调用，传入业务 noteId */
+    complete: (noteId: string) => Promise<void>;
+}
+
+/** 自定义笔记创建：宿主打开 UI 后调用 complete(noteId) */
+declare interface NoteCreateRequestPayload_2 {
+    draft: NoteDraft;
+    complete: (noteId: string) => Promise<void>;
+}
+
+/** 一个尚未持久化的草稿（开发者回调拿到的） */
+export declare type NoteDraft = Omit<NoteAnchor, 'noteId'>;
+
+declare interface NoteMarkerMenuActionCtx {
+    note: NoteAnchor;
+    onEdit: () => void;
+    onDelete: () => void;
+}
+
+declare interface NoteMarkerUiConfig {
+    /** 自定义笔记标识图标；提供时无圆形背景 */
+    renderIcon?: (ctx: {
+        note: NoteAnchor;
+    }) => unknown;
+    /** 完全自定义编辑/删除区域；不提供则使用默认 card */
+    renderMenuActions?: (ctx: NoteMarkerMenuActionCtx) => unknown;
+    iconSize?: number;
+    /** 笔记高亮底色的 CSS 颜色，默认 rgba(245,158,11,0.08) */
+    highlightColor?: string;
+}
+
+declare interface OperationHandlerContext {
+    documentId: string | null;
+    chapterId: string | null;
+}
+
+/**
+ * 收集开发者自定义操作，并把它们注入到 secondary toolbar 的 items 里。
+ * Commands 插件侧的 register 由宿主在引擎初始化时根据 spec.handler 完成。
+ */
+declare class OperationRegistry {
+    private readonly specs;
+    register(operation: OperationSpec): void;
+    registerAll(operations: OperationSpec[]): void;
+    list(): readonly OperationSpec[];
+    /**
+     * 返回注入了 customOperations 的 toolbar 副本（不修改原始 fragment）。
+     */
+    buildToolbars(): typeof editorSecondaryToolbars;
+}
+
+/** 自定义操作挂载到某条 secondary toolbar */
+declare interface OperationSpec {
+    id: string;
+    modeId: EditorModeId;
+    /** 对应 {@link editorSecondaryToolbars} 的 key */
+    toolbarSlot: 'annotation-toolbar' | 'shapes-toolbar' | 'insert-toolbar' | 'form-toolbar' | 'redaction-toolbar';
+    /** 插入到某 toolbar item 之后；缺省则追加到 tools group 末尾 */
+    position?: {
+        after?: string;
+        before?: string;
+    };
+    commandId: string;
+    icon?: string;
+    i18nKey?: string;
+    label?: string;
+    categories?: string[];
+    /** 注册到 Commands 插件时的执行体（由宿主在 createPdfChapterEditor 里注入） */
+    handler?: (ctx: OperationHandlerContext) => void | Promise<void>;
+}
+
+/**
+ * 决定相邻章节在重叠页上谁拥有该页（owner）。
+ * - first-wins / last-wins：按 manifest 顺序的先到/后到
+ * - explicit：依赖 `ChapterDescriptor.ownedGlobalPages`
+ * - custom：开发者完全接管
+ */
+declare type OverlapOwnerStrategy = {
+    kind: 'first-wins';
+} | {
+    kind: 'last-wins';
+} | {
+    kind: 'explicit';
+} | {
+    kind: 'custom';
+    resolve: (globalPage: number, candidates: ChapterDescriptor[]) => string;
+};
+
+export declare interface ParagraphBookmark {
+    id: string;
+    label: string;
+    /** 业务可选元数据；插件直接存不解释 */
+    metadata?: Record<string, unknown>;
+    anchor: {
+        chapterId: string;
+        localPageIndex: number;
+        /** 创建时虚拟页索引（与附注一致，避免 toGlobal 映射偏差） */
+        globalPageIndex?: number;
+        /** 创建时业务页号 */
+        globalPageNumber?: number;
+        /** PDF 坐标系包围盒（多行选区时为各行并集） */
+        rectPdfCoord: Rect;
+        /** 各行 PDF 矩形（划词书签时与选区高亮一致） */
+        rectsPdfCoord?: Rect[];
+        /** 书签图标锚点（通常为选区末行右下角，PDF 坐标） */
+        markerAnchor?: {
+            x: number;
+            y: number;
+        };
+    };
+    createdAt: number;
+}
+
+declare interface ParagraphBookmarkCallbacks {
+    /** 初次加载已有书签 */
+    load?: () => Promise<ParagraphBookmark[]>;
+    /** 任意变更（新增 / 删除 / 改名）后回调，便于持久化 */
+    persist?: (entries: ParagraphBookmark[]) => Promise<void>;
+    /**
+     * 用户请求删除书签：由外部完成持久化删除。
+     * 返回 true 时插件会从渲染层移除该书签。
+     */
+    onRequestRemove?: (bookmark: ParagraphBookmark) => Promise<boolean>;
+    /** 书签已从插件内存移除后通知（便于 UI 收尾） */
+    onRemoveSuccess?: (bookmarkId: string) => void;
+}
+
+declare interface ParagraphBookmarkPluginConfig extends BasePluginConfig {
+    callbacks?: ParagraphBookmarkCallbacks;
+    ui?: BookmarkMarkerUiConfig;
+    hover?: HoverBookmarkUiConfig;
+}
+
+export declare interface PdfChapterEditorBookmarksConfig {
+    callbacks: NonNullable<ParagraphBookmarkPluginConfig['callbacks']>;
+}
+
+declare interface PdfChapterEditorBundle {
+    plugins: PluginBatchRegistration<any, any, any, any>[];
+    uiSchema: UISchema;
+    operationRegistry: OperationRegistry;
+}
+
+export declare interface PdfChapterEditorNotesConfig {
+    callbacks: NoteCallbacks;
+}
+
+declare interface PdfChapterEditorToolbarConfig extends CreateEditorUiSchemaOptions {
+}
+
+export { PdfChapterViewport }
+
+export { PdfChapterViewportProps }
+
+/** 划线类型 */
+declare type SelectionMarkupKind = 'highlight' | 'underline' | 'squiggly' | 'strikeout';
+
+declare interface SelectionToolbarConfig {
+    /** 是否显示默认 card，默认 true */
+    enabled?: boolean;
+    /** 隐藏部分内置按钮 */
+    hiddenBuiltinActions?: BuiltinSelectionToolbarAction[];
+    /** 扩展操作（由宿主在 buildSelectionMenu 或 onExtraAction 中处理） */
+    extraActions?: SelectionToolbarExtraAction[];
+}
+
+/** 扩展选区操作 */
+export declare interface SelectionToolbarExtraAction {
+    id: string;
+    label: string;
+    /** 排序权重，越小越靠前（在内置 markup 之后、note 之前） */
+    order?: number;
+}
+
+export { useCapability }
+
+export { usePdfiumEngine }
+
+/**
+ * 一个虚拟页位的解析结果。`localPageIndex` 是 owner 章节 PDF 内的 0-based 索引。
+ */
+declare interface VirtualPageLocation {
+    globalPageIndex: number;
+    globalPageNumber: number;
+    chapterId: string;
+    localPageIndex: number;
+}
+
+/**
+ * 跨章节 PDF 的「全局页 ↔ (章节, 本地页)」映射。
+ *
+ * 设计要点：
+ * - 「globalPageNumber」是后端 manifest 里的业务页号，可能不连续（极端情况）。
+ * - 「globalPageIndex」是去重后排序的 0-based 紧凑索引，是滚动/虚拟列表使用的页位。
+ *   这样上层 `ChapterScroll` 不必关心业务页号是否连续。
+ */
+declare class VirtualPageMap {
+    private readonly _pages;
+    private readonly _byChapter;
+    private readonly _byGlobalNumber;
+    constructor(pages: VirtualPageLocation[]);
+    get totalPages(): number;
+    /** 顺序返回所有去重后的页位 */
+    list(): readonly VirtualPageLocation[];
+    /** 由 0-based 紧凑索引取页位 */
+    atIndex(globalPageIndex: number): VirtualPageLocation | null;
+    /** 由后端业务页号取页位 */
+    byGlobalNumber(globalPageNumber: number): VirtualPageLocation | null;
+    /** 由 (章节, 本地页) 反查到 owner 视图下的全局位置；非 owner 章节会返回 null */
+    toGlobal(chapterId: string, localPageIndex: number): VirtualPageLocation | null;
+    /** 该章节在虚拟视图中实际「被采用」的页（owner 命中的） */
+    pagesOfChapter(chapterId: string): readonly VirtualPageLocation[];
+    /** 拿一个章节首次出现的虚拟索引（用于 scrollToChapter） */
+    firstIndexOfChapter(chapterId: string): number;
+}
+
+declare interface VisibleChangeEvent {
+    /** 当前可见页紧凑索引（去重后的全局序号），按顺序 */
+    visibleGlobalPageIndices: number[];
+    currentGlobalPageIndex: number;
+}
+
+export { }