refactor(auto-thumbnail): [PKG-AUTO-THUMB-03] wait for native frame presentation

refactor/changes/2026-09-13-PKG-AUTO-THUMB-03-frame-presentation.md

@@ -0,0 +1,47 @@
+# PKG-AUTO-THUMB-03 原生帧就绪检查点（doing）
+
+新增frames.js，集中拥有每次抽帧的数据等待、seek、原生帧回调和30秒deadline。
+同时支持requestVideoFrameCallback及cancelVideoFrameCallback时，等待loadeddata后
+注册回调再seek，必须seek完成且帧已呈现才draw。无该能力时仍用已记录的seek路径，
+不以UA字符串选择浏览器。每次重试递增回调身份，阻止被取消的旧回调完成当前帧；
+每个job只注册一个统一清理函数，避免逐帧累计清理闭包。
+
+销毁、切源、正常完成及失败均释放timer、帧回调、data/seek处理器。句柄0有效；
+同步注册/销毁交错产生的迟到句柄也回收。清理一个资源抛错仍继续其他清理，失败保留
+之前的可用预览。等待超时使用既有console.warn通道；未新增公开参数、结果或依赖，
+不改变注册Promise和目标时间公式。30秒是每次数据/seek/帧等待上限，尚不是全部网络、
+编码、后台标签和整体内存预算；不声称已完成这些边界。
+
+新增19项回归，纳入test:unit及test:auto-thumbnail。此前a128706f检查点19项为
+2通过/17失败；两项保留原兼容行为，其余覆盖就绪、两种事件顺序、超时、取消、重试、
+重复/迟到回调、同步重入、清理异常及旧预览保留。加上原33项生命周期共52项。
+
+提交前追加审查抓到readyState getter触发销毁后仍可能装回loadeddata处理器；新测试
+在修复前19项18通过/1失败，修复为读完就绪状态后再核对任务身份。此前1817项CI和84项
+原生结果保留为中间证据，最终证据使用frames-final文件，重新构建后核对全部候选。
+
+真实像素验收增强为：有原生帧回调时必须五格全部正确，包括单独紫色首帧、第二格红色、
+合法黑色、蓝色和黄色，同时核对实际呈现时间。空间样本防止1px平均色伪修复。新增原生
+回调被挂起期间destroy/restart测试，之后重复交付也不生成URL/写入/恢复decoder。
+无原生回调的浏览器相应场景使用原生Blob挂起，报告明确标出能力和路径。
+
+Chromium/Firefox此前的早期像素问题进入候选验证；Windows WebKit26.6没有该帧回调，
+前两格继续诊断而不验收，仅第2-4格沿用已有像素断言。未将实验或局部通过扩成全浏览器
+正确，也未关闭AUTO-THUMB-PIXEL-01、标记03完成。物理Safari及核心组合仍属后续验收。
+
+正常构建再生三份dist及docs副本，架构地图和任务/风险证据同步。TS仍留在04。
+见[验证](../baselines/auto-thumbnail-frame-presentation.json)。
+
+最终源码/main/legacy各52项单元通过；原生源码两轮42项及main/legacy各21项，共84项
+通过，0重试/跳过/未处理页面错误。完整CI1818项（1572单元+14工程+232基线）、339生产TS
+及4种实际bundle入口通过；产物与docs副本字节相等。旧产物新浏览器断言2通过/4失败，
+包括缺少原生呈现证据和Firefox早期错误像素；不得称为所有旧浏览器都出现同一故障。
+
+独立密集采样实验在Chromium/Firefox对0/.005/.01/.02/.03/.04秒均收到帧回调，前五个
+目标保留紫色首帧，.04秒为红色，未出现同一帧重复采样导致等待卡死。该实验不是完整
+默认100格候选验收。WebKit另测createImageBitmap(video)仍有首帧偏移，VideoFrame
+不可用；保留原始结果，不据此豁免像素风险。
+
+去B帧的独立媒体对照中，Chromium仍读到紫色首帧，而Windows WebKit隐藏元素0秒
+仍为空、.01秒已变红，普通元素的一轮seek还超时；不能把问题简单归因于B帧，也不能
+统一偏移.04秒。该诊断保留输入指纹和生成命令，未修改生产回退算法或声明能力豁免。

refactor/plan.md

@@ -496,7 +496,7 @@
 - PKG-AUDIO-05: [记录](changes/2026-09-12-PKG-AUDIO-05-combinations.md) [记录](baselines/audio-combinations-first.json) [记录](baselines/audio-combinations-checkpoint.json) [记录](audio-validation.md)
 - PKG-AUTO-THUMB-01: [记录](baselines/auto-thumbnail-release.json) [记录](baselines/auto-thumbnail-contract.md) [记录](changes/2026-09-13-PKG-AUTO-THUMB-01-contract.md) [记录](baselines/auto-thumbnail-contract-validation.json)
 - PKG-AUTO-THUMB-02: [记录](baselines/auto-thumbnail-failures.md) [记录](baselines/auto-thumbnail-failures-validation.json) [记录](changes/2026-09-13-PKG-AUTO-THUMB-02-failures.md)
-- PKG-AUTO-THUMB-03: [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-lifecycle-checkpoint.md) [记录](baselines/auto-thumbnail-lifecycle-checkpoint.json) [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-hidden-renderer.md) [记录](baselines/auto-thumbnail-hidden-renderer.json) [记录](baselines/auto-thumbnail-timeline-media.json)
+- PKG-AUTO-THUMB-03: [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-lifecycle-checkpoint.md) [记录](baselines/auto-thumbnail-lifecycle-checkpoint.json) [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-hidden-renderer.md) [记录](baselines/auto-thumbnail-hidden-renderer.json) [记录](baselines/auto-thumbnail-timeline-media.json) [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-frame-presentation.md) [记录](baselines/auto-thumbnail-frame-presentation.json)
 - PKG-HLS-01: [记录](baselines/hls-control-contract.md) [记录](baselines/hls-control-release.json) [记录](changes/2026-09-11-PKG-HLS-01-contract.md)
 - PKG-HLS-02: [记录](hls-validation.md) [记录](baselines/hls-sdk.json) [记录](baselines/hls-validation.json) [记录](changes/2026-09-11-PKG-HLS-02-tests.md)
 - PKG-HLS-03: [记录](changes/2026-09-12-PKG-HLS-03-modules.md) [记录](baselines/hls-modules-validation.json) [记录](hls-validation.md)

refactor/progress.md

@@ -1,5 +1,16 @@
 # 进度与证据
 
+## PKG-AUTO-THUMB-03 原生帧就绪检查点（doing）
+
+新增frames模块，对支持的浏览器同时等待seek完成与原生帧呈现，补齐取消、超时、
+重复/迟到回调和重试身份。Chromium/Firefox五格像素全部验收，WebKit缺该API时前两格
+仍只诊断，像素风险继续open。19项新回归此前2通过/17失败；源码/main/legacy各52通过。
+最终原生源码两轮42项，main/legacy各21项，共84项通过；包含真实帧挂起时destroy/restart。
+完整CI1818项、339生产TS及4种bundle入口通过；见[验证](baselines/auto-thumbnail-frame-presentation.json)；
+[变更](changes/2026-09-13-PKG-AUTO-THUMB-03-frame-presentation.md)记录能力边界和后续要求。
+正常构建及文档同步，TS仍属04。222项：114 done、12 doing、96 todo；03未标完成。
+
+
 ## PKG-AUTO-THUMB-03 隐藏解码与错时seek重试检查点（doing）
 
 新增video模块，挂载隐藏且保持实际尺寸的解码元素，完善DOM回收及插入/清理重入。

refactor/risks.json

@@ -4113,11 +4113,13 @@
         "refactor/baselines/auto-thumbnail-failures-validation.json",
         "test/browser/auto-thumbnail-pixels.spec.js",
         "refactor/baselines/auto-thumbnail-hidden-renderer.json",
-        "refactor/baselines/auto-thumbnail-timeline-media.json"
+        "refactor/baselines/auto-thumbnail-timeline-media.json",
+        "test/auto-thumbnail-frames.test.js",
+        "refactor/baselines/auto-thumbnail-frame-presentation.json"
       ],
       "compatibleResolution": "Establish actual decoded-frame readiness for the existing timeline/grid and preserve silent independent extraction; do not waive colored pixel checks as unsupported media.",
       "closureCriteria": "Candidate source and artifacts generate usable sampled pixels on native browser controls with lifecycle checks; supported Safari and core combinations remain explicit final gates.",
-      "workspaceState": "Hidden intrinsic-sized attached decoder mitigates detached WebKit black later frames. Source 45 repeated native cases plus main/legacy 15 each verify lifecycle and cells 2-4 only. Initial cells 0-1 remain diagnostic: transparent/stale draws and Windows WebKit first-frame timing remain unresolved. Bounded retries now reject wrong-time seeked events before drawing. Do not close this risk or task03 based on partial pixel acceptance."
+      "workspaceState": "The frames module now waits for native presentation and seek completion on capable browsers. Chromium/Firefox source/main/legacy assert all five cells including first purple frame, second red cell, legitimate black and presentation times. Callback-less Windows WebKit first two cells remain diagnostic, later cells asserted; physical Safari/core combinations remain open. 84 native lifecycle/pixel cases passed with explicit held native-frame vs Blob-fallback paths; 19 new Node cases fail 17 ways on prior checkpoint and all 52 current cases pass per candidate. Risk and task03 remain open."
     }
   ]
 }

refactor/tasks.json

@@ -1786,7 +1786,9 @@
         "baselines/auto-thumbnail-lifecycle-checkpoint.json",
         "changes/2026-09-13-PKG-AUTO-THUMB-03-hidden-renderer.md",
         "baselines/auto-thumbnail-hidden-renderer.json",
-        "baselines/auto-thumbnail-timeline-media.json"
+        "baselines/auto-thumbnail-timeline-media.json",
+        "changes/2026-09-13-PKG-AUTO-THUMB-03-frame-presentation.md",
+        "baselines/auto-thumbnail-frame-presentation.json"
       ]
     },
     {