refactor(mediabunny): [PKG-MB-03] type inputs and cancel owned loads

2026-10-21 21:01:20 -08:00 · 2026-09-12 18:08:37 +08:00
1 parent 03451c029b
commit adba8a3d12
@@ -0,0 +1,62 @@
+# PKG-MB-03 输入、Range 与加载取消
+
+## 结构与兼容
+
+原input.js拆为input.ts、media.ts、tracks.ts、hls-state.ts；新增preflight.ts和load-session.ts，
+共六个strict生产TS模块。原Engine/VideoEngine仅接入新边界，主协调、视频、音频和HLS UI的
+其余迁移仍分别归04/05/06/07。实际维护地图见包内ARCHITECTURE.md。
+
+保留String/Blob/ReadableStream、SDK Source/SourceRef转交和SDK对错误输入的验证；
+HLS匹配、成对音轨、live/metadata/computed时长、语言别名和默认auto/manual模式保持。
+公开factory、Canvas精确Result、types及main/module/legacy路径均未更改。
+
+API-05/10的明确缺陷修正：旧加载在切源/销毁/超时后无需等待底层操作即可settle，
+不能再发晚error/Range事件或持有等待定时器；成功加载清除deadline；销毁后load无副作用。
+当前活动错误仍code4，超时仍Load timeout/networkState3。合法正常Range行为保留：
+缺头/none发RangeNotSupported detail但不设置engine.error，网络失败警告后继续，HLS跳过HEAD。
+
+Input在创建后、异步选轨前就属于LoadSession；engine.input/media只在选轨后暴露，
+避免旧实现未绑定Input期间无法取消。Input.dispose由唯一session负责，幂等释放；
+SDK声明明确不允许UrlSource.requestInit.signal，媒体请求交给Input.dispose取消。
+独立HEAD使用AbortController和代次守卫；无AbortController仍隔离过期结果，不能声称物理中止请求。
+
+## 类型与依赖决策
+
+首次严格检查实际复现SDK依赖dom-webcodecs0.1.13与TS5.9.3 DOM的重复声明和BufferSource冲突，
+以及缺失Disposable。未开启skipLibCheck，也未使用自制any类型掩盖SDK。
+通过Yarn registry确认并固定@types/dom-webcodecs0.1.19（最低TS5.8），root resolutions覆盖两个
+传递路径；yarn.lock记录完整性。SDK运行时仍1.56.1、原始四文件哈希未改。
+Yarn会明确提示替换SDK精确0.1.13，这是有记录的仅声明覆盖，不是无意漂移。
+包内lib追加ESNext.Disposable以检查SDK声明；target仍ES2020，源代码未引入using/Symbol.dispose。
+公共声明不引用SDK，不把内部编译器版本要求传给旧消费者。
+
+## 验证
+
+32项候选专项：12项来源/轨道/时长/HLS与真实SDK解析，20项加载正常及竞态回归。
+同一20项加载断言跑冻结旧main：6正常通过、14失败；候选20通过。原24项历史基线继续通过，
+yarn test:mediabunny共56项已接入test:unit。main与legacy各20项通过；三格式由仓库build生成。
+
+首轮21项候选源码浏览器检查通过，包含12次实际播放、7次Windows WebKit能力对照、
+2次待修复的无轨道就绪行为。构建产物的完整矩阵另加真实浏览器Stream取消（无模拟timer），
+最终报告、结果和源码/产物哈希见[验证证据](../baselines/mb-input-validation.json)。
+
+测试初稿的空源操作在受控环境触发真实AudioContext缺失，仅在对应隔离Range用例中明确控制
+无音轨处理；跨VM对象原型改为字段比较；MP4 fixture实际8秒修正了测试草稿2秒假设。
+这些失败日志与SDK声明冲突日志保留，均未修改冻结基线或扩大媒体成功定义。
+
+## 剩余范围与回退
+
+本步没有宣称解决所有生命周期问题。重复/无轨道就绪、事件重入、pending play/seek、
+已经进入解码器的晚帧/音频回调、长期AV sync、HLS UI并发、完整安装与MPL通知仍有责任任务。
+旧createTimeout内部方法仍在Engine供后续协调迁移审查，正常load已不通过它创建无人管理的timer。
+PKG-MB-09/10及全局发布复盘未完成。保持Canvas/Ambilight类型决策待确认；未推送或发布。
+
+回退以本任务独立提交为单位，同时回退六模块、JS接入、产物、Yarn声明覆盖、测试和文档；
+不要覆盖03451c02的历史媒体基线。完成状态以任务表、最终验证证据和独立commit为准。
+
+首轮完整CI的单元/工程通过，基线中第三方来源清单仍指向已拆分input.js。
+已同步third-party.json的六模块来源路径与验证范围，专项台账及完整CI随后复跑；未降低台账校验。
+
+最终完整CI1217项通过（1062单元、14工程、141基线），另44重复契约，296生产TS严格检查。
+最终72项浏览器无失败/重试/跳过；候选30项为12次播放、9次原生Stream取消、7次能力对照、
+2次已登记trackless就绪缺口。源码、产物、测试哈希与报告匹配，docs/compiled与dist三格式逐字节一致。
@@ -25,6 +25,14 @@ play/load/seek转发测试刻意截获engine方法；不得宣传为真实播放

 ## 后续顺序

+MB-03实施将input分离为六个strict TS模块，接入加载session、Range取消和SDK Input释放。
+实际文件地图见包内ARCHITECTURE.md，过程见[输入迁移](changes/2026-09-12-PKG-MB-03-input.md)。
+`yarn test:mediabunny`现在包括24历史、20候选加载及12输入/轨道检查；20加载断言可通过
+`ARTPLAYER_MB_BASELINE=1`重跑冻结main，正常控制6通过、缺陷回归14失败。
+浏览器默认包含两个发布版与候选，并增加mediabunny-load.spec.js的三种真实Stream取消；
+`ARTPLAYER_MB_ARTIFACT`指定构建的UMD文件，`ARTPLAYER_MB_BROWSER_CANDIDATE=1`可仅跑候选。
+每轮须读取报告确认具体数量和结果；配置了用例不等于该轮已运行。
+
 1. MB-02的输入、seek、HLS轨道、无轨道和失败样本见行为基线。42项浏览器检查须区分
   20次实际播放、12次能力对照、6次历史输入失败及4次无轨道就绪行为；24项生命周期测试含18个历史缺陷。
   后续修改须复跑对应正常和负例，不把全部负例变为候选豁免；并发选轨、晚帧和音频回调的完整修复分别在04/05/06/07。
@@ -4,7 +4,7 @@

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

-状态：todo 116 / doing 7 / blocked 0 / done 99 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 115 / doing 7 / blocked 0 / done 100 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -331,7 +331,7 @@
 | --- | --- | --- | --- | --- | --- | --- |
 | PKG-MB-01 | artplayer-proxy-mediabunny<br>核对 shim 与媒体契约 | BASE-05 | 全部 option、art.mediabunny、canvas/shim 属性及事件表 | 公开暴露成员和实际发布依赖/资源范围明确；核实 third-party.json 所记录依赖 MPL-2.0 元数据与实际 bundle 的许可/通知范围，不从根 MIT 推断 | H | done |
 | PKG-MB-02 | artplayer-proxy-mediabunny<br>建立真实媒体与事件基线 | PKG-MB-01, ENG-05, ENG-08 | MP4/WebM/HLS/Blob/Stream、seek/错误/轨道切换样本 | ready 事件顺序、音画同步、超时和释放可重跑 | H | done |
-| PKG-MB-03 | artplayer-proxy-mediabunny<br>整理 input 与加载取消 | PKG-MB-02, CORE-09 | input.js 源检测、输入资源、Range 与取消 | HLS 检测在 input 边界，旧来源类型和超时保持 | H | todo |
+| PKG-MB-03 | artplayer-proxy-mediabunny<br>整理 input 与加载取消 | PKG-MB-02, CORE-09 | input.js 源检测、输入资源、Range 与取消 | HLS 检测在 input 边界，旧来源类型和超时保持 | H | done |
 | PKG-MB-04 | artplayer-proxy-mediabunny<br>整理 VideoShim/EventTarget/Engine 协调 | PKG-MB-03, CORE-06, CORE-11 | shim 描述符、事件桥、加载状态和操作隔离 | 公开属性/同步异步返回与事件重入顺序保持 | H | todo |
 | PKG-MB-05 | artplayer-proxy-mediabunny<br>整理视频解码、seek 和帧释放 | PKG-MB-04 | VideoEngine 调度、队列、晚帧处理和资源释放 | 暂停/seek/切源无旧帧覆盖，默认丢帧策略不变 | H | todo |
 | PKG-MB-06 | artplayer-proxy-mediabunny<br>整理音频解码、时钟与同步 | PKG-MB-04 | AudioEngine 时钟、缓冲和 AudioContext 归属 | AV sync、倍速、无音轨、静音/音量和暂停恢复通过 | H | todo |
@@ -522,4 +522,5 @@
 - PKG-CANVAS-04: [记录](changes/2026-09-12-PKG-CANVAS-04-types.md) [记录](baselines/canvas-types-validation.json) [记录](canvas-validation.md)
 - PKG-MB-01: [记录](baselines/mb-release.json) [记录](baselines/mb-surface.json) [记录](baselines/mb-contract.md) [记录](baselines/mb-contract-validation.json) [记录](mb-validation.md) [记录](changes/2026-09-12-PKG-MB-01-contract.md)
 - PKG-MB-02: [记录](changes/2026-09-12-PKG-MB-02-checkpoint.md) [记录](baselines/mb-media-checkpoint.json) [记录](mb-validation.md) [记录](changes/2026-09-12-PKG-MB-02-baseline.md) [记录](baselines/mb-behavior-validation.json)
+- PKG-MB-03: [记录](changes/2026-09-12-PKG-MB-03-input.md) [记录](baselines/mb-input-validation.json)
 - PKG-FACTORY-01: [记录](baselines/factory-assignment-gaps.json) [记录](baselines/factory-compatibility-proposals.json) [记录](factory-compatibility-decision.md) [记录](changes/2026-09-12-PKG-FACTORY-01-decision.md)
@@ -1,5 +1,16 @@
 # 进度与证据

+## 最新完成：PKG-MB-03 输入、Range与加载取消
+
+六个strict TS模块已接入生产，修复切源/销毁/超时后的待加载Input、HEAD及timer资源与陈旧回调。
+同一20项加载断言在冻结版6通过/14失败，候选source/main/legacy各20通过；来源/轨道12项与
+旧基线24项继续通过。实际SDK保持1.56.1，WebCodecs补充声明固定0.1.19解决严格DOM声明冲突。
+三格式构建与导出通过，72项最终浏览器检查通过；候选30项含12播放、9原生Stream取消、7能力
+失败对照、2待修复无轨道就绪。完整CI1217项（1062单元+14工程+141基线），另44重复契约，296生产TS。
+见[步骤记录](changes/2026-09-12-PKG-MB-03-input.md)和[验证证据](baselines/mb-input-validation.json)。
+下一步MB-04主协调/事件/VideoShim；晚帧、音频、HLS UI和完整发布验收仍未完成。
+222项：100 done、7 doing、115 todo。Canvas/Ambilight类型决定仍待确认；独立本地commit，不推送/发布。
+
 ## 最新完成：PKG-MB-02 媒体、事件与资源基线

 24项历史生命周期检查通过，已接入统一CI；42项真实浏览器检查包含20次播放、12次环境能力
@@ -755,7 +755,7 @@
        "PKG-MB-09"
      ],
      "evidence": [
-        "packages/artplayer-proxy-mediabunny/src/input.js",
+        "packages/artplayer-proxy-mediabunny/src/input.ts",
        "packages/artplayer-proxy-mediabunny/package.json"
      ],
      "compatibleResolution": "Preserve native-video-like events, HLS input and topology, codec capability failures and AV sync; actual library/codec environment still requires verification.",
@@ -3648,7 +3648,7 @@
        "PKG-MB-07",
        "PKG-MB-09"
      ],
-      "compatibleResolution": "Reproduce pending operations and destroy/source-switch races before migrating each owner; preserve public event and promise behavior while preventing stale resource use. MB-02 now reproduces late load rejection and uncancelled waiting/loadstart timers after destroy in all three historical implementations using a controlled host. Other interleavings and full-core native behavior are not yet verified. Expanded MB-02 baseline reproduces play-after-pause/destroy, rejected-play false state, seek-after-destroy and retained successful-load timeout timers in all three actual historical implementations; Range and active-timeout normal controls remain separate.",
+      "compatibleResolution": "Reproduce pending operations and destroy/source-switch races before migrating each owner; preserve public event and promise behavior while preventing stale resource use. MB-02 now reproduces late load rejection and uncancelled waiting/loadstart timers after destroy in all three historical implementations using a controlled host. Other interleavings and full-core native behavior are not yet verified. Expanded MB-02 baseline reproduces play-after-pause/destroy, rejected-play false state, seek-after-destroy and retained successful-load timeout timers in all three actual historical implementations; Range and active-timeout normal controls remain separate. MB-03 candidate owns pending Input before track selection and cancels load/HEAD/timers on source replacement, timeout and destroy; source/main/legacy regressions pass. Pending play/seek, late decoder work and full readiness coordination remain MB-04/05/06, so this risk stays open.",
      "closureCriteria": "Historical failing interleavings and candidate cancellation/cleanup pass with real media and event evidence, including long playback and track topology.",
      "status": "open",
      "evidence": [
@@ -3658,7 +3658,8 @@
        "refactor/changes/2026-09-12-PKG-MB-02-checkpoint.md",
        "refactor/baselines/mb-media-checkpoint.json",
        "refactor/changes/2026-09-12-PKG-MB-02-baseline.md",
-        "refactor/baselines/mb-behavior-validation.json"
+        "refactor/baselines/mb-behavior-validation.json",
+        "refactor/changes/2026-09-12-PKG-MB-03-input.md"
      ]
    },
    {
@@ -3439,11 +3439,14 @@
        "PKG-MB-02",
        "CORE-09"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "H",
      "deliverable": "input.js 源检测、输入资源、Range 与取消",
      "acceptance": "HLS 检测在 input 边界，旧来源类型和超时保持",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-12-PKG-MB-03-input.md",
+        "baselines/mb-input-validation.json"
+      ]
    },
    {
      "id": "PKG-MB-04",
@@ -1172,11 +1172,16 @@
        "PKG-MB-09"
      ],
      "sourceFiles": [
-        "packages/artplayer-proxy-mediabunny/src/input.js",
+        "packages/artplayer-proxy-mediabunny/src/input.ts",
+        "packages/artplayer-proxy-mediabunny/src/media.ts",
+        "packages/artplayer-proxy-mediabunny/src/tracks.ts",
+        "packages/artplayer-proxy-mediabunny/src/hls-state.ts",
+        "packages/artplayer-proxy-mediabunny/src/preflight.ts",
+        "packages/artplayer-proxy-mediabunny/src/load-session.ts",
        "packages/artplayer-proxy-mediabunny/package.json"
      ],
      "contract": "Preserve native-video-like events, HLS input and topology, codec capability failures and AV sync; actual library/codec environment still requires verification.",
-      "validationStatus": "PKG-MB-01 verifies actual 1.0.0/1.2.0 archives and installed 1.56.1 MPL-2.0 provenance, recorded in mb-release.json and mb-contract.md. Historical embedded SDK version is unknown; notices are MB-LICENSE-01/MB-10. Native codec, SDK media and AV sync remain MB-02/09.",
+      "validationStatus": "PKG-MB-01 verifies actual 1.0.0/1.2.0 archives and installed 1.56.1 MPL-2.0 provenance, recorded in mb-release.json and mb-contract.md. Historical embedded SDK version is unknown; notices are MB-LICENSE-01/MB-10. Native codec, SDK media and AV sync remain MB-02/09. MB-02 freezes actual native input behavior; MB-03 candidate has 72 browser checks including 12 candidate plays and nine native pending-stream cancellations, six strict TS modules and a build-only WebCodecs 0.1.19 resolution. Full AV sync/decoder cleanup and release notices remain MB-04/05/06/09/10.",
      "demoPathsSource": "refactor/baselines/demo-inventory.json"
    },
    {