refactor(mediabunny): [PKG-MB-05] own video iterators, frame pools and rendering

refactor/changes/2026-09-12-PKG-MB-05-video.md

@@ -0,0 +1,80 @@
+# PKG-MB-05：视频迭代器、seek、晚帧与RAF
+
+任务通过完整CI后标记done，并立即以专用本地提交交付。冻结来源为5d0b1284，源码与实际main哈希见
+mb-video-source.json；SDK仍为已锁定MediaBunny 1.56.1，未升级依赖。
+
+## 实际实现
+
+VideoEngine.js已迁移为严格TS并删除VideoEngine.d.ts桥。拆出video-frames.ts、
+video-renderer.ts、video-poster.ts，包内共20个生产TS模块；仅AudioEngine.d.ts仍是
+显式的临时JS边界。ARCHITECTURE.md记录文件地图和状态/资源归属。
+
+- source/load、seek迭代和render活动分别拥有身份；旧load、第一/第二seek帧、能力查询和
+  异步frame读取结果不得覆盖新source或seek。新source开始解析时即取消旧视频操作。
+- 加载能力检测期间seek等待该加载，不能把合法metadata一起取消；暂停状态的正常seek
+  仍显示目标第一帧并保留第二帧。load/reset不等待废弃迭代器无限期返回。
+- 迭代器先同步脱离当前字段，再观察return；每个迭代器只释放一次。stop/start对同一
+  pending next共享读取，旧finally不清掉新fetch状态。
+- RAF每实例单一归属，ID 0有效；暂停、销毁与事件回调重入后不再排程旧任务。
+  未创建RAF的实例不能取消其他实例的ID 0。正常timeupdate/ended/stall事件顺序保持。
+- 海报请求有源身份和请求身份，替换、真正绘制帧、销毁时解除回调。
+- 活动后台解码失败停止渲染并通过协调器报告一次MediaError，音频清理异常不覆盖原错误。
+  后台iterator return拒绝有观察和警告；显式stopIterator保持Promise拒绝。
+- 无2D context时在实际使用阶段报明确错误，替代旧的空值TypeError；不会伪造就绪。
+
+默认dropLateFrames=false、容差/倍速公式、CanvasSink poolSize=2、contain、透明度保持。
+SDK的CanvasSink把VideoSample画入池化canvas后自行close；代理负责迭代器，不对WrappedCanvas
+调用VideoFrame.close，不增加每帧拷贝。公开factory/类型/Canvas门面与三种产物入口保持。
+
+## 证据
+
+38项新视频断言对5d0b1284实际main为7通过/31失败；候选全部通过。包专项146项通过。
+main/legacy各110项通过，106候选断言+4冻结正常对照。三格式构建与严格类型检查通过。
+最终浏览器结果归档并记录在mb-video-validation.json。54项由12普通真实播放、10真实
+解码帧竞态、9原生Stream取消、9synthetic RAF、11Windows WebKit能力对照、3无轨道拒绝组成。
+其中10个新竞态场景对旧main全部失败，另5能力对照通过；失败trace与报告完整保留。
+新场景使用实际SDK解析/解码、实际CanvasSink帧和浏览器时钟，只延迟一帧的交付来控制
+暂停/连续seek/切源时序。timeupdate回调暂停检查真实RAF，不是mock codec或纯事件出口测试。
+
+开发时修正了测试宿主：控制音频seek来隔离视频测试；两个实例的RAF测试直接创建两个实际
+VideoEngine，避免测试helper重复返回同一canvas。旧32项测试中25失败，扩展到37项后30失败。
+初始复现读取必须在下一次返回done，避免旧实现缺陷造成测试自身无限循环；没有扩大超时。
+
+## 后续
+
+MB-06继续实际音频解码、时钟与节点释放；MB-07继续并发HLS选轨和UI拓扑；MB-08完善
+消费者声明矩阵。MB-09仍需要长播放、AV同步和完整核心/插件/设备组合。既有轨道但不可解码
+时的fallback还需MB-CAP-01/MB-READY-01评审，不以这次晚帧修复宣布所有能力问题已关闭。
+MPL通知、8082示例与真实安装包在MB-10；未推送、打tag或发布。
+
+最终复核另复现了启动预取覆盖已排队第二帧，修复为消费该帧后再取下一帧，保持默认
+不丢帧意图及容差策略。新增第38项回归，旧main为7通过/31失败。首轮完整CI1306通过
+之后因这项实际源码修复重新构建、验证产物/浏览器并运行完整CI，不复用旧的绿色结果。
+
+进一步使用两个实际解码VideoSample在进入CanvasSink池化转换前暂停交付，连续seek
+1→3→5后释放旧样本：当前帧timestamp仍属于5秒，但排队canvas像素校验从1220654181
+变成2730873815。此缺陷在已通过第二轮CI的实现上也复现，报告为mb05-pool-before-results。
+已改为每个seek独立CanvasSink池（仍2个canvas，无每帧拷贝），保留公开canvas实例；
+内部sink身份可变化。对应浏览器测试跟踪SDK原型以覆盖新sink，而非绑定一次旧实例。
+修复后像素稳定；最终54项浏览器及对应旧main15项对照另行归档。
+
+构建中两次发生Windows copyfile UNKNOWN，仅覆盖已有docs/compiled legacy目标失败；
+源码和目标读取、r+打开及复制到cache均成功，磁盘空间充足。备份并移除该可再生目标，
+由正常yarn build重新生成后三格式构建成功，没有手改产物内容或扩大文件删除范围。
+首次54项浏览器所用main与重新完整构建的main哈希相同，仍有效；legacy重新运行110项检查。
+
+进一步补充新迭代器保持断言：Firefox旧切源在某次运行中未多画旧帧，却已被旧清理
+清空新迭代器，原画面断言不足以发现。新增断言后最终旧main10个原生竞态均失败，
+5个能力对照通过；先前9失败/6通过报告另存，不把同一副作用的不同调度结果隐去。
+
+最终浏览器清理断言改为按现有expect超时等待AudioContext真实closed状态；close本来是
+异步操作，固定两帧不足以判定失败。此处只调整测试等待，生产代码未改。末次完整CI
+1307项覆盖最终生产源码；之后单独重跑浏览器spec lint和全部54浏览器用例。旧main
+同样重跑15项以保留清理后的原始视频断言结论，未提高超时或跳过失败。
+
+最终完整CI1307项（1152单元+14工程+141基线）通过，另44重复契约；310生产TS。
+源码、测试、产物与报告哈希已核验，三格式docs/compiled与dist逐字节一致。
+38视频断言在旧main为7通过/31失败；最终包专项146、main/legacy各110、浏览器54均通过。
+旧产物10个原生帧竞态失败均为绘制计数、帧像素、迭代器保留或RAF状态断言，不是超时：暂停后绘制2→10，
+旧seek结果在新seek/source后绘制2→3，timeupdate暂停后残留1个RAF；候选均无此残留。
+回退可revert专用提交，原始5d0b1284及基线保持可追溯。下一项PKG-MB-06继续音频引擎。