feat: 实现 Chromium PDF 导出与精确预览

docs/PROGRESS.md

@@ -19,6 +19,8 @@ main
 已有提交：
 
 ```text
+d625523 fix: 修复长文档分页与滚动同步
+1d93f31 feat: 实现真实分页预览
 52cf816 feat: 完善导出设置与打印预览
 ec14f79 feat: 扩展本地主题兼容能力
 fa07472 feat: 实现网页实时预览
@@ -26,7 +28,7 @@ fa07472 feat: 实现网页实时预览
 ec48bce chore: 初始化项目骨架
 ```
 
-当前工作区存在未提交修改，主要是基于 Paged.js 的真实分页预览、页眉页码、跨页表格和超高 Mermaid 图表适配。接手时必须保留并审查这些修改，不要重置工作区。
+最新阶段已完成 Chromium PDF 导出、精确预览、PDF.js 渲染缓冲和 Mermaid 分页性能优化。
 
 ## 2. 已完成
 
@@ -136,38 +138,44 @@ ec48bce chore: 初始化项目骨架
 - Markdown 表格对齐属性保留和自适应列宽；
 - 纸张尺寸和页边距实时预览。
 
-## 3. 当前未提交工作
+## 3. Chromium PDF 导出与精确预览
 
-以下内容已写入工作区，但尚未提交：
+### 3.1 Chromium PDF 导出
 
-### 3.1 Paged.js 真实分页预览
+- 引入固定版本 Playwright Chromium。
+- 新增 `POST /api/pdf`，复用服务端 Markdown 渲染结果、`#write` DOM、主题 CSS、打印 CSS 和统一分页运行时。
+- PDF 文本可搜索，支持中文、长表格、KaTeX、Mermaid、页眉、页脚和页码。
+- Chromium 浏览器实例复用，每个请求使用独立 BrowserContext。
+- 支持浏览器预热、并发门控、排队上限、超时和关闭清理。
+- 仅允许同源、`data:`、`blob:` 和 `about:` 资源，阻止 PDF 页面访问外部网络。
+- PDF 响应提供安全的 UTF-8 文件名、页数、Mermaid 错误数和 `Server-Timing`。
+- 前端“导出 PDF”按钮已启用，生成完成后直接下载。
 
-- 引入 MIT 许可证的 Paged.js 0.4.3。
-- 使用独立同源沙箱 iframe 执行分页，父页面通过严格消息协议传递渲染载荷。
-- 每张纸以真实物理尺寸独立显示，页面间保留 24px 间隔和预览阴影。
-- 主题 CSS 原样交给 Paged.js，使主题 `@media print` 规则与未来 PDF 一致。
-- GitHub 主题打印字号已与 Typora PDF 对齐：正文 13px、一级标题 29.25px、二级标题 22.75px。
-- W30 对照文档在 Typora 和网页预览中均为 4 页。
-- 主题切换会重置 iframe 就绪握手，GitHub、Pixyll 和 Whitey 可连续切换且无需刷新。
+### 3.2 快速预览与精确预览
 
-### 3.2 页眉、页码与跨页内容
+- 快速预览继续使用 Paged.js，适合编辑时即时反馈。
+- 精确预览直接复用 `/api/pdf` 结果，确保显示页数和最终下载一致。
+- 快速与精确模式可以切换，PDF 缓存按 Markdown、主题和导出配置失效。
+- PDF.js 使用集中渲染队列，当前可见页优先，滚动方向上的相邻页次优先。
+- 远离视口的 Canvas 延迟释放，避免 65 页长文档持续占用大尺寸位图内存。
+- 未完成渲染的页面显示白色占位，Canvas 完成后才显示，消除快速滚动时的黑影。
+- 编辑区和两种预览模式支持按滚动比例同步定位。
 
-- 页眉支持左中右三栏、标题、作者和文件名变量及分隔线。
-- 页脚支持五种页码格式、左中右位置、起始页码和分隔线。
-- 当前页码逐页递增，总页数使用真实分页结果。
-- 标题避免孤立在页尾，段落使用孤行和寡行约束。
-- 长表格允许跨页，并通过 Paged.js 处理器重复表头。
-- 表格行、代码块、引用、公式、图片和 Mermaid 默认避免从中间断开。
+### 3.3 Mermaid 分页性能优化
 
-### 3.3 Mermaid 单页适配
+- Mermaid 仍使用官方渲染器、配置 frontmatter、严格安全模式、默认主题和 classic 样式。
+- 渲染完成后记录 SVG 与容器的实际小数宽高，将 SVG 转为内嵌 Data URL 图片再交给 Paged.js 分页。
+- 静态 SVG 仍由 Chromium 以矢量和可搜索文字输出，不发生位图化。
+- 快速预览和 PDF 默认使用相同的静态 SVG；`mermaid-output=inline-svg` 仅保留为内部诊断开关。
+- 65 页、67 个 Mermaid 的附件中，分页耗时约从 2.60 秒降至 1.29 秒，总生成耗时约降低 12.7%。
+- A/B PDF 均为 65 页，逐页 61,102 个非空白字符和 11,762 个文本项完全一致。
 
-- Mermaid、字体和图片完成后再启动分页。
-- 普通 Mermaid 保持主题原有尺寸和布局。
-- 根据纸张和页边距计算正文区域的 CSS 像素宽高。
-- 当 SVG 按正文宽度适配后仍高于一页时，读取 `viewBox` 并改为按正文高度等比例缩小。
-- 超高 Mermaid 整体换页、水平居中，不跨页裁切。
-- 浏览器实测 A4 超高图高度约 1000.56px，正文可用高度约 1001.57px，未侵入上下页边距。
-- 增加 SVG `viewBox` 解析、正文尺寸和缩放算法测试。
+### 3.4 PDF 性能观测
+
+- 记录排队、浏览器、上下文、导航、文档渲染、Mermaid、资源等待、分页、PDF 打印和总耗时。
+- `Server-Timing` 已暴露上述关键阶段，包括 `mermaid-conversion`。
+- 65 页附件的主要耗时来自 Mermaid 渲染、Paged.js 分页和 Chromium PDF 打印。
+- PDF 缓冲区直接返回，避免无意义的二次 `Buffer` 复制。
 
 ## 4. 已执行验证
 
@@ -184,27 +192,20 @@ git diff --check
 
 - 共享配置测试：6 项通过；
 - 渲染器测试：7 项通过；
-- 前端测试：21 项通过；
-- 后端测试：6 项通过；
+- 前端测试：47 项通过；
+- 后端测试：17 项通过；
 - 全项目类型检查通过；
 - 生产构建通过；
-- `git diff --check` 通过，仅出现工作区 LF 将来可能转为 CRLF 的提示；
-- 导入器默认的已存在目标保护通过；
-- GitHub、Pixyll 和 Whitey 三套本地主题的 CSS API 均返回成功，组合结果无残留 `@import`。
-- 同一份 W30 Markdown 在 GitHub 分页预览和 Typora PDF 中均为 4 页。
-- 三个本地主题无需刷新即可连续切换并重新分页。
-- 超高 Mermaid 整体缩放到单页正文区域，普通 Mermaid 尺寸不受影响。
+- `git diff --check` 通过。
 
 已使用浏览器插件完成视觉验证：
 
-- 导出设置抽屉桌面布局正常；
-- 尺寸选择器只包含五种目标纸张；
-- 默认 A4 纵向及 16mm 四边距正确；
-- A5 横向和 12.5mm 上边距实时反映到纸张；
-- GitHub 主题的 `#write` 宽度、最大宽度、内外边距已由共享几何层接管；
-- 刷新页面后纸张、方向、页边距、页眉和页码配置可以恢复；
-- 恢复默认功能正常；
-- 浏览器控制台无警告或错误。
+- 65 页附件的快速预览生成 64 页，67 个 Mermaid 全部使用静态 SVG；
+- 同一附件的精确预览和最终 PDF 均为 65 页；
+- 精确预览快速跳转至第 46、47、65 页，无黑色 Canvas、空白页或渲染错误；
+- PDF.js 同时只保留视口邻近页面的 Canvas，远端页面资源可以释放；
+- Mermaid A/B PDF 页数、逐页文字和抽样视觉结果一致；
+- 抽查第 2、6、27、53、65 页，Mermaid 尺寸、分页位置和末页内容正常。
 
 此前主题阶段已使用浏览器插件完成视觉验证：
 
@@ -221,12 +222,16 @@ git diff --check
 
 ## 5. 当前注意事项
 
-- 工作区不是干净状态，禁止重置。
+- `output/` 可能包含本地 PDF 验证产物，不得提交。
 - `apps/web/src/App.tsx` 负责分页 iframe 生命周期和父页面消息处理。
-- `apps/web/src/paged-preview-frame.ts` 负责 iframe 内 Mermaid、资源等待和 Paged.js 分页。
+- `apps/web/src/paged-document-runtime.ts` 是快速预览和 PDF 共用的 Mermaid、资源等待和 Paged.js 分页运行时。
+- `apps/web/src/paged-preview-frame.ts` 负责 iframe 消息协议和运行目标选择。
 - `apps/web/src/paged-preview.ts` 负责分页协议、共享文档 CSS、页眉和页码 CSS。
 - `apps/web/src/mermaid-page-fit.ts` 负责超高 Mermaid 的单页等比例适配。
+- `apps/web/src/mermaid-static-image.ts` 负责锁定 Mermaid 盒模型并转换为静态矢量 SVG 图片。
 - `apps/web/src/paged-table-handler.ts` 负责跨页表格表头处理。
+- `apps/web/src/PrecisePdfPreview.tsx` 和 `pdf-render-queue.ts` 负责 PDF.js 精确预览和 Canvas 生命周期。
+- `apps/server/src/pdf-engine.ts` 负责 Chromium 生命周期、并发、网络限制、分页调用和 PDF 输出。
 - `apps/web/src/ExportSettingsDrawer.tsx` 是导出设置界面。
 - `apps/web/src/export-settings.ts` 负责版本化浏览器缓存。
 - `packages/core/src/export-config.ts` 是纸张、页边距、页眉页脚和页码的共享模型。
@@ -235,46 +240,27 @@ git diff --check
 - `.local/themes/typora-*` 是用户本机副本，已被 Git 忽略，不得提交。
 - `.local/theme-backups` 中保留 GitHub、Pixyll 和 Whitey 的可恢复备份；Newsprint 和 Night 的当前副本及备份已按用户要求删除。
 - Typora 官方资源是 All Rights Reserved，仅限当前用户本机使用，不进入 Git、容器或发布包。
-- Mermaid 已按需加载，但生产构建仍提示 `mermaid.core` 和 `cynefin` 两个分块超过 500 kB；这不影响功能，可后续优化。
-- PDF 生成尚未实现。
 - 资源目录上传、本地相对图片、临时目录和路径安全尚未实现。
 - Dockerfile 和 Compose 尚未实现。
 
 ## 6. 推荐接手顺序
 
-### 阶段一：提交分页预览
+### 阶段一：资源与安全
 
-当前分页预览已经实现并通过验证。检查完整差异并创建一个清晰的阶段提交后，再进入真实 PDF。
+- Markdown 文件夹或 ZIP；
+- 相对图片解析；
+- 每请求独立临时目录；
+- 路径穿越和符号链接越界防护；
+- 文件数量、单文件大小、总大小和超时限制；
+- 请求结束可靠清理。
 
-### 阶段二：实现真实 PDF
-
-分页预览提交后再实现：
-
-1. 增加 Playwright 和固定版本 Chromium。
-2. 抽取可复用的完整 HTML 文档组装器。
-3. 预览和 PDF 共用文章 HTML、主题 CSS、打印 CSS及资源。
-4. 等待字体、图片、KaTeX 和 Mermaid 完成。
-5. 实现 `POST /api/pdf`，响应 `application/pdf`。
-6. 前端启用“导出 PDF”按钮并下载文件。
-7. 增加 PDF 接口与端到端测试。
-
-### 阶段三：导出配置扩展
+### 阶段二：导出配置扩展
 
 - Front Matter 元数据覆盖；
 - 浏览器本地配置预设；
 - 配置 JSON 导入和导出。
 
-### 阶段四：资源与安全
-
-- Markdown 文件夹或 ZIP；
-- 相对图片解析；
-- 每请求独立临时目录；
-- 路径穿越防护；
-- 文件数量、大小和超时限制；
-- Chromium 并发和网络访问限制；
-- 请求结束可靠清理。
-
-### 阶段五：容器化与交付
+### 阶段三：容器化与交付
 
 - Dockerfile；
 - Docker Compose；