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

package/README.md

@@ -1,299 +1,296 @@
 # @embedpdf-editor/vue3-chapter-viewer
 
-Vue 3 章节 PDF 阅读器：多章 PDF 拼成一条连续滚动流，支持划词划线、附注、段落书签、工具栏与标注 JSON 导入导出。
+Vue 3 版章节 PDF 阅读器。它把多份章节 PDF 组织成一本连续滚动的书，并内置划线/高亮、附注、段落书签、章节目录和标注导入导出能力。
 
-底层引擎：`@embedpdf-editor/editor-engine`（Preact 渲染岛 + `@embedpdf/core` 插件体系）。
+底层使用 `@embedpdf/core` 插件体系和 PDFium 引擎；Vue 3 包只负责提供 SFC 组件、composition hooks 和类型导出。
 
 ## 安装
 
 ```bash
-pnpm add @embedpdf-editor/vue3-chapter-viewer @embedpdf/engines
+pnpm add @embedpdf-editor/vue3-chapter-viewer
 ```
 
-## Vite 与 WASM
+## Vite
+
+包内导出的是一段 Vite 配置，不是 Vite plugin。它用于补齐 `scheduler` alias 和 PDFium 引擎的预构建配置；`@embedpdf/engines` 已经是本包依赖，业务项目不需要单独安装。
 
 ```ts
 // vite.config.ts
-import { defineConfig } from 'vite';
+import { defineConfig, mergeConfig } from 'vite';
 import vue from '@vitejs/plugin-vue';
-import { chapterViewerVitePlugin } from '@embedpdf-editor/vue3-chapter-viewer/vite';
-
-export default defineConfig({
-  plugins: [vue(), chapterViewerVitePlugin()],
-});
+import { chapterViewerViteResolve } from '@embedpdf-editor/vue3-chapter-viewer/vite';
+
+export default mergeConfig(
+  defineConfig({
+    plugins: [vue()],
+  }),
+  chapterViewerViteResolve(),
+);
 ```
 
-将 `pdfium.wasm` 放到 `public/`（或由 `chapterViewerVitePlugin` 自动复制）。`usePdfiumEngine({ wasmUrl: '/pdfium.wasm' })` 的地址须与静态资源路径一致。
+如果不用 `mergeConfig`，需要手动合并 `resolve.alias` 和 `optimizeDeps.include`，不要直接覆盖现有配置。
 
-## 快速上手
+## 快速开始
+
+推荐只传 `options`。`editorOptions` 和 `features` 仍兼容，但已作为低层/旧写法保留。
 
 ```vue
 <script setup lang="ts">
-import { ref } from 'vue';
 import {
   ChapterPdfViewer,
   usePdfiumEngine,
-  createChapterViewerEditorOptions,
-  DEFAULT_CHAPTER_VIEWER_FEATURES,
-  CallbackPasswordProvider,
+  type ChapterViewerOptions,
 } from '@embedpdf-editor/vue3-chapter-viewer';
-import type { ChapterManifest, NoteAnchor } from '@embedpdf-editor/vue3-chapter-viewer';
-
-const { engine, isLoading } = usePdfiumEngine({ wasmUrl: '/pdfium.wasm' });
-
-const manifest: ChapterManifest = {
-  chapters: [
-    {
-      chapterId: 'ch-1',
-      title: '第一章',
-      globalPageRange: [1, 10],
-      localPageRange: [0, 9],
-      source: { url: '/pdfs/ch1.pdf' },
-      encrypted: true, // 可选：业务标记该章为加密 PDF
-    },
-  ],
-};
 
-const viewerProps = createChapterViewerEditorOptions({
-  manifest,
+const { engine, isLoading, error } = usePdfiumEngine();
+
+const options: ChapterViewerOptions = {
+  manifest: {
+    chapters: [
+      {
+        chapterId: 'ch-1',
+        title: '第一章',
+        globalPageRange: [1, 12],
+        localPageRange: [0, 11],
+        source: { url: '/pdfs/chapter-1.pdf' },
+      },
+    ],
+  },
   notes: {
-    loadNotes: async () => [] as NoteAnchor[],
-    onCreateNote: async (draft) => ({ noteId: crypto.randomUUID() }),
+    loadNotes: async () => [],
+    onCreateNote: async () => ({ noteId: crypto.randomUUID() }),
+    onUpdateNote: async () => {},
+    onDeleteNote: async () => {},
   },
   bookmarks: {
     load: async () => [],
     persist: async () => {},
+    onRequestRemove: async () => true,
   },
-  features: DEFAULT_CHAPTER_VIEWER_FEATURES,
-});
-
-// 加密章：在 createPdfChapterEditor / 低层 options 中传入 passwordProvider（见下文）
+  features: {
+    markup: true,
+    bookmarks: true,
+    notes: true,
+    selectionToolbar: true,
+    zoom: { pageWidth: 720 },
+  },
+};
 </script>
 
 <template>
-  <ChapterPdfViewer v-if="engine && !isLoading" :engine="engine" :viewer-props="viewerProps" />
+  <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>
+
+<style scoped>
+.reader {
+  height: 100vh;
+  min-height: 0;
+}
+
+.reader-fill {
+  height: 100%;
+  min-height: 0;
+}
+</style>
 ```
 
-完整交互见 monorepo 示例：`examples/chapter-viewer-demo-vue3`。
+## `ChapterViewerOptions`
 
-## Manifest（章节清单）
+`options` 是三端渲染器的统一配置入口。
 
 | 字段 | 说明 |
-|------|------|
-| `chapterId` | 业务唯一 ID，同时作为 `documentManager` 的 `documentId` |
-| `title` | 展示标题 |
-| `globalPageRange` | 该章在「整本」中的全局页闭区间；相邻章可重叠 |
-| `localPageRange` | 该章 PDF 内 0-based 页闭区间；页数须与 global 区间一致 |
-| `source` | `{ url }` / `{ buffer }` / `{ load: () => Promise<...> }`；可省略并在 `chapterPdfLoader` 统一加载 |
-| `encrypted` | **可选提示位**：标记该章可能需密码；真正触发密码流程的是 PDFium 打开时报 `Password` 错误 |
-| `ownedGlobalPages` | 仅 `overlapStrategy: 'explicit'` 时使用 |
+| --- | --- |
+| `manifest` | 章节清单，描述每章 PDF 和全局页码关系 |
+| `notes` | 附注加载、创建、更新、删除回调 |
+| `bookmarks` | 段落书签加载、持久化、删除确认回调 |
+| `chapterPdfLoader` | 可选：全局 PDF 预处理/拉取（见下文） |
+| `overlapStrategy` | 可选：同一全局页多章节重叠时，用先/后出现的章节 PDF 渲染 |
+| `features` | 可选：功能开关与样式配置，省略时使用默认能力 |
+
+### Manifest
 
-## 加密 PDF（密码 / 解密）
+```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;
+};
+```
 
-章节 PDF 若带打开密码，引擎在 `documentManager` 打开失败且错误码为 **Password** 时，会向 `passwordProvider` 索取密码；用户放弃则该章进入 **`password-required`** 状态。
+`globalPageRange` 和 `localPageRange` 都是闭区间，且页数必须一致。`chapterId` 同时作为内部 `documentId`，需要在整本书内唯一。
 
-### 配置方式
+### 嵌套目录树与重叠页
 
-`createChapterViewerEditorOptions` 默认使用「始终返回 `null`」的 `CallbackPasswordProvider`（即不弹窗、直接失败）。业务须在 **`createPdfChapterEditor`** 或展开 `viewerProps` 底层 options 时传入自定义 provider：
+侧栏目录支持**任意层级**（`ChapterTreePanel` + `ChapterTreeNode.children`）。引擎滚动用的 `manifest.chapters` 是**扁平列表**：父节点页范围可包含子节点，相邻/重叠全局页由 **owner 策略** 决定只渲染一个章节的 PDF，避免同页画两遍。
 
 ```ts
 import {
-  createChapterViewerEditorOptions,
-  CallbackPasswordProvider,
+  buildChapterViewerCatalog,
+  overlapStrategyForSamePageOwner,
+  type ChapterViewerOptions,
 } from '@embedpdf-editor/vue3-chapter-viewer';
-// StaticPasswordProvider / UiPromptPasswordProvider 从 @embedpdf-editor/chapter-core 引入
 
-const passwordProvider = new CallbackPasswordProvider(async (chapter, attempt) => {
-  // attempt: 0 为首次，递增表示重试次数（可做「错三次锁定」）
-  const pwd = await myAskPasswordUi(chapter.title, attempt);
-  return pwd; // 返回 null 表示用户取消 → 章节 status: password-required
-});
+// 从业务树生成 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: [/* ... */],
+  },
+]);
 
-const viewerProps = createChapterViewerEditorOptions({ manifest, notes, bookmarks });
-// viewerProps 内部会 merge 到 createPdfChapterEditor；若需覆盖 passwordProvider，
-// 请使用 createPdfChapterEditor({ ...opts, passwordProvider }) + 自行组装 EmbedPDF。
+const options: ChapterViewerOptions = {
+  manifest,
+  overlapStrategy: overlapStrategyForSamePageOwner('last'), // 重叠页用 manifest 中「后出现」的章节
+  // overlapStrategy: { kind: 'first-wins' }, // 默认：先出现的章节
+  notes: { /* ... */ },
+  bookmarks: { /* ... */ },
+};
 ```
 
-### 内置 Provider（`@embedpdf-editor/chapter-core`）
+| `overlapStrategy` | 同一全局页多个章节条目时 |
+| --- | --- |
+| `{ kind: 'first-wins' }`（默认） | 使用 **manifest 中先出现** 的章节的 PDF |
+| `{ kind: 'last-wins' }` | 使用 **后出现** 的章节（目录 flatten 后，重叠页常以「当前页最后一节」为准） |
+| `{ kind: 'explicit' }` | 各章在 `ownedGlobalPages` 上声明归属页 |
+| `{ kind: 'custom', resolve }` | 完全自定义 |
 
-| 类 | 用途 |
-|----|------|
-| `CallbackPasswordProvider` | 异步回调 `(chapter, attempt) => string \| null`，最常用 |
-| `StaticPasswordProvider` | 构造时传入 `Record<chapterId, password>`，适合 SSO 一次解锁多章 |
-| `UiPromptPasswordProvider` | `onPrompt(chapter, attempt)` 通知 UI，UI 调 `submit(chapterId, password \| null)` 完成 Promise |
+简写：`overlapStrategyForSamePageOwner('first' | 'last')`。
 
-`getCachedPassword?(chapterId)` 可选：同步返回已缓存密码，避免重复弹窗。
+**注意**：仅作分组、没有独立 PDF 的父节点不要放进 flatten 后的 manifest；只保留需要加载 PDF 的节点。Demo：`examples/chapter-viewer-demo-vue3/src/demo/load-catalog.ts`。
 
-### 章节加载状态
+### PDF 加载与预处理
 
-`ChapterLoadStatus` 包含：`idle` | `loading` | `loaded` | `error` | **`password-required`**。密码提交成功后 `ChapterManagerPlugin` 会带密码重试打开。
+打开章节前，引擎按以下优先级解析 PDF（`ChapterManagerPlugin.resolvePdfPayload`）：
 
-## 标注导入 / 导出（JSON 格式）
+1. `chapter.source.url` / `source.buffer` — 直接使用  
+2. `chapter.source.load()` — **按章**异步预处理，返回 `{ url }` 或 `{ buffer }`  
+3. `chapterPdfLoader.loadPdf(chapter)` — **全局**统一逻辑  
 
-类型定义见 `editor-engine` → `chapter-annotations-io/types.ts`。当前归档版本常量：`CHAPTER_ANNOTATIONS_ARCHIVE_VERSION === 1`。
+**按章 `source.load`（单章解密、鉴权 URL）：**
 
-### 全书归档 `ChapterAnnotationsArchive`
-
-```jsonc
+```ts
 {
-  // 固定为 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"
-          }
-        }
-      ]
-    }
-  }
+  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) };
+    },
+  },
 }
 ```
 
-### 单章快照 `ChapterAnnotationsSnapshot`
+**全局 `chapterPdfLoader`（所有章走同一套 API）：**
 
-与归档中某一章对象相同，但**顶层多一个** `chapterId`：
-
-```jsonc
-{
-  "chapterId": "ch-1",
-  "bookmarks": [],
-  "notes": [],
-  "markup": []
-}
-```
+```ts
+import type { ChapterViewerOptions, IChapterPdfLoader } from '@embedpdf-editor/vue3-chapter-viewer';
 
-`bookmarks` / `notes` / `markup` 均可省略；导出时可按 `ExportChapterAnnotationsOptions` 关闭某一类。
+const loader: IChapterPdfLoader = {
+  async loadPdf(chapter) {
+    const res = await api.getChapterPdf(chapter.chapterId);
+    return { url: res.signedUrl };
+    // 或 return { buffer: await res.arrayBuffer() };
+  },
+};
 
-### 导入选项 `ImportChapterAnnotationsOptions`
+const options: ChapterViewerOptions = {
+  manifest: { chapters: [/* 可省略各条 source */] },
+  chapterPdfLoader: loader,
+  notes: { /* ... */ },
+  bookmarks: { /* ... */ },
+};
+```
 
-| 选项 | 默认 | 说明 |
-|------|------|------|
-| `mode` | `replace` | `replace`：先清空该章对应数据再写入；`merge`：与现有合并（书签按 anchor 去重） |
-| `ensureChapterLoaded` | `true` | 导入划线前确保该章 PDF 已打开 |
-| `bookmarks` / `notes` / `markup` | `true` | 控制是否处理对应字段 |
-| `persistNotes` | — | 导入完成后回调，参数为**全书**附注列表，便于写 localStorage / 后端 |
-| `persistBookmarks` | — | 同上，段落书签列表 |
+## Worker 与 WASM
 
-### API（均需 `PluginRegistry`，Vue 3 用 `useRegistry()`）
+`usePdfiumEngine()` 默认使用 `@embedpdf/engines` 内置的 PDFium CDN wasm 地址，并默认启用 worker：
 
 ```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();
+usePdfiumEngine();
+```
 
-const archive = await exportAllChapterAnnotations(registry.value!);
-const json = chapterAnnotationsArchiveToJson(archive);
+如果业务要求内网部署、固定版本或自定义 CDN，再传入自托管地址：
 
-await importChapterAnnotationsArchive(registry.value!, parseChapterAnnotationsArchiveJson(json), {
-  mode: 'replace',
-  persistNotes: (all) => myStore.saveNotes(all),
-  persistBookmarks: (all) => myStore.saveBookmarks(all),
-});
+```ts
+usePdfiumEngine({ wasmUrl: '/assets/pdfium.wasm', worker: true });
 ```
 
-| 函数 | 说明 |
-|------|------|
-| `exportChapterAnnotations(registry, chapterId, options?)` | 导出单章快照 |
-| `exportAllChapterAnnotations(registry, options?)` | 导出全书归档 |
-| `importChapterAnnotations(registry, snapshot, options?)` | 导入单章 |
-| `importChapterAnnotationsArchive(registry, archive, options?)` | 导入全书 |
-| `chapterAnnotationsArchiveToJson` / `parseChapterAnnotationsArchiveJson` | 序列化 / 反序列化 |
-| `chapterAnnotationsSnapshotToJson` / `parseChapterAnnotationsSnapshotJson` | 单章版 |
-| `downloadChapterAnnotationsArchive` / `downloadChapterAnnotationsSnapshot` | 触发浏览器下载 `.json` |
+使用 `worker: true` 时，部署环境需要允许 worker 加载 wasm。若只在 worker 模式失败，可先用 `worker: false` 定位资源或响应头问题。
+
+## 进阶组合
 
-Demo 参考：`examples/chapter-viewer-demo-vue3/src/components/AnnotationsDemoBar.vue`。
+内置 `ChapterPdfViewer` 已完成插件注册和章节视口渲染。需要插入自定义 shell、目录、工具栏或直接访问 registry 时，可以使用低层组合：
 
-## 功能开关 `features`
+```vue
+<script setup lang="ts">
+import {
+  EmbedPDF,
+  PdfChapterViewport,
+  createChapterViewerBundle,
+} from '@embedpdf-editor/vue3-chapter-viewer';
 
-通过 `createChapterViewerEditorOptions({ features })` 或 `DEFAULT_CHAPTER_VIEWER_FEATURES` 控制划线样式、笔记、书签、选区卡片、缩放等。详见 `@embedpdf-editor/chapter-viewer` 的 `ChapterViewerFeaturesConfig`。
+const { plugins, features } = createChapterViewerBundle(options);
+</script>
 
-## 笔记与书签
+<template>
+  <EmbedPDF :engine="engine" :plugins="plugins">
+    <template #default="{ pluginsReady }">
+      <PdfChapterViewport v-if="pluginsReady" :features="features" />
+    </template>
+  </EmbedPDF>
+</template>
+```
 
-- **附注**：`notes.loadNotes`、`onCreateNote` 或 `onRequestCreateNote`（自定义弹窗）、`onUpdateNote`、`onDeleteNote` 等，类型 `NoteCallbacks`。
-- **书签**：`bookmarks.load`、`persist`、`onRequestRemove`，类型 `ParagraphBookmarkCallbacks`。
+`createChapterViewerEditorOptions()` 只生成旧式 editor 配置，不含 `features`；新代码优先使用 `options` 或 `createChapterViewerBundle(options)`。
 
-## 主要导出
+## 标注导入导出
 
-| 导出 | 说明 |
-|------|------|
-| `ChapterPdfViewer` | 开箱即用阅读器壳 |
-| `PdfChapterViewport` / `ChapterTreePanel` | 自定义布局 |
-| `usePdfiumEngine` | 加载 PDFium WASM |
-| `useRegistry` / `EmbedPDF` / `useCapability` | 插件注册表与能力 |
-| `createChapterViewerEditorOptions` | 推荐配置入口 |
-| `CallbackPasswordProvider` | 密码回调（更多 Provider 见 `@embedpdf-editor/chapter-core`） |
-| 标注 IO 函数与类型 | 见上表 |
+包内直接导出章节标注 IO：
 
-## 与其它包
+```ts
+import {
+  exportAllChapterAnnotations,
+  importChapterAnnotationsArchive,
+  chapterAnnotationsArchiveToJson,
+  parseChapterAnnotationsArchiveJson,
+  useRegistry,
+} from '@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 |
+导出格式包含 `bookmarks`、`notes`、`markup`，版本常量为 `CHAPTER_ANNOTATIONS_ARCHIVE_VERSION`。导入时可选择 `mode: 'replace' | 'merge'`，并可传 `persistNotes` / `persistBookmarks` 把导入结果写回业务存储。
 
-## 故障排查
+## 常见问题
 
-- **一直 Loading**：确认 `manifest` 已 `setManifest`、章节 `source` / `chapterPdfLoader` 可访问、WASM 与 COOP/COEP 已配置。
-- **加密章无法打开**：检查 `passwordProvider` 是否返回非空密码；取消时为 `password-required`。
-- **导出 markup 为空**：该章须已 `loaded`，且 `ensureChapterLoaded` 为 true（默认）。
+| 现象 | 处理 |
+| --- | --- |
+| 一直停在引擎加载 | 如果传了自定义 `wasmUrl`，检查地址是否 200、MIME/跨源头是否正确 |
+| 只显示空白 | 确认外层容器有高度，且章节 `source.url` 可访问 |
+| 页码或滚动错位 | 检查 `globalPageRange` 与 `localPageRange` 页数是否一致 |
+| 划词笔记没有保存 | 实现 `notes.onCreateNote` 或自定义 `onRequestCreateNote` 流程 |
+| 书签删除无效 | `bookmarks.onRequestRemove` 需要返回 `true` 才会删除 |