fix(danmuku): [PKG-DANMUKU-12] keep frame sampling during async placement

2026-10-18 19:01:20 -08:00 · 2026-09-13 22:49:26 +08:00
1 parent df6a6fe82e
commit 4f559cb31d
@@ -0,0 +1,67 @@
+# PKG-DANMUKU-12 连续采样与串行放置
+
+07原生诊断确认：beforeVisible等待600ms时，浏览器仍以约19–64ms媒体间隔出帧，
+但旧调度不再读取readys达约583–647ms，中间已到时弹幕未被选中。单次ready快照
+还会使已显示弹幕的到期回收等待后续异步准备。拆分本任务处理，07仍独立待验收。
+
+## 设计与兼容边界
+
+- 保留公开readys的当前时间±0.1秒规则，不补扫过去时间、不追赶seek跨过的区间。
+  每次真实RAF继续维护可见寿命并采样。已经真实采到的项由内部buffer保留引用，
+  不擅自把公开wait状态改为ready，不复制/替换队列对象。
+- 用户beforeVisible和Worker放置仍串行，最多一个异步批次。当前批次不重排，
+  批内所有项保留身份占位直到整批结束，false/无轨道只能在后续RAF再捕获。
+  下一批次从pending按当前ready优先、各组捕获顺序构造，防止轨道满的ready行
+  反复抢占同批后续wait。
+- pause/stop/reset/替换加载/seek/hide/destroy及失败恢复保持既有代际取消；清空
+  buffered引用，旧Promise迟到不能清掉新批次或显示已取消行。拒绝按本代跳过，
+  false仍以未来真实采样决定是否重试；没有任意条数上限或并行用户回调。
+- 明确内部变化：等待异步准备时仍有一个待执行RAF，而不是把采样也暂停。公开
+  事件顺序、门面返回与声明不变；先前漏采样而丢失的弹幕可在其串行轮次显示。
+
+本任务已完成实现与验证，任务和提交状态以tasks.json及Git为准。主线程完全卡住造成的未采样窗口
+没有被本设计恢复，不得把这个修复称为任意负载下无漏弹幕。
+
+## 实现与测试依据
+
+`scheduler.ts` 拆开实际帧维护与异步批次，`scheduling-buffer.ts` 只持有观察过的
+行引用及当前批次占位。没有新增依赖、公开字段、回调、声明或分发入口。
+保留 API-04/05/07/08/11/12 边界；只修正异步等待期间漏采样和延期回收。
+源码受控红测10项中3项失败，分别证明没有继续排队RAF、中间行丢失、可见行
+未按期回收；其余7项覆盖取消和轨道占用保护。
+
+最初原生红测有两项失败：候选确实丢失middle；已发布插件还触发其已知的
+play/playing双循环，使对旧版新增的“回调串行”断言失败。该串行断言只适用
+重构候选；旧版保留缺失middle的精确历史断言，不伪称旧版有串行保证。
+首次接入后单测65/66通过，余下一项仍断言异步期间RAF为0；按明确的新内部
+调度约束改为1，并增加执行该帧后callback仍只调用一次的保护，未放松公开事件。
+
+包内 ARCHITECTURE.md 已同步文件职责、采样/放置关系、代际清理及CPU阻塞限制。
+最终命令、构建格式、浏览器版本和结果在本任务机器证据中记录后才关闭任务。
+
+最终验证：Node 24.21.0 / Yarn 1.22.22，完整源码264项、main/legacy调度与Worker
+各68项全部通过。独立审查新增旧代finally不清新buffer、跨帧ready优先两项保护。
+源码/main/legacy各102项原生浏览器测试全部通过，0重试/跳过；其中每格式66项
+两核心调度、24项新旧插件真实延迟Worker寿命，以及12项候选核心时间窗口测试。
+后者有6项CPU阻塞诊断，并不证明无漏弹幕；准确范围见机器证据。
+分包严格TS、目标lint、三格式构建和严格工具链检查通过；没有新增依赖或修改声明。
+
+可重跑命令：
+
+```sh
+yarn test:danmuku
+yarn exec tsc -p packages/artplayer-plugin-danmuku/tsconfig.json --noEmit
+yarn build artplayer-plugin-danmuku
+yarn test:browser test/browser/danmuku-timing-diagnostic.spec.js test/browser/danmuku-scheduler.spec.js test/browser/danmuku-lifetime.spec.js --workers=2
+```
+
+产物复跑分别设置 `ARTPLAYER_DANMUKU_ARTIFACT` 为dist下的 `.js` / `.legacy.js`，
+每次等待进程终态并归档报告再启动下一格式。受控产物测试运行
+`node --test test/danmuku-scheduler.test.js test/danmuku-worker-client.test.js`。
+证据：[danmuku-frame-sampling-validation.json](../baselines/danmuku-frame-sampling-validation.json)。
+
+## 发布与回退
+
+沿用每包下一major及原接口兼容政策，本次没有发布授权。回退本任务的scheduler、
+buffer和生成产物即可恢复11的串行采样实现；保留测试用于展示回退会重现的漏采样。
+不要同时回退11已修正的Worker可见寿命起点。07仍需真实持续负载、资源及Mask验收。
@@ -2,9 +2,9 @@

 > 由 tasks.json 生成。请修改数据后运行 `node refactor/scripts/plan.mjs --write`，不要手改本表。

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

-状态：todo 68 / doing 15 / blocked 0 / done 147 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 68 / doing 15 / blocked 0 / done 148 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -22,7 +22,7 @@
 | artplayer-plugin-auto-thumbnail | 1.1.0 | PKG-AUTO-THUMB-01, PKG-AUTO-THUMB-02, PKG-AUTO-THUMB-03, PKG-AUTO-THUMB-04, PKG-AUTO-THUMB-05, PKG-AUTO-THUMB-06 |
 | artplayer-plugin-chapter | 1.1.0 | PILOT-01, PKG-CHAPTER-01, PKG-CHAPTER-02, PKG-CHAPTER-03, PKG-CHAPTER-04, PKG-CHAPTER-05, PKG-CHAPTER-06 |
 | artplayer-plugin-chromecast | 1.1.0 | PKG-CAST-01, PKG-CAST-02, PKG-CAST-03, PKG-CAST-04, PKG-CAST-05, PKG-CAST-06 |
-| artplayer-plugin-danmuku | 5.3.0 | PKG-DANMUKU-01, PKG-DANMUKU-02, PKG-DANMUKU-03, PKG-DANMUKU-04, PKG-DANMUKU-05, PKG-DANMUKU-06, PKG-DANMUKU-07, PKG-DANMUKU-08, PKG-DANMUKU-09, PKG-DANMUKU-10, PKG-DANMUKU-11 |
+| artplayer-plugin-danmuku | 5.3.0 | PKG-DANMUKU-01, PKG-DANMUKU-02, PKG-DANMUKU-03, PKG-DANMUKU-04, PKG-DANMUKU-05, PKG-DANMUKU-06, PKG-DANMUKU-07, PKG-DANMUKU-08, PKG-DANMUKU-09, PKG-DANMUKU-10, PKG-DANMUKU-11, PKG-DANMUKU-12 |
 | artplayer-plugin-danmuku-mask | 1.1.0 | PKG-MASK-01, PKG-MASK-02, PKG-MASK-03, PKG-MASK-04, PKG-MASK-05, PKG-MASK-06 |
 | artplayer-plugin-dash-control | 1.1.0 | PKG-DASH-01, PKG-DASH-02, PKG-DASH-03, PKG-DASH-04, PKG-DASH-05, PKG-DASH-06 |
 | artplayer-plugin-document-pip | 1.1.0 | PKG-DPIP-01, PKG-DPIP-02, PKG-DPIP-03, PKG-DPIP-04, PKG-DPIP-05, PKG-DPIP-06 |
@@ -315,11 +315,12 @@
 | PKG-DANMUKU-04 | artplayer-plugin-danmuku<br>整理时钟、队列与轨道调度 | PKG-DANMUKU-03, CORE-10 | danmuku 调度器和确定性时钟测试 | seek/暂停/倍率/长时间运行无顺序和碰撞回归 | H | done |
 | PKG-DANMUKU-05 | artplayer-plugin-danmuku<br>整理 DOM 渲染、设置、热力图与 worker | PKG-DANMUKU-04, CORE-14, CORE-18 | renderer/setting/heatmap/worker 职责及资源归属 | mount/icons/设置和 worker 协议保持，销毁无后台工作 | H | done |
 | PKG-DANMUKU-06 | artplayer-plugin-danmuku<br>迁移 TS 与公开声明 | PKG-DANMUKU-05, ENG-04, ENG-06 | 自有模块、worker 消息、option/item/result 类型 | 旧参数、扩展字段和事件消费通过，vendored 边界清楚 | H | done |
-| PKG-DANMUKU-07 | artplayer-plugin-danmuku<br>弹幕能力稳定性验收 | PKG-DANMUKU-06, PKG-DANMUKU-10, PKG-DANMUKU-11 | 负载/渲染/资源对比及 mask 可依赖的稳定边界 | 在试点核心中旧插件 API 与关键帧路径通过 | H | doing |
+| PKG-DANMUKU-07 | artplayer-plugin-danmuku<br>弹幕能力稳定性验收 | PKG-DANMUKU-06, PKG-DANMUKU-10, PKG-DANMUKU-11, PKG-DANMUKU-12 | 负载/渲染/资源对比及 mask 可依赖的稳定边界 | 在试点核心中旧插件 API 与关键帧路径通过 | H | doing |
 | PKG-DANMUKU-08 | artplayer-plugin-danmuku<br>完成新旧核心与组合验收 | PKG-DANMUKU-07, CORE-22 | 最终核心/旧核心、mask/fullscreen/PiP 组合报告 | 性能无未解释退化，反复装卸无累计资源 | H | todo |
 | PKG-DANMUKU-09 | artplayer-plugin-danmuku<br>完成分发、示例与文档 | PKG-DANMUKU-08, ENG-07 | danmuku.js、README、声明、worker 与产物 | tarball 和静态 icons 等旧调用通过，有独立回退版本 | H | todo |
 | PKG-DANMUKU-10 | artplayer-plugin-danmuku<br>修复 issue958 密集热力图过高与曲线裁平 | PKG-DANMUKU-05 | 自动密度缩放与曲线边界、历史自定义坐标兼容及真实浏览器红绿证据 | 16000条三种分布在两核心三引擎和source/main/legacy不遮挡；显式轴和自定义points保持旧解释，有单独commit | M | done |
 | PKG-DANMUKU-11 | artplayer-plugin-danmuku<br>修复 Worker 隐藏等待吞掉可见寿命 | PKG-DANMUKU-06 | 成功放置时的可见计时与延迟回复回归 | 真实 Worker 延迟下完整显示寿命；保留暂停/回收/取消和公开契约 | M | done |
+| PKG-DANMUKU-12 | artplayer-plugin-danmuku<br>保持异步放置期间的原生帧采样与寿命维护 | PKG-DANMUKU-11 | 每帧采样与串行dispatcher、代际buffer及回归 | 异步等待不丢已到时采样、不延迟既有寿命维护；保留顺序、取消与公开readys窗口 | H | done |

 ## 5 包迁移：artplayer-proxy-canvas

@@ -591,3 +592,4 @@
 - PKG-ASR-09: [记录](changes/2026-09-13-PKG-ASR-09-explicit-capture.md) [记录](baselines/asr-explicit-capture-validation.json)
 - PKG-DANMUKU-10: [记录](changes/2026-09-13-PKG-DANMUKU-10-heatmap-density.md) [记录](baselines/danmuku-heatmap-density-validation.json)
 - PKG-DANMUKU-11: [记录](changes/2026-09-13-PKG-DANMUKU-11-visible-lifetime.md) [记录](baselines/danmuku-lifetime-validation.json)
+- PKG-DANMUKU-12: [记录](changes/2026-09-13-PKG-DANMUKU-12-frame-sampling.md) [记录](baselines/danmuku-frame-sampling-validation.json)
@@ -1,5 +1,19 @@
 # 进度与证据

+## PKG-DANMUKU-12 持续采样与串行放置完成
+
+异步beforeVisible/Worker等待期间继续原生RAF采样和可见寿命维护，以内部身份
+buffer保留真实采到的行；公开readys窗口和状态不改，callback/放置仍串行。
+取消清空待处理引用，旧finally不清新代buffer；同批不重排，后续批保持ready优先。
+完整源码264项、main/legacy各68项单测，以及三格式各102共306项浏览器通过，
+无重试/跳过；后者含CPU阻塞诊断，不能计作任意负载无漏弹幕证明。
+严格分包TS、lint、构建和工具链检查通过。红测、历史双循环差异、内部RAF断言
+更新及准确验证范围见[变更](changes/2026-09-13-PKG-DANMUKU-12-frame-sampling.md)
+和[证据](baselines/danmuku-frame-sampling-validation.json)。
+231项：148 done、15 doing、68 todo。关闭DANMUKU-SAMPLING-01；07恢复doing，
+DANMUKU-LOAD-01保留，继续真实持续负载、资源和Mask边界，不跳过后续插件迁移。
+本任务独立本地commit；未推送、未发布。
+
 ## PKG-DANMUKU-11 Worker 等待寿命修复

 07负载审查独立发现并复现：隐藏Worker等待超过speed时，刚显示的弹幕下一帧就被
@@ -240,3 +240,4 @@
 | DANMUKU-LOAD-01 | open / 待取证 | Native lifecycle fixtures sometimes miss timestamp eligibility during concurrent workload; real frame/window behavior needs load evidence | PKG-DANMUKU-07 |
 | DANMUKU-HEATMAP-02 | resolved / 已复现 | Issue958 dense automatic heatmaps exceed the fixed Y domain and flatten across video | PKG-DANMUKU-10 |
 | DANMUKU-TIMING-01 | resolved / 已复现 | Hidden Worker wait is deducted from visible lifetime and can recycle a comment immediately after visible | PKG-DANMUKU-11 |
+| DANMUKU-SAMPLING-01 | resolved / 已复现 | Serial asynchronous placement stops native frame eligibility sampling and delays existing visible expiry | PKG-DANMUKU-12 |
@@ -5346,6 +5346,27 @@
        "refactor/changes/2026-09-13-PKG-DANMUKU-11-visible-lifetime.md"
      ],
      "resolutionRationale": "Three exact controlled modes and real delayed Worker/native video regression establish full visible lifetime, with the unchanged published defect retained and existing scheduling/pause/cancellation checks green."
+    },
+    {
+      "id": "DANMUKU-SAMPLING-01",
+      "title": "Serial asynchronous placement stops native frame eligibility sampling and delays existing visible expiry",
+      "confirmation": "reproduced",
+      "status": "resolved",
+      "owners": [
+        "PKG-DANMUKU-12"
+      ],
+      "evidence": [
+        "refactor/changes/2026-09-13-PKG-DANMUKU-12-frame-sampling.md",
+        "test/browser/danmuku-timing-diagnostic.spec.js",
+        "refactor/baselines/danmuku-frame-sampling-validation.json"
+      ],
+      "compatibleResolution": "Keep original per-frame readys semantics and serial callbacks, buffer actually sampled rows by identity, expire visible rows independently, and cancel all buffered work on lifecycle invalidation.",
+      "closureCriteria": "Controlled ordering/expiry/cancellation tests and native media/RAF evidence show sampled rows survive asynchronous waits without parallel callbacks or stale lifecycle emissions.",
+      "resolutionEvidence": [
+        "refactor/baselines/danmuku-frame-sampling-validation.json",
+        "refactor/changes/2026-09-13-PKG-DANMUKU-12-frame-sampling.md"
+      ],
+      "resolutionRationale": "Controlled red/green tests prove continued observation and expiry with serial callback/Worker ownership, lifecycle clearing and ready priority. Three-format native media/RAF and existing two-core scheduling/lifetime tests pass. CPU-blocked unobserved timestamps and sustained load remain separately tracked."
    }
  ]
 }
@@ -3381,7 +3381,8 @@
      "dependsOn": [
        "PKG-DANMUKU-06",
        "PKG-DANMUKU-10",
-        "PKG-DANMUKU-11"
+        "PKG-DANMUKU-11",
+        "PKG-DANMUKU-12"
      ],
      "status": "doing",
      "risk": "H",
@@ -4701,6 +4702,25 @@
        "changes/2026-09-13-PKG-DANMUKU-11-visible-lifetime.md",
        "baselines/danmuku-lifetime-validation.json"
      ]
+    },
+    {
+      "id": "PKG-DANMUKU-12",
+      "phase": "5 包迁移：artplayer-plugin-danmuku",
+      "title": "保持异步放置期间的原生帧采样与寿命维护",
+      "scope": [
+        "artplayer-plugin-danmuku"
+      ],
+      "dependsOn": [
+        "PKG-DANMUKU-11"
+      ],
+      "status": "done",
+      "risk": "H",
+      "deliverable": "每帧采样与串行dispatcher、代际buffer及回归",
+      "acceptance": "异步等待不丢已到时采样、不延迟既有寿命维护；保留顺序、取消与公开readys窗口",
+      "evidence": [
+        "changes/2026-09-13-PKG-DANMUKU-12-frame-sampling.md",
+        "baselines/danmuku-frame-sampling-validation.json"
+      ]
    }
  ]
 }