fix(core): [CORE-24] preserve source playback intent and explicit pauses

2026-10-19 19:51:20 -08:00 · 2026-09-12 03:26:26 +08:00
1 parent b5e96664ee
commit 0218196df9
@@ -0,0 +1,63 @@
+# CORE-24：连续切源的播放意图
+
+状态：完成验收，独立本地提交；起点 b5e96664。Audio-05 的首轮三引擎证据确认六项候选核心回归。
+
+原切源每次读取 art.playing 并立即 art.pause()。第二次同步切源读取到第一次内部
+暂停后的 false；旧操作被正确取消后，原先负责恢复播放的旧监听器不再执行，新
+操作也没有恢复意图。修复必须传递最新切源的播放意图，同时保留过期操作无副作用。
+
+将意图归属当前 source operation，在仍待恢复的操作间转移；用户明确 pause 可以
+取消恢复。内部 pause 仍走既有公开事件，不能把它误当作用户放弃播放。补真实暂停
+状态的受控宿主、重入/取消/失败/销毁和真实浏览器测试。完成后独立提交并恢复 Audio-05。
+
+## 实现与兼容
+
+source/operation.ts 保存待恢复意图、内部暂停标记及暂停修订号；switch.ts 在取消旧
+操作前取得意图，结算时清除，避免完整结束/失败操作的状态泄漏到之后的来源。
+playMix/pauseMix 在原生命令之前更新意图。内部暂停标记由进入 pauseMix 的第一次调用
+消费，嵌套用户暂停仍然生效，不改变现有 pause 事件、同步返回或 play Promise 值/拒绝。
+play 的副作用还核对暂停修订号：晚到的 native play 不能在用户暂停之后更新提示、
+发出 play 或执行互斥，switch 的旧恢复也不能清空新暂停提示。
+
+最初尝试监听 play/pause 事件，已有用例虽通过，但无法保证比用户预注册的回调先执行；
+审查发现用户 pause 回调同步切源时可能先继承旧意图。因此采用命令入口方案（ADR-024），
+没有增加额外监听器、定时器、依赖或公开字段。新用例使用真实 pauseMix/playMix，
+不再让受控宿主的 pause 只计数却不改变播放状态。
+
+一项既有晚到恢复测试原来只写 art.playing=false，未表达暂停命令；它现在同时调用
+真实 art.pause，保留其旧操作不能覆盖新提示的断言。早期事件方案因此悬挂的运行已
+主动终止并保留日志，没有当作通过。新增“恢复未完成时用户暂停”也先复现了错误 play
+事件，再以修订号修复，失败日志均保留。
+
+## 验证结果
+
+- 源切换 34 项单元通过；新增 8 项覆盖连续操作、显式暂停、嵌套暂停、用户监听器重入、
+  未兑现的公开 play 意图、晚到恢复，以及直接 URL/失败/完成/销毁边界。
+- 完整 `yarn ci:check` 594 项通过（548 单元、11 工程、35 基线），严格 TS 与声明检查通过。
+  后续新增一个浏览器命令顺序用例，最终单独 lint 和下面两套矩阵验证。
+- 正常 `yarn build artplayer`、`yarn build:i18n` 通过；后者恢复核心构建清理的语言产物，
+  i18n 与上次提交无差异。三种核心 JS 与 docs/compiled 一致，公开声明/版本未改变。
+- 正式 main/legacy 产物的 source-intent/source/media-events/playback-properties
+  三引擎最终各 81 项通过，无重试或跳过。早期事件方案的 39 项及新增用例前的 78 项
+  保留为过程记录，不充当最终实现证据。
+- 原先失败的六项“候选核心 + 旧/新 Audio”连续切源用例全部通过，测试断言未改。
+  该组合重跑使用核心源码构建与明确指定的 Audio main 产物；正式核心产物另由上述矩阵验证。
+- `yarn test:package` 在仓库外实际安装 tarball 并冻结重装：34 个运行时检查，5 组兼容类型
+  与 8 组精确类型通过。打包核心 JS 与浏览器所测的正式文件逐字节比对。
+- `yarn test:coverage` 通过，224 个运行时文件进入报告、26 个明确排除，0 项门槛违例。
+  总体 Node 行覆盖 61.04%、分支 86.70%、函数 66.75%；不能将浏览器数量当作覆盖率。
+  变动文件的独立计数及产物体积差异见 [冻结证据](../baselines/core-source-intent-validation.json)。
+
+main gzip 从 58,555 增至 58,748 字节（+193），legacy +181、ESM +248；这是兼容行为
+修复的实际体积成本，不声称有性能/体积优化收益。source/operation.ts 的行/分支/函数
+覆盖均 100%，source/switch.ts 行 98.08%、分支 94.20%，其他浏览器路径仍有 Node 覆盖缺口。
+
+## 后续与回退
+
+CORE-SOURCE-01 按上述公开命令与连续切源范围关闭；AUDIO-RESUME-01（旧核心 + 新音频
+在 WebKit 上恢复）、原生偏移边界对照和真实网络缓冲仍由 Audio-05 接续，未一并关闭。
+核心完整安装包全量矩阵、性能/体积风险和物理设备/发布复盘门槛仍需后续最终候选验证；
+本任务的 81 项矩阵不等于重复了 CORE-22 的所有场景，也不代表 npm 发布放行。
+
+回退此独立提交会恢复上次核心运行实现及三种构建文件，同时重新打开 CORE-SOURCE-01；
+不应只回退命令入口或操作状态的一半。无 push/tag/publish/merge。
@@ -5,8 +5,9 @@ CORE-22 汇总核心自有源码、公开声明、生成产物和当前固定消
 [交付记录](changes/2026-09-11-CORE-22-core-acceptance.md)；任务状态以 tasks.json 为准。

 后续 Audio-05 的新组合测试复现了候选核心连续切源丢失播放意图，见
-[首轮证据](baselines/audio-combinations-first.json)。CORE-SOURCE-01/CORE-24 作为新发现
-继续修复，当前不能据本文件历史阶段结果放行；原有通过记录保留其当时的测试范围。
+[首轮证据](baselines/audio-combinations-first.json)。CORE-24 已修复并通过针对性正式
+产物/隔离安装验收，见 [修复记录](changes/2026-09-12-CORE-24-source-intent.md)。
+原有通过记录保留其当时的测试范围，不能据历史阶段结果替代最终候选的全量发布验收。

 ## 契约与回归入口

@@ -28,6 +28,7 @@
 | ADR-021 | 采用方向 | 用户指定 Yarn，固定 Classic 1.22.22 和唯一 yarn.lock | 与原 v1 锁格式一致；保留 Node 24.21.0 和既有依赖版本，ENG-PM-01 验证；替代 ENG-01 的 npm 默认工具选择 |
 | ADR-022 | 采用方向 | Chrome 不可用时使用 Codex 内置浏览器 | 用户明确授权；记录实际环境和能力范围，必要设备测试仍独立验收 |
 | ADR-023 | 已验证于 Audio Track | 参数类型纠正会破坏旧推断时，默认入口保留兼容类型，/runtime 复用相同运行文件提供精确类型 | PKG-AUDIO-04 的 Parameters 与无注解 update 实现证明 Partial/重载仍可能破坏旧用户；沿用核心的类型分层方向，具体包需独立编译与入口身份验证，不增加第二套实现或用 any 绕过 |
+| ADR-024 | 已验证于 CORE-24 | 切源播放意图归属当前操作，在公开 play/pause 命令入口更新，内部暂停不覆盖用户意图 | Audio-05 三引擎复现连续切源最终停在 0；新操作继承未完成操作的意图，显式暂停及其修订号终止旧恢复副作用，过期 Promise 仍保留原结算语义；不依赖用户回调之后才执行的事件监听器 |

 ## 开始实现前需补齐的决定

@@ -4,7 +4,7 @@

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

-状态：todo 147 / doing 1 / blocked 0 / done 69 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 146 / doing 1 / blocked 0 / done 70 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -128,7 +128,7 @@
 | CORE-21 | artplayer<br>生成核心声明并校验包内容 | CORE-20, ENG-07 | 由 TS 生成的既有入口声明与三种发布产物 | 内部类型不泄漏，旧 JS/TS 消费者与 i18n 通过；逐项完成 CORE-07 留下的 BASE-TYPE-04/05/07 声明方案，旧合法消费者与实际返回分别留证；不能以虚假的交叉返回类型或改变运行时来掩盖冲突，未决项阻止核心声明出口；处理 CORE-10 / BASE-TYPE-08 的 setter-only 属性虚构 getter 声明，并复核 PlaybackControls 精确视图与旧 toggle 声明共存策略 | H | done |
 | CORE-23 | artplayer<br>检查并补齐键盘、焦点与可访问名称 | CORE-13, CORE-14, CORE-17, ENG-05, BASE-04 | 主要控件/设置/模式退出的键盘与焦点回归、名称和字幕可用性检查及必要兼容修正 | 保持旧快捷键和 DOM/CSS 钩子；真实浏览器验证，不以静态属性检查代替交互；处理 BASE-DOM-01 的主要控件 Tab 不可达，保留既有名称与快捷键 | H | done |
 | CORE-22 | artplayer<br>核心阶段完整验收 | CORE-21, CORE-23, PILOT-01, ENG-08, ENG-10, ENG-11 | 核心与旧插件的可自动化完整回归、资源/性能及明确外部验证缺口 | 核心自动化和公开差异处置通过；真实环境缺口链接包集成/REL 门槛，阶段完成不代表可公开发布 | H | done |
-| CORE-24 | artplayer<br>修复连续切源的播放意图继承 | CORE-22, PKG-AUDIO-04 | 连续切源保留原播放意图，同时尊重显式暂停与最新来源，回归旧/新 audio | 真实暂停状态的受控测试、重入/取消/失败/销毁、三引擎和 main/legacy 产物验证通过；不恢复过期来源的公开副作用 | H | todo |
+| CORE-24 | artplayer<br>修复连续切源的播放意图继承 | CORE-22, PKG-AUDIO-04 | 连续切源保留原播放意图，同时尊重显式暂停与最新来源，回归旧/新 audio | 真实暂停状态的受控测试、重入/取消/失败/销毁、三引擎和 main/legacy 产物验证通过；不恢复过期来源的公开副作用 | H | done |

 ## 5 包迁移：artplayer-plugin-chapter

@@ -463,7 +463,7 @@
 - CORE-21: [记录](changes/2026-09-11-CORE-21-public-declarations.md) [记录](baselines/core-declarations-validation.json) [记录](core-public-types.md) [记录](typechecking.md)
 - CORE-23: [记录](changes/2026-09-11-CORE-23-keyboard-focus.md) [记录](baselines/keyboard-validation.json)
 - CORE-22: [记录](changes/2026-09-11-CORE-22-core-acceptance.md) [记录](baselines/core-setting-navigation-partial.json) [记录](core-acceptance.md) [记录](baselines/core-acceptance-validation.json)
- CORE-24: [记录](baselines/audio-combinations-first.json)
+- CORE-24: [记录](baselines/audio-combinations-first.json) [记录](changes/2026-09-12-CORE-24-source-intent.md) [记录](baselines/core-source-intent-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,20 @@
 # 进度与证据

+## 最新完成：CORE-24 连续切源播放意图修复
+
+Audio-05 检查点已提交 b5e96664，原六项候选核心回归保持原断言重跑全部通过。
+切源现在继承尚未完成操作的播放意图，公开 play/pause 在用户回调前更新它；内部
+暂停不覆盖意图，显式暂停和暂停修订号阻止晚到恢复的事件/提示副作用。
+
+源切换单元 34 项、完整 CI 594 项通过；正式 main/legacy 三引擎各 81 项通过；
+隔离 tarball 的 34 项运行时、5 组兼容类型、8 组精确类型通过，运行字节与正式文件一致。
+覆盖率 0 门槛违例，Node 总行覆盖 61.04%，不声称全部源码均已覆盖。
+CORE-SOURCE-01 关闭，AUDIO-RESUME-01、偏移原生对照、真实缓冲及 HLS 风险仍开放。
+
+当前 217 项、70 done、1 doing、146 todo。本任务独立本地提交核实后恢复 Audio-05。
+详见 [修复记录](changes/2026-09-12-CORE-24-source-intent.md) 和
+[冻结证据](baselines/core-source-intent-validation.json)。未推送或发布，全局目标保持不变。
+
 ## 当前实施：Audio-05 发现连续切源回归，拆分 CORE-24

 Audio-04 已独立提交 13c898c1。新组合测试覆盖旧/新核心、旧/新 audio 的连续切源、
@@ -130,5 +130,5 @@
 | AUDIO-SYNC-01 | open / 已复现 | Audio Track 未同步原生暂停/结束，偏移边界与切源/缓冲仍待完整验证 | PKG-AUDIO-02, PKG-AUDIO-03, PKG-AUDIO-05 |
 | AUDIO-TYPE-01 | accepted-with-scope / 源码/产物事实 | Audio Track update 部分配置与公开/编辑器声明不一致 | PKG-AUDIO-04 |
 | AUDIO-DEMO-01 | open / 源码/产物事实 | Audio Track README 示例链接名称不匹配且缺维护说明 | PKG-AUDIO-06 |
-| CORE-SOURCE-01 | open / 已复现 | 候选核心连续切源丢失原播放意图 | CORE-24 |
+| CORE-SOURCE-01 | resolved / 已复现 | 候选核心连续切源丢失原播放意图 | CORE-24 |
 | AUDIO-RESUME-01 | open / 已复现 | WebKit 旧核心切源后候选音频保持暂停 | PKG-AUDIO-05 |
@@ -2731,7 +2731,7 @@
      "id": "CORE-SOURCE-01",
      "title": "候选核心连续切源丢失原播放意图",
      "confirmation": "reproduced",
-      "status": "open",
+      "status": "resolved",
      "owners": [
        "CORE-24"
      ],
@@ -2740,7 +2740,14 @@
        "packages/artplayer/src/source/switch.ts"
      ],
      "compatibleResolution": "继承被替代切源操作的播放意图；显式暂停可以取消恢复，过期操作继续只结算不发布副作用。",
-      "closureCriteria": "新旧对照的连续切源、手动暂停、重入/取消/错误/销毁和正式产物三引擎验证通过。"
+      "closureCriteria": "新旧对照的连续切源、手动暂停、重入/取消/错误/销毁和正式产物三引擎验证通过。",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-12-CORE-24-source-intent.md",
+        "refactor/baselines/core-source-intent-validation.json",
+        "test/source.test.js",
+        "test/browser/source-intent.spec.js"
+      ],
+      "resolutionRationale": "待完成切源操作继承播放意图，公开 play/pause 在原生调用及用户监听器之前更新；内部暂停标记仅消费一次，暂停修订号阻止晚到恢复副作用。34 项源测试、594 项 CI、正式 main/legacy 各 81 项三引擎和原六项 Audio 失败重跑通过，隔离 tarball 字节/运行时/类型验证通过。范围是公开命令及切源操作，不关闭独立 AUDIO-RESUME-01、真机或完整发布门槛。"
    },
    {
      "id": "AUDIO-RESUME-01",
@@ -1249,12 +1249,14 @@
        "CORE-22",
        "PKG-AUDIO-04"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "H",
      "deliverable": "连续切源保留原播放意图，同时尊重显式暂停与最新来源，回归旧/新 audio",
      "acceptance": "真实暂停状态的受控测试、重入/取消/失败/销毁、三引擎和 main/legacy 产物验证通过；不恢复过期来源的公开副作用",
      "evidence": [
-        "baselines/audio-combinations-first.json"
+        "baselines/audio-combinations-first.json",
+        "changes/2026-09-12-CORE-24-source-intent.md",
+        "baselines/core-source-intent-validation.json"
      ]
    },
    {