@embedpdf-editor/vue3-chapter-viewer 0.2.1 → 0.3.0

package/README.md

@@ -1,473 +1,299 @@
 # @embedpdf-editor/vue3-chapter-viewer
 
-面向 Vue 3 的**章节 PDF 阅读器**统一入口：多章 PDF 纵向拼接滚动、划词高亮/划线、段落书签、选区笔记，以及可选缩放。
+Vue 3 章节 PDF 阅读器：多章 PDF 拼成一条连续滚动流，支持划词划线、附注、段落书签、工具栏与标注 JSON 导入导出。
 
-业务侧只需安装本包与 `vue`；PDFium（`@embedpdf/engines`）、`scheduler` 及阅读器依赖的 `@embedpdf/*` 插件由本包 **dependencies** 带入，**不必**在业务 `package.json` 里逐个声明 `@embedpdf/engines` 等。
-
-> 组件样式以 **inline style** 为主，**不需要** Tailwind。  
-> 下文提供可直接复制到业务项目中的完整示例（不依赖仓库内 demo 工程）。
-
----
+底层引擎：`@embedpdf-editor/editor-engine`（Preact 渲染岛 + `@embedpdf/core` 插件体系）。
 
 ## 安装
 
 ```bash
-pnpm add @embedpdf-editor/vue3-chapter-viewer
-# 或 npm / yarn
+pnpm add @embedpdf-editor/vue3-chapter-viewer @embedpdf/engines
 ```
 
-| 依赖 | 说明 |
-|------|------|
-| `vue` | **peerDependencies**（建议 Vue 3.3+） |
-| 本包 `dependencies` | 已包含 `@embedpdf/engines`、`scheduler`、章节插件与 `editor-engine` |
-
-在业务入口注册本包组件前，请确保已 `import { createApp } from 'vue'` 并正常挂载应用（与常规 Vue 3 项目一致）。
-
----
-
-## Vite 项目（推荐）
-
-若 dev 时出现 `scheduler` 解析失败，可合并本包提供的 Vite 片段（将 `scheduler` 指到本包依赖目录并加入预构建）：
+## Vite 与 WASM
 
 ```ts
 // vite.config.ts
-import { defineConfig, mergeConfig } from 'vite';
+import { defineConfig } from 'vite';
 import vue from '@vitejs/plugin-vue';
-import { chapterViewerViteResolve } from '@embedpdf-editor/vue3-chapter-viewer/vite';
-
-export default mergeConfig(
-  defineConfig({
-    plugins: [vue()],
-  }),
-  chapterViewerViteResolve(),
-);
-```
+import { chapterViewerVitePlugin } from '@embedpdf-editor/vue3-chapter-viewer/vite';
 
----
-
-## 你需要准备的数据
+export default defineConfig({
+  plugins: [vue(), chapterViewerVitePlugin()],
+});
+```
 
-阅读器**不内置**目录与 PDF 文件，全部由业务提供。
+将 `pdfium.wasm` 放到 `public/`（或由 `chapterViewerVitePlugin` 自动复制）。`usePdfiumEngine({ wasmUrl: '/pdfium.wasm' })` 的地址须与静态资源路径一致。
 
-### 1. `ChapterManifest`（引擎用）
+## 快速上手
 
-描述每一章对应的 PDF 与在「整本」中的页码区间：
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  ChapterPdfViewer,
+  usePdfiumEngine,
+  createChapterViewerEditorOptions,
+  DEFAULT_CHAPTER_VIEWER_FEATURES,
+  CallbackPasswordProvider,
+} from '@embedpdf-editor/vue3-chapter-viewer';
+import type { ChapterManifest, NoteAnchor } from '@embedpdf-editor/vue3-chapter-viewer';
 
-```ts
-import type { ChapterManifest } from '@embedpdf-editor/vue3-chapter-viewer';
+const { engine, isLoading } = usePdfiumEngine({ wasmUrl: '/pdfium.wasm' });
 
 const manifest: ChapterManifest = {
   chapters: [
     {
-      chapterId: '001_封面',            // 唯一 ID，同时作为 documentId
-      title: '封面',
-      globalPageRange: [1, 1],        // 在整本中的全局页（闭区间）
-      localPageRange: [0, 0],         // 该 PDF 内 0-based 页（页数须与 global 一致）
-      source: { url: '/001_封面.pdf' }, // 或 buffer / load()
-    },
-    {
-      chapterId: '002_前言',
-      title: '前言',
-      globalPageRange: [2, 5],
-      localPageRange: [0, 3],
-      source: { url: '/002_前言.pdf' },
+      chapterId: 'ch-1',
+      title: '第一章',
+      globalPageRange: [1, 10],
+      localPageRange: [0, 9],
+      source: { url: '/pdfs/ch1.pdf' },
+      encrypted: true, // 可选：业务标记该章为加密 PDF
     },
   ],
 };
-```
-
-**`ChapterSource` 三种写法：**
-
-| 写法 | 场景 |
-|------|------|
-| `{ url: string }` | 静态或可直链的 PDF |
-| `{ buffer: ArrayBuffer }` | 已下载的二进制 |
-| `{ load: () => Promise<{ url } \| { buffer }> }` | 单章自定义拉取（鉴权等） |
-
-若 manifest 里**未写** `source`，需传入全局加载器 `chapterPdfLoader`（实现 `IChapterPdfLoader.loadPdf(chapter)`）。
-
-相邻章节的 `globalPageRange` **允许重叠**（例如上下章各含一页过渡页）；默认按 `first-wins` 解析归属。
-
-### 2. `ChapterViewerCatalog`（带目录树时）
-
-左侧章节目录由业务构造，与 manifest 对应：
-
-```ts
-import type { ChapterViewerCatalog } from '@embedpdf-editor/vue3-chapter-viewer';
 
-const catalog: ChapterViewerCatalog = {
-  tree: [
-    { id: '001_封面', title: '封面', startPage: 1, endPage: 1 },
-    {
-      id: '002_前言',
-      title: '前言',
-      startPage: 2,
-      endPage: 5,
-      children: [/* 可选子节点 */],
-    },
-  ],
+const viewerProps = createChapterViewerEditorOptions({
   manifest,
-};
-```
-
-`tree` 仅用于 UI；真正加载 PDF 以 `manifest.chapters` 为准。
-
----
-
-## 快速开始：`<ChapterPdfViewer />`
-
-适合「单容器铺满、manifest 已就绪」的页面。推荐只传 **`options`**（不必再拆 `editorOptions` + `features`，也不必包一层 `callbacks`）。
-
-`usePdfiumEngine()` 返回的是 **ref**，模板里会自动解包；在 `<script setup>` 中请使用 `engine.value`。
-
-```vue
-<script setup lang="ts">
-import { computed } from 'vue';
-import {
-  usePdfiumEngine,
-  ChapterPdfViewer,
-  type ChapterManifest,
-  type ChapterViewerOptions,
-} from '@embedpdf-editor/vue3-chapter-viewer';
-
-const props = defineProps<{ manifest: ChapterManifest }>();
-const { engine, isLoading, error } = usePdfiumEngine();
-
-const options = computed<ChapterViewerOptions>(() => ({
-  manifest: props.manifest,
-  bookmarks: {
-    load: () => fetchBookmarks(),
-    persist: (list) => saveBookmarks(list),
-    onRequestRemove: async (b) => {
-      await api.deleteBookmark(b.id);
-      return true;
-    },
-  },
   notes: {
-    loadNotes: () => fetchNotes(),
-    onRequestCreateNote: ({ draft, complete }) => {
-      openCreateModal(draft).then((noteId) => complete(noteId));
-    },
-    onRequestEditNote: (noteId) => openEditModal(noteId),
-    onDeleteNote: (id) => api.deleteNote(id),
+    loadNotes: async () => [] as NoteAnchor[],
+    onCreateNote: async (draft) => ({ noteId: crypto.randomUUID() }),
   },
-  features: {
-    zoom: { pageWidth: 800 },
+  bookmarks: {
+    load: async () => [],
+    persist: async () => {},
   },
-}));
-</script>
-
-<template>
-  <div v-if="error" style="padding: 16px">引擎失败：{{ error.message }}</div>
-  <div v-else-if="isLoading || !engine" style="padding: 16px">正在加载 PDFium…</div>
-  <ChapterPdfViewer
-    v-else
-    :engine="engine"
-    :options="options"
-    style="height: 100vh; width: 100%"
-  />
-</template>
-```
+  features: DEFAULT_CHAPTER_VIEWER_FEATURES,
+});
 
-### 笔记弹窗（推荐 `onRequestCreateNote`）
-
-阅读器不会自带 Modal，需在宿主里监听 `onRequestCreateNote` / `onRequestEditNote`，弹窗确认后调用 `complete(noteId)` 或 `onUpdateNote`：
-
-```vue
-<script setup lang="ts">
-import { ref, shallowRef } from 'vue';
-import type { NoteDraft } from '@embedpdf-editor/vue3-chapter-viewer';
-
-const pendingCreate = shallowRef<{
-  draft: NoteDraft;
-  complete: (noteId: string) => void | Promise<void>;
-} | null>(null);
-
-function onRequestCreateNote(payload: {
-  draft: NoteDraft;
-  complete: (noteId: string) => void | Promise<void>;
-}) {
-  pendingCreate.value = payload;
-}
-
-async function confirmCreate(content: string) {
-  const pending = pendingCreate.value;
-  if (!pending) return;
-  const noteId = await api.createNote({ ...pending.draft, content });
-  await pending.complete(noteId);
-  pendingCreate.value = null;
-}
+// 加密章：在 createPdfChapterEditor / 低层 options 中传入 passwordProvider（见下文）
 </script>
 
 <template>
-  <!-- YourNoteModal：业务自有组件 -->
-  <YourNoteModal
-    :open="!!pendingCreate"
-    :quoted-text="pendingCreate?.draft.selectedText"
-    @confirm="confirmCreate"
-    @cancel="pendingCreate = null"
-  />
+  <ChapterPdfViewer v-if="engine && !isLoading" :engine="engine" :viewer-props="viewerProps" />
 </template>
 ```
 
-将 `onRequestCreateNote` 传入上一节的 `options.notes` 即可。
+完整交互见 monorepo 示例：`examples/chapter-viewer-demo-vue3`。
 
-### `features` 简写
+## Manifest（章节清单）
 
-| 写法 | 含义 |
+| 字段 | 说明 |
 |------|------|
-| 省略 | 划线、书签、笔记、选区浮窗、缩放 **全部开启** |
-| `markup: false` | 关闭划词高亮/划线 |
-| `zoom: false` | 关闭缩放 |
-| `zoom: { pageWidth: 800 }` | 按宽度适配 |
-
-**交互说明（默认开启时）：**
+| `chapterId` | 业务唯一 ID，同时作为 `documentManager` 的 `documentId` |
+| `title` | 展示标题 |
+| `globalPageRange` | 该章在「整本」中的全局页闭区间；相邻章可重叠 |
+| `localPageRange` | 该章 PDF 内 0-based 页闭区间；页数须与 global 区间一致 |
+| `source` | `{ url }` / `{ buffer }` / `{ load: () => Promise<...> }`；可省略并在 `chapterPdfLoader` 统一加载 |
+| `encrypted` | **可选提示位**：标记该章可能需密码；真正触发密码流程的是 PDFium 打开时报 `Password` 错误 |
+| `ownedGlobalPages` | 仅 `overlapStrategy: 'explicit'` 时使用 |
 
-- 划词 → 浮窗：高亮、下划线、波浪线、删除线、笔记
-- 鼠标移到文本行末 → 显示「添加书签」；已加书签点击 → 删除确认（走 `onRequestRemove`）
-- 笔记区域悬停 → 编辑 / 删除
-- **缩放**：`features.zoom.enabled !== false` 时，在 PDF 滚动区域内 **`Ctrl/Cmd + 滚轮`** 或 **双指捏合**（触控板）缩放；缩放写入 core 的 `document.scale`，PDF 与书签/笔记 overlay 同步变化
+## 加密 PDF（密码 / 解密）
 
-> 普通滚轮用于上下滚动章节，不会触发缩放；Mac 触控板请按住 Ctrl 或双指捏合。
+章节 PDF 若带打开密码，引擎在 `documentManager` 打开失败且错误码为 **Password** 时，会向 `passwordProvider` 索取密码；用户放弃则该章进入 **`password-required`** 状态。
 
----
+### 配置方式
 
-## 进阶：自定义布局（目录 + 首章预加载）
+`createChapterViewerEditorOptions` 默认使用「始终返回 `null`」的 `CallbackPasswordProvider`（即不弹窗、直接失败）。业务须在 **`createPdfChapterEditor`** 或展开 `viewerProps` 底层 options 时传入自定义 provider：
 
-需要**左侧章节目录**、或要在挂载视口前**先 `ensureChapterLoaded`** 时，不要用一站式 `<ChapterPdfViewer />`，改用：
-
-`createChapterViewerBundle` → `EmbedPDF` → `ChapterTreePanel` + `PdfChapterViewport`
-
-**步骤简述：**
-
-1. 用 `createChapterViewerBundle(options)` 得到 `{ plugins, features }`（`options` 与上一节相同）。
-2. 用 `<EmbedPDF>` 挂载 `plugins`，在 scoped slot 里等 `pluginsReady === true` 再渲染子树。
-3. 在 `EmbedPDF` 子树内用 `useCapability(ChapterManagerPlugin.id)` 对首章调用 `ensureChapterLoaded`。
-4. 章节状态为 `loaded` 后再挂载 `<PdfChapterViewport :features="bundle.features" />`。
-
-**父页面（可复制）：**
-
-```vue
-<script setup lang="ts">
-import { computed } from 'vue';
+```ts
 import {
-  usePdfiumEngine,
-  EmbedPDF,
-  createChapterViewerBundle,
-  type ChapterViewerCatalog,
-  type ChapterViewerOptions,
+  createChapterViewerEditorOptions,
+  CallbackPasswordProvider,
 } from '@embedpdf-editor/vue3-chapter-viewer';
-import ChapterWorkspace from './ChapterWorkspace.vue';
-
-const props = defineProps<{
-  catalog: ChapterViewerCatalog;
-  notes: ChapterViewerOptions['notes'];
-  bookmarks: ChapterViewerOptions['bookmarks'];
-}>();
-
-const { engine, isLoading, error } = usePdfiumEngine();
-
-const bundle = computed(() =>
-  createChapterViewerBundle({
-    manifest: props.catalog.manifest,
-    notes: props.notes,
-    bookmarks: props.bookmarks,
-    features: { zoom: { pageWidth: 800 } },
-  }),
-);
-
-const firstChapterId = computed(
-  () => props.catalog.manifest.chapters[0]?.chapterId ?? '',
-);
-</script>
-
-<template>
-  <div v-if="error">引擎失败：{{ error.message }}</div>
-  <div v-else-if="isLoading || !engine">正在加载 PDFium…</div>
-  <div v-else style="height: 100vh; display: flex; flex-direction: column">
-    <EmbedPDF :engine="engine" :plugins="bundle.plugins">
-      <template #default="{ pluginsReady }">
-        <ChapterWorkspace
-          v-if="pluginsReady"
-          :tree="catalog.tree"
-          :first-chapter-id="firstChapterId"
-          :features="bundle.features"
-        />
-        <div v-else>正在初始化插件…</div>
-      </template>
-    </EmbedPDF>
-  </div>
-</template>
-```
+// StaticPasswordProvider / UiPromptPasswordProvider 从 @embedpdf-editor/chapter-core 引入
 
-**`ChapterWorkspace.vue`（须在 `EmbedPDF` 子树内）：**
+const passwordProvider = new CallbackPasswordProvider(async (chapter, attempt) => {
+  // attempt: 0 为首次，递增表示重试次数（可做「错三次锁定」）
+  const pwd = await myAskPasswordUi(chapter.title, attempt);
+  return pwd; // 返回 null 表示用户取消 → 章节 status: password-required
+});
 
-```vue
-<script setup lang="ts">
-import { ref, watch } from 'vue';
-import {
-  useCapability,
-  ChapterManagerPlugin,
-  ChapterTreePanel,
-  PdfChapterViewport,
-  type ChapterViewerFeaturesConfig,
-  type ChapterTreeNode,
-} from '@embedpdf-editor/vue3-chapter-viewer';
-
-const props = defineProps<{
-  tree: ChapterTreeNode[];
-  firstChapterId: string;
-  features: ChapterViewerFeaturesConfig;
-}>();
+const viewerProps = createChapterViewerEditorOptions({ manifest, notes, bookmarks });
+// viewerProps 内部会 merge 到 createPdfChapterEditor；若需覆盖 passwordProvider，
+// 请使用 createPdfChapterEditor({ ...opts, passwordProvider }) + 自行组装 EmbedPDF。
+```
 
-const activeChapterId = ref(props.firstChapterId);
-const chapterReady = ref(false);
+### 内置 Provider（`@embedpdf-editor/chapter-core`）
 
-const { provides: chapterManager } = useCapability<ChapterManagerPlugin>(
-  ChapterManagerPlugin.id,
-);
+| 类 | 用途 |
+|----|------|
+| `CallbackPasswordProvider` | 异步回调 `(chapter, attempt) => string \| null`，最常用 |
+| `StaticPasswordProvider` | 构造时传入 `Record<chapterId, password>`，适合 SSO 一次解锁多章 |
+| `UiPromptPasswordProvider` | `onPrompt(chapter, attempt)` 通知 UI，UI 调 `submit(chapterId, password \| null)` 完成 Promise |
+
+`getCachedPassword?(chapterId)` 可选：同步返回已缓存密码，避免重复弹窗。
+
+### 章节加载状态
+
+`ChapterLoadStatus` 包含：`idle` | `loading` | `loaded` | `error` | **`password-required`**。密码提交成功后 `ChapterManagerPlugin` 会带密码重试打开。
+
+## 标注导入 / 导出（JSON 格式）
+
+类型定义见 `editor-engine` → `chapter-annotations-io/types.ts`。当前归档版本常量：`CHAPTER_ANNOTATIONS_ARCHIVE_VERSION === 1`。
+
+### 全书归档 `ChapterAnnotationsArchive`
+
+```jsonc
+{
+  // 固定为 1；未来格式升级时解析器可据此分支
+  "version": 1,
+  // ISO 8601 导出时间（UTC 字符串）
+  "exportedAt": "2026-06-01T12:00:00.000Z",
+  // key = chapterId；value 不含重复的 chapterId 字段
+  "chapters": {
+    "ch-1": {
+      // ---------- 段落书签（plugin-paragraph-bookmark）----------
+      "bookmarks": [
+        {
+          "id": "bm-uuid",
+          "label": "用户可见标题",
+          "metadata": { "任意业务字段": true },
+          "anchor": {
+            "chapterId": "ch-1",
+            "localPageIndex": 0,
+            "globalPageIndex": 1,
+            "globalPageNumber": 1,
+            "rectPdfCoord": { "origin": { "x": 0, "y": 0 }, "size": { "width": 100, "height": 20 } },
+            "rectsPdfCoord": [],
+            "markerAnchor": { "x": 100, "y": 20 }
+          },
+          "createdAt": 1717243200000
+        }
+      ],
+      // ---------- 附注（plugin-note）----------
+      "notes": [
+        {
+          "noteId": "note-uuid",
+          "chapterId": "ch-1",
+          "globalPageIndex": 1,
+          "globalPageNumber": 1,
+          "localPageIndex": 0,
+          "rectsPdfCoord": [{ "origin": { "x": 0, "y": 0 }, "size": { "width": 200, "height": 16 } }],
+          "endAnchor": { "x": 200, "y": 16 },
+          "selectedText": "被选中的原文",
+          "content": "用户笔记正文"
+        }
+      ],
+      // ---------- 划线 / 高亮 / 图章等（@embedpdf/plugin-annotation）----------
+      "markup": [
+        {
+          // 与 AnnotationTransferItem.annotation 同结构（类型、页码、几何、颜色等）
+          "annotation": {
+            "id": "ann-uuid",
+            "type": "highlight",
+            "pageIndex": 0,
+            "rect": { "origin": { "x": 0, "y": 0 }, "size": { "width": 100, "height": 12 } }
+          },
+          // 图章等二进制附件：导出时 ArrayBuffer → base64
+          "ctx": {
+            "dataBase64": "iVBORw0KGgo...",
+            "mimeType": "image/png"
+          }
+        }
+      ]
+    }
+  }
+}
+```
 
-watch(
-  [chapterManager, () => props.firstChapterId],
-  ([mgr, chapterId], _prev, onCleanup) => {
-    if (!mgr || !chapterId) return;
+### 单章快照 `ChapterAnnotationsSnapshot`
 
-    let cancelled = false;
-    chapterReady.value = false;
+与归档中某一章对象相同，但**顶层多一个** `chapterId`：
 
-    const unsub = mgr.onChapterStatusChange(() => {
-      if (cancelled) return;
-      if (mgr.getChapterStatus(chapterId) === 'loaded') chapterReady.value = true;
-    });
+```jsonc
+{
+  "chapterId": "ch-1",
+  "bookmarks": [],
+  "notes": [],
+  "markup": []
+}
+```
 
-    void mgr.ensureChapterLoaded(chapterId).then((status) => {
-      if (!cancelled && status === 'loaded') chapterReady.value = true;
-    });
+`bookmarks` / `notes` / `markup` 均可省略；导出时可按 `ExportChapterAnnotationsOptions` 关闭某一类。
 
-    onCleanup(() => {
-      cancelled = true;
-      unsub();
-    });
-  },
-  { immediate: true },
-);
-</script>
+### 导入选项 `ImportChapterAnnotationsOptions`
 
-<template>
-  <div style="display: flex; flex: 1; min-height: 0; gap: 12px">
-    <ChapterTreePanel
-      :tree="tree"
-      :active-chapter-id="activeChapterId"
-      @active-chapter-change="activeChapterId = $event"
-    />
-    <div style="flex: 1; min-width: 0; min-height: 0; position: relative">
-      <div v-if="chapterReady" style="position: absolute; inset: 0">
-        <PdfChapterViewport :features="features" />
-      </div>
-      <div v-else style="padding: 16px">正在加载章节 PDF…</div>
-    </div>
-  </div>
-</template>
-```
+| 选项 | 默认 | 说明 |
+|------|------|------|
+| `mode` | `replace` | `replace`：先清空该章对应数据再写入；`merge`：与现有合并（书签按 anchor 去重） |
+| `ensureChapterLoaded` | `true` | 导入划线前确保该章 PDF 已打开 |
+| `bookmarks` / `notes` / `markup` | `true` | 控制是否处理对应字段 |
+| `persistNotes` | — | 导入完成后回调，参数为**全书**附注列表，便于写 localStorage / 后端 |
+| `persistBookmarks` | — | 同上，段落书签列表 |
 
-切换目录项时，可对新的 `activeChapterId` 同样调用 `ensureChapterLoaded`（`ChapterTreePanel` 内部也会触发章节加载，按产品需求组合使用即可）。
+### API（均需 `PluginRegistry`，Vue 3 用 `useRegistry()`）
 
----
+```ts
+import { useRegistry } from '@embedpdf-editor/vue3-chapter-viewer';
+import {
+  exportChapterAnnotations,
+  exportAllChapterAnnotations,
+  importChapterAnnotations,
+  importChapterAnnotationsArchive,
+  chapterAnnotationsArchiveToJson,
+  parseChapterAnnotationsArchiveJson,
+  chapterAnnotationsSnapshotToJson,
+  parseChapterAnnotationsSnapshotJson,
+  downloadChapterAnnotationsArchive,
+  downloadChapterAnnotationsSnapshot,
+} from '@embedpdf-editor/vue3-chapter-viewer';
 
-## 笔记与书签回调
+const { registry } = useRegistry();
 
-直接写在 `options.notes` / `options.bookmarks`（不再嵌套 `callbacks`）。
+const archive = await exportAllChapterAnnotations(registry.value!);
+const json = chapterAnnotationsArchiveToJson(archive);
 
-### 笔记 `options.notes`
+await importChapterAnnotationsArchive(registry.value!, parseChapterAnnotationsArchiveJson(json), {
+  mode: 'replace',
+  persistNotes: (all) => myStore.saveNotes(all),
+  persistBookmarks: (all) => myStore.saveBookmarks(all),
+});
+```
 
-| 回调 | 说明 |
+| 函数 | 说明 |
 |------|------|
-| `loadNotes` | 初始化加载已有笔记 |
-| `onRequestCreateNote` | **推荐**：宿主弹窗后 `complete(noteId)` |
-| `onCreateNote` | 内置创建（与上一项二选一） |
-| `onRequestEditNote` / `onUpdateNote` / `onDeleteNote` | 编辑、更新、删除 |
-
-### 书签 `options.bookmarks`
+| `exportChapterAnnotations(registry, chapterId, options?)` | 导出单章快照 |
+| `exportAllChapterAnnotations(registry, options?)` | 导出全书归档 |
+| `importChapterAnnotations(registry, snapshot, options?)` | 导入单章 |
+| `importChapterAnnotationsArchive(registry, archive, options?)` | 导入全书 |
+| `chapterAnnotationsArchiveToJson` / `parseChapterAnnotationsArchiveJson` | 序列化 / 反序列化 |
+| `chapterAnnotationsSnapshotToJson` / `parseChapterAnnotationsSnapshotJson` | 单章版 |
+| `downloadChapterAnnotationsArchive` / `downloadChapterAnnotationsSnapshot` | 触发浏览器下载 `.json` |
 
-| 回调 | 说明 |
-|------|------|
-| `load` | 加载已有书签 |
-| `persist` | 增删改后持久化 |
-| `onRequestRemove` | 删除确认，返回 `true` 后从渲染层移除 |
+Demo 参考：`examples/chapter-viewer-demo-vue3/src/components/AnnotationsDemoBar.vue`。
 
----
+## 功能开关 `features`
 
-## 内部默认（无需配置）
+通过 `createChapterViewerEditorOptions({ features })` 或 `DEFAULT_CHAPTER_VIEWER_FEATURES` 控制划线样式、笔记、书签、选区卡片、缩放等。详见 `@embedpdf-editor/chapter-viewer` 的 `ChapterViewerFeaturesConfig`。
 
-以下由引擎内置，业务**不用**再写：`overlapStrategy`、`passwordProvider`、`prefetchChapters`、`loadDefaultStampLibrary`、`toolbar`（Annotate 模式栏已关闭）等。需要改时再使用进阶 API `createPdfChapterEditor`。
+## 笔记与书签
 
----
+- **附注**：`notes.loadNotes`、`onCreateNote` 或 `onRequestCreateNote`（自定义弹窗）、`onUpdateNote`、`onDeleteNote` 等，类型 `NoteCallbacks`。
+- **书签**：`bookmarks.load`、`persist`、`onRequestRemove`，类型 `ParagraphBookmarkCallbacks`。
 
 ## 主要导出
 
-| 导出 | 用途 |
+| 导出 | 说明 |
 |------|------|
-| `ChapterPdfViewer` | 一站式阅读器（传 `engine` + `options`） |
-| `createChapterViewerBundle` | 生成 `{ plugins, features }`（自定义布局） |
-| `PdfChapterViewport` | 仅视口（需在 `EmbedPDF` 内） |
-| `ChapterTreePanel` | 章节目录树 |
-| `EmbedPDF` / `useCapability` | 插件宿主与能力钩子 |
-| `usePdfiumEngine` | PDFium 引擎（返回 ref） |
-| `ChapterManagerPlugin` | 章节加载（`ensureChapterLoaded`） |
-| `ChapterViewerOptions` | `options` 的类型 |
-| `ChapterViewerConfig` | `options.features` 的类型 |
-| `ChapterManifest` / `ChapterDescriptor` / `IChapterPdfLoader` | 数据与加载契约 |
-| `ChapterViewerCatalog` / `ChapterTreeNode` | 目录树类型 |
-| `applySelectionMarkup` | 编程式应用划线（高级） |
-| `chapterViewerViteResolve` | Vite 配置辅助（`/vite` 子路径） |
+| `ChapterPdfViewer` | 开箱即用阅读器壳 |
+| `PdfChapterViewport` / `ChapterTreePanel` | 自定义布局 |
+| `usePdfiumEngine` | 加载 PDFium WASM |
+| `useRegistry` / `EmbedPDF` / `useCapability` | 插件注册表与能力 |
+| `createChapterViewerEditorOptions` | 推荐配置入口 |
+| `CallbackPasswordProvider` | 密码回调（更多 Provider 见 `@embedpdf-editor/chapter-core`） |
+| 标注 IO 函数与类型 | 见上表 |
 
-类型详见 `dist/index.d.ts`。
+## 与其它包
 
----
-
-## 接入检查清单
-
-在业务项目中接入时，请确认：
-
-1. **静态资源**：`manifest` 里每章 `source.url` 可被浏览器访问（或实现 `chapterPdfLoader` / `load()`）。
-2. **目录数据**：若使用 `ChapterTreePanel`，自行从后端组装 `ChapterViewerCatalog`（`tree` + `manifest` 字段一致）。
-3. **首章加载**：自定义布局下，首章 `ensureChapterLoaded` 返回 `loaded` 后再挂载 `PdfChapterViewport`。
-4. **笔记 UI**：`onRequestCreateNote` 需在宿主弹窗后调用 `complete(noteId)`。
-5. **Vue ref**：`usePdfiumEngine()` 的 `engine` 在 script 中为 ref，传给 `ChapterPdfViewer` 时模板写 `:engine="engine"` 即可。
-
-本包随 npm 发布，**不包含**可运行的示例站点或 mock 数据；请以上文代码片段为模板，在业务仓库中创建页面并放置自有 PDF。
-
----
-
-## 其他框架
-
-| 包 | 说明 |
+| 包 | 场景 |
 |----|------|
-| `@embedpdf-editor/react-chapter-viewer` | React 18+ |
-| `@embedpdf-editor/chapter-snippet` | Vue 2.6+ Web Component / 无构建集成 |
-
-能力与 React 版视口内核对齐；API 命名一致，仅组合方式随框架变化。
-
----
-
-## 常见问题
-
-**Q：页面一直「正在加载」？**  
-确认 `manifest` 中每章 `source.url` 可访问，或 `chapterPdfLoader` / `ensureChapterLoaded` 返回 `loaded`。首章未加载完成时不要提前挂载 `PdfChapterViewport`。
-
-**Q：需要用户安装 `@embedpdf/engines` 吗？**  
-不需要，已作为本包依赖。只需 `vue`。
-
-**Q：如何关闭缩放？**  
-`features: { zoom: false }`，或 `zoom: { enabled: false }`。
-
-**Q：`zoom.enabled: true` 但缩放手势没反应？**  
-1. 确认使用 `<ChapterPdfViewer />` 或 `<PdfChapterViewport :features="..." />`（缩放逻辑在视口内）。  
-2. 在 PDF 区域使用 **Ctrl/Cmd + 滚轮**，不要用普通滚轮。  
-3. 升级 `@embedpdf-editor/vue3-chapter-viewer` 后硬刷新浏览器。
+| `@embedpdf-editor/react-chapter-viewer` | React 18，API 与本包对称 |
+| `@embedpdf-editor/vue2-chapter-viewer` | Vue 2.6，内部为 `chapter-snippet` Web Component |
 
-**Q：笔记弹窗想完全自定义？**  
-使用 `onRequestCreateNote` + `complete(noteId)`，不要实现 `onCreateNote`。
+## 故障排查
 
-**Q：`useCapability` 报错 “must be used inside EmbedPDF”？**  
-`ChapterWorkspace` 等子组件必须渲染在 `<EmbedPDF>` 的默认 slot 内，不能与它平级。
+- **一直 Loading**：确认 `manifest` 已 `setManifest`、章节 `source` / `chapterPdfLoader` 可访问、WASM 与 COOP/COEP 已配置。
+- **加密章无法打开**：检查 `passwordProvider` 是否返回非空密码；取消时为 `password-required`。
+- **导出 markup 为空**：该章须已 `loaded`，且 `ensureChapterLoaded` 为 true（默认）。