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

package/README.md

@@ -1,33 +1,18 @@
 # @embedpdf-editor/vue3-chapter-viewer
 
-面向 Vue 3 的**章节 PDF 阅读器**统一入口：多章 PDF 纵向拼接滚动、划词高亮/划线、段落书签、选区笔记，以及可选缩放。
+Vue 3 版章节 PDF 阅读器。它把多份章节 PDF 组织成一本连续滚动的书，并内置划线/高亮、附注、段落书签、章节目录和标注导入导出能力。
 
-业务侧只需安装本包与 `vue`；PDFium（`@embedpdf/engines`）、`scheduler` 及阅读器依赖的 `@embedpdf/*` 插件由本包 **dependencies** 带入，**不必**在业务 `package.json` 里逐个声明 `@embedpdf/engines` 等。
-
-> 组件样式以 **inline style** 为主，**不需要** Tailwind。  
-> 下文提供可直接复制到业务项目中的完整示例（不依赖仓库内 demo 工程）。
-
----
+底层使用 `@embedpdf/core` 插件体系和 PDFium 引擎；Vue 3 包只负责提供 SFC 组件、composition hooks 和类型导出。
 
 ## 安装
 
 ```bash
 pnpm add @embedpdf-editor/vue3-chapter-viewer
-# 或 npm / yarn
 ```
 
-| 依赖 | 说明 |
-|------|------|
-| `vue` | **peerDependencies**（建议 Vue 3.3+） |
-| 本包 `dependencies` | 已包含 `@embedpdf/engines`、`scheduler`、章节插件与 `editor-engine` |
-
-在业务入口注册本包组件前，请确保已 `import { createApp } from 'vue'` 并正常挂载应用（与常规 Vue 3 项目一致）。
-
----
-
-## Vite 项目（推荐）
+## Vite
 
-若 dev 时出现 `scheduler` 解析失败，可合并本包提供的 Vite 片段（将 `scheduler` 指到本包依赖目录并加入预构建）：
+包内导出的是一段 Vite 配置，不是 Vite plugin。它用于补齐 `scheduler` alias 和 PDFium 引擎的预构建配置；`@embedpdf/engines` 已经是本包依赖，业务项目不需要单独安装。
 
 ```ts
 // vite.config.ts
@@ -43,431 +28,269 @@ export default mergeConfig(
 );
 ```
 
----
-
-## 你需要准备的数据
-
-阅读器**不内置**目录与 PDF 文件，全部由业务提供。
-
-### 1. `ChapterManifest`（引擎用）
-
-描述每一章对应的 PDF 与在「整本」中的页码区间：
-
-```ts
-import type { ChapterManifest } from '@embedpdf-editor/vue3-chapter-viewer';
-
-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' },
-    },
-  ],
-};
-```
-
-**`ChapterSource` 三种写法：**
-
-| 写法 | 场景 |
-|------|------|
-| `{ url: string }` | 静态或可直链的 PDF |
-| `{ buffer: ArrayBuffer }` | 已下载的二进制 |
-| `{ load: () => Promise<{ url } \| { buffer }> }` | 单章自定义拉取（鉴权等） |
+如果不用 `mergeConfig`，需要手动合并 `resolve.alias` 和 `optimizeDeps.include`，不要直接覆盖现有配置。
 
-若 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: [/* 可选子节点 */],
-    },
-  ],
-  manifest,
-};
-```
-
-`tree` 仅用于 UI；真正加载 PDF 以 `manifest.chapters` 为准。
-
----
-
-## 快速开始：`<ChapterPdfViewer />`
-
-适合「单容器铺满、manifest 已就绪」的页面。推荐只传 **`options`**（不必再拆 `editorOptions` + `features`，也不必包一层 `callbacks`）。
-
-`usePdfiumEngine()` 返回的是 **ref**，模板里会自动解包；在 `<script setup>` 中请使用 `engine.value`。
+推荐只传 `options`。`editorOptions` 和 `features` 仍兼容，但已作为低层/旧写法保留。
 
 ```vue
 <script setup lang="ts">
-import { computed } from 'vue';
 import {
-  usePdfiumEngine,
   ChapterPdfViewer,
-  type ChapterManifest,
+  usePdfiumEngine,
   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;
-    },
+const options: ChapterViewerOptions = {
+  manifest: {
+    chapters: [
+      {
+        chapterId: 'ch-1',
+        title: '第一章',
+        globalPageRange: [1, 12],
+        localPageRange: [0, 11],
+        source: { url: '/pdfs/chapter-1.pdf' },
+      },
+    ],
   },
   notes: {
-    loadNotes: () => fetchNotes(),
-    onRequestCreateNote: ({ draft, complete }) => {
-      openCreateModal(draft).then((noteId) => complete(noteId));
-    },
-    onRequestEditNote: (noteId) => openEditModal(noteId),
-    onDeleteNote: (id) => api.deleteNote(id),
+    loadNotes: async () => [],
+    onCreateNote: async () => ({ noteId: crypto.randomUUID() }),
+    onUpdateNote: async () => {},
+    onDeleteNote: async () => {},
+  },
+  bookmarks: {
+    load: async () => [],
+    persist: async () => {},
+    onRequestRemove: async () => true,
   },
   features: {
-    zoom: { pageWidth: 800 },
+    markup: true,
+    bookmarks: true,
+    notes: true,
+    selectionToolbar: true,
+    zoom: { pageWidth: 720 },
   },
-}));
+};
 </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%"
-  />
+  <div class="reader">
+    <div v-if="error">PDF engine failed: {{ error.message }}</div>
+    <div v-else-if="isLoading || !engine">Loading PDF engine...</div>
+    <ChapterPdfViewer
+      v-else
+      :engine="engine"
+      :options="options"
+      class-name="reader-fill"
+      viewport-class-name="reader-viewport"
+    />
+  </div>
 </template>
-```
 
-### 笔记弹窗（推荐 `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;
+<style scoped>
+.reader {
+  height: 100vh;
+  min-height: 0;
 }
 
-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;
+.reader-fill {
+  height: 100%;
+  min-height: 0;
 }
-</script>
-
-<template>
-  <!-- YourNoteModal：业务自有组件 -->
-  <YourNoteModal
-    :open="!!pendingCreate"
-    :quoted-text="pendingCreate?.draft.selectedText"
-    @confirm="confirmCreate"
-    @cancel="pendingCreate = null"
-  />
-</template>
+</style>
 ```
 
-将 `onRequestCreateNote` 传入上一节的 `options.notes` 即可。
+## `ChapterViewerOptions`
 
-### `features` 简写
+`options` 是三端渲染器的统一配置入口。
 
-| 写法 | 含义 |
-|------|------|
-| 省略 | 划线、书签、笔记、选区浮窗、缩放 **全部开启** |
-| `markup: false` | 关闭划词高亮/划线 |
-| `zoom: false` | 关闭缩放 |
-| `zoom: { pageWidth: 800 }` | 按宽度适配 |
+| 字段 | 说明 |
+| --- | --- |
+| `manifest` | 章节清单，描述每章 PDF 和全局页码关系 |
+| `notes` | 附注加载、创建、更新、删除回调 |
+| `bookmarks` | 段落书签加载、持久化、删除确认回调 |
+| `chapterPdfLoader` | 可选：全局 PDF 预处理/拉取（见下文） |
+| `overlapStrategy` | 可选：同一全局页多章节重叠时，用先/后出现的章节 PDF 渲染 |
+| `features` | 可选：功能开关与样式配置，省略时使用默认能力 |
 
-**交互说明（默认开启时）：**
+### Manifest
 
-- 划词 → 浮窗：高亮、下划线、波浪线、删除线、笔记
-- 鼠标移到文本行末 → 显示「添加书签」；已加书签点击 → 删除确认（走 `onRequestRemove`）
-- 笔记区域悬停 → 编辑 / 删除
-- **缩放**：`features.zoom.enabled !== false` 时，在 PDF 滚动区域内 **`Ctrl/Cmd + 滚轮`** 或 **双指捏合**（触控板）缩放；缩放写入 core 的 `document.scale`，PDF 与书签/笔记 overlay 同步变化
-
-> 普通滚轮用于上下滚动章节，不会触发缩放；Mac 触控板请按住 Ctrl 或双指捏合。
-
----
-
-## 进阶：自定义布局（目录 + 首章预加载）
-
-需要**左侧章节目录**、或要在挂载视口前**先 `ensureChapterLoaded`** 时，不要用一站式 `<ChapterPdfViewer />`，改用：
-
-`createChapterViewerBundle` → `EmbedPDF` → `ChapterTreePanel` + `PdfChapterViewport`
+```ts
+type ChapterManifest = {
+  chapters: Array<{
+    chapterId: string;
+    title: string;
+    globalPageRange: [number, number];
+    localPageRange: [number, number];
+    source?: { url: string } | { buffer: ArrayBuffer } | { load: () => Promise<{ url: string } | { buffer: ArrayBuffer }> };
+    encrypted?: boolean;
+    ownedGlobalPages?: number[];
+  }>;
+  totalGlobalPages?: number;
+};
+```
 
-**步骤简述：**
+`globalPageRange` 和 `localPageRange` 都是闭区间，且页数必须一致。`chapterId` 同时作为内部 `documentId`，需要在整本书内唯一。
 
-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" />`。
+### 嵌套目录树与重叠页
 
-**父页面（可复制）：**
+侧栏目录支持**任意层级**（`ChapterTreePanel` + `ChapterTreeNode.children`）。引擎滚动用的 `manifest.chapters` 是**扁平列表**：父节点页范围可包含子节点，相邻/重叠全局页由 **owner 策略** 决定只渲染一个章节的 PDF，避免同页画两遍。
 
-```vue
-<script setup lang="ts">
-import { computed } from 'vue';
+```ts
 import {
-  usePdfiumEngine,
-  EmbedPDF,
-  createChapterViewerBundle,
-  type ChapterViewerCatalog,
+  buildChapterViewerCatalog,
+  overlapStrategyForSamePageOwner,
   type ChapterViewerOptions,
 } 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>
+// 从业务树生成 tree + manifest（深度优先 flatten，顺序影响重叠页归属）
+const { tree, manifest } = buildChapterViewerCatalog([
+  { chapterId: 'part-1', title: '第一篇', startPage: 1, endPage: 50, source: { url: '/p1.pdf' } },
+  {
+    chapterId: 'sec-1',
+    title: '1.1 节',
+    startPage: 5,
+    endPage: 20,
+    source: { url: '/s1.pdf' },
+    children: [/* ... */],
+  },
+]);
 
-<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>
+const options: ChapterViewerOptions = {
+  manifest,
+  overlapStrategy: overlapStrategyForSamePageOwner('last'), // 重叠页用 manifest 中「后出现」的章节
+  // overlapStrategy: { kind: 'first-wins' }, // 默认：先出现的章节
+  notes: { /* ... */ },
+  bookmarks: { /* ... */ },
+};
 ```
 
-**`ChapterWorkspace.vue`（须在 `EmbedPDF` 子树内）：**
-
-```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;
-}>();
+| `overlapStrategy` | 同一全局页多个章节条目时 |
+| --- | --- |
+| `{ kind: 'first-wins' }`（默认） | 使用 **manifest 中先出现** 的章节的 PDF |
+| `{ kind: 'last-wins' }` | 使用 **后出现** 的章节（目录 flatten 后，重叠页常以「当前页最后一节」为准） |
+| `{ kind: 'explicit' }` | 各章在 `ownedGlobalPages` 上声明归属页 |
+| `{ kind: 'custom', resolve }` | 完全自定义 |
 
-const activeChapterId = ref(props.firstChapterId);
-const chapterReady = ref(false);
+简写：`overlapStrategyForSamePageOwner('first' | 'last')`。
 
-const { provides: chapterManager } = useCapability<ChapterManagerPlugin>(
-  ChapterManagerPlugin.id,
-);
+**注意**：仅作分组、没有独立 PDF 的父节点不要放进 flatten 后的 manifest；只保留需要加载 PDF 的节点。Demo：`examples/chapter-viewer-demo-vue3/src/demo/load-catalog.ts`。
 
-watch(
-  [chapterManager, () => props.firstChapterId],
-  ([mgr, chapterId], _prev, onCleanup) => {
-    if (!mgr || !chapterId) return;
+### PDF 加载与预处理
 
-    let cancelled = false;
-    chapterReady.value = false;
+打开章节前，引擎按以下优先级解析 PDF（`ChapterManagerPlugin.resolvePdfPayload`）：
 
-    const unsub = mgr.onChapterStatusChange(() => {
-      if (cancelled) return;
-      if (mgr.getChapterStatus(chapterId) === 'loaded') chapterReady.value = true;
-    });
+1. `chapter.source.url` / `source.buffer` — 直接使用  
+2. `chapter.source.load()` — **按章**异步预处理，返回 `{ url }` 或 `{ buffer }`  
+3. `chapterPdfLoader.loadPdf(chapter)` — **全局**统一逻辑  
 
-    void mgr.ensureChapterLoaded(chapterId).then((status) => {
-      if (!cancelled && status === 'loaded') chapterReady.value = true;
-    });
+**按章 `source.load`（单章解密、鉴权 URL）：**
 
-    onCleanup(() => {
-      cancelled = true;
-      unsub();
-    });
+```ts
+{
+  chapterId: 'ch-1',
+  title: '第一章',
+  globalPageRange: [1, 10],
+  localPageRange: [0, 9],
+  source: {
+    load: async () => {
+      const bytes = await fetchDecryptedPdf('ch-1');
+      return { buffer: bytes };
+      // 或 return { url: URL.createObjectURL(blob) };
+    },
   },
-  { immediate: true },
-);
-</script>
-
-<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>
+}
 ```
 
-切换目录项时，可对新的 `activeChapterId` 同样调用 `ensureChapterLoaded`（`ChapterTreePanel` 内部也会触发章节加载，按产品需求组合使用即可）。
-
----
-
-## 笔记与书签回调
+**全局 `chapterPdfLoader`（所有章走同一套 API）：**
 
-直接写在 `options.notes` / `options.bookmarks`（不再嵌套 `callbacks`）。
-
-### 笔记 `options.notes`
-
-| 回调 | 说明 |
-|------|------|
-| `loadNotes` | 初始化加载已有笔记 |
-| `onRequestCreateNote` | **推荐**：宿主弹窗后 `complete(noteId)` |
-| `onCreateNote` | 内置创建（与上一项二选一） |
-| `onRequestEditNote` / `onUpdateNote` / `onDeleteNote` | 编辑、更新、删除 |
-
-### 书签 `options.bookmarks`
+```ts
+import type { ChapterViewerOptions, IChapterPdfLoader } from '@embedpdf-editor/vue3-chapter-viewer';
 
-| 回调 | 说明 |
-|------|------|
-| `load` | 加载已有书签 |
-| `persist` | 增删改后持久化 |
-| `onRequestRemove` | 删除确认，返回 `true` 后从渲染层移除 |
+const loader: IChapterPdfLoader = {
+  async loadPdf(chapter) {
+    const res = await api.getChapterPdf(chapter.chapterId);
+    return { url: res.signedUrl };
+    // 或 return { buffer: await res.arrayBuffer() };
+  },
+};
 
----
+const options: ChapterViewerOptions = {
+  manifest: { chapters: [/* 可省略各条 source */] },
+  chapterPdfLoader: loader,
+  notes: { /* ... */ },
+  bookmarks: { /* ... */ },
+};
+```
 
-## 内部默认（无需配置）
+## Worker 与 WASM
 
-以下由引擎内置，业务**不用**再写：`overlapStrategy`、`passwordProvider`、`prefetchChapters`、`loadDefaultStampLibrary`、`toolbar`（Annotate 模式栏已关闭）等。需要改时再使用进阶 API `createPdfChapterEditor`。
+`usePdfiumEngine()` 默认使用 `@embedpdf/engines` 内置的 PDFium CDN wasm 地址，并默认启用 worker：
 
----
+```ts
+usePdfiumEngine();
+```
 
-## 主要导出
+如果业务要求内网部署、固定版本或自定义 CDN，再传入自托管地址：
 
-| 导出 | 用途 |
-|------|------|
-| `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` 子路径） |
+```ts
+usePdfiumEngine({ wasmUrl: '/assets/pdfium.wasm', worker: true });
+```
 
-类型详见 `dist/index.d.ts`。
+使用 `worker: true` 时，部署环境需要允许 worker 加载 wasm。若只在 worker 模式失败，可先用 `worker: false` 定位资源或响应头问题。
 
----
+## 进阶组合
 
-## 接入检查清单
+内置 `ChapterPdfViewer` 已完成插件注册和章节视口渲染。需要插入自定义 shell、目录、工具栏或直接访问 registry 时，可以使用低层组合：
 
-在业务项目中接入时，请确认：
+```vue
+<script setup lang="ts">
+import {
+  EmbedPDF,
+  PdfChapterViewport,
+  createChapterViewerBundle,
+} from '@embedpdf-editor/vue3-chapter-viewer';
 
-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"` 即可。
+const { plugins, features } = createChapterViewerBundle(options);
+</script>
 
-本包随 npm 发布，**不包含**可运行的示例站点或 mock 数据；请以上文代码片段为模板，在业务仓库中创建页面并放置自有 PDF。
+<template>
+  <EmbedPDF :engine="engine" :plugins="plugins">
+    <template #default="{ pluginsReady }">
+      <PdfChapterViewport v-if="pluginsReady" :features="features" />
+    </template>
+  </EmbedPDF>
+</template>
+```
 
----
+`createChapterViewerEditorOptions()` 只生成旧式 editor 配置，不含 `features`；新代码优先使用 `options` 或 `createChapterViewerBundle(options)`。
 
-## 其他框架
+## 标注导入导出
 
-| 包 | 说明 |
-|----|------|
-| `@embedpdf-editor/react-chapter-viewer` | React 18+ |
-| `@embedpdf-editor/chapter-snippet` | Vue 2.6+ Web Component / 无构建集成 |
+包内直接导出章节标注 IO：
 
-能力与 React 版视口内核对齐；API 命名一致，仅组合方式随框架变化。
+```ts
+import {
+  exportAllChapterAnnotations,
+  importChapterAnnotationsArchive,
+  chapterAnnotationsArchiveToJson,
+  parseChapterAnnotationsArchiveJson,
+  useRegistry,
+} from '@embedpdf-editor/vue3-chapter-viewer';
+```
 
----
+导出格式包含 `bookmarks`、`notes`、`markup`，版本常量为 `CHAPTER_ANNOTATIONS_ARCHIVE_VERSION`。导入时可选择 `mode: 'replace' | 'merge'`，并可传 `persistNotes` / `persistBookmarks` 把导入结果写回业务存储。
 
 ## 常见问题
 
-**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` 后硬刷新浏览器。
-
-**Q：笔记弹窗想完全自定义？**  
-使用 `onRequestCreateNote` + `complete(noteId)`，不要实现 `onCreateNote`。
-
-**Q：`useCapability` 报错 “must be used inside EmbedPDF”？**  
-`ChapterWorkspace` 等子组件必须渲染在 `<EmbedPDF>` 的默认 slot 内，不能与它平级。
+| 现象 | 处理 |
+| --- | --- |
+| 一直停在引擎加载 | 如果传了自定义 `wasmUrl`，检查地址是否 200、MIME/跨源头是否正确 |
+| 只显示空白 | 确认外层容器有高度，且章节 `source.url` 可访问 |
+| 页码或滚动错位 | 检查 `globalPageRange` 与 `localPageRange` 页数是否一致 |
+| 划词笔记没有保存 | 实现 `notes.onCreateNote` 或自定义 `onRequestCreateNote` 流程 |
+| 书签删除无效 | `bookmarks.onRequestRemove` 需要返回 `true` 才会删除 |