@embedpdf-editor/chapter-snippet 0.3.0

package/dist/embedpdf-chapter.d.ts

@@ -0,0 +1,806 @@
+import { AnnotationCapability } from '@embedpdf/plugin-annotation';
+import { AnnotationTransferItem } from '@embedpdf/plugin-annotation';
+import { BasePlugin } from '@embedpdf/core';
+import { BasePluginConfig } from '@embedpdf/core';
+import { ChapterTreeNode } from '../vue/chapter-tree';
+import { ChapterViewerCatalog } from '../vue/chapter-tree';
+import { Command } from '@embedpdf/plugin-commands';
+import { EventHook } from '@embedpdf/core';
+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 { UISchema } from '@embedpdf/plugin-ui';
+
+/** 对当前选区应用 PDF 划线/高亮，支持按类型自定义颜色、粗细与偏移 */
+export declare function applySelectionMarkup(documentId: string, kind: SelectionMarkupKind, annotation: AnnotationCapability, selection: SelectionCapability, styles?: MarkupStylesConfig): boolean;
+
+declare interface BookmarkMarkerUiConfig {
+    /** 自定义图标；提供时仅渲染图标，无默认蓝色圆角背景 */
+    renderIcon?: (ctx: {
+        bookmark: ParagraphBookmark;
+    }) => unknown;
+    iconSize?: number;
+}
+
+declare interface BookmarkMarkerUiConfig_2 {
+    /** 自定义图标；提供时仅渲染图标，无默认蓝色背景按钮 */
+    renderIcon?: (ctx: {
+        bookmark: ParagraphBookmark;
+    }) => ReactNode;
+    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 const CHAPTER_ANNOTATIONS_ARCHIVE_VERSION: 1;
+
+export declare const CHAPTER_SNIPPET_EVENTS: {
+    readonly noteRequestCreate: "chapter-note-request-create";
+    readonly noteRequestEdit: "chapter-note-request-edit";
+    readonly selectionExtraAction: "chapter-selection-extra-action";
+    readonly ready: "chapter-viewer-ready";
+};
+
+/** 全书按 chapterId 分组的归档 */
+export declare interface ChapterAnnotationsArchive {
+    version: typeof CHAPTER_ANNOTATIONS_ARCHIVE_VERSION;
+    exportedAt: string;
+    chapters: Record<string, Omit<ChapterAnnotationsSnapshot, 'chapterId'>>;
+}
+
+export declare function chapterAnnotationsArchiveToJson(archive: ChapterAnnotationsArchive): string;
+
+declare type ChapterAnnotationsContentFlags = {
+    /** 默认 true */
+    bookmarks?: boolean;
+    /** 默认 true */
+    notes?: boolean;
+    /** 默认 true；对应 @embedpdf/plugin-annotation 的 export/import */
+    markup?: boolean;
+};
+
+/** 单章用户标注快照 */
+export declare interface ChapterAnnotationsSnapshot {
+    chapterId: string;
+    bookmarks?: ParagraphBookmark[];
+    notes?: NoteAnchor[];
+    markup?: SerializableAnnotationTransferItem[];
+}
+
+export declare function chapterAnnotationsSnapshotToJson(snapshot: ChapterAnnotationsSnapshot): string;
+
+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[];
+}
+
+declare const ChapterEmbedPDF: {
+    version: string;
+    init: (config: ContainerInitConfig) => EmbedPdfChapterContainer | undefined;
+};
+export default ChapterEmbedPDF;
+
+/**
+ * 章节级加载状态。区别于 `@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;
+}
+
+/** 笔记创建请求（与 plugin-note 回调 payload 对齐） */
+export declare type ChapterNoteRequestCreateDetail = {
+    draft: NoteDraft;
+    complete: (noteId: string) => void | Promise<void>;
+};
+
+/** 笔记编辑请求 */
+export declare type ChapterNoteRequestEditDetail = {
+    noteId: string;
+    anchor: NoteAnchor;
+};
+
+/**
+ * Backend-supplied chapter contract.
+ *
+ * 一个 PDF 整体被后端按章节切成若干独立 PDF 文件；前端将它们组装成一条
+ * 连续滚动流。相邻章节在 `globalPageRange` 上**允许重叠**（业务上下章
+ * 经常各含一个过渡页），由 OverlapResolver 决定每个全局页归属的「owner
+ * chapter」，渲染与标注都落在 owner 上以保持唯一性。
+ */
+/** 章节 PDF 解析结果 */
+export declare type ChapterPdfPayload = {
+    url: string;
+} | {
+    buffer: ArrayBuffer;
+};
+
+/** 划词工具栏扩展操作事件 */
+export declare type ChapterSelectionActionDetail = {
+    actionId: string;
+};
+
+/**
+ * 章节 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;
+    };
+}
+
+export { ChapterTreeNode }
+
+export { ChapterViewerCatalog }
+
+/**
+ * 用户侧功能配置（简化写法）：
+ * - 省略或 `true`：开启并使用默认样式
+ * - `false`：关闭
+ * - 对象：开启并覆盖对应字段
+ */
+export declare type ChapterViewerConfig = {
+    markup?: boolean | {
+        styles?: MarkupStylesConfig;
+    };
+    bookmarks?: boolean | {
+        marker?: BookmarkMarkerUiConfig;
+        hover?: HoverBookmarkUiConfig;
+    };
+    notes?: boolean | {
+        marker?: NoteMarkerUiConfig;
+    };
+    zoom?: boolean | ChapterViewerZoomConfig;
+    /** 默认随划线/笔记开启；仅在有扩展按钮或需隐藏内置按钮时配置 */
+    selectionToolbar?: boolean | SelectionToolbarConfig;
+};
+
+export declare type ChapterViewerContainerConfig = ChapterViewerSnippetConfig;
+
+/** 渲染器内部使用的规范化功能配置 */
+export declare interface ChapterViewerFeaturesConfig {
+    /** 划线/高亮 */
+    markup?: {
+        enabled?: boolean;
+        styles?: MarkupStylesConfig;
+    };
+    /** 段落书签（含悬停添加） */
+    bookmarks?: {
+        enabled?: boolean;
+        marker?: BookmarkMarkerUiConfig;
+        hover?: HoverBookmarkUiConfig;
+    };
+    /** 笔记 */
+    notes?: {
+        enabled?: boolean;
+        marker?: NoteMarkerUiConfig;
+    };
+    /** 选区浮窗 */
+    selectionToolbar?: SelectionToolbarConfig;
+    /** 缩放 */
+    zoom?: ChapterViewerZoomConfig;
+}
+
+/** 章节阅读器统一配置（推荐入口） */
+export declare interface ChapterViewerOptions {
+    manifest: ChapterManifest;
+    /** 笔记持久化与弹窗回调 */
+    notes: NoteCallbacks;
+    /** 书签持久化与删除回调 */
+    bookmarks: ParagraphBookmarkCallbacks;
+    chapterPdfLoader?: IChapterPdfLoader;
+    /** 功能开关与样式；省略则全开 */
+    features?: ChapterViewerConfig;
+}
+
+export declare type ChapterViewerSnippetConfig = {
+    /** PDFium wasm 地址，默认 jsdelivr */
+    wasmUrl?: string;
+    /** 是否使用 worker 引擎，默认 true */
+    worker?: boolean;
+    /** worker 首章加载超时后是否自动降级到 direct engine，默认 true */
+    fallbackToDirectEngine?: boolean;
+    /** 首章加载超时时间；用于 worker fallback，默认 8000ms */
+    workerOpenTimeoutMs?: number;
+    /** 章节编辑器选项（manifest + 书签/笔记回调） */
+    editorInput: CreateChapterViewerEditorOptionsInput;
+    /** 阅读器功能开关，默认与 DEFAULT_CHAPTER_VIEWER_FEATURES 合并 */
+    features?: ChapterViewerFeaturesConfig;
+    className?: string;
+    viewportClassName?: string;
+};
+
+declare interface ChapterViewerZoomConfig {
+    /** 是否启用 Ctrl+滚轮 / 双指捏合等交互缩放，默认 true；为 false 时仍可用 pageWidth / initial 设置版面宽度 */
+    enabled?: boolean;
+    min?: number;
+    max?: number;
+    /** 文档 scale 初始值；未设置且配置了 pageWidth 时由 pageWidth 按首页宽度推导 */
+    initial?: number;
+    /**
+     * 页面布局目标宽度（CSS px）。
+     * 章节 PDF 加载后按 `pageWidth / pdfPageWidth` 设置 document scale，与 RenderLayer / 滚动占位一致。
+     */
+    pageWidth?: number;
+}
+
+export declare type ContainerInitConfig = ChapterViewerContainerConfig & {
+    type: 'container';
+    target: Element;
+};
+
+/** 生成插件列表 + 规范化后的 features（供 EmbedPDF / PdfChapterViewport 使用） */
+export declare function createChapterViewerBundle(input: ChapterViewerOptions | CreateChapterViewerEditorOptionsInput): {
+    plugins: PluginBatchRegistration<any, any, any, any>[];
+    features: ChapterViewerFeaturesConfig;
+    editorOptions: CreatePdfChapterEditorOptions;
+};
+
+/** 进阶用法：仅生成 editor 配置（不含 features，需自行传给 PdfChapterViewport） */
+export declare function createChapterViewerEditorOptions(input: ChapterViewerOptions | CreateChapterViewerEditorOptionsInput): Omit<CreatePdfChapterEditorOptions, 'features'>;
+
+/** @deprecated 旧版嵌套 `callbacks` 写法，仍兼容 */
+export declare type CreateChapterViewerEditorOptionsInput = {
+    manifest: ChapterManifest;
+    chapterPdfLoader?: IChapterPdfLoader;
+    bookmarks: {
+        callbacks: ParagraphBookmarkCallbacks;
+    };
+    notes: {
+        callbacks: NoteCallbacks;
+    };
+};
+
+declare interface CreateEditorUiSchemaOptions {
+    /** 默认全开 */
+    enabledModes?: EditorModeId[];
+    customOperations?: OperationSpec[];
+    /** 合并进最终 schema 的额外 toolbars / menus 等 */
+    extend?: Partial<Pick<UISchema, 'toolbars' | 'menus' | 'sidebars' | 'modals' | 'selectionMenus'>>;
+}
+
+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;
+}
+
+/** 用户侧默认：省略 `options.features` 即等价于此空对象（全部功能开启） */
+export declare const DEFAULT_CHAPTER_VIEWER_CONFIG: ChapterViewerConfig;
+
+/** 默认全开的功能配置（内部规范化结果） */
+export declare const DEFAULT_CHAPTER_VIEWER_FEATURES: ChapterViewerFeaturesConfig;
+
+export declare function downloadChapterAnnotationsArchive(archive: ChapterAnnotationsArchive, filename?: string): void;
+
+export declare function downloadChapterAnnotationsSnapshot(snapshot: ChapterAnnotationsSnapshot, filename?: string): void;
+
+/** 触发浏览器下载 JSON 文件（仅浏览器环境） */
+export declare function downloadJsonFile(filename: string, json: string): void;
+
+/** 与 snippet 主工具栏 mode tabs 对齐的编辑模式 */
+declare type EditorModeId = 'view' | 'annotate' | 'shapes' | 'insert' | 'form' | 'redact';
+
+export declare class EmbedPdfChapterContainer extends EmbedPdfChapterContainer_base {
+    private root;
+    private mountEl;
+    private _config?;
+    private _registryPromise;
+    private _resolveRegistry;
+    constructor();
+    connectedCallback(): void;
+    private ensureMountEl;
+    /**
+     * Preact render() 会清空挂载点；样式作为 shadow 内兄弟节点，在每次 render 后注入。
+     */
+    private ensureBaseStyles;
+    disconnectedCallback(): void;
+    set config(newConfig: ChapterViewerContainerConfig);
+    get config(): ChapterViewerContainerConfig | undefined;
+    get registry(): Promise<PluginRegistry>;
+    private handleRegistryReady;
+    private renderViewer;
+}
+
+declare const EmbedPdfChapterContainer_base: typeof HTMLElement;
+
+/**
+ * 导出 manifest 中全部章节（按 chapterId 存 JSON 对象）。
+ */
+export declare function exportAllChapterAnnotations(registry: PluginRegistry, manifest: ChapterManifest, options?: ExportChapterAnnotationsOptions): Promise<ChapterAnnotationsArchive>;
+
+/**
+ * 导出单章用户标注（书签、笔记、划词划线）。
+ * `chapterId` 与章节 documentId 一致。
+ */
+export declare function exportChapterAnnotations(registry: PluginRegistry, chapterId: string, options?: ExportChapterAnnotationsOptions): Promise<ChapterAnnotationsSnapshot>;
+
+export declare type ExportChapterAnnotationsOptions = ChapterAnnotationsContentFlags & {
+    /** 导出前确保章节 PDF 已加载（划线需要），默认 true */
+    ensureChapterLoaded?: boolean;
+};
+
+declare interface HoverBookmarkUiConfig {
+    /** 悬停行末「添加书签」自定义图标；无背景 */
+    renderAddIcon?: () => unknown;
+    iconSize?: number;
+}
+
+declare interface HoverBookmarkUiConfig_2 {
+    renderAddIcon?: () => ReactNode;
+    iconSize?: number;
+}
+
+/**
+ * 全局章节 PDF 加载器：当 `ChapterDescriptor.source` 未提供 url/buffer/load 时使用。
+ * 适合统一走业务 API、鉴权下载等场景。
+ */
+export declare interface IChapterPdfLoader {
+    loadPdf(chapter: ChapterDescriptor): Promise<ChapterPdfPayload>;
+}
+
+/**
+ * 导入单章快照。
+ */
+export declare function importChapterAnnotations(registry: PluginRegistry, snapshot: ChapterAnnotationsSnapshot, options?: ImportChapterAnnotationsOptions): Promise<void>;
+
+/**
+ * 导入全书归档（仅处理 archive.chapters 中存在的 chapterId）。
+ */
+export declare function importChapterAnnotationsArchive(registry: PluginRegistry, archive: ChapterAnnotationsArchive, options?: ImportChapterAnnotationsOptions): Promise<void>;
+
+export declare type ImportChapterAnnotationsOptions = ChapterAnnotationsContentFlags & {
+    /**
+     * replace：先清空该章对应数据再写入；
+     * merge：划线/笔记/书签与现有合并（书签按 anchor 去重）。
+     */
+    mode?: 'replace' | 'merge';
+    /** 导入前确保章节已加载，默认 true */
+    ensureChapterLoaded?: boolean;
+    /** 导入完成后回调，便于写入 localStorage / 后端 */
+    persistNotes?: (allNotes: NoteAnchor[]) => void | Promise<void>;
+    persistBookmarks?: (allBookmarks: ParagraphBookmark[]) => void | Promise<void>;
+};
+
+/**
+ * 章节加密的抽象接口：当某章节首次或重试加载因密码失败时，
+ * `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 点） */
+declare interface MarkupKindStyle {
+    /** 描边/填充色，如 #facc15 */
+    color?: string;
+    /** 线宽（下划线/删除线等），PDF 点 */
+    thickness?: number;
+    /** 相对字形底边的垂直偏移，正值向下（PDF 点） */
+    offsetY?: number;
+    opacity?: number;
+}
+
+declare type MarkupStylesConfig = Partial<Record<SelectionMarkupKind, MarkupKindStyle>>;
+
+/** 将用户侧简化配置规范为渲染器内部使用的结构 */
+export declare function normalizeChapterViewerConfig(config?: ChapterViewerConfig): ChapterViewerFeaturesConfig;
+
+/**
+ * 一条附注（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;
+}
+
+declare interface NoteCallbacks {
+    /** 初次加载已有附注 */
+    loadNotes?: () => Promise<NoteAnchor[]>;
+    /**
+     * 内置创建：持久化后返回 noteId。
+     * 与 onRequestCreateNote 二选一（至少配置其一）。
+     */
+    onCreateNote?: (draft: NoteDraft) => Promise<{
+        noteId: string;
+    } | null>;
+    /**
+     * 自定义创建弹窗：仅发出事件，由宿主 complete(noteId)。
+     * 配置后划词/默认流程不再调用 onCreateNote。
+     */
+    onRequestCreateNote?: (payload: NoteCreateRequestPayload) => 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;
+}
+
+/** 自定义笔记创建：宿主打开 UI 后调用 complete(noteId) */
+declare interface NoteCreateRequestPayload {
+    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 */
+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_2;
+    hover?: HoverBookmarkUiConfig_2;
+}
+
+export declare function parseChapterAnnotationsArchiveJson(json: string): ChapterAnnotationsArchive;
+
+export declare function parseChapterAnnotationsSnapshotJson(json: string): ChapterAnnotationsSnapshot;
+
+export declare interface PdfChapterEditorBookmarksConfig {
+    callbacks: NonNullable<ParagraphBookmarkPluginConfig['callbacks']>;
+}
+
+export declare interface PdfChapterEditorNotesConfig {
+    callbacks: NoteCallbacks;
+}
+
+declare interface PdfChapterEditorToolbarConfig extends CreateEditorUiSchemaOptions {
+}
+
+/** 划线类型 */
+declare type SelectionMarkupKind = 'highlight' | 'underline' | 'squiggly' | 'strikeout';
+
+declare interface SelectionToolbarConfig {
+    /** 是否显示默认 card，默认 true */
+    enabled?: boolean;
+    /** 隐藏部分内置按钮 */
+    hiddenBuiltinActions?: BuiltinSelectionToolbarAction[];
+    /** 扩展操作（由宿主在 buildSelectionMenu 或 onExtraAction 中处理） */
+    extraActions?: SelectionToolbarExtraAction[];
+}
+
+/** 扩展选区操作 */
+declare interface SelectionToolbarExtraAction {
+    id: string;
+    label: string;
+    /** 排序权重，越小越靠前（在内置 markup 之后、note 之前） */
+    order?: number;
+}
+
+/** JSON 中可存储的划线（stamp 的 ArrayBuffer 转为 base64） */
+export declare interface SerializableAnnotationTransferItem {
+    annotation: AnnotationTransferItem['annotation'];
+    ctx?: {
+        dataBase64?: string;
+        mimeType?: string;
+    };
+}
+
+export declare const version = "0.1.0";
+
+/**
+ * 一个虚拟页位的解析结果。`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;
+}
+
+export { }