@embedpdf-editor/chapter-snippet 0.3.0 → 0.3.1

package/README.md

@@ -1,6 +1,8 @@
 # @embedpdf-editor/chapter-snippet
 
-章节 PDF 阅读器独立运行时（Preact + Web Component），供 **Vue 2.6** 等宿主通过薄包装挂载，无需引入 Vue 3。
+框架无关的章节 PDF 阅读器运行时。它把 Preact 阅读器封装成 Web Component，适合 Vue 2、传统页面、微前端或任何不想引入 React/Vue3 渲染器的宿主。
+
+能力与 React/Vue3 渲染器保持一致：多章连续滚动、划线/高亮、附注、段落书签、章节目录和标注导入导出。
 
 ## 安装
 
@@ -8,61 +10,171 @@
 pnpm add @embedpdf-editor/chapter-snippet
 ```
 
+## Vite
+
+`chapterSnippetViteResolve()` 用于 Vue2/snippet 场景：
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { chapterSnippetViteResolve } from '@embedpdf-editor/chapter-snippet/vite';
+
+export default defineConfig({
+  ...chapterSnippetViteResolve(),
+});
+```
+
+它会：
+
+| 配置 | 作用 |
+| --- | --- |
+| `server.headers` | 开发环境添加 COOP/COEP，满足 worker/wasm 常见要求 |
+| `optimizeDeps.exclude` | 避免 Vite 二次预构建 snippet 和 PDFium 引擎 |
+
 ## 快速开始
 
+不需要把 `pdfium.wasm` 手动放到宿主项目的 `public/`。默认会从 `@embedpdf-editor/chapter-snippet/dist/pdfium.wasm` 加载。只有当你要走 CDN 或自定义静态域名时，才需要传 `wasmUrl`。
+
 ```js
-import ChapterEmbedPDF, { createChapterViewerEditorOptions } from '@embedpdf-editor/chapter-snippet';
+import ChapterEmbedPDF, {
+  CHAPTER_SNIPPET_EVENTS,
+} from '@embedpdf-editor/chapter-snippet';
 
-const container = ChapterEmbedPDF.init({
+const viewer = ChapterEmbedPDF.init({
   type: 'container',
-  target: document.getElementById('viewer'),
-  wasmUrl: '/pdfium.wasm',
+  target: document.getElementById('reader'),
   worker: true,
-  editorInput: createChapterViewerEditorOptions({ manifest, bookmarks, notes }),
+  options: {
+    manifest: {
+      chapters: [
+        {
+          chapterId: 'ch-1',
+          title: '第一章',
+          globalPageRange: [1, 12],
+          localPageRange: [0, 11],
+          source: { url: '/pdfs/chapter-1.pdf' },
+        },
+      ],
+    },
+    notes: {
+      loadNotes: async () => [],
+      onUpdateNote: async () => {},
+      onDeleteNote: async () => {},
+    },
+    bookmarks: {
+      load: async () => [],
+      persist: async () => {},
+      onRequestRemove: async () => true,
+    },
+    features: {
+      markup: true,
+      bookmarks: true,
+      notes: true,
+      selectionToolbar: true,
+      zoom: { pageWidth: 720 },
+    },
+  },
+});
+
+viewer?.addEventListener(CHAPTER_SNIPPET_EVENTS.noteRequestCreate, (event) => {
+  const { draft, complete } = event.detail;
+  openNoteDialog(draft, async (content) => {
+    const noteId = await saveNote(content, draft);
+    await complete(noteId);
+  });
 });
 
-container.addEventListener('chapter-note-request-create', (e) => {
-  console.log(e.detail);
+viewer?.addEventListener(CHAPTER_SNIPPET_EVENTS.ready, (event) => {
+  console.log('registry ready', event.detail.registry);
 });
 ```
 
-## WASM / Worker
+容器需要稳定高度：
 
-构建产物 `dist/` 包含：
+```css
+#reader {
+  height: 100vh;
+  min-height: 0;
+}
+```
 
-- `embedpdf-chapter.js` — 主入口（ESM）
-- `pdfium.wasm` — 需与 JS 同域可访问，或通过 `wasmUrl` 指定
+## 配置
 
-开发服务器需设置 COOP/COEP（SharedArrayBuffer）：
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `type` | 必填 | 目前使用 `'container'` |
+| `target` | 必填 | 挂载目标元素 |
+| `options` | 必填 | 推荐的章节阅读器配置，和 React/Vue3 的 `options` 语义一致 |
+| `wasmUrl` | `dist/pdfium.wasm` | 自定义 PDFium wasm 地址 |
+| `worker` | `true` | 是否启用 PDFium worker |
+| `fallbackToDirectEngine` | `true` | 首章 worker 加载超时后自动降级到 direct engine |
+| `workerOpenTimeoutMs` | `8000` | 首章加载超时时间 |
+| `features` | - | 兼容旧写法；会覆盖 `options.features` 中同名项 |
+| `className` / `viewportClassName` | - | 传给内部阅读器容器 |
 
-```
-Cross-Origin-Opener-Policy: same-origin
-Cross-Origin-Embedder-Policy: require-corp
-```
+旧版本的 `editorInput` 仍可使用，但新代码应改为 `options`。`options.features` 会参与合并，顶层 `features` 仅作为兼容覆盖保留。
+
+## 事件
+
+snippet 通过 DOM `CustomEvent` 把需要宿主 UI 参与的动作抛出来。
 
-## CustomEvent
+| 常量 | 事件名 | detail |
+| --- | --- | --- |
+| `noteRequestCreate` | `chapter-note-request-create` | `{ draft, complete }` |
+| `noteRequestEdit` | `chapter-note-request-edit` | `{ noteId, anchor }` |
+| `selectionExtraAction` | `chapter-selection-extra-action` | `{ actionId }` |
+| `ready` | `chapter-viewer-ready` | `{ registry }` |
 
-| 事件名 | 说明 |
-|--------|------|
-| `chapter-note-request-create` | 划词创建笔记 |
-| `chapter-note-request-edit` | 编辑笔记 |
-| `chapter-selection-extra-action` | 划词工具栏扩展动作 |
-| `chapter-viewer-ready` | 引擎就绪，`detail.registry` |
+附注创建在 snippet 中默认走事件流：宿主展示自己的弹窗、保存内容，然后调用 `complete(noteId)` 让阅读器把锚点与业务 noteId 关联起来。
 
-常量：`CHAPTER_SNIPPET_EVENTS`
+## Vue 2 用法
 
-## Vue 2.6
+Vue 2 组件只需要在 `mounted` 时初始化，在 `beforeDestroy` 时销毁：
 
 ```js
-import ChapterEmbedPDF, { createChapterViewerEditorOptions } from '@embedpdf-editor/chapter-snippet';
+import ChapterEmbedPDF from '@embedpdf-editor/chapter-snippet';
+
+export default {
+  props: {
+    options: { type: Object, required: true },
+  },
+  mounted() {
+    this.viewer = ChapterEmbedPDF.init({
+      type: 'container',
+      target: this.$refs.host,
+      options: this.options,
+      worker: true,
+    });
+  },
+  beforeDestroy() {
+    this.viewer?.destroy?.();
+  },
+};
 ```
 
-Demo：`examples/chapter-viewer-demo-vue2`。Vite 需 `optimizeDeps.exclude: ['@embedpdf-editor/chapter-snippet', '@embedpdf/engines']`，并将 `pdfium.wasm` 放到站点根路径。
+完整示例见 `examples/chapter-viewer-demo-vue2`。
+
+## 标注导入导出
+
+包内直接导出章节标注 IO：
+
+```js
+import {
+  exportAllChapterAnnotations,
+  importChapterAnnotationsArchive,
+  chapterAnnotationsArchiveToJson,
+  parseChapterAnnotationsArchiveJson,
+} from '@embedpdf-editor/chapter-snippet';
+```
 
-也可使用 `@embedpdf-editor/vue2-chapter-viewer` 薄包装（内部同样 `import` 本包）。
+在 snippet 中可通过 `chapter-viewer-ready` 事件拿到 `registry`，再调用这些 API。导出格式包含 `bookmarks`、`notes`、`markup`，版本常量为 `CHAPTER_ANNOTATIONS_ARCHIVE_VERSION`。
 
-## 与 vue3-chapter-viewer 差异
+## 常见问题
 
-- 渲染在 Shadow DOM 内的 Preact 岛，宿主仅负责配置与弹窗
-- 不依赖 `@embedpdf-editor/editor-engine/vue`（Vue 3）
-- 能力集与 `DEFAULT_CHAPTER_VIEWER_FEATURES` 对齐
+| 现象 | 处理 |
+| --- | --- |
+| 卡在“正在加载 PDFium” | 检查 `dist/pdfium.wasm` 是否随包发布并能被浏览器访问；自定义部署时传 `wasmUrl` |
+| 卡在“正在加载 xxx.pdf” | 优先确认章节 PDF URL 是否 200；如只在 worker 模式出现，可保留默认 fallback 或临时设 `worker: false` 定位环境问题 |
+| 只显示空白 | 确认宿主元素有高度，且没有被父容器 `overflow`/flex 布局压到 0 |
+| 划词后没有笔记弹窗 | 监听 `chapter-note-request-create`，保存后调用 `detail.complete(noteId)` |
+| Vue/Vite 开发环境异常预构建 | 使用 `chapterSnippetViteResolve()`，确保 snippet 和 PDFium 引擎没有被 optimizeDeps 预构建 |

package/dist/embedpdf-chapter.d.ts

@@ -32,6 +32,11 @@ declare interface BookmarkMarkerUiConfig_2 {
     iconSize?: number;
 }
 
+export declare function buildChapterViewerCatalog(nodes: ChapterTreeInput[]): {
+    tree: ChapterTreeNode_2[];
+    manifest: ChapterManifest;
+};
+
 export declare function buildParagraphBookmarkAnchor(chapterId: string, localPageIndex: number, rectsPdfCoord: Rect[], virtualPage?: {
     globalPageIndex: number;
     globalPageNumber: number;
@@ -113,6 +118,8 @@ export declare interface ChapterDescriptor {
     ownedGlobalPages?: number[];
 }
 
+export declare function chapterDescriptorFromTreeNode(node: ChapterTreeInput): ChapterDescriptor;
+
 declare const ChapterEmbedPDF: {
     version: string;
     init: (config: ContainerInitConfig) => EmbedPdfChapterContainer | undefined;
@@ -261,7 +268,9 @@ export declare type ChapterSource = {
     url: string;
 } | {
     buffer: ArrayBuffer;
-} | {
+}
+/** 按章预处理：拉取、解密、转换后返回 url 或 buffer */
+| {
     load: () => Promise<ChapterPdfPayload>;
 };
 
@@ -275,8 +284,31 @@ declare interface ChapterStatusEvent {
     };
 }
 
+/**
+ * 业务目录树输入：父节点页范围可覆盖子节点；flatten 后每条对应一个可加载的 PDF 章节。
+ * 父节点若仅作分组、无独立 PDF，请勿放入 manifest（不要 flatten 该节点）。
+ */
+export declare type ChapterTreeInput = {
+    chapterId: string;
+    title: string;
+    startPage: number;
+    endPage: number;
+    source?: ChapterSource;
+    encrypted?: boolean;
+    children?: ChapterTreeInput[];
+};
+
 export { ChapterTreeNode }
 
+/** 侧栏目录树节点（仅 UI；渲染以 flatten 后的 manifest 为准） */
+declare type ChapterTreeNode_2 = {
+    id: string;
+    title: string;
+    startPage: number;
+    endPage: number;
+    children?: ChapterTreeNode_2[];
+};
+
 export { ChapterViewerCatalog }
 
 /**
@@ -335,12 +367,19 @@ export declare interface ChapterViewerOptions {
     /** 书签持久化与删除回调 */
     bookmarks: ParagraphBookmarkCallbacks;
     chapterPdfLoader?: IChapterPdfLoader;
+    /**
+     * 同一全局页被多个章节条目覆盖时，用哪一个章节的 PDF 渲染（非 owner 的章节在该页不绘制真实 PDF）。
+     * - `{ kind: 'first-wins' }`：manifest 中先出现的章节（默认）
+     * - `{ kind: 'last-wins' }`：后出现的章节（目录 flatten 后常用于「以当前页最后一节为准」）
+     * 亦可用 `overlapStrategyForSamePageOwner('first' | 'last')`（chapter-core 包）
+     */
+    overlapStrategy?: OverlapOwnerStrategy;
     /** 功能开关与样式；省略则全开 */
     features?: ChapterViewerConfig;
 }
 
 export declare type ChapterViewerSnippetConfig = {
-    /** PDFium wasm 地址，默认 jsdelivr */
+    /** PDFium wasm 地址；默认使用 chapter-snippet/dist/pdfium.wasm */
     wasmUrl?: string;
     /** 是否使用 worker 引擎，默认 true */
     worker?: boolean;
@@ -348,8 +387,10 @@ export declare type ChapterViewerSnippetConfig = {
     fallbackToDirectEngine?: boolean;
     /** 首章加载超时时间；用于 worker fallback，默认 8000ms */
     workerOpenTimeoutMs?: number;
-    /** 章节编辑器选项（manifest + 书签/笔记回调） */
-    editorInput: CreateChapterViewerEditorOptionsInput;
+    /** 推荐：章节阅读器配置（manifest + 书签/笔记回调 + 可选 features） */
+    options?: ChapterViewerOptions;
+    /** @deprecated 请改用 options */
+    editorInput?: CreateChapterViewerEditorOptionsInput;
     /** 阅读器功能开关，默认与 DEFAULT_CHAPTER_VIEWER_FEATURES 合并 */
     features?: ChapterViewerFeaturesConfig;
     className?: string;
@@ -437,6 +478,8 @@ export declare const DEFAULT_CHAPTER_VIEWER_CONFIG: ChapterViewerConfig;
 /** 默认全开的功能配置（内部规范化结果） */
 export declare const DEFAULT_CHAPTER_VIEWER_FEATURES: ChapterViewerFeaturesConfig;
 
+export declare const defaultOverlapStrategy: OverlapOwnerStrategy;
+
 export declare function downloadChapterAnnotationsArchive(archive: ChapterAnnotationsArchive, filename?: string): void;
 
 export declare function downloadChapterAnnotationsSnapshot(snapshot: ChapterAnnotationsSnapshot, filename?: string): void;
@@ -486,6 +529,9 @@ export declare type ExportChapterAnnotationsOptions = ChapterAnnotationsContentF
     ensureChapterLoaded?: boolean;
 };
 
+/** 深度优先展开目录树为 manifest.chapters（含父、子各一条，与 demo flatten 一致） */
+export declare function flattenChapterTree(nodes: ChapterTreeInput[]): ChapterDescriptor[];
+
 declare interface HoverBookmarkUiConfig {
     /** 悬停行末「添加书签」自定义图标；无背景 */
     renderAddIcon?: () => unknown;
@@ -498,8 +544,14 @@ declare interface HoverBookmarkUiConfig_2 {
 }
 
 /**
- * 全局章节 PDF 加载器：当 `ChapterDescriptor.source` 未提供 url/buffer/load 时使用。
- * 适合统一走业务 API、鉴权下载等场景。
+ * 全局章节 PDF 加载器：在打开章节前由引擎调用，用于预处理/拉取 PDF。
+ *
+ * 优先级（`ChapterManagerPlugin.resolvePdfPayload`）：
+ * 1. `chapter.source.url` / `source.buffer` — 直接使用
+ * 2. `chapter.source.load()` — 按章异步，返回 `{ url }` 或 `{ buffer }`
+ * 3. `chapterPdfLoader.loadPdf(chapter)` — 全局统一逻辑（鉴权、解密、转 blob URL 等）
+ *
+ * 适合：所有章节走同一套 API、在内存中解密后再以 buffer 打开、动态签名 URL 等。
  */
 export declare interface IChapterPdfLoader {
     loadPdf(chapter: ChapterDescriptor): Promise<ChapterPdfPayload>;
@@ -658,12 +710,17 @@ declare interface OperationSpec {
 }
 
 /**
- * 决定相邻章节在重叠页上谁拥有该页（owner）。
- * - first-wins / last-wins：按 manifest 顺序的先到/后到
- * - explicit：依赖 `ChapterDescriptor.ownedGlobalPages`
- * - custom：开发者完全接管
+ * 决定同一全局页被多个章节 manifest 条目覆盖时，用哪一个章节的 PDF 渲染（owner）。
+ * 非 owner 章节在该页仅占位/不绘制真实 PDF，避免重复。
+ *
+ * - **first-wins**：manifest 中**先**出现的章节（默认）
+ * - **last-wins**：**后**出现的章节（目录 flatten 后，重叠页常以「当前页最后一节」为准）
+ * - **explicit**：`ChapterDescriptor.ownedGlobalPages` 声明归属
+ * - **custom**：`resolve(globalPage, candidates)` 完全自定义
+ *
+ * 简写：`overlapStrategyForSamePageOwner('first' | 'last')`（chapter-core）
  */
-declare type OverlapOwnerStrategy = {
+export declare type OverlapOwnerStrategy = {
     kind: 'first-wins';
 } | {
     kind: 'last-wins';
@@ -674,6 +731,8 @@ declare type OverlapOwnerStrategy = {
     resolve: (globalPage: number, candidates: ChapterDescriptor[]) => string;
 };
 
+export declare function overlapStrategyForSamePageOwner(owner: SamePageOverlapOwner): OverlapOwnerStrategy;
+
 export declare interface ParagraphBookmark {
     id: string;
     label: string;
@@ -734,6 +793,9 @@ export declare interface PdfChapterEditorNotesConfig {
 declare interface PdfChapterEditorToolbarConfig extends CreateEditorUiSchemaOptions {
 }
 
+/** 同一全局页多章节重叠时，选用 manifest 中先/后出现的章节 PDF */
+export declare type SamePageOverlapOwner = 'first' | 'last';
+
 /** 划线类型 */
 declare type SelectionMarkupKind = 'highlight' | 'underline' | 'squiggly' | 'strikeout';
 
@@ -763,6 +825,8 @@ export declare interface SerializableAnnotationTransferItem {
     };
 }
 
+export declare function toChapterTreeNodes(nodes: ChapterTreeInput[]): ChapterTreeNode_2[];
+
 export declare const version = "0.1.0";
 
 /**