refactor(mediabunny): [PKG-MB-07] own HLS selection intent and menu lifecycle

2026-10-14 16:36:18 -08:00 · 2026-09-12 20:51:31 +08:00
1 parent ccee9157a7
commit 8a2b56e829
@@ -0,0 +1,13 @@
+{
+  "task": "PKG-MB-07",
+  "sourceCommit": "ccee9157a70725e7f6bf77dc43ff2566bfa14540",
+  "sourceSha256LF": {
+    "packages/artplayer-proxy-mediabunny/src/m3u8.js": "4639f09e0c743dc2b24078f48ca1e58eaaedaa3f5e6b863583cbd4bc4a7d3142",
+    "packages/artplayer-proxy-mediabunny/src/hls-selection.ts": "a8632c0ea7d0c59434de005eee81bbf8d1dea8ae73c690673b603e5d6fa3cfd6",
+    "packages/artplayer-proxy-mediabunny/src/hls-state.ts": "ff9ffd742f9763349df1f50eac6b6bd488a80d05aaab8ca198f387f0d17d5e25",
+    "packages/artplayer-proxy-mediabunny/src/MediaBunnyEngine.ts": "3d51f6ecd247d1622809b5b679b906eb9b5ad4f9332a5d52dd38e5e2e29f38e9",
+    "packages/artplayer-proxy-mediabunny/src/playback.ts": "e2a65782c89627198752ff1fe691d4eea0bef215d883a59f0bdcd3e904a4fb47",
+    "packages/artplayer-proxy-mediabunny/src/index.js": "4e1be8937908ff6e6ef8a4e863e22b4468312cf31d66ac299322e475757773bb",
+    "packages/artplayer-proxy-mediabunny/dist/artplayer-proxy-mediabunny.js": "c80fd9015dd5d9c338ea780948dcb82f97a32f8395de20e19daf5cc65f05eb57"
+  }
+}
@@ -0,0 +1,70 @@
+# PKG-MB-07：HLS配对、选择意图与UI拓扑
+
+任务通过完整CI后标记done，并立即以专用本地提交交付。来源ccee9157a70725e7f6bf77dc43ff2566bfa14540，
+冻结源码及main见[来源基线](../baselines/mb-hls-source.json)，最终检查、报告和哈希见
+[验证记录](../baselines/mb-hls-validation.json)。
+
+## 实际结构
+
+删除m3u8.js，迁移为m3u8.ts，拆出m3u8-model.ts、m3u8-menu.ts、m3u8-types.ts。
+协调模块管理refresh版本、选择意图、source与事件；model生成label、排序和selector；
+menu拥有controls/setting两个独立入口，types限定所需UI/shim能力，避免接收不受约束的art。
+包内30个生产TS模块，剩index.js由MB-08接续。tsconfig引用现有共享assets.d.ts声明SVG导入；
+没有新依赖，public Option/Result/factory声明未修改。
+
+hls-selection.ts统一质量/音频请求的意图标识与source/Input检查，并分别保留配对策略。
+较新的请求使尚在查询的旧请求失效，包括质量和音频交叉选择。已进入replaceTracks的操作
+仍由Playback控制，到下一个replacement开始才被替代，不声称点击即同步终止SDK解码。
+当先前replacement在最新查询期间安装另一份media时，最新查询对新的media重新计算，
+避免简单的media相等检查丢弃最新意图，或Auto音轨按旧视频配对。当前查询失败仍拒绝；
+过期查询/替换失败被观察，不覆盖当前选择。状态getter同时检查source代数和media身份。
+
+## 兼容与生命周期修复
+
+保留原有mediabunny-quality/audio名称、右侧control、setting宽度200、图标、间距、
+标题/Auto/getName默认值、质量降序、通知格式、onSelect Promise与label返回值。
+Auto仍是操作入口，显示与高亮基于实际选择轨道；自动模式下也不会只按mode伪造高亮。
+相同label仍合并，但合并组中保留实际选中的ID，修复选中项被前一个同名条目遮蔽的问题。
+排序改为提前建立height索引，避免比较器反复find数组。
+
+refresh版本与选择意图分开：迟到状态不覆盖新模型，同一可见菜单在首个选择未完成时
+仍接受下一次点击；自身loadedmetadata刷新不使有效选择的完成失效。被替换菜单或旧source
+回调不再切轨、通知或刷新。选择失败恢复实际轨道高亮后保持原拒绝，恢复期间被新意图替代的
+旧失败不再外溢；事件自动refresh明确观察拒绝。getName和registry回调的同步切源/销毁
+在每个后续阶段前重新检查，避免重建已关闭UI。
+
+control/setting分别拥有与移除。关闭一侧会清理它并保留另一侧；单音轨/纯视频清理audio，
+非HLS清理两类菜单；loadstart/error/destroy立即使旧工作失效并清理已拥有入口。
+清理尝试全部入口和全部监听器，即使其中一个抛错也继续，并保证入口的shim销毁仍执行。
+这些模块不对外新增canvas属性或API；EnginePort补充已有只读source/destroyed能力用于内部检查。
+
+## 复现与验证
+
+- 首批27条旧main断言5通过/22失败；最终43条旧main为11通过/32失败，无取消或跳过。
+  候选全部通过，覆盖乱序刷新、旧回调、单入口关闭、失败恢复、清理异常、实际选中ID、
+  连续/跨类型轨道选择和配对期间media变化。配对和失败恢复的中间候选缺陷另有复现日志。
+- 候选包专项226通过；main/legacy各202通过，每个产物命令含198候选断言及4冻结正常事件对照。
+- 新增30浏览器场景：两套真实核心×五类场景×三个引擎。Chromium/Firefox共20项真实
+  MediaBunny解析/解码和DOM菜单验证；Windows WebKit10项明确媒体能力缺失对照。
+- 同30条浏览器断言对旧main：14通过/16失败。四个正常菜单场景和十个能力对照通过；
+  失败分布在单侧control关闭、旧source/destroy状态写回、最新选择被早期请求覆盖。
+  单侧关闭失败是明确等待目标UI被删除未满足，其余是状态/写入次数/最终轨道断言。
+- 真实菜单场景点击quality控件和audio设置项，再切Auto，验证实际配对与两个入口高亮；
+  每次替换恰好一套loadedmetadata/loadeddata/canplay/canplaythrough/seeked，三次共三套。
+- 首次Firefox检查在解码完成前读取事件计数（为0）而失败，改用原超时等待精确完成序列；
+  下一轮暴露轮询未处理状态getter合法的临时null，改为等待非null目标值。没有放宽事件数量、
+  静默跳过或拉长超时，失败报告/results均保留。
+- 最终构建main运行全部七个MediaBunny浏览器文件；详细结果在验证记录中核验。
+- 严格TS、lint、三格式build、ESM默认factory及dist/docs逐字节一致性单独检查。
+  根test:unit与test:mediabunny加入HLS断言，完整CI持续执行。
+
+最终完整CI1387项（1232单元+14工程+141基线）通过，另44重复契约；320生产TS。
+全部七个MediaBunny浏览器文件108项通过，其中29项为Windows WebKit能力缺失对照。
+最终源码/测试/产物/报告哈希已核验，main与浏览器所测文件字节一致，dist与docs三格式一致。
+
+## 后续与回退
+
+MB-LIFE-01仍open，剩长播放、完整媒体/核心/插件组合和物理设备证据归MB-09；编码能力/
+undecodable fallback与公共shim/factory声明由MB-08及MB-CAP-01/MB-READY-01处理。
+MB-10验证demo、真实安装包和MPL/source通知。本项通过不构成npm发布验收。
+回退revert专用提交，历史冻结源码与报告保留。下一项MB-08完成入口TS、能力与声明边界。
@@ -71,3 +71,12 @@ main/legacy各159通过。最终78浏览器含16新增原生音频场景及8新
 同24音频浏览器断言对旧main20通过/4失败，失败为实际暂停后的节点清理；其余为回归对照。
 短时1×/2×帧/音频时钟偏差验证不替代长播放、听觉及设备验收；全部报告/results已归档。
 完整CI1344项及另44重复契约通过，316生产TS；完成后立即专用提交，MB-LIFE-01剩余范围仍open。
+
+## PKG-MB-07 HLS配对、选择与UI拓扑
+
+实际m3u8迁移并拆成四个TS模块，包内30生产TS，仅index.js由08接续。
+[变更](changes/2026-09-12-PKG-MB-07-hls.md)记录刷新/选择/source归属、稳定media配对、
+兼容默认值、清理及回退；[证据](baselines/mb-hls-validation.json)记录43条断言旧main
+11通过/32失败，候选专项226及main/legacy各202通过。最终108浏览器含20新增原生HLS
+新旧核心/UI/SDK场景与10新增能力对照。旧main同30项14通过/16失败，未把能力缺失计作播放。
+全部报告/results已归档；完整CI1387项及44重复契约通过，320生产TS；完成后立即专用提交，MB-LIFE-01剩余组合/长播范围仍open。
@@ -4,7 +4,7 @@

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

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

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

@@ -335,7 +335,7 @@
 | PKG-MB-04 | artplayer-proxy-mediabunny<br>整理 VideoShim/EventTarget/Engine 协调 | PKG-MB-03, CORE-06, CORE-11 | shim 描述符、事件桥、加载状态和操作隔离 | 公开属性/同步异步返回与事件重入顺序保持 | H | done |
 | 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 | todo |
+| 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 | todo |
 | 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 |
@@ -526,4 +526,5 @@
 - PKG-MB-04: [记录](baselines/mb-coordination-source.json) [记录](changes/2026-09-12-PKG-MB-04-shim-checkpoint.md) [记录](baselines/mb-shim-checkpoint.json) [记录](changes/2026-09-12-PKG-MB-04-coordination.md) [记录](baselines/mb-coordination-validation.json)
 - 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-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,18 @@
 # 进度与证据

+## PKG-MB-07完成：HLS配对、选择意图与UI拓扑
+
+m3u8实际迁移为四个TS模块，包内30生产TS，仅剩index.js待MB-08。
+旧查询/菜单回调不再覆盖当前source；control/setting各自清理，失败恢复实际轨道高亮。
+质量/音频共享最新选择意图，media在配对查询期间变化会重新计算，保留匹配轨道与正常默认行为。
+43断言旧main11通过/32失败，候选专项226、main/legacy各202通过；旧main30项HLS浏览器
+14通过/16失败，候选20新增原生新旧核心/UI/SDK场景和10能力对照通过。最终全部七个
+MediaBunny文件108浏览器通过，29项为能力对照，不计作播放。完整CI1387及44重复契约通过，
+320生产TS；源码/产物/报告哈希及三格式复制一致。
+见[变更](changes/2026-09-12-PKG-MB-07-hls.md)与[证据](baselines/mb-hls-validation.json)。
+222项：104 done、7 doing、111 todo；立即专用本地提交，下一项MB-08入口、能力与声明。
+长播放、全组合、设备及安装包仍待后续；未放行npm发布。
+
 ## PKG-MB-06完成：音频解码、时钟与资源归属

 AudioEngine实际迁移TS，拆清clock、context、nodes、pump、task职责，删除最后音频声明桥。
@@ -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. 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. MB-04 shim checkpoint fixes synthetic RAF retention and terminal event-listener cleanup, including engine cleanup exceptions. Closing the event bridge does not prove pending engine operations stopped; coordination remains in progress. MB-04 now guards play/seek/replacement completion, preserves explicit pause, observes stale failures and isolates reentrant event sequences. Decoder-internal late frames/audio and HLS UI races remain MB-05/06/07; risk stays open. MB-05 migrates VideoEngine and owns iterators, late first/second seek frames, pending reads, per-instance RAF and poster callbacks; same native race assertions fail on old main and pass on candidate. Independent CanvasSink pools also prevent multiple obsolete seek samples from overwriting queued current-frame pixels. Audio nodes, long-run AV sync and HLS UI topology remain MB-06/07/09. MB-06 migrates AudioEngine into six checked modules, owns context/gain/nodes/iterators and removable cancellation waits, preserves clock and gain formulas, and invalidates pending resume/decoding across pause/source/destroy. Same old main fails 29 of 37 audio assertions and four native pause-cleanup cases; candidate passes with short native 1x/2x AV-clock samples. Long-run AV sync, full combinations and HLS UI topology remain MB-07/09, so risk stays open.",
+      "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. MB-04 shim checkpoint fixes synthetic RAF retention and terminal event-listener cleanup, including engine cleanup exceptions. Closing the event bridge does not prove pending engine operations stopped; coordination remains in progress. MB-04 now guards play/seek/replacement completion, preserves explicit pause, observes stale failures and isolates reentrant event sequences. Decoder-internal late frames/audio and HLS UI races remain MB-05/06/07; risk stays open. MB-05 migrates VideoEngine and owns iterators, late first/second seek frames, pending reads, per-instance RAF and poster callbacks; same native race assertions fail on old main and pass on candidate. Independent CanvasSink pools also prevent multiple obsolete seek samples from overwriting queued current-frame pixels. Audio nodes, long-run AV sync and HLS UI topology remain MB-06/07/09. MB-06 migrates AudioEngine into six checked modules, owns context/gain/nodes/iterators and removable cancellation waits, preserves clock and gain formulas, and invalidates pending resume/decoding across pause/source/destroy. Same old main fails 29 of 37 audio assertions and four native pause-cleanup cases; candidate passes with short native 1x/2x AV-clock samples. Long-run AV sync, full combinations and HLS UI topology remain MB-07/09, so risk stays open. MB-07 migrates HLS UI to four checked modules, guards stale refresh/selection callbacks, cleans each surface and owns terminal listeners. Quality/audio queries share a latest-intent token and retry pairing against changed media snapshots. Forty-three old-main assertions yield 11 pass/32 fail; sixteen old native UI/query cases fail and twenty candidate native cases pass across old/new cores. Long-run AV sync and full combinations remain MB-09; capability/type/package gates remain MB-08/10.",
      "closureCriteria": "Historical failing interleavings and candidate cancellation/cleanup pass with real media and event evidence, including long playback and track topology.",
      "status": "open",
      "evidence": [
@@ -3666,7 +3666,9 @@
        "refactor/changes/2026-09-12-PKG-MB-05-video.md",
        "refactor/baselines/mb-video-validation.json",
        "refactor/changes/2026-09-12-PKG-MB-06-audio.md",
-        "refactor/baselines/mb-audio-validation.json"
+        "refactor/baselines/mb-audio-validation.json",
+        "refactor/changes/2026-09-12-PKG-MB-07-hls.md",
+        "refactor/baselines/mb-hls-validation.json"
      ]
    },
    {
@@ -3524,11 +3524,15 @@
        "PKG-MB-06",
        "CORE-14"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "H",
      "deliverable": "m3u8 配对、质量/音频选择及拓扑清理",
      "acceptance": "实际选择高亮、切到无轨道来源清理、无重复 readiness",
-      "evidence": []
+      "evidence": [
+        "baselines/mb-hls-source.json",
+        "changes/2026-09-12-PKG-MB-07-hls.md",
+        "baselines/mb-hls-validation.json"
+      ]
    },
    {
      "id": "PKG-MB-08",