refactor(mediabunny): [PKG-MB-08] finish typed media capability boundaries

2026-10-12 06:26:16 -08:00 · 2026-09-12 21:51:47 +08:00
1 parent 5e28dfee95
commit fb9fb23f53
@@ -0,0 +1,11 @@
+{
+  "task": "PKG-MB-08",
+  "sourceCommit": "5e28dfee950a748f5a92dc0d26508815f23c6aec",
+  "sourceSha256LF": {
+    "packages/artplayer-proxy-mediabunny/src/readiness.ts": "9aa24b5e994006b45bda9eafad602785c3e0e334cef54ff45a4939e386c4aceb",
+    "packages/artplayer-proxy-mediabunny/src/MediaBunnyEngine.ts": "f8c6d96d11878712a40571961d734d4baa4e6bb5317dd32b776ea7a4795ca951",
+    "packages/artplayer-proxy-mediabunny/src/playback.ts": "e2a65782c89627198752ff1fe691d4eea0bef215d883a59f0bdcd3e904a4fb47",
+    "packages/artplayer-proxy-mediabunny/src/engine-ports.ts": "c56fad4a8f9578aa37686972d96d925012df8160c62337a53200b23a4fc3b164",
+    "packages/artplayer-proxy-mediabunny/dist/artplayer-proxy-mediabunny.js": "b7f4ff882a59cdff2b351d0ffcf4948dc9c06317c11dfaf6257f4865bf8c4134"
+  }
+}
@@ -0,0 +1,58 @@
+# PKG-MB-08：完成类型迁移与解码能力边界
+
+入口与公开类型已在5e28dfee检查点落地，本轮完成剩余能力/就绪问题。
+实际接续源码及main冻结于[能力基线](../baselines/mb-capability-source.json)。
+完整CI与最终证据核对通过，任务标记done并立即专用本地提交。
+
+## 问题与修复
+
+实际SDK解析出的video-only/audio-only输入，在codec=null或canDecode=false时，旧引擎把
+两端都降级为空轨道，却仍发布loadedmetadata/data/canplay/through并进入readyState 4。
+HLS替换轨道也有相同问题。仅有音频时使用音频解码，或仅有视频时使用AudioContext作为时钟，
+本来是有效场景；不能一律要求音频和视频两条轨道都支持。
+
+readiness.ts新增内部requireDecoder，根据两个引擎完成现有能力检查后实际建立的sink判断。
+不重复调用SDK canDecode，不改变decoder.load的Promise<void>返回，也不添加Canvas公开字段。
+metadata barrier在发布metadata前检查；load在发布data/canplay前检查；轨道替换在decoder
+加载后、seek及成功事件前检查。全部不可用时readyState归零，通过既有code 4错误通道报告
+`Input has no decodable audio or video tracks.`。原SDK查询拒绝保留原消息。
+
+至少一条轨道可用时，原有部分播放、事件顺序和AudioContext时钟保留。暂停不取消仍有效的加载；
+过期能力查询不能对新source或已destroy实例发就绪/错误。后续有效source可正常恢复。
+HLS失败触发现有error清理，移除失效菜单；旧canPlayType恒maybe及synthetic ranges/RAF不变。
+内部AudioPort/VideoPort补上准确SDK sink类型，公共声明仍不引入这些SDK依赖。
+
+## 验证
+
+新增16项Node回归：两个单轨输入的false/null能力、轨道替换、正常音频、晚查询false/reject、
+暂停期间查询、活动SDK错误、有效source恢复。使用真实SDK输入/track与受控能力响应；正常替换
+夹具先模拟已工作的decoder并保留真实Input，再使用实际引擎执行失败替换。
+同断言旧main8通过/8失败；候选全部通过。原协调器两个正常夹具补齐其声明模拟的有效sink，
+事件/顺序断言保持原样，没有为错误实现放宽预期。候选包专项257、main/legacy各233通过；
+每个产物命令包含229候选断言与4冻结正常控制。
+
+新增30浏览器用例涵盖发布版/候选核心与三个引擎。Chromium/Firefox中12项受控不可解码
+检查通过，8项混合媒体保留另一实际原生解码器并播放；Windows WebKit的10项API缺失为能力对照。
+canDecode=false是受控输入，不把它描述为浏览器自身拒绝该真实fixture的编码。
+旧main相同30项18通过/12失败；失败均为单轨假就绪和HLS替换假成功，正常部分播放仍通过。
+每轮report及整个results目录均保留。
+
+最终整组浏览器、隔离安装、完整CI及哈希记录见[最终证据](../baselines/mb-capability-validation.json)。
+入口检查点的17组安装类型/导出矩阵在最终候选上重跑；两个冻结声明整工厂双向赋值、精确Canvas
+结果和旧Option保持，新的可选shim/Player/HLS/RAF类型仍由实际VideoShim实现约束。
+
+## 维护与验收边界
+
+原有8个JS模块已在前序步骤细分并全部迁为34个生产TS模块，无相邻声明桥替代实现检查。
+包内ARCHITECTURE.md记录模块、资源归属、能力/类型边界，README给出可选类型用法；
+test:unit/test:mediabunny接入本轮用例，三种构建及docs复制由标准build生成。本轮没有新依赖。
+
+MB-08交付严格TS实现、兼容媒体声明与明确的不可解码错误处理。MB-CAP-01仍保留物理Safari/
+支持范围核验，MB-09负责长播放/音画同步/设备/组合，MB-10负责示例、完整分发与MPL/source notice。
+这些门槛不因本轮正常检查通过而视为完成。后续发现具体失败应修复并加入回归，不能只增加豁免。
+回退本轮commit可还原能力处理；入口/声明检查点单独回退5e28dfee，不改冻结历史输入。
+
+最终9个MediaBunny浏览器文件150项通过，其中39项为Windows WebKit能力缺失对照；
+完整CI1418项（1263单元+14工程+141基线）与44重复契约通过，324生产TS。
+最终源码/声明/测试/产物/安装文件及报告哈希一致，三格式dist与docs复制一致。
+MB-TYPE-01和MB-READY-01按其声明/就绪验收条件关闭；MB-CAP-01、MB-LIFE-01与MB-LICENSE-01仍open。
@@ -91,3 +91,13 @@ index实际迁移，入口/Canvas桥/生命周期/清理拆为四模块，全包
 见[变更](changes/2026-09-12-PKG-MB-08-entry-checkpoint.md)和[证据](baselines/mb-entry-checkpoint.json)。
 完整CI1402项及44重复契约通过，324生产TS。受控canDecode=false已复现旧/候选
 video-only输入及替换无sink仍readyState=4；任务保持doing，下一步修复该能力边界。
+
+## PKG-MB-08 完成：能力与公开声明验收
+
+入口检查点后补齐解码能力就绪门槛：全部无sink时通过原code 4通道拒绝，至少一条可用则
+保留正常部分播放。16新增Node断言旧main8通过/8失败；候选专项257、main/legacy各233通过。
+新增30浏览器中12受控拒绝、8原生部分播放及10能力对照；旧main相同30项18通过/12失败。
+最终150浏览器、17组实际安装类型/导出、完整CI1418与44重复契约通过，324生产TS。
+[变更](changes/2026-09-12-PKG-MB-08-capability.md)和[证据](baselines/mb-capability-validation.json)
+核对全部源码/产物/报告/安装文件哈希。MB-TYPE-01/MB-READY-01关闭；任务done并立即专用提交。
+39个WebKit能力对照不是播放或物理Safari支持，长播放/设备/组合及分发许可仍由09/10接续。
@@ -4,7 +4,7 @@

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

-状态：todo 110 / doing 8 / blocked 0 / done 104 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 110 / doing 7 / blocked 0 / done 105 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -336,7 +336,7 @@
 | PKG-MB-05 | artplayer-proxy-mediabunny<br>整理视频解码、seek 和帧释放 | PKG-MB-04 | VideoEngine 调度、队列、晚帧处理和资源释放 | 暂停/seek/切源无旧帧覆盖，默认丢帧策略不变 | H | done |
 | PKG-MB-06 | artplayer-proxy-mediabunny<br>整理音频解码、时钟与同步 | PKG-MB-04 | AudioEngine 时钟、缓冲和 AudioContext 归属 | AV sync、倍速、无音轨、静音/音量和暂停恢复通过 | H | done |
 | PKG-MB-07 | artplayer-proxy-mediabunny<br>整理 HLS 配对轨道与 selector | PKG-MB-05, PKG-MB-06, CORE-14 | m3u8 配对、质量/音频选择及拓扑清理 | 实际选择高亮、切到无轨道来源清理、无重复 readiness | H | done |
-| PKG-MB-08 | artplayer-proxy-mediabunny<br>完成 TS 与媒体能力声明 | PKG-MB-07, ENG-04, ENG-06 | 8 个自有 JS 模块迁移与 Result/shim 类型 | 解码器/Stream/DOM 类型清楚，旧 Option 和 art.mediabunny 使用保持 | H | doing |
+| PKG-MB-08 | artplayer-proxy-mediabunny<br>完成 TS 与媒体能力声明 | PKG-MB-07, ENG-04, ENG-06 | 8 个自有 JS 模块迁移与 Result/shim 类型 | 解码器/Stream/DOM 类型清楚，旧 Option 和 art.mediabunny 使用保持 | H | done |
 | PKG-MB-09 | artplayer-proxy-mediabunny<br>完成新旧核心和真实媒体组合 | PKG-MB-08, CORE-22 | 跨浏览器能力、长播放、DPiP、HLS 音轨/质量报告 | 资源释放、事件顺序、AV sync 与支持范围满足基线 | H | todo |
 | PKG-MB-10 | artplayer-proxy-mediabunny<br>完成分发和文档 | PKG-MB-09, ENG-07 | mediabunny.js、README、依赖版本、三产物和许可 | tarball 可消费、无意外依赖升级、旧调用与回退可用 | H | todo |

@@ -527,5 +527,5 @@
 - PKG-MB-05: [记录](baselines/mb-video-source.json) [记录](changes/2026-09-12-PKG-MB-05-video.md) [记录](baselines/mb-video-validation.json)
 - PKG-MB-06: [记录](baselines/mb-audio-source.json) [记录](changes/2026-09-12-PKG-MB-06-audio.md) [记录](baselines/mb-audio-validation.json)
 - PKG-MB-07: [记录](baselines/mb-hls-source.json) [记录](changes/2026-09-12-PKG-MB-07-hls.md) [记录](baselines/mb-hls-validation.json)
- PKG-MB-08: [记录](baselines/mb-entry-source.json) [记录](changes/2026-09-12-PKG-MB-08-entry-checkpoint.md) [记录](baselines/mb-entry-checkpoint.json)
+- PKG-MB-08: [记录](baselines/mb-entry-source.json) [记录](changes/2026-09-12-PKG-MB-08-entry-checkpoint.md) [记录](baselines/mb-entry-checkpoint.json) [记录](baselines/mb-capability-source.json) [记录](changes/2026-09-12-PKG-MB-08-capability.md) [记录](baselines/mb-capability-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,17 @@
 # 进度与证据

+## PKG-MB-08完成：严格TS、兼容声明与解码能力边界
+
+全包34生产TS已迁移，默认可选工厂/精确Canvas兼容；显式媒体类型不泄漏SDK现代声明。
+本轮修复全部轨道不可解码时仍发布就绪和替换成功的问题；保留一条可用轨道的部分播放，
+不重复canDecode查询，SDK原错误和过期查询取消保持。16新断言旧main8通过/8失败，
+候选专项257及main/legacy各233通过。新增30浏览器含12受控拒绝、8实际部分解码播放、
+10能力对照；旧main相同30项18通过/12失败。最终150浏览器全部通过，39能力对照不计播放。
+最终实际安装17类型/导出矩阵、完整CI1418及44重复契约通过，324生产TS，全部哈希核对。
+见[变更](changes/2026-09-12-PKG-MB-08-capability.md)与[证据](baselines/mb-capability-validation.json)。
+222项：105 done、7 doing、110 todo；立即专用本地提交。MB-TYPE-01/MB-READY-01关闭。
+下一项MB-09处理长播放、AV sync、原生DPiP与新旧核心组合；能力/设备、完整分发与许可门槛仍open。
+
 ## PKG-MB-08检查点：入口TS与兼容媒体声明（doing）

 全包34个自有生产模块已转TS，入口/Canvas桥/生命周期/清理分离。默认工厂仍可选Option、
@@ -170,6 +170,6 @@
 | FACTORY-TYPE-01 | open / 已复现 | Canvas and Ambilight default self property narrows assignability of historical factory replacements | PKG-FACTORY-01 |
 | MB-LICENSE-01 | open / 已复现 | Historical MediaBunny proxy bundles embed SDK code without MPL notice markers or separate license/source provenance | PKG-MB-10 |
 | MB-LIFE-01 | open / 已复现 | MediaBunny load, track replacement, timeout, RAF and audio callbacks lack one shared terminal owner | PKG-MB-02, PKG-MB-03, PKG-MB-04, PKG-MB-05, PKG-MB-06, PKG-MB-07, PKG-MB-09 |
-| MB-TYPE-01 | open / 已复现 | MediaBunny proxy declares only Canvas while exposing a shim and changes CommonJS export generation between releases | PKG-MB-08, PKG-MB-10 |
+| MB-TYPE-01 | resolved / 已复现 | MediaBunny proxy declares only Canvas while exposing a shim and changes CommonJS export generation between releases | PKG-MB-08, PKG-MB-10 |
 | MB-CAP-01 | open / 已复现 | Current Windows WebKit lacks WebCodecs and Web Audio constructors needed by historical MediaBunny proxies | PKG-MB-02, PKG-MB-09 |
-| MB-READY-01 | open / 已复现 | MediaBunny historical readiness can repeat for trackless input and occur after capability errors | PKG-MB-04, PKG-MB-09 |
+| MB-READY-01 | resolved / 已复现 | MediaBunny historical readiness can repeat for trackless input and occur after capability errors | PKG-MB-04, PKG-MB-09 |
@@ -3679,15 +3679,17 @@
        "PKG-MB-08",
        "PKG-MB-10"
      ],
-      "compatibleResolution": "Preserve optional whole-factory and exact Canvas assignment, model explicit shim capabilities separately and verify historical default namespace and callable consumers. MB-08 entry checkpoint preserves exact optional factory/Canvas assignment, adds opt-in checked media types without SDK imports, and fixes classic legacy/NodeNext ESM resolution. Seventeen installed compiler cases plus runtime exports passed against two frozen releases and candidate; seven candidate cases reject fifteen invalid uses each. Type facade/runtime export part is verified; final MB-08 capability and MB-10 distribution gates remain open.",
+      "compatibleResolution": "Preserved exact optional whole-factory and HTMLCanvasElement result; real VideoShim implements opt-in media/Player/HLS/synthetic-frame types without modern SDK declarations leaking to older compilers. Conditional ESM declarations and classic legacy resolution work. Runtime supports both historical default namespace and callable use without a required default property narrowing factory replacement. Final isolated installs of two frozen releases and candidate pass 17 compiler/runtime cases; seven candidate modes each reject fifteen invalid uses and check bidirectional assignments against actual frozen declaration bytes. Complete distribution/license/device gates remain separate.",
      "closureCriteria": "Actual installed old/candidate compiler and runtime export matrices pass with negative controls; any incompatible declaration generation requires an explicit decision.",
-      "status": "open",
+      "status": "resolved",
      "evidence": [
        "refactor/baselines/mb-release.json",
        "refactor/baselines/mb-contract.md",
        "refactor/changes/2026-09-12-PKG-MB-01-contract.md",
        "refactor/changes/2026-09-12-PKG-MB-08-entry-checkpoint.md",
-        "refactor/baselines/mb-entry-checkpoint.json"
+        "refactor/baselines/mb-entry-checkpoint.json",
+        "refactor/changes/2026-09-12-PKG-MB-08-capability.md",
+        "refactor/baselines/mb-capability-validation.json"
      ]
    },
    {
@@ -3711,20 +3713,22 @@
    {
      "id": "MB-READY-01",
      "title": "MediaBunny historical readiness can repeat for trackless input and occur after capability errors",
-      "status": "open",
+      "status": "resolved",
      "confirmation": "reproduced",
      "owners": [
        "PKG-MB-04",
        "PKG-MB-09"
      ],
-      "compatibleResolution": "Use explicit coordinated readiness and failure state, preserving valid event order while preventing duplicate or stale callbacks; evaluate trackless behavior separately from normal media. MB-04 coordinates metadata once, suppresses stale readiness and rejects trackless input before decoder setup. Existing-track unsupported-codec behavior and full native combinations remain MB-05/06/09; risk stays open. MB-08 entry checkpoint reproduces remaining false readiness in both previous and candidate builds: actual SDK-parsed video-only MP4 with controlled canDecode=false and AudioContext yields null audio/video sinks but readyState 4 and all readiness events, including replaceTracks. Keep open for the next MB-08 capability implementation; this controlled case is not native decoding evidence.",
+      "compatibleResolution": "Coordinated metadata publishes once, trackless input rejects before decoder setup, and stale callbacks cannot publish. MB-08 additionally rejects existing but wholly undecodable tracks before metadata/data/canplay and before replacement success, preserving one usable audio/video track, SDK query errors and late-operation cancellation. Sixteen controlled Node cases and thirty added browser cases distinguish twelve controlled rejection cases, eight native partial-decoder playback cases and ten missing-API controls; the final 150-case media suite passes. Physical Safari/support-range work remains MB-CAP-01 rather than being claimed from these controls.",
      "closureCriteria": "Candidate metadata/data/canplay ordering and counts pass normal, absent-track and failure interleavings in native browsers and controlled race tests.",
      "evidence": [
        "refactor/changes/2026-09-12-PKG-MB-02-baseline.md",
        "refactor/baselines/mb-behavior-validation.json",
        "refactor/changes/2026-09-12-PKG-MB-04-coordination.md",
        "refactor/baselines/mb-coordination-validation.json",
-        "refactor/baselines/mb-entry-checkpoint.json"
+        "refactor/baselines/mb-entry-checkpoint.json",
+        "refactor/changes/2026-09-12-PKG-MB-08-capability.md",
+        "refactor/baselines/mb-capability-validation.json"
      ]
    }
  ]
@@ -3546,14 +3546,17 @@
        "ENG-04",
        "ENG-06"
      ],
-      "status": "doing",
+      "status": "done",
      "risk": "H",
      "deliverable": "8 个自有 JS 模块迁移与 Result/shim 类型",
      "acceptance": "解码器/Stream/DOM 类型清楚，旧 Option 和 art.mediabunny 使用保持",
      "evidence": [
        "baselines/mb-entry-source.json",
        "changes/2026-09-12-PKG-MB-08-entry-checkpoint.md",
-        "baselines/mb-entry-checkpoint.json"
+        "baselines/mb-entry-checkpoint.json",
+        "baselines/mb-capability-source.json",
+        "changes/2026-09-12-PKG-MB-08-capability.md",
+        "baselines/mb-capability-validation.json"
      ]
    },
    {