refactor(mediabunny): [PKG-MB-06] own audio clocks, buffers and context lifecycle

refactor/changes/2026-09-12-PKG-MB-06-audio.md

@@ -0,0 +1,72 @@
+# PKG-MB-06：音频解码、时钟与资源归属
+
+任务通过完整CI后标记done，并立即以专用本地提交交付。来源是9d037dcbf913fef2d2a9eb4f3924d6abf3ab5597，
+冻结旧AudioEngine、协调器、playback和main的LF哈希见[源码基线](../baselines/mb-audio-source.json)。
+候选文件、测试、产物和浏览器报告见[验证记录](../baselines/mb-audio-validation.json)。
+
+## 实现与拆分
+
+实际删除AudioEngine.js及临时AudioEngine.d.ts，迁移到AudioEngine.ts；拆出audio-clock、
+audio-context、audio-nodes、audio-pump、audio-task五个模块，分别管理时钟计算、
+Context/Gain、源节点、SDK迭代器/背压、取消等待/计时器。模块地图和维护命令同步到
+包内ARCHITECTURE.md。包内26个生产TS模块，没有遗留JS声明桥；index.js和m3u8.js
+分别由MB-08/07接续，不能据此声称整个包已经完成TS化。
+
+source、play和pump分别拥有取消状态。暂停会取消尚未完成的resume；新source在解析轨道
+之前就使旧音频操作失效。迟到的canDecode、resume、next不能重建context、写入sink、
+发出旧playing或排队旧节点。迭代器同步脱离引用、return只调用一次且观察拒绝。
+每批16buffer、0ms让出及1秒/50ms背压参数保留，任务释放包含ID零的计时器。
+复查新实现时消除了对单个长期未决Promise反复race的设计：每次读取完成就移除取消回调，
+避免正常长播放累积已完成读取的等待监听。这是源码审查改进，不声称已做长时间堆内存验收。
+
+节点在start前即登记归属，自然ended也断开连接并清除回调；暂停、seek、倍速与destroy
+停止/断开旧队列。一个节点失败仍尝试其余节点及Context/Gain清理，保留首个失败。
+后台解码失败先停止播放并报告一次MediaError；清理失败不会替换解码原始错误。
+Context/Gain设置成功后才安装引用；失败释放部分资源，销毁清空引用并观察close拒绝。
+真正异步的AudioContext.close通过浏览器状态轮询验证，不以固定两帧声称关闭完成。
+
+## 兼容边界与修复行为
+
+公开factory、canvas转发、声明、默认选项、三种分发入口及MediaBunny 1.56.1依赖保持原有契约。
+时钟仍按锚点和倍速计算，volume仍用平方增益，mute为零；暂停冻结位置，seek/rate更新锚点。
+无音轨但有视频仍使用Web Audio时钟，完全无轨道容器继续MB-04的明确拒绝行为。
+已完全过期的buffer不再创建无效节点，部分迟到buffer保留原offset计算。视频结束会停止
+音频时钟和余留节点，倍速切换会停止旧速节点。仍使用原生source.playbackRate，未引入保调算法。
+
+原先playback层缓存整个audio.play Promise；如今音频play可在取消时提前完成，该缓存不再
+能代表底层resume状态，因此去重下移到ContextOwner。协调器新意图各调用audio.play，
+实际原生resume仍共享一次。受控协调器测试的audio.play调用数由1改为2，新增实际AudioEngine
+测试验证play→pause→play的原生resume次数仍为1，只有当前意图启动视频。
+这项变化是内部归属修正，不能把stub调用数变化隐瞒为原样不变的测试。
+
+## 验证与证据边界
+
+- 37项新增音频断言：最终候选全部通过；同一断言对旧main为8通过/29失败，无取消或跳过。
+  首轮旧测试的一项等待夹具超时已归档；修正夹具在finally释放受控读后，最终旧基线没有超时。
+- 包专项183通过，main/legacy各159通过；每个产物命令含155候选断言及4个冻结正常事件对照。
+- 新增24项浏览器：Chromium/Firefox各8项实际Web Audio/SDK解码场景，Windows WebKit
+  8项精确能力缺失对照。包括暂停恢复、1×/2×、增益/静音、无音轨时钟、迟到buffer与resume、
+  seek后的HLS音画时钟取样。短时实际绘制帧与音频时钟偏差上限为250ms，报告保存原始样本；
+  这不是听觉输出、长时间漂移、物理设备或所有Safari安装的验收。
+- 同24项对旧main：20通过/4失败；失败是Chromium/Firefox音频与HLS暂停后节点/回调
+  仍保留的状态断言，不是加载超时。其他旧浏览器场景通过属于回归对照，不能算作复现缺陷。
+- 最终构建main运行全部六个MediaBunny浏览器文件，共78项：包含既有视频竞态、输入、
+  Stream取消及synthetic RAF。报告与整个results目录在下一次运行前归档。
+- 严格TS、lint、三格式构建、ESM默认factory和dist/docs逐字节一致性独立核验。
+- 本项不增加依赖；根test:unit与test:mediabunny加入音频测试，使完整CI持续执行。
+
+最终完整CI1344项（1189单元+14工程+141基线）通过，另44重复契约；316生产TS。
+最终78浏览器报告中，Chromium 27个播放帧取样最大偏差39.34ms，Firefox 28个取样最大
+偏差37.67ms。所有源码/测试/产物及报告哈希已复核，dist与docs/compiled三个格式一致。
+
+## 环境问题与后续
+
+一次Windows copyfile UNKNOWN发生在构建复制既有legacy生成文件时。保留失败日志和旧生成文件，
+核对唯一绝对路径后删除该生成目标，再由正常yarn build重建；未手改生成内容或停止用户进程。
+首轮78浏览器报告也保留，因为取消等待实现随后改进，最终产物重新构建并重跑对应验证。
+
+MB-LIFE-01仍open：音视频各自的取消与短时组合已覆盖，HLS UI拓扑/并发选择、长播放/AV同步、
+codec能力矩阵和全核心/插件组合仍由MB-07/08/09及能力风险条目处理。MB-10承担真实安装包、
+demo与MPL/source通知；本项通过不是npm发布许可或发布验收。
+
+回退通过revert本项专用提交，冻结旧实现保持可追溯。下一步MB-07整理m3u8.ts选择与拓扑清理。