refactor(core): CORE-15 type subtitles and own request and track lifetimes

2026-10-23 22:01:20 -08:00 · 2026-09-11 07:23:10 +08:00
1 parent 64d1939daa
commit 1b83081e8f
@@ -0,0 +1,58 @@
+# CORE-15 字幕请求、track 与渲染
+
+状态：完成。以下阶段记录保留当时的进度；当前交付结论以末尾最终验收为准。
+
+## 结构和兼容边界
+
+- 原 src/subtitle.js 拆为 subtitle/index.ts、types.ts、request.ts、parse.ts、state.ts、track.ts、render.ts；字幕偏移 mixin 同时迁移 TS。
+- 保留实际 Component 原型链和 update 绑定、url/style/show/toggle/init/switch/createTrack、原生 cue 对象、默认 escape 与 DOM/CSS 行结构。正常转换仍调用现有 SRT/ASS 工具，onVttLoad 的 this 仍为字幕选项对象。
+- 正常 switch/init 返回转换 URL；无 textTrack 返回 null；空 URL 返回 undefined。字幕切换仍基于 art.option.subtitle 合并，不静默把上一次 switch 的临时配置变成默认值。
+- 内部准确声明 SubtitleCue[]。旧公开声明及 CORE-07 的显式数组监听重载保持；旧隐式 scalar 回调冲突仍由 BASE-TYPE-07 / CORE-21 协调。
+
+## 已复现问题和修正
+
+三个真实浏览器引擎分别对发布基线和迁移前候选执行受控异步请求。HTTP 响应由测试控制，track/Blob/DOM 为原生浏览器对象。不是网络可靠性或实体设备测试。
+
+1. 旧 first 请求晚于 second 完成时覆盖后者，notice 也回到 first；已加入请求代次及 AbortController，过期结果不再写页面。
+2. 销毁后，旧请求仍生成 Blob 并替换 track；请求归实例作用域，关闭时及时以 undefined 结算，即使 fetch 忽略 signal 也不等待它。
+3. 旧代码替换字幕时撤销调用者传入的 Blob URL，却未在销毁时撤销最后的自建 URL；现在仅释放自己创建的资源，原生全屏 track 重建保留当前资源。
+
+这些异常竞争路径按缺陷修正处理。主动调用 switch/init 的真实错误仍拒绝；构造和 url setter 没有可接收的 Promise，内部处理拒绝，避免已显示 notice 的失败再成为未处理异常。HTTP 非成功响应在生成 track 前报告错误，具体新旧对照及错误回归仍在补齐。
+
+render.ts 在 before 事件后检查代次，防止监听者切换/销毁后旧渲染继续写入；正常回调修改 cue 文本仍在同次渲染生效。track.ts 持有 onload/cuechange 清理，失败安装尝试恢复旧节点。复杂重入和清理异常仍需补齐测试后才能验收。
+
+## 阶段证据
+
+- 初始浏览器复现报告 core15-baseline-browser.json：首轮 notice 断言包含模板空白导致额外三项失败，已保留，未作为通过证据。
+- 修正后的 core15-baseline-corrected-browser.json：18 项中，发布基线 9 项确认旧缺陷；候选 9 项按目标行为失败。修改源码前生成。
+- 第一批 core15-first-browser.json：30 项三浏览器通过，含上述生命周期路径和既有声明契约。
+- 第一批严格类型及五组消费者检查通过：135 个生产 TS 文件；后续代码和新增用例仍需重新检查。
+- Node 新增请求取消/异常/能力缺失、解析及偏移共 9 项通过。
+- 最终产物、原生全屏、完整浏览器回归和失败路径证据待补充。
+
+## 依赖、脚本和后续
+
+不增加依赖。test:unit 将加入 test/subtitle.test.js；仍使用 Node 24.21.0 / Yarn Classic 1.22.22。不修改公开类型、版本或 lockfile。本任务完成后独立本地提交，不推送/发布。
+
+需继续审查：track 事件错误与原生全屏、重入/清理失败、代理无 textTracks、cue/偏移组合、产物与安装消费。源码、测试、文档一起回退，不覆盖 BASE 历史发布证据。
+
+规范参考：[HTML TextTrack 模型](https://html.spec.whatwg.org/multipage/media.html#text-track-api)规定 disabled 模式 cue 列表可为 null；内部 getter 对此返回空数组。真实设备 Safari/iOS 能力仍需按全项目环境矩阵验证。
+
+## 最终验收
+
+- 七个字幕 TS 模块及字幕偏移 mixin 完成，核心 130 个与 chapter 5 个生产 TS 文件严格检查。旧公开声明保持，内部明确 cue 数组与 string/null/undefined 返回。
+- yarn ci:check：210 项通过（181 单元、4 工程、25 基线）；新增字幕 Node 10 项覆盖取消、错误、能力缺失、解析、偏移及属性失败后的作用域释放。
+- 实际核心/chapter tarball 仓库外安装：27 项运行时、五组类型零诊断。最终安装 UMD 和 legacy 各 600 项三浏览器通过，其中各 81 项字幕检查；无重试、跳过或未处理页面错误。
+- [最终证据](../baselines/subtitle-validation.json)核对当前全部核心源码与构建快照、三个分发格式与 tarball/docs、公开类型、包内架构说明、22 个语言文件及独立分发许可。
+- 真实 native fullscreen 在三个桌面引擎执行进出与字幕 DOM 检查；另外驱动 WebKit 视频全屏信号验证 metadata/subtitles track 重建、旧 handler 清理及 URL 保留。这不是实体 iOS 验证。
+- 插入失败恢复旧 track；注册重入保留胜出的 track；旧清理抛错后保留已提交新资源。标签属性抛错立即释放本次作用域。HTTP 失败、实际 native track 失败、disabled cue 列表、转换重入和空 URL 取消均有覆盖。
+- Node/cue 身份与默认 escape、SRT/ASS 转换 this、样式返回、show/toggle 事件、偏移原始时间和旧 cue 数组事件均保留。正式 TYPE-07 出口还在 CORE-18/21；不把保留的历史公开声明说成全部精确。
+
+### 验证中发现并保留的失败
+
+- 最初 notice 文本包含模板空白；断言改为 trim 后保留旧缺陷/候选失败对照。VTT 空白行在 Firefox 是 cue 分隔符，改用有效 VTT，并直接改变原生 cue 文本验证空行过滤。
+- WebKit 原生 cue 改文案后会暂时更新 activeCues，改为等待真实字幕行就绪后读取结果；没有放宽最终行文本或样式断言。短暂 notice 通过实际 setter 完成后的 DOM 写入记录验收，避免错过自动隐藏的提示；没有替换真实 setter。
+- 第一次安装 UMD 全套 600 项通过后，额外修正属性失败作用域释放；最终重新构建/安装，UMD 与 legacy 都基于新包再验证。旧结果仅作阶段证据。
+- 两次 Windows copyfile UNKNOWN（分别复制 mjs/js 到 docs/compiled）保留日志。磁盘/权限/独立复制检查未复现根因；后续串行正常构建通过，未修改依赖或跳过分发复制。
+
+关闭 BASE-LIFE-15/16。当前 214 项中 51 完成、163 待办；下一项 CORE-16 全屏、PiP、mini 与尺寸模式。全生态 SDK、实体设备、远端 CI、多轮复盘和发布门槛仍按原计划继续。本任务独立本地提交，不推送或发布。
@@ -21,7 +21,7 @@
 | 播放流程 | play/pause/toggle/seek/url/switch/eventInit  | 媒体状态、操作身份、加载恢复与 UI 响应分离                                   |
 | UI 注册  | utils/component、control、layer、contextmenu | 保留 name/cache/update/remove；明确 DOM 和绑定的归属                         |
 | 设置面板 | setting/index.ts                             | 分开树整理、选择状态、渲染、布局、绑定；共享能共享的逻辑，不强行统一返回类型 |
-| 字幕     | subtitle.js、utils/subtitle.js               | 获取、解析、track/DOM 渲染、取消和对象 URL 回收分开                          |
+| 字幕     | subtitle/index.ts、utils/subtitle.ts         | 获取、解析、track/DOM 渲染、取消和对象 URL 回收分开                          |
 | 显示模式 | fullscreen/fullscreenWeb/pip/mini/auto*      | 显式恢复位置和样式，保持互斥顺序、用户手势与移动端语义                       |
 | 输入     | events、hotkey                               | 鼠标/触控/键盘/焦点归属清晰，跨 document 重新绑定和清理                      |
 | 无障碍   | template、control、setting、显示模式         | 明确键盘导航、可访问名称、焦点进入退出和字幕能力，保留旧 DOM/CSS 与热键契约  |
@@ -4,7 +4,7 @@

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

-状态：todo 164 / doing 0 / blocked 0 / done 50 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 163 / doing 0 / blocked 0 / done 51 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -118,7 +118,7 @@
 | CORE-12 | artplayer<br>迁移模板及公开资源入口 | CORE-06, CORE-04, BASE-04 | template/icons/i18n/style、SSR 与 proxy 挂载 | DOM/CSS/global/样式注入、i18n 子路径及 SSR import 保持；不把 SSR import/useSSR 保持扩大为服务端构造播放器；复跑 BASE-05 的 SSR import/模板、浏览器 useSSR 节点复用和非浏览器构造错误；接续 VENDOR-01/02，核对 screenfull/hint 复制版本、修改与分发通知，保留 DOM/CSS/fullscreen 行为 | H | done |
 | CORE-13 | artplayer<br>迁移组件注册与控件 | CORE-12, CORE-08 | Component/control/layer/contextmenu 的资源与 TS 边界 | add/update/remove、name、selector、mounted/beforeUnmount 通过；处理 BASE-DOM-02 窄容器控件裁切，保留 controls.update 的旧 undefined 返回值 | H | done |
 | CORE-14 | artplayer<br>拆分设置树、渲染和布局 | CORE-13 | setting model/selection/render/layout 的分批实现 | 不强行统一控件返回值，嵌套选择、默认高亮、更新清理通过；结合 BASE-DOM-02 验证窄容器设置定位；接续 BASE-TYPE-07 的 find null、add/update item、remove undefined 声明冲突 | H | done |
-| CORE-15 | artplayer<br>迁移字幕获取、解析和渲染 | CORE-11, CORE-13 | subtitle 请求/track/DOM/URL 生命周期与类型 | 过期结果、偏移、cue 数组、原生全屏及错误路径通过；接续 BASE-TYPE-07 的真实 cue 数组与旧隐式 scalar 回调声明兼容 | H | todo |
+| CORE-15 | artplayer<br>迁移字幕获取、解析和渲染 | CORE-11, CORE-13 | subtitle 请求/track/DOM/URL 生命周期与类型 | 过期结果、偏移、cue 数组、原生全屏及错误路径通过；接续 BASE-TYPE-07 的真实 cue 数组与旧隐式 scalar 回调声明兼容 | H | done |
 | CORE-16 | artplayer<br>迁移全屏、PiP、mini 与尺寸模式 | CORE-11, CORE-12 | 显示模式服务和原公开属性门面 | 模式互斥/恢复位置、手势权限、移动方向和退出失败通过 | H | todo |
 | CORE-17 | artplayer<br>迁移键盘、手势、焦点和全局事件 | CORE-13, CORE-16 | events/hotkey 的明确 document 与资源归属 | 跨 document 重绑、触摸/键盘、快捷键及销毁无重复响应；修复 BASE-PERF-01 pending resize debounce 销毁后执行，并验证正常 resize 不变 | H | todo |
 | CORE-18 | artplayer<br>迁移内置插件和提示模块 | CORE-14, CORE-16, CORE-17 | autoPlayback/autoOrientation/fastForward/lock/miniProgressBar 及 info/notice/loading/mask | 默认启用条件、storage 格式、定时器/动画清理通过；结合 BASE-PERF-01 防止销毁后重新安排 notice timer；接续 BASE-TYPE-07 的 notice.show boolean getter 与历史读类型冲突 | M | todo |
@@ -449,6 +449,7 @@
 - CORE-12: [记录](changes/2026-09-11-CORE-12-template-resources.md) [记录](baselines/template-resources-validation.json)
 - CORE-13: [记录](changes/2026-09-11-CORE-13-components.md) [记录](baselines/components-validation.json)
 - CORE-14: [记录](changes/2026-09-11-CORE-14-setting.md) [记录](baselines/setting-validation.json)
+- CORE-15: [记录](changes/2026-09-11-CORE-15-subtitle.md) [记录](baselines/subtitle-validation.json)
 - PKG-CHAPTER-01: [记录](changes/2026-09-10-PKG-CHAPTER-01-contract.md) [记录](baselines/chapter-contract.md)
 - PKG-CHAPTER-02: [记录](changes/2026-09-10-PKG-CHAPTER-02-tests.md) [记录](baselines/chapter-validation.json)
 - PKG-CHAPTER-03: [记录](changes/2026-09-10-PKG-CHAPTER-03-typescript-modules.md) [记录](baselines/chapter-migration-validation.json)
@@ -1,5 +1,13 @@
 # 进度与证据

+## 当前实施：CORE-15 字幕请求、track 与渲染完成
+
+字幕管理器拆为 7 个 TS 模块，字幕偏移 mixin 同时迁移；请求取消及时结算，过期结果停止写入；仅释放自建 URL，处理 track 重入/失败恢复、原生 cue/全屏、错误及清理。正常转换、回调、DOM、返回和事件契约保留。
+
+CI 210 项通过，核心 130 个与 chapter 5 个生产 TS 文件严格检查；实际安装 UMD 与 legacy 各 600 项三浏览器通过，其中各 81 项字幕检查。真实 tarball 27 项运行时、五组类型零诊断；当前源码/产物/声明/文档/语言/许可指纹一致。见 [交付](changes/2026-09-11-CORE-15-subtitle.md) 和 [最终证据](baselines/subtitle-validation.json)。
+
+关闭 BASE-LIFE-15/16，BASE-TYPE-07 公开类型协调保持开放。当前 214 项，51 完成、163 待办；下一项 CORE-16 全屏、PiP、mini 与尺寸模式。当前仅本地提交，未推送或发布。
+
 ## 当前实施：CORE-14 设置树、渲染与布局完成

 设置目录迁移为 17 个 TS 模块，拆清树模型、渲染、布局、选择、条目/面板资源、更新事务、注册代次与根事件；保留原对象和返回约定，修复失效回调、残留订阅、失败恢复、跨实例绑定抢占及长文本控件裁切。
@@ -68,3 +68,5 @@
 | BASE-LIFE-13 | resolved / 已复现 | Obsolete setting callback completions overwrite current UI and failures are unhandled | CORE-14 |
 | BASE-LIFE-14 | resolved / 已复现 | Removed or replaced setting items still run deferred mounted callbacks | CORE-14 |
 | BASE-DOM-08 | resolved / 已复现 | Sharing a live setting object leaves a second published instance blank and can steal candidate bindings | CORE-14 |
+| BASE-LIFE-15 | resolved / 已复现 | Subtitle requests overwrite newer state and mutate tracks after destroy | CORE-15 |
+| BASE-LIFE-16 | resolved / 已复现 | Subtitle URLs revoke caller resources and leak the final generated resource | CORE-15 |
@@ -900,7 +900,7 @@
      "compatibleResolution": "Keep legacy consumers; add explicit cue-array listener overloads, type internal implementations accurately, and resolve remaining generated/public facade contracts at CORE-21 without false intersections.",
      "closureCriteria": "Actual setting/null/void and notice boolean returns, cue array callbacks and old legal type consumers all have an explicit compatible declaration strategy and package tests.",
      "scopeNote": "CORE-07 provides runtime evidence and explicit cue-array overloads; old inferred scalar event callbacks and return signatures are not claimed corrected.",
-      "workspaceState": "CORE-14 source manager accurately models add/update item, remove void and missing find null; installed historical public consumers still compile. Public declaration coordination remains open for CORE-15/18/21."
+      "workspaceState": "CORE-14 source models item/null/void setting returns; CORE-15 source models cue arrays and string/null/undefined subtitle results. Historical public consumers and explicit array listener overloads still compile; scalar inference and public return facade coordination remain CORE-18/21."
    },
    {
      "id": "BASE-TYPE-08",
@@ -1306,6 +1306,50 @@
        "test/setting-resources.test.js"
      ],
      "resolutionRationale": "Final installed UMD and legacy each pass the complete 519-case three-engine matrix. Managed tree/DOM/resource rollback, async generation guards, scoped mounts and panel/header ownership preserve normal identities, callbacks and returns. Narrow layouts and native input/touch interactions pass; simultaneous live object sharing fails before mutation while transfer after removal/destruction preserves the original object. Source and shipped package bytes match the tested artifacts."
+    },
+    {
+      "id": "BASE-LIFE-15",
+      "title": "Subtitle requests overwrite newer state and mutate tracks after destroy",
+      "confirmation": "reproduced",
+      "status": "resolved",
+      "owners": [
+        "CORE-15"
+      ],
+      "evidence": [
+        "test/browser/subtitle-lifecycle.spec.js",
+        "refactor/changes/2026-09-11-CORE-15-subtitle.md"
+      ],
+      "compatibleResolution": "Scope requests, abort and settle superseded calls; ignore stale conversion, errors and notices.",
+      "closureCriteria": "Installed UMD/legacy cover out-of-order fetch/body completion, rejection, cancellation, reentry and destroy.",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-11-CORE-15-subtitle.md",
+        "refactor/baselines/subtitle-validation.json",
+        "test/browser/subtitle-lifecycle.spec.js",
+        "test/subtitle.test.js"
+      ],
+      "resolutionRationale": "Final installed UMD and legacy each pass 600 real-browser checks. Subtitle cancellation settles promptly and stale work cannot commit. Only generated URLs are owned; native fullscreen-kind rebuilds retain them and failure/reentry/destroy cleanup is verified. Runtime and type consumers pass against the exact packed source and artifacts."
+    },
+    {
+      "id": "BASE-LIFE-16",
+      "title": "Subtitle URLs revoke caller resources and leak the final generated resource",
+      "confirmation": "reproduced",
+      "status": "resolved",
+      "owners": [
+        "CORE-15"
+      ],
+      "evidence": [
+        "test/browser/subtitle-lifecycle.spec.js",
+        "refactor/changes/2026-09-11-CORE-15-subtitle.md"
+      ],
+      "compatibleResolution": "Own only generated URLs and release track callbacks/resources on replace, failure and destroy.",
+      "closureCriteria": "Installed UMD/legacy prove caller URL survival, owned URL release, full-screen reuse, failed replacement and callback cleanup.",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-11-CORE-15-subtitle.md",
+        "refactor/baselines/subtitle-validation.json",
+        "test/browser/subtitle-lifecycle.spec.js",
+        "test/subtitle.test.js"
+      ],
+      "resolutionRationale": "Final installed UMD and legacy each pass 600 real-browser checks. Subtitle cancellation settles promptly and stale work cannot commit. Only generated URLs are owned; native fullscreen-kind rebuilds retain them and failure/reentry/destroy cleanup is verified. Runtime and type consumers pass against the exact packed source and artifacts."
    }
  ]
 }
@@ -1029,11 +1029,14 @@
        "CORE-11",
        "CORE-13"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "H",
      "deliverable": "subtitle 请求/track/DOM/URL 生命周期与类型",
      "acceptance": "过期结果、偏移、cue 数组、原生全屏及错误路径通过；接续 BASE-TYPE-07 的真实 cue 数组与旧隐式 scalar 回调声明兼容",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-11-CORE-15-subtitle.md",
+        "baselines/subtitle-validation.json"
+      ]
    },
    {
      "id": "CORE-16",