refactor(vtt-thumbnail): [PKG-VTT-THUMB-03] validate cues and separate pure lookup

2026-10-10 21:06:15 -08:00 · 2026-09-13 08:50:33 +08:00
1 parent 524ddf784f
commit 80588a3046
@@ -0,0 +1,38 @@
+# PKG-VTT-THUMB-03 解析与模块整理完成
+
+在 524ddf78 的请求/资源检查点基础上，完成纯解析与区间查找边界。
+parseVtt 导出纯 findThumbnail，preview 只负责消费 cue、定位和计时器。
+注册、请求、生命周期、解析、视图及旧源码 helper 的职责详见包内 ARCHITECTURE.md。
+
+## 格式支持和修复
+
+新解析器识别 BOM/CRLF、header 注释、cue ID、NOTE 注释、STYLE/REGION 块与 timing settings。
+这些块不用于修改播放器样式。三位及更长小时数不再被截断。无效头、时间戳、逆向区间、
+缺失图片、重复/未知 xywh 键、非有限/负数坐标、零尺寸等给出带原始行号的 TypeError，
+在安装 UI 之前整体拒绝。坐标前后空白现在规范为可用 CSS 数字。
+
+格式结构参考 [W3C WebVTT](https://www.w3.org/TR/webvtt1/)（2026-09-13 核对），
+采用自有实现，没有引入第三方解析器或复制其实现。这里仅解析 thumbnail metadata，
+不是完整字幕解析/渲染器；不处理多行字幕 payload、timestamp-map 偏移或全部字幕设置。
+
+## 兼容边界
+
+保留 floor 时间边界、首个包含端点的命中、原始输入顺序、重叠/未排序 cue、正常小数矩形、
+四键排列与字面 URL 拼接。还保留历史紧凑箭头、纯秒时间、分钟/秒字段的进位算术、
+零时长 cue、紧密 cue 对及 time/payload 间空行；不因标准校验重新收紧已可用的旧输入。
+空文件/仅头/仅注释均为空预览。真实 demo 120 个 cue 与旧 parser 深度比较完全相同。
+坏格式曾生成错误 CSS 或无法定位的异常，不视为要求继续保持的有效 API。
+
+## 验证
+
+26 项解析测试在固定旧 parser/运行产物上 5 通过、21 失败；新源码通过。
+坏输入还通过候选工厂验证 Promise 拒绝及监听器/控件清理；扩展 cue 验证重叠首个命中。
+浏览器用真实 HTTP 文本、sprite、旧/新核心验证扩展 VTT 悬停与坏格式拒绝后的重试恢复，
+继续运行原生请求取消和 destroy(false) 清理。各入口和最终 CI 以
+[验证记录](../baselines/vtt-thumbnail-parser.json)为准，不把纯 parser 测试称为安装包证据。
+
+本任务完成的是 03 的内部结构和已复现输入/生命周期修复。04 继续严格 TS、公开类型和
+旧消费形式；05/06 继续旧核心范围、移动/全屏/chapter 组合、安装/demo/编辑器。
+类型/导出/完整生命周期风险继续由后续任务承接，不能据此声称包已可发布。
+无新依赖或版本变化；正常构建生成 main/legacy/ESM 及 docs 副本。本任务独立提交，
+回退只恢复解析检查点，前次资源修复仍可保留；不推送或发布。
@@ -4,7 +4,7 @@

 基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 222 项，范围 22 个包及工作区/示例。

-状态：todo 93 / doing 13 / blocked 0 / done 116 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 93 / doing 12 / blocked 0 / done 117 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。

@@ -184,7 +184,7 @@
 | --- | --- | --- | --- | --- | --- | --- |
 | PKG-VTT-THUMB-01 | artplayer-plugin-vtt-thumbnail<br>核对包契约与历史用法 | BASE-05 | vtt/style、异步返回、预览控件名与样式契约 | 源码/声明/README/demo/发布包差异已登记；公开形状和版本范围冻结 | M | done |
 | PKG-VTT-THUMB-02 | artplayer-plugin-vtt-thumbnail<br>建立特有行为与错误测试 | PKG-VTT-THUMB-01, ENG-03, ENG-05 | VTT 解析、xywh、相对 URL、时间边界、请求失败和定位 | 旧版本行为可重跑，成功/失败/切源/销毁有必要断言 | M | done |
-| PKG-VTT-THUMB-03 | artplayer-plugin-vtt-thumbnail<br>整理内部职责与资源 | PKG-VTT-THUMB-02, CORE-09, CORE-19 | 纯解析/区间查找与 DOM、请求/定时器生命周期分离 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | M | doing |
+| PKG-VTT-THUMB-03 | artplayer-plugin-vtt-thumbnail<br>整理内部职责与资源 | PKG-VTT-THUMB-02, CORE-09, CORE-19 | 纯解析/区间查找与 DOM、请求/定时器生命周期分离 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | M | done |
 | PKG-VTT-THUMB-04 | artplayer-plugin-vtt-thumbnail<br>迁移自有源码和公开类型 | PKG-VTT-THUMB-03, ENG-04, ENG-06, CORE-07 | cue/rect/result 和参数可选性保持兼容 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | M | todo |
 | PKG-VTT-THUMB-05 | artplayer-plugin-vtt-thumbnail<br>验证新旧核心和组合 | PKG-VTT-THUMB-04, CORE-22 | 鼠标和移动进度、全屏、切源、chapter 组合 | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | M | todo |
 | PKG-VTT-THUMB-06 | artplayer-plugin-vtt-thumbnail<br>验证分发并同步文档 | PKG-VTT-THUMB-05, ENG-07 | vtt.thumbnail.js、VTT/图片资源解析和产物验证 | tarball 入口/资源、类型、8082 demo 和 README 一致，有回退记录 | M | todo |
@@ -499,7 +499,7 @@
 - PKG-AUTO-THUMB-03: [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-lifecycle-checkpoint.md) [记录](baselines/auto-thumbnail-lifecycle-checkpoint.json) [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-hidden-renderer.md) [记录](baselines/auto-thumbnail-hidden-renderer.json) [记录](baselines/auto-thumbnail-timeline-media.json) [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-frame-presentation.md) [记录](baselines/auto-thumbnail-frame-presentation.json)
 - PKG-VTT-THUMB-01: [记录](baselines/vtt-thumbnail-release.json) [记录](baselines/vtt-thumbnail-contract.md) [记录](changes/2026-09-13-PKG-VTT-THUMB-01-contract.md)
 - PKG-VTT-THUMB-02: [记录](baselines/vtt-thumbnail-failures.json) [记录](changes/2026-09-13-PKG-VTT-THUMB-02-failures.md)
- PKG-VTT-THUMB-03: [记录](changes/2026-09-13-PKG-VTT-THUMB-03-resources.md) [记录](baselines/vtt-thumbnail-resources.json)
+- PKG-VTT-THUMB-03: [记录](changes/2026-09-13-PKG-VTT-THUMB-03-resources.md) [记录](baselines/vtt-thumbnail-resources.json) [记录](changes/2026-09-13-PKG-VTT-THUMB-03-parser.md) [记录](baselines/vtt-thumbnail-parser.json)
 - PKG-HLS-01: [记录](baselines/hls-control-contract.md) [记录](baselines/hls-control-release.json) [记录](changes/2026-09-11-PKG-HLS-01-contract.md)
 - PKG-HLS-02: [记录](hls-validation.md) [记录](baselines/hls-sdk.json) [记录](baselines/hls-validation.json) [记录](changes/2026-09-11-PKG-HLS-02-tests.md)
 - PKG-HLS-03: [记录](changes/2026-09-12-PKG-HLS-03-modules.md) [记录](baselines/hls-modules-validation.json) [记录](hls-validation.md)
@@ -1,5 +1,16 @@
 # 进度与证据

+## PKG-VTT-THUMB-03 内部模块与解析修复完成
+
+在资源检查点上完成纯解析/首个区间查找，支持 cue ID、注释/元数据块和 timing settings，
+修复长小时截断及非法输入无定位/坏 CSS。26 项解析在旧版 5 通过/21 失败；正常 demo 120 cue
+完全相同。源码/main/legacy 的解析+生命周期各 47 通过，原生三入口各 18 通过，共 54 项。
+实际 ESM 与完整 CI 2064 项（1727 单元、14 工程、323 基线）通过；无依赖/声明/版本变更。
+见[变更](changes/2026-09-13-PKG-VTT-THUMB-03-parser.md)与[验证](baselines/vtt-thumbnail-parser.json)。
+解析风险已关闭，类型/导出/完整设备和组合仍待 04–06。下一步严格 TS 及旧消费者。
+222 项：117 done、12 doing、93 todo；独立本地任务提交，不推送、不发布。
+
+
 ## PKG-VTT-THUMB-03 请求与预览资源检查点（doing）

 生产入口拆为注册、生命周期、请求、预览和纯解析，保留旧源码 helper。已修复销毁后
@@ -190,7 +190,7 @@
 | AUTO-THUMB-ENCODE-01 | open / 已复现 | Unserialized encodes include blank output and lack media/canvas/input failure handling | PKG-AUTO-THUMB-02, PKG-AUTO-THUMB-03, PKG-AUTO-THUMB-05 |
 | AUTO-THUMB-PIXEL-01 | open / 已复现 | Historical auto-thumbnail yields black sampled JPEG cells on Windows WebKit while played native video and static JPEG controls yield color | PKG-AUTO-THUMB-03, PKG-AUTO-THUMB-05 |
 | VTT-THUMB-DIST-01 | open / 已复现 | Historical 1.0.0 main/legacy contain invalid regular expressions and cannot load | PKG-VTT-THUMB-06 |
-| VTT-THUMB-PARSE-01 | open / 已复现 | Historical compiled arrows differ from shipped source; parsing floors bounds and assumes alternating lines | PKG-VTT-THUMB-02, PKG-VTT-THUMB-03 |
+| VTT-THUMB-PARSE-01 | resolved / 已复现 | Historical compiled arrows differ from shipped source; parsing floors bounds and assumes alternating lines | PKG-VTT-THUMB-02, PKG-VTT-THUMB-03 |
 | VTT-THUMB-LIFE-01 | open / 已复现 | Fetch completion, setBar listeners and mobile timers have no destroy ownership | PKG-VTT-THUMB-02, PKG-VTT-THUMB-03, PKG-VTT-THUMB-05 |
 | VTT-THUMB-TYPE-01 | open / 已复现 | Published declarations falsely describe async registration as a synchronous result | PKG-VTT-THUMB-04 |
 | VTT-THUMB-EXPORT-01 | open / 已复现 | Older CommonJS default objects and thumbnails control names differ from latest direct export and vtt-thumbnail name | PKG-VTT-THUMB-04, PKG-VTT-THUMB-05, PKG-VTT-THUMB-06 |
@@ -4141,7 +4141,7 @@
      "id": "VTT-THUMB-PARSE-01",
      "title": "Historical compiled arrows differ from shipped source; parsing floors bounds and assumes alternating lines",
      "confirmation": "reproduced",
-      "status": "open",
+      "status": "resolved",
      "owners": [
        "PKG-VTT-THUMB-02",
        "PKG-VTT-THUMB-03"
@@ -4157,7 +4157,14 @@
        "refactor/baselines/vtt-thumbnail-resources.json"
      ],
      "compatibleResolution": "Preserve valid cue selection and geometry; test malformed data and standard VTT separately from old compiler defects.",
-      "closureCriteria": "Parser fixtures include malformed, empty, real demo VTT, fractional and shared bounds, relative URLs and historical accepted formats."
+      "closureCriteria": "Parser fixtures include malformed, empty, real demo VTT, fractional and shared bounds, relative URLs and historical accepted formats.",
+      "resolutionEvidence": [
+        "test/vtt-thumbnail-parser.test.js",
+        "test/browser/vtt-thumbnail-lifecycle.spec.js",
+        "refactor/baselines/vtt-thumbnail-parser.json",
+        "refactor/changes/2026-09-13-PKG-VTT-THUMB-03-parser.md"
+      ],
+      "resolutionRationale": "Historical compiled/source arrow differences stay frozen. Pure parser validates malformed input with original lines, handles metadata blocks/IDs/settings and long hours, retains legacy boundaries/URL/coordinate semantics and compares all 120 demo cues. Candidate factories and native old/new core cases demonstrate rejection before mounting and recovery. This resolves the thumbnail parsing scope; declaration, full device/core and installed-package risks remain separate."
    },
    {
      "id": "VTT-THUMB-LIFE-01",
@@ -1897,13 +1897,15 @@
        "CORE-09",
        "CORE-19"
      ],
-      "status": "doing",
+      "status": "done",
      "risk": "M",
      "deliverable": "纯解析/区间查找与 DOM、请求/定时器生命周期分离",
      "acceptance": "结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过",
      "evidence": [
        "changes/2026-09-13-PKG-VTT-THUMB-03-resources.md",
-        "baselines/vtt-thumbnail-resources.json"
+        "baselines/vtt-thumbnail-resources.json",
+        "changes/2026-09-13-PKG-VTT-THUMB-03-parser.md",
+        "baselines/vtt-thumbnail-parser.json"
      ]
    },
    {