@web-ppt/viewer-core 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,7 +2,26 @@
 
 本文件记录对使用者可见的变化。版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
-## 未发布
+## 0.6.0 - 2026-11-02
+
+0.6.0 稳定版：`0.6.0-beta.1` 的全部内容转正到 `latest`，包括 Agent 结构化读出、布局检查与 Node 无 Office 渲染，矢量 PDF 正式入口，视频音轨与内嵌视频合成，以及 OLE DOCX / XLSX 深度编辑官网入口。相对 0.5.0 的逐项变化见下方 `0.6.0-beta.1` 条目。
+
+安装：无版本号安装即得 0.6.0，八包必须同版本；`@next` 标签留给 0.7 线。
+
+`@web-ppt/collab` 发布入口为 12.20KB gzip；排除 peer 的完整测试薄包为 14,333B gzip。
+
+Windows PowerPoint 真机验收经维护者决定延后，未记为通过；0.6.0 先行转正，四项自动门禁与 LibreOffice 外部打开清单全部通过。
+
+## 0.6.0-beta.1 - 2026-10-31
+
+0.6.0 第一批与第二批全部七张票据收口：Agent Node 渲染、矢量 PDF 转正、视频音轨证据、内嵌视频合成、OLE 深度编辑官网入口。
+
+- 新增 `@web-ppt/core/node` 按需入口（Agent 无 Office 渲染）：`renderSlideSvgInNode` / `renderSlidePngInNode` 在纯 Node 环境渲染 `.pptx` / `.ppt` 为原生 `<text>` SVG 或宿主光栅化 PNG；测字与光栅化全部注入（推荐 `@web-ppt/fonts/glyphs` 的 `withFontMeasurement`），缺注入抛稳定 reason（`node-measure-required` / `node-rasterizer-required`）不退回估算断行；跨进程确定性按资源字节寻址口径验证，与浏览器原生路径 148/152 页整页 SVG 指纹逐字节一致（差异页归因：公式测量源 / 艺术字字距放大）。
+- 矢量 PDF 转为正式入口（去除实验性标记）：验收对照扩展到 MuPDF / poppler / CoreGraphics / PDFium 四个独立实现；文字提取（含中文与组合字符）对第三方文本引擎有效，文字渐变（Pattern colorspace）在 PDFium 下方向断言通过。透明文字渐变与渐变变换方言经裁决无输入语义来源（渲染层不产出该形态），覆盖检查器按稳定原因显式拒绝。
+- 内嵌视频合成（`videoOverlay`，仍默认关闭）升级：组链经 `placeGroupChild` 折算、元素 rotate / flip / 裁剪 / 透明度 / CSS filter 与媒体间层叠在画布按 SVG 渲染一致重建；`playback.loop` 循环取模；跨页策略为元素随所属页呈现。可变帧率按时间戳取帧、60s 长视频内存有界（<60MB）、`video-overlay-frame-unavailable` 稳定复现样本（MSE 缺口媒体）均通过独立验收。
+- 视频音轨（`audio`，已随 0.5.0-beta.6 发布）补齐验收证据：FFmpeg 独立测量的脉冲与画面标记同轴（偏差 ≤130ms 声明边界）、`AbortSignal` 取消与资源释放、循环音频跨页持续。
+- OLE 嵌入文档官网面板补齐：嵌入 DOCX 的 run 级改字（保留相邻 run 格式）、嵌入 XLSX 的单元格样式（字体 / 填充 / 边框）与 sharedStrings 富文本入口，中英文文案与撤销语义齐全；`readEmbeddedPackage` 自 `@web-ppt/edit-core/ole` 公开导出供宿主提取嵌入文档；改写后的 DOCX / XLSX 经 LibreOffice 打开与重写往返验证（文字、颜色与 run 边界保留）。
+- `@web-ppt/collab` 发布入口为 12.20KB gzip；排除 peer 的完整测试薄包为 14,333B gzip，两种口径分别核对。
 
 ## 0.5.0 - 2026-10-29
 

package/dist/video/media-overlay.d.ts

@@ -2,26 +2,32 @@ import type { Presentation, Slide } from '@web-ppt/core';
 import type { VideoOptions } from './timing';
 type OverlayWarning = NonNullable<VideoOptions['onWarning']>;
 /**
- * 内嵌视频合成层：把 `<video>` 当前帧叠加到导出画布的媒体元素位置。
+ * 内嵌视频合成层：把 `<video>` 当前帧按元素的全部视觉属性叠加到导出画布。
  *
- * 用 seek + drawImage 而非 WebCodecs 逐帧解码：导出本就是逐帧离线流程，
- * seek 的异步等待不破坏确定性（同一媒体字节 + 同一时间戳 → 同一帧），
- * 且浏览器 `<video>` 已覆盖全部容器 / 编码组合，免去手写 MP4 demux。
+ * 取帧用 seek + drawImage 而非手写解封装：浏览器 `<video>` 覆盖全部容器 / 编码组合，
+ * seek 内部即关键帧定位 + 解码到目标时刻（有界——每个媒体只保留一个按需 seek 的实例，
+ * 不按页面长度预解码）；导出是逐帧离线流程，同一媒体字节 + 同一时间戳得到同一帧。
  *
- * 合成失败不阻断导出（调用方已经以 `mediaPosters` 显式接受海报呈现），
- * 但每次退回海报都经 `onWarning` 以稳定 reason 暴露：
+ * 元素保真与 SVG 渲染逐层对齐：组链先经 `placeGroupChild` 把位置尺寸折算到页面坐标
+ * （clipPath 也随之缩放），组的 rotate / flip 与元素自身的 rotate / flip / crop / alpha /
+ * clipPath / CSS filter 在画布上按同一变换顺序重建。媒体之间的绘制顺序沿元素顺序（z 序）。
+ *
+ * 语义：`playback.loop` 循环取模；媒体元素随其所属页呈现，翻页后不再显示（音频不受此限，
+ * 由混音链路的全局时间轴处理）——PowerPoint 的元素归属语义。合成失败不阻断导出（调用方
+ * 已经以 `mediaPosters` 显式接受海报呈现），但每次退回海报都经 `onWarning` 暴露稳定 reason：
  * - `video-overlay-unavailable`：加载失败、5s 内未取得首帧或时长无效，该视频全程保留海报帧
  * - `video-overlay-frame-unavailable`：seek 超时或帧数据不可用，受影响的帧可能是海报或非目标时刻的画面
  */
 export declare class MediaOverlay {
     private readonly warn;
+    /** 全局媒体表：元素属于某页，但时间轴是全稿毫秒轴（跨页媒体由起始页登记） */
     private videos;
     private disposed;
     constructor(warn: OverlayWarning | undefined);
     /** 预加载页面的视频媒体（每页一个列表；须在导出循环前调用） */
     load(pres: Presentation, slide: Slide, slideNumber: number, groupStarts: number[]): Promise<void>;
     /**
-     * 把当前时间轴的视频帧画到画布。在 SVG 光栅化之后调用，叠加在海报帧之上。
+     * 把当前时间轴的视频帧画到画布。在 SVG 光栅化之后调用，叠加在海报帧之上；
      * scaleX/scaleY 把幻灯片坐标换算到导出画布坐标。
      */
     draw(context: CanvasRenderingContext2D, slideNumber: number, timelineMs: number, scaleX: number, scaleY: number): Promise<void>;