pdf-h5-react 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 superjunjie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,431 @@
-# Temporary Holding Version
+# pdf-h5-react
+
+基于 [pdf.js](https://mozilla.github.io/pdf.js/) 的**移动端优先** React PDF 阅读器组件。
+面向 H5 场景（微信内置浏览器、iOS Safari、Android Chrome），开箱即用，同时把性能和内存控制做在架构里。
+
+[![npm](https://img.shields.io/npm/v/pdf-h5-react.svg)](https://www.npmjs.com/package/pdf-h5-react)
+[![npm downloads](https://img.shields.io/npm/dm/pdf-h5-react.svg)](https://www.npmjs.com/package/pdf-h5-react)
+[![Release](https://github.com/superjunjie/pdf-h5-react/actions/workflows/release.yml/badge.svg)](https://github.com/superjunjie/pdf-h5-react/actions/workflows/release.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+
+```
+连续滚动 / 翻页吸附 · 捏合缩放 · 双击缩放 · 文本选中 · 全文搜索
+缩略图 · 多级目录 · 内链跳转 · 密码文档 · 深浅色主题 · 旋转页 · 混尺寸页面
+高亮批注 · 文字批注 · 手写笔迹 · 事件系统 · 缩放动画
+```
+
+- 组件库本体 **81KB**（gzip 23KB），样式 12KB；`pdfjs-dist` 作为 peerDependency 由使用方安装。
+- 300 页文档实测只挂载 **2–9 个页面 DOM**，位图缓存严格受字节上限约束。
+- 端到端验证脚本用无头 Chrome 跑真实浏览器，**21 项断言全部通过**（见 [验证](#验证)）。
+
+## 效果
+
+以下截图均由 `npm run verify` 在无头 Chrome 中真实渲染后截取（移动端 390×844 @2x）：
+
+| 连续滚动（中文） | 混尺寸页面（横向 A4 + 窄页） |
+| --- | --- |
+| ![连续滚动](docs/screenshots/mobile-scroll.png) | ![混尺寸](docs/screenshots/mobile-mixed-size.png) |
+
+| 多级目录 | 全文搜索 |
+| --- | --- |
+| ![目录](docs/screenshots/mobile-outline.png) | ![搜索](docs/screenshots/mobile-search.png) |
+
+| 页面缩略图 | 翻页模式（scroll-snap） |
+| --- | --- |
+| ![缩略图](docs/screenshots/mobile-thumbnails.png) | ![翻页](docs/screenshots/mobile-page-mode.png) |
+
+| 300 页大文档 | 桌面端 |
+| --- | --- |
+| ![大文档](docs/screenshots/mobile-large.png) | ![桌面](docs/screenshots/desktop.png) |
+
+批注（高亮 + 跨行高亮 + 文字批注 + 手写），缩放 200% 后仍精确贴合原文：
+
+| 批注总览 | 放大 200% |
+| --- | --- |
+| ![批注](docs/screenshots/annotations.png) | ![批注缩放](docs/screenshots/annotations-zoom.png) |
+
+
+---
+
+## 安装
+
+```bash
+npm i pdf-h5-react pdfjs-dist
+```
+
+`react` / `react-dom` 是 peer 依赖，宿主项目已有则不会重复安装。
+包发布在 npm 公共源：[npmjs.com/package/pdf-h5-react](https://www.npmjs.com/package/pdf-h5-react)
+### 生产环境：自托管 pdf.js 资源
+
+库默认从 jsDelivr 加载与依赖版本严格一致的 worker / cmaps / 标准字体 / wasm，**零配置即可运行**。
+内网、离线或对 CDN 有顾虑时，把资源拷到自己的静态目录：
+
+```bash
+# 在依赖了本包的项目里执行（脚本会从 node_modules 解析 pdfjs-dist 的实际版本）
+node node_modules/pdf-h5-react/scripts/copy-pdfjs-assets.mjs public/pdfjs
+```
+
+```ts
+import { configurePdfjs } from 'pdf-h5-react';
+
+configurePdfjs({
+  workerSrc: '/pdfjs/build/pdf.worker.min.mjs',
+  cMapUrl: '/pdfjs/cmaps/',
+  standardFontDataUrl: '/pdfjs/standard_fonts/',
+  wasmUrl: '/pdfjs/wasm/',
+  iccUrl: '/pdfjs/iccs/',
+});
+```
+
+> `pdfjs` 的 worker 版本必须与 `pdfjs-dist` 一致，否则会抛 `API version does not match Worker version`。
+> 仓库里的 `scripts/copy-pdfjs-assets.mjs` 会按 `node_modules` 里的实际版本拷贝，并在目录下写 `VERSION` 文件。
+
+---
+
+## 快速开始
+
+```tsx
+import { PdfH5Reader } from 'pdf-h5-react';
+import 'pdf-h5-react/style.css';
+
+export default function App() {
+  return (
+    <div style={{ height: '100dvh' }}>
+      <PdfH5Reader src="/files/report.pdf" />
+    </div>
+  );
+}
+```
+
+容器必须有确定高度（`height` 不能是 auto），阅读器会填满父容器。
+
+
+---
+
+## 核心设计
+
+移动端 PDF 阅读的三个真实瓶颈是：**DOM 数量**、**位图内存**、**高频事件**。对应的三层结构与三个机制：
+
+```
+usePdfDocument   文档层   加载 / 密码 / 进度（进度事件节流 120ms）
+      ↓
+usePageMetrics   度量层   首屏并发解析 N 页真实尺寸，其余页渐进解析（rAF 批量校正）
+      ↓
+useVirtualPages  视图层   只挂载可视区内的页面 DOM
+      ↓
+RenderQueue      渲染层   可见/预取双并发 + 抢占 + 引用计数取消
+```
+
+### 1. 懒加载与性能优化
+
+| 手段 | 实现位置 | 效果（实测） |
+| --- | --- | --- |
+| 页面 DOM 虚拟化 | `hooks/useVirtualPages.ts` | 300 页文档只挂载 2–9 页 |
+| 渐进度量 | `hooks/usePageMetrics.ts` | 首屏只解析 6 页尺寸，其余用均值占位，滚动时按需解析 |
+| 渲染档位量化 | `core/layout.ts` `quantizeScale` | 缩放只升不降、命中有限档位，捏合时不重渲染 |
+| canvas 限幅 | `core/layout.ts` `clampCanvasSize` | 规避 iOS 约 1670 万像素上限导致的空白画布 |
+| 渲染队列双并发 | `core/renderQueue.ts` | 可见页优先（2 并发），预取页低优先（1 并发） |
+| 抢占式丢弃 | `RenderQueue.dropPendingPrefetch` | 快速滚动时丢弃无意义的预取任务 |
+| 缩略图按区间渲染 | `components/ThumbnailPanel.tsx` | 300 页缩略图只渲染可见行区间 |
+
+### 2. LRU 缓存
+
+四类缓存独立计量，全部按**字节/条目双上限**淘汰（`core/lru.ts`、`core/cache.ts`）：
+
+| 缓存 | 默认上限 | key | 说明 |
+| --- | --- | --- | --- |
+| 位图 | 96MB | `page@scaleBucket` | 离屏 canvas，缩放来回命中；淘汰时把 canvas 尺寸置 0 尽快归还 GPU 内存 |
+| 文本层 | 24 页 / 24MB | `page` | 已构建的 TextLayer DOM，缩放走 `update()` 重排而非重建 |
+| 页面代理 | 64 页 | `page` | `PDFPageProxy`，并发请求合并为同一个 Promise |
+| 缩略图 | 120 张 | `page` | JPEG dataURL，单张 3–8KB |
+
+两个容易踩的坑，实现里都处理了：
+
+- **唯一超大对象不立刻淘汰**：否则「渲染完就被淘汰 → 下一帧重渲染」会形成抖动。
+- **显示 canvas 必须每页独占**：缓存里是共享的离屏位图，而 DOM 节点只有一个父节点；直接把缓存 canvas 挂进页面，后挂载的页会把前面页的 canvas 抢走，表现为空白。因此渲染结果用 `drawImage` 拷到本页 canvas。
+
+### 3. 高频操作节流
+
+`core/throttle.ts` 提供三个原语，全部可通过 `getCacheStats().throttle` 观测：
+
+| 原语 | 用在 | 说明 |
+| --- | --- | --- |
+| `rafThrottle` | 滚动 → 当前页、缩略图区间 | 每帧最多一次，实测 61 次事件 → 1 次处理 |
+| `throttle` | 加载进度、日志上报 | 固定时间窗，首尾可配 |
+| `debounce` | 搜索输入（260ms）、重排定位（120ms） | 静默期结束才执行 |
+| `rafBatch` | 多页尺寸批量校正 | 一帧内合并多个 setState，避免连续重排 |
+
+捏合缩放走的是**另一条路径**：手势进行中只设置一个 CSS `transform` 做预演（只触发合成，不触发布局），松手后才一次性提交真实 `zoom` + `scroll`。
+因为内容（页面、间距、内边距）对 `zoom` 严格线性，预演与提交在数学上等价，松手不会跳变 —— 这一点由 `src/core/gestures.test.ts` 断言。
+
+---
+
+## API
+
+### `<PdfH5Reader />`
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `src` | `PdfSource` | — | `string \| URL \| ArrayBuffer \| Uint8Array \| { url, data, password, httpHeaders, withCredentials }` |
+| `mode` | `'scroll' \| 'page'` | `'scroll'` | 连续滚动 / 横向翻页（`scroll-snap`，由合成线程处理，比 JS 修正更跟手） |
+| `fitMode` | `'width' \| 'page' \| 'none'` | `'width'` | 适配方式 |
+| `initialPage` / `initialZoom` | `number` | `1` / `1` | 初始页与初始倍率 |
+| `minZoom` / `maxZoom` / `doubleTapZoom` | `number` | `0.5` / `5` / `2.5` | 缩放边界与双击目标 |
+| `animationDuration` | `number` | `300` | 双击 / 按钮缩放的动画时长（ms），`0` 表示立即跳变 |
+| `zoomEnable` / `scrollEnable` | `boolean` | `true` | 是否允许缩放 / 滚动（禁用手势，按钮与 API 仍可用） |
+| `rotation` | `number` | `0` | 额外旋转（叠加在 PDF 自带 `/Rotate` 之上） |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | `auto` 跟随系统并实时响应 |
+| `gap` / `padding` | `number` | `12` / `12` | 页间距 / 内容内边距（均随 zoom 缩放） |
+| `textLayer` | `boolean` | `true` | 关闭可省内存，代价是不可选中/复制 |
+| `links` | `boolean` | `true` | 内链跳转与外链 |
+| `toolbar` / `showControls` | `boolean` | `true` | 内置工具栏 / 页码缩放浮层 |
+| `backTop` / `loadingBar` | `boolean` | `true` | 回到顶部悬浮按钮 / 顶部加载进度条 |
+| `bitmapCacheBytes` | `number` | `96MB` | 位图缓存上限 |
+| `textLayerCacheEntries` | `number` | `24` | 文本层缓存条目上限 |
+| `maxCanvasPixels` / `maxCanvasDimension` | `number` | iOS 安全值 | canvas 限幅 |
+| `annotation` | `boolean` | `false` | 启用批注功能（工具栏出现批注按钮） |
+| `annotations` | `Annotation[]` | — | 受控批注列表；不传则内部维护 |
+| `annotationStyle` | `Partial<AnnotationStyle>` | — | 批注配色、字号、线宽 |
+| `onAnnotationsChange` | `(list) => void` | — | 批注变化回调 |
+| `onDocumentLoad` / `onPageChange` / `onProgress` / `onError` / `onZoomChange` | callback | — | 事件回调（`onProgress` 已节流） |
+| `onReady` / `onRender` / `onScroll` / `onZoomEnd` / `onComplete` | callback | — | 生命周期与交互事件（见 [事件系统](#事件系统)） |
+| `onInternalLink` / `onExternalLink` | callback | — | 拦截链接行为 |
+| `renderError` | `(error, retry) => ReactNode` | — | 自定义错误态 |
+
+### 命令式 API（通过 `ref`）
+
+```tsx
+const ref = useRef<PdfH5ReaderHandle>(null);
+
+ref.current?.goToPage(10, { smooth: true });
+ref.current?.nextPage();
+ref.current?.setZoom(2, { x: 200, y: 400 });   // 以视口坐标点为锚点缩放
+ref.current?.zoomIn();
+ref.current?.resetZoom();
+await ref.current?.search('关键词');            // 返回 SearchHit[]
+ref.current?.openPanel('outline');              // 'outline' | 'thumbnails' | 'search' | null
+ref.current?.getCacheStats();                   // 缓存与渲染运行时统计
+ref.current?.getStatus();                       // 运行状态快照
+ref.current?.clearCaches();
+```
+
+### 事件系统
+
+两种写法等价，按团队习惯选一种即可（内部走同一条派发路径，行为不会漂移）：
+
+```tsx
+// 方式 A：React props
+<PdfH5Reader
+  src={url}
+  onReady={({ total }) => setTotal(total)}
+  onZoomEnd={(e) => track('zoom', e.zoom)}
+/>
+
+// 方式 B：命令式 on/off（适合在 effect 里按条件订阅）
+const off = ref.current.on('pageChange', ({ page, total }) => setPage(page));
+off();                                              // 取消这一条
+ref.current.off('pageChange');                       // 清空该事件
+ref.current.once('complete', (e) => console.log(e));  // 只监听一次
+ref.current.trigger('backTop', { from: 3 });          // 手动派发
+```
+
+| 事件 | 载荷 | 说明 |
+| --- | --- | --- |
+| `init` | `{ src }` | 开始初始化 |
+| `ready` | `{ doc, total }` | 文档就绪，可拿总页数 |
+| `render` | `{ pageNumber, pageTime, totalTime }` | 单页渲染完成（含耗时，便于做性能埋点） |
+| `success` | `{ message, time }` | 加载成功 |
+| `error` | `{ error, message, time }` | 加载失败 |
+| `complete` | `{ status: 'success' \| 'error', message, time }` | 加载流程结束（成功失败都触发） |
+| `scroll` | `{ scrollTop, scrollLeft, currentPage, progress }` | 滚动（已 rAF 节流） |
+| `pageChange` | `{ page, total }` | 当前页变化 |
+| `zoom` / `zoomStart` | `{ zoom, source }` | 缩放中 / 开始 |
+| `zoomEnd` | `{ zoom, startZoom, scaleChange, duration, source }` | 缩放结束（动画也计入） |
+| `zoomEnabled` / `scrollEnabled` | `{ enabled }` | 开关变化 |
+| `backTop` | `{ from }` | 点击回到顶部 |
+| `destroy` | `{}` | 组件卸载 |
+
+`getStatus()` 返回运行快照，适合做埋点或调试面板：
+
+```ts
+{
+  ready: true, loading: false, total: 22, page: 3, zoom: 1,
+  measured: 22,          // 已解析尺寸的页数
+  cacheBytes: 10_485_760, // 位图缓存占用
+  mountedPages: 5,       // 实际挂载的页面 DOM 数（虚拟化效果）
+  error: null, zoomEnabled: true, scrollEnabled: true,
+}
+```
+
+### 批注
+
+支持**高亮 / 文字批注 / 手写笔迹**三种。数据层与渲染层分离，不修改 PDF 字节。
+
+```tsx
+<PdfH5Reader src={url} annotation onAnnotationsChange={setAnnotations} />
+```
+
+开启 `annotation` 后工具栏出现批注按钮，点开可选三种工具；**单次绘制后自动退出批注模式**，避免想滑动时又画出一条。
+
+受控用法（数据自己管）：
+
+```tsx
+const [annotations, setAnnotations] = useState<Annotation[]>([]);
+
+<PdfH5Reader
+  src={url}
+  annotation
+  annotations={annotations}
+  onAnnotationsChange={setAnnotations}
+/>
+```
+
+命令式 API：
+
+```ts
+ref.current.getAnnotations();
+ref.current.addAnnotation({
+  id: 'a1', kind: 'highlight', pageNumber: 1, createdAt: Date.now(),
+  rects: [{ x: 0.1, y: 0.2, width: 0.4, height: 0.03 }],
+  color: '#ffd400', opacity: 0.4,
+});
+ref.current.removeAnnotation('a1');
+ref.current.clearAnnotations();
+ref.current.setAnnotationMode('ink');  // 'none' | 'highlight' | 'freetext' | 'ink'
+```
+
+**坐标用归一化值（0-1，相对页面宽高），不是像素。** 这样缩放、旋转、切换 fitMode 后批注仍然贴合原文 —— 这是批注功能最容易做错的地方。三种批注的数据结构：
+
+```ts
+// 高亮：支持多段矩形（跨行高亮）
+{ kind: 'highlight', rects: NormRect[], color, opacity, text? }
+
+// 文字批注：锚点 + 文字；fontSize 是相对页面宽度的比例
+{ kind: 'freetext', anchor: NormPoint, text, fontSize, color }
+
+// 手写：归一化点序列；thickness 相对页面宽度
+{ kind: 'ink', points: NormPoint[], thickness, color }
+```
+
+样式可通过 `annotationStyle` 覆盖，或用 CSS 变量 `--pdfh5-anno-hl` / `--pdfh5-anno-ink` 改色。
+
+> 批注默认**不写入 PDF 文件**。改 PDF 需要 pdf-lib 之类依赖，且会破坏原文件的签名与增量更新语义；
+> 需要落盘时用 `getAnnotations()` 导出，自行决定存储方式。
+
+### 可单独复用的模块
+
+不想用内置 UI 时，可以只拿底层能力：
+
+```ts
+import {
+  usePdfDocument, usePageMetrics, useVirtualPages, usePinchGesture,
+  RenderQueue, BitmapCache, TextLayerCache, LruCache,
+  computeLayout, quantizeScale, clampCanvasSize,
+  pinchTransform, pinchCommit, rafThrottle, debounce, rafBatch,
+  searchDocument, flattenOutline, createThumbnailCanvas,
+} from 'pdf-h5-react';
+```
+
+`src/core/{lru,throttle,layout,gestures}.ts` 都是纯函数/纯类，不依赖 React 与 DOM（`clampCanvasSize` 除外），已覆盖单元测试。
+
+---
+
+## 验证
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm test            # 42 个单元测试（LRU / 节流 / 版面数学 / 手势数学 / 渲染队列 / 文本搜索）
+npm run samples     # 生成示例 PDF（含多级书签、混尺寸页、旋转页、加密文档）
+npm run assets      # 拷贝 pdf.js 运行时资源到 public/pdfjs
+npm run build:demo && npm run preview
+npm run verify      # 无头 Chrome 端到端验证 + 截图
+```
+
+`npm run verify` 在真实 Chrome 里跑的 21 项断言（最近一次结果）：
+
+```
+文档加载成功 · 首屏渲染出图 · 虚拟化只挂载少量页面 · 画布实际有内容
+所有可见页均已绘制（无空白页）
+300 页文档只挂载极少数页面 · 滚动后挂载数受控 · 快速滚动后仍无空白可见页
+LRU 回滚命中 > 0 · 位图缓存始终不超过字节上限 · LRU 有实际淘汰行为
+渲染任务有取消而非堆积 · 同一帧滚动风暴合并为一次处理（61 事件 → 1 处理）
+全文档搜索命中 · 放大后内容高度按比例增长 · 翻页模式横向吸附生效
+缩略图面板可用 · 目录面板可用（17 条多级）· 目录标题可读 · 点击目录可跳转
+无未捕获的前端错误
+```
+
+截图在 `screenshots/`（`final-*`），报告在 `screenshots/verify-report.json`。
+
+### 示例文档
+
+| 文件 | 页数 | 说明 |
+| --- | --- | --- |
+| `public/samples/demo-zh.pdf` | 22 | 中文（SimHei 子集嵌入，121KB）；17 条多级书签；第 3 页横向 A4、第 5 页窄页、第 7 页 `/Rotate 90`；内链跳第 10 页、外链到 pdf.js 官网；第 13 页矢量插图 |
+| `public/samples/large.pdf` | 300 | 性能压测（163KB） |
+| `public/samples/encrypted.pdf` | 1 | 加密文档，**打开密码 `test`**（来自 pdf.js 官方测试集 `issue15893_reduced.pdf`） |
+
+`scripts/make-samples.mjs` 自带断言：页数、大纲条目及 `/Dest` 可解析性、文本层可提取、混尺寸与旋转页、文本不越界、**文本层无 `U+0000`**（字体缺字会静默写入该字符，复制出来是乱码）。
+
+---
+
+## 已知边界
+
+- **批注不写入 PDF 文件**。数据存在独立层（`getAnnotations()` 可导出），不修改原文件字节——改 PDF 需要 pdf-lib 等依赖，且会破坏签名与增量更新语义。
+- **链接层只铺透明命中区**，没有渲染完整的 annotation layer（PDF 自带的表单与批注外观不会显示）。需要时可用 `pdfjs-dist` 的 `AnnotationLayer` 自行扩展。
+- **横向页混排时会出现横向滚动**。为保证全篇缩放一致（视觉整齐），不压缩超宽页；阅读器会自动把横向滚动位置居中，避免看起来「右侧被裁」。
+- **canvas 单页上限**。iOS Safari 约 1670 万像素，超限会得到空白画布；`clampCanvasSize` 会自动降分辨率，因此极端放大时是「位图不够清晰」而不是「白屏」。
+- **`fitMode: 'page'` 在连续滚动下按宽度优先**，避免窄页被缩得过小；翻页模式下才严格整页可见。
+- **加密文档**只走 pdf.js 的密码回调，不支持证书/权限密码的细粒度控制。
+- **SSR 场景的 pdf.js 提示**。`pdfjs-dist` 在 Node 环境会在 import 时打印
+  `Please use the legacy build in Node.js environments`。这是 pdf.js 自身的行为，
+  对浏览器产物无影响；在 Next.js 等服务端渲染框架里用 `dynamic(() => import(...), { ssr: false })`
+  或 `'use client'` 即可避免。
+
+## 开发
+
+```bash
+npm i
+npm run assets      # 首次需要：准备 pdf.js 运行时资源
+npm run samples     # 首次需要：生成示例 PDF
+npm run dev         # http://127.0.0.1:5273
+```
+
+技术栈：Vite 7 + React 19 + TypeScript 5.9 + pdfjs-dist 6（peer）。
+库产物为 ESM + 独立 CSS + 完整 `.d.ts`，`react` / `react-dom` / `pdfjs-dist` 均为 external。
+
+## 发布
+
+发布由 [GitHub Actions](.github/workflows/release.yml) 自动完成，推 tag 即触发。
+
+**前置条件**：仓库 `Settings → Secrets and variables → Actions` 里配置 `NPM_TOKEN`
+（npmjs.com 的 Automation token，权限只需 *Read and write*）。
+GitHub 自带的 `GITHUB_TOKEN` 只能发 GitHub Packages，发不了 npmjs，因此必须配这个 Secret。
+
+```bash
+# 1. 改版本号
+npm version 0.4.0 --no-git-tag-version
+git commit -am "chore: release v0.4.0"
+
+# 2. 推送并打 tag（脚本会校验 tag 与 package.json 一致）
+node scripts/publish-gh.mjs --tag 0.4.0
+```
+
+推送 `v*` tag 后 workflow 会依次执行：类型检查 → 单元测试 → 构建库 → 校验 `dist` 产物 → `npm publish`。
+版本校验不通过（tag 与 `package.json` 不一致）会直接失败，避免发错版本。
+
+也可以在 [Actions 页面](https://github.com/superjunjie/pdf-h5-react/actions/workflows/release.yml)
+手动触发 `Run workflow`，并用输入框覆盖版本号。
+
+### 手动发布（本地）
+
+不想等 CI 时可以本地直发，需要先 `npm login`：
+
+```bash
+npm run build && npm publish        # prepublishOnly 会自动跑 typecheck + test + build
+```
+
+## License
+
+MIT
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/dist/components/AnnotationLayer.d.ts

@@ -0,0 +1,26 @@
+import { DEFAULT_ANNOTATION_STYLE, Annotation, AnnotationMode, AnnotationStyle } from '../core/annotations';
+export interface AnnotationLayerProps {
+    pageNumber: number;
+    width: number;
+    height: number;
+    mode: AnnotationMode;
+    style: AnnotationStyle;
+    annotations: readonly Annotation[];
+    /** 交互总开关：翻页动画 / 面板打开时应关闭，避免抢手势 */
+    enabled: boolean;
+    onAdd(annotation: Annotation): void;
+    onSelect?(annotation: Annotation): void;
+    onActiveChange?(active: boolean): void;
+}
+/**
+ * 注释层。
+ *
+ * 三层结构（自下而上）：
+ *  1. 既有注释的渲染层（pointer-events: none，不影响阅读与选词）
+ *  2. 交互层（仅在 mode !== 'none' 时启用 pointer-events: auto）
+ *  3. 自由文本输入浮层（用 textarea，聚焦时阻止阅读器手势）
+ *
+ * 为什么用归一化坐标：见 core/annotations.ts 的说明。缩放 / 旋转后注释仍贴合原文。
+ */
+export declare function AnnotationLayer({ pageNumber, width, height, mode, style, annotations, enabled, onAdd, onSelect, onActiveChange, }: AnnotationLayerProps): import("react").JSX.Element;
+export { DEFAULT_ANNOTATION_STYLE };

package/dist/components/LinkLayer.d.ts

@@ -0,0 +1,17 @@
+import { PDFPageProxy } from 'pdfjs-dist';
+export interface LinkLayerProps {
+    page: PDFPageProxy | null;
+    pageNumber: number;
+    width: number;
+    height: number;
+    displayScale: number;
+    rotation: number;
+    enabled: boolean;
+    onInternalLink?: (dest: string | unknown[] | null) => void;
+    onExternalLink?: (url: string) => void;
+}
+/**
+ * 链接层。只保留可点击区域，不渲染 PDF 的完整 annotation layer
+ * （表单、批注编辑器在 H5 里体积大且意义有限）。
+ */
+export declare function LinkLayer({ page, pageNumber, width, height, displayScale, rotation, enabled, onInternalLink, onExternalLink, }: LinkLayerProps): import("react").JSX.Element | null;

package/dist/components/OutlinePanel.d.ts

@@ -0,0 +1,8 @@
+import { PDFDocumentProxy } from 'pdfjs-dist';
+export interface OutlinePanelProps {
+    doc: PDFDocumentProxy;
+    onNavigate(pageNumber: number): void;
+    onClose(): void;
+}
+/** 目录（书签）面板：扁平化 + 缩进，适合 H5 抽屉 */
+export declare function OutlinePanel({ doc, onNavigate, onClose }: OutlinePanelProps): import("react").JSX.Element;

package/dist/components/PageCanvas.d.ts

@@ -0,0 +1,41 @@
+import { PDFPageProxy } from 'pdfjs-dist';
+import { BitmapCache } from '../core/cache';
+import { RenderQueue } from '../core/renderQueue';
+export interface PageCanvasProps {
+    page: PDFPageProxy | null;
+    pageNumber: number;
+    /** 页面在 CSS 中的显示尺寸 */
+    width: number;
+    height: number;
+    /** 显示尺寸对应的 PDF scale（width / pdfWidth） */
+    displayScale: number;
+    devicePixelRatio: number;
+    rotation: number;
+    bitmapCache: BitmapCache;
+    renderQueue: RenderQueue;
+    /** 可见页高优先级，预取页低优先级 */
+    priority: 'visible' | 'prefetch';
+    /** false 时只显示缓存，不主动渲染（用于远区） */
+    shouldRender: boolean;
+    maxCanvasPixels?: number;
+    maxCanvasDimension?: number;
+    onRendered?: (pageNumber: number) => void;
+}
+/**
+ * 单页画布。
+ *
+ * 性能与正确性要点：
+ *
+ * 1. **显示 canvas 必须每页独占**：缓存里的是可共享的离屏位图，但 DOM 节点只有一个父节点，
+ *    若直接把缓存 canvas 挂进页面，后挂载的页会把前面页的 canvas 抢走（表现为空白）。
+ *    所以渲染结果用 drawImage 拷贝到本组件自己的 canvas。
+ *
+ * 2. **创建与绘制必须在同一个 effect**：拆成两个 effect 时，绘制可能先于创建执行，
+ *    拿到的 canvas 是 null，首屏会一直空白。
+ *
+ * 3. **量化渲染档位**：捏合过程中不重渲染，只有档位跃迁才触发，缩放来回能持续命中 LRU。
+ *
+ * 4. **取消后必须重试**：渲染任务可能因为「尺寸变化 / 离开视口 / 队列抢占」被取消。
+ *    若此时页面仍在屏上，不重试就会留下永久空白 —— 这是最容易漏掉的一类 bug。
+ */
+export declare function PageCanvas({ page, pageNumber, width, height, displayScale, devicePixelRatio, rotation, bitmapCache, renderQueue, priority, shouldRender, maxCanvasPixels, maxCanvasDimension, onRendered, }: PageCanvasProps): import("react").JSX.Element;

package/dist/components/PageThumbnail.d.ts

@@ -0,0 +1,23 @@
+import { PDFDocumentProxy } from 'pdfjs-dist';
+import { ThumbnailCache } from '../core/cache';
+import { RenderQueue } from '../core/renderQueue';
+export interface PageThumbnailProps {
+    doc: PDFDocumentProxy;
+    pageNumber: number;
+    width: number;
+    cache: ThumbnailCache;
+    queue: RenderQueue;
+    /** 进入视口才渲染 */
+    active: boolean;
+    rotation: number;
+    onSelect(pageNumber: number): void;
+    current: boolean;
+}
+/**
+ * 单张缩略图。
+ *
+ * 缩略图数量可能上百，两个限制：
+ * 1. 只有 active（进入视口附近）才提交渲染；
+ * 2. 结果按页缓存成 dataURL（体积小），再次打开面板直接复用。
+ */
+export declare function PageThumbnail({ doc, pageNumber, width, cache, queue, active, rotation, onSelect, current, }: PageThumbnailProps): import("react").JSX.Element;

package/dist/components/PdfH5Reader.d.ts

@@ -0,0 +1,101 @@
+import { PDFDocumentProxy } from 'pdfjs-dist';
+import { ZoomEventPayload } from '../core/readerEvents';
+import { Annotation, AnnotationStyle } from '../core/annotations';
+import { PdfH5ReaderHandle, PdfSource, ThemeMode, ViewerMode, FitMode } from '../types';
+export interface PdfH5ReaderProps {
+    /** PDF 来源：URL / 二进制 / 参数对象 */
+    src: PdfSource | null | undefined;
+    /** 连续滚动 / 单页翻页 */
+    mode?: ViewerMode;
+    /** 适配方式，默认 width */
+    fitMode?: FitMode;
+    initialPage?: number;
+    /** 初始缩放倍率（相对适配尺寸），默认 1 */
+    initialZoom?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    /** 双击 / 双指点击的放大目标倍率，默认 2.5 */
+    doubleTapZoom?: number;
+    /** 缩放动画时长（ms），默认 300；设为 0 立即跳变 */
+    animationDuration?: number;
+    /** 是否允许缩放手势，默认 true */
+    zoomEnable?: boolean;
+    /** 是否允许滚动，默认 true */
+    scrollEnable?: boolean;
+    rotation?: number;
+    theme?: ThemeMode;
+    gap?: number;
+    padding?: number;
+    /** 文本层（可选中 / 可复制），默认开启 */
+    textLayer?: boolean;
+    /** 链接层，默认开启 */
+    links?: boolean;
+    /** 是否显示内置工具栏，默认 true */
+    toolbar?: boolean;
+    /** 是否显示页码 / 缩放浮层，默认 true */
+    showControls?: boolean;
+    /** 是否显示「回到顶部」悬浮按钮，默认 true */
+    backTop?: boolean;
+    /** 是否显示顶部加载进度条，默认 true */
+    loadingBar?: boolean;
+    /** 是否启用注释功能（工具栏出现批注按钮），默认 false */
+    annotation?: boolean;
+    /** 受控注释列表；不传则由组件内部维护 */
+    annotations?: Annotation[];
+    /** 注释样式覆盖 */
+    annotationStyle?: Partial<AnnotationStyle>;
+    /** 注释变化回调（新增 / 删除 / 清空） */
+    onAnnotationsChange?: (annotations: Annotation[]) => void;
+    /** 位图缓存上限（字节），默认 96MB */
+    bitmapCacheBytes?: number;
+    /** 文本层缓存条目上限，默认 24 */
+    textLayerCacheEntries?: number;
+    maxCanvasPixels?: number;
+    maxCanvasDimension?: number;
+    className?: string;
+    style?: React.CSSProperties;
+    onDocumentLoad?: (doc: PDFDocumentProxy) => void;
+    onPageChange?: (page: number, total: number) => void;
+    onProgress?: (loaded: number, total: number) => void;
+    onError?: (error: Error) => void;
+    onZoomChange?: (zoom: number) => void;
+    onInternalLink?: (dest: string | unknown[] | null) => void;
+    onExternalLink?: (url: string) => void;
+    /** 自定义空状态 / 加载失败渲染 */
+    renderError?: (error: Error, retry: () => void) => React.ReactNode;
+    /** 文档就绪，可拿到总页数 */
+    onReady?: (payload: {
+        doc: PDFDocumentProxy;
+        total: number;
+    }) => void;
+    /** 某一页渲染完成 */
+    onRender?: (payload: {
+        pageNumber: number;
+        pageTime: number;
+        totalTime: number;
+    }) => void;
+    /** 滚动（已节流） */
+    onScroll?: (payload: {
+        scrollTop: number;
+        scrollLeft: number;
+        currentPage: number;
+        progress: number;
+    }) => void;
+    /** 缩放结束 */
+    onZoomEnd?: (payload: ZoomEventPayload) => void;
+    /** 加载流程结束（成功或失败都会触发） */
+    onComplete?: (payload: {
+        status: 'success' | 'error';
+        message: string;
+        time: number;
+    }) => void;
+}
+/**
+ * 移动端优先的 PDF 阅读器。
+ *
+ * 三层性能结构：
+ *  文档层  usePdfDocument   —— 加载 / 密码 / 进度（进度事件节流）
+ *  度量层  usePageMetrics   —— 首屏 N 页真实尺寸 + 其余页渐进解析（rAF 批量校正）
+ *  视图层  useVirtualPages  —— 只挂载可视区内的页面 DOM，位图走 LRU，渲染走双并发队列
+ */
+export declare const PdfH5Reader: import('react').ForwardRefExoticComponent<PdfH5ReaderProps & import('react').RefAttributes<PdfH5ReaderHandle>>;