fix(danmuku): [PKG-DANMUKU-10] bound dense heatmaps for issue 958

2026-10-14 00:06:17 -08:00 · 2026-09-13 21:20:37 +08:00
1 parent 053d211fb0
commit abc8008da7
@@ -0,0 +1,66 @@
+# PKG-DANMUKU-10：修复 issue #958 密集弹幕热力图遮挡
+
+用户在 PKG-DANMUKU-06 的 TS 迁移过程中补充
+[issue #958](https://github.com/zhw2590582/ArtPlayer/issues/958)，要求顺便检查并修复。
+本修复基于已提交的 PKG-DANMUKU-05（053d211fb），在独立 worktree 完成，
+有自己的任务与提交；06 的未完成 TS/声明工作不计入本任务。
+
+## 复现与原因
+
+Issue 描述加载约 1.6 万条弹幕后热力图变高，评论进一步确认顶部被拉平。
+原截图和反馈来自 Chrome 136 / macOS 13；本次没有取得报告者的原始弹幕数据，
+使用确定性的 16000 条均匀、集中和混合分布独立复现同类问题。
+
+默认 yMax 固定为 128，采样数量经 scale/minHeight 变换后可能远大于128。
+在真实 Chromium、旧核心、新候选插件的未修复代码上，均匀分布 SVG
+getBBox().y 为 -65.23090362548828；100px 容器裁掉曲线，留下全高平块。
+控制点还可能超出端点范围，因此仅扩大 yMax 或增加 overflow:hidden 不够。
+
+## 修复与兼容边界
+
+- 只修改 heatmap-geometry 的自动纵轴计算；采样计数、队列、渲染调度和公开入口不变。
+- 自动采样的变换后峰值超过32时，yMax采用峰值的4倍，将密集热图拟合到底部四分之一。
+  当前100px控制容器中为25px；同时约束曲线端点和控制点，使Bezier不会重新越界。
+- 小曲线保留旧 SVG 路径，包括未触发拟合时的小幅Bezier过冲。
+  25px约束只承诺触发拟合的默认密集图，不是所有自定义曲线的全局限制。
+- 显式有限 yMin/yMax 和非空自定义 points 继续使用旧坐标解释。
+  原points嵌套数组写入、重复变换、resize后重新采样均有原历史差分保护。
+- 配置自有可枚举字段只读取一次；getter、原型字段和非枚举字段遵循原Object.assign语义。
+- CSS类、100px控制容器、渐变/进度钩子、opacity、销毁归属、类型定义和分发入口均保留。
+  这是用户要求的视觉缺陷修正；采用显式坐标域的旧自定义图不被强制改样式。
+
+## 验证
+
+最终执行结果、候选文件指纹、浏览器版本、每条用例结果与原生几何/媒体观察，见
+[机器证据](../baselines/danmuku-heatmap-density-validation.json)。
+
+- `yarn test:danmuku`：250通过，包括热图19项、真实历史路径和配置属性语义。
+- `yarn build artplayer-plugin-danmuku`：main/legacy/ESM及docs拷贝成功。
+- 定向只读ESLint通过。102项原生浏览器通过：源码、main、legacy均执行同一密度浏览器矩阵；
+  每种格式为两核心×三分布×三引擎，另外main执行原48项资源浏览器回归。
+- 实际解码并在安装插件后继续播放；验证原生timeupdate渐变变化，再暂停检查
+  640/400宽度的SVG局部边界、实际屏幕像素高度、进度及destroy清理。
+- 使用Windows上的Playwright Chromium/Firefox/WebKit；这不是报告者macOS/Chrome136的真机验收，
+  也不是16000条同时可见DOM弹幕的吞吐、长时内存或完整播放调度压力测试。后者仍归07。
+
+## 复核中处理的问题
+
+首次浏览器夹具误将plugins.add的返回值当插件；该次在load前失败，单独留档，
+不作为缺陷红测。修正取注册插件后得到上面的真实越界红测。
+首版拟合改变了第二次custom points的旧路径；保留失败日志并限制自动采样范围，
+原测试未删除或放宽。子代理只读复核进一步发现getter重复读取/原型轴误识别以及
+“仅在安装前播放”的证据不足，均已在实现或夹具中修正。
+同时修正null/非数组points仍应回退队列采样的旧宽容行为；拟合判断复用同一输入分类。
+
+独立worktree复用了主工作区的缓存，契约报告路径保护和Node reporter路径断言因此
+分别拒绝重定向路径和出现8/9通过。未放宽检查器；修复提交快进回主重构工作区后，
+契约检查和同一组9项元数据测试全部通过。Git检出把计划表转为CRLF，按既有
+`plan.mjs --write`重新生成后`--check`通过。每任务提交审计确认145个完成任务、
+141个独立完成提交及原4个引导例外。上述环境差异不计为生产热力图失败。
+
+## 维护与回退
+
+模块地图和默认/显式坐标域边界同步写入包README及ARCHITECTURE。
+无需新依赖或锁文件变更；复用Yarn1.22.22、Node24.21.0和已有构建、Node测试、Playwright。
+回退本任务的单个commit可恢复旧曲线与产物；回退会重新引入#958，不影响06的类型迁移计划。
+本地提交不代表推送、关闭远端issue或npm发布；全包major升级和发布复盘按原计划继续。
@@ -2,9 +2,9 @@

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

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

-状态：todo 69 / doing 15 / blocked 0 / done 144 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 69 / doing 15 / blocked 0 / done 145 / 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 |
+| 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 |
 | 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,9 +315,10 @@
 | 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 | doing |
-| PKG-DANMUKU-07 | artplayer-plugin-danmuku<br>弹幕能力稳定性验收 | PKG-DANMUKU-06 | 负载/渲染/资源对比及 mask 可依赖的稳定边界 | 在试点核心中旧插件 API 与关键帧路径通过 | H | todo |
+| PKG-DANMUKU-07 | artplayer-plugin-danmuku<br>弹幕能力稳定性验收 | PKG-DANMUKU-06, PKG-DANMUKU-10 | 负载/渲染/资源对比及 mask 可依赖的稳定边界 | 在试点核心中旧插件 API 与关键帧路径通过 | H | todo |
 | 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 |

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

@@ -586,3 +587,4 @@
 - PKG-ASR-07: [记录](changes/2026-09-13-PKG-ASR-07-playback-volume.md) [记录](baselines/asr-volume-validation.json)
 - PKG-ASR-08: [记录](changes/2026-09-13-PKG-ASR-08-capture-output.md) [记录](baselines/asr-fallback-validation.json)
 - 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)
@@ -1,5 +1,13 @@
 # 进度与证据

+## PKG-DANMUKU-10：issue #958 密集热力图修复
+
+用户新增的16000条弹幕热图过高/裁平已独立复现并修复。自动密度拟合到底部四分之一，
+保留显式坐标、自定义points、getter和历史生命周期。完整弹幕250项与102项真实浏览器
+通过，包含两核心/三引擎/三格式；构建和lint通过。详见[变更](changes/2026-09-13-PKG-DANMUKU-10-heatmap-density.md)及[证据](baselines/danmuku-heatmap-density-validation.json)。
+229项：145 done、15 doing、69 todo。06的TS迁移仍进行中，07长负载与发布复盘未完成。
+独立本地提交；未推送、未发布、未关闭远端issue。
+
 ## PKG-DANMUKU-05 渲染、设置与热力图完成

 拆renderer、Setting模板/滑块/发送/资源/全局样式和heatmap采样/几何/生命周期。
@@ -238,3 +238,4 @@
 | DANMUKU-TRACK-01 | resolved / 已复现 | Native simultaneous fixed Danmuku comments can overlap with duplicate start loops and repeated Worker IDs | PKG-DANMUKU-04, PKG-DANMUKU-05, PKG-DANMUKU-07 |
 | DANMUKU-INPUT-02 | resolved / 已复现 | Intermediate explicit-zero correction regressed accepted NaN timestamp fallback | PKG-DANMUKU-04 |
 | 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 |
@@ -5288,6 +5288,28 @@
      ],
      "compatibleResolution": "Capture native RAF/media-time gaps and scheduled/eligible/visible item counts under realistic load before deciding whether the old plus/minus 0.1 second eligibility rule needs a compatible correction.",
      "closureCriteria": "Real load runs explain missing scheduled items with frame and media evidence, and any confirmed implementation defect has a regression and compatible fix; seeding ready in lifecycle fixtures is not closure evidence."
+    },
+    {
+      "id": "DANMUKU-HEATMAP-02",
+      "title": "Issue958 dense automatic heatmaps exceed the fixed Y domain and flatten across video",
+      "confirmation": "reproduced",
+      "status": "resolved",
+      "owners": [
+        "PKG-DANMUKU-10"
+      ],
+      "evidence": [
+        "refactor/changes/2026-09-13-PKG-DANMUKU-10-heatmap-density.md",
+        "refactor/baselines/danmuku-heatmap-density-validation.json",
+        "test/danmuku-heatmap.test.js",
+        "test/browser/danmuku-heatmap-density.spec.js"
+      ],
+      "compatibleResolution": "Fit dense automatically sampled curves while preserving explicit axes, custom points, option property semantics and lifecycle.",
+      "closureCriteria": "Native playback, SVG/screen bounds, gradients and resize verified for uniform/clustered/mixed 16000 rows on both cores; historical custom paths retain exact behavior.",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-13-PKG-DANMUKU-10-heatmap-density.md",
+        "refactor/baselines/danmuku-heatmap-density-validation.json"
+      ],
+      "resolutionRationale": "250 unit tests and 102 native browser cases passed, including source/main/legacy density matrices and main resource regression. No claim of full load or macOS device acceptance."
    }
  ]
 }
@@ -3376,7 +3376,8 @@
        "artplayer-plugin-danmuku"
      ],
      "dependsOn": [
-        "PKG-DANMUKU-06"
+        "PKG-DANMUKU-06",
+        "PKG-DANMUKU-10"
      ],
      "status": "todo",
      "risk": "H",
@@ -4658,6 +4659,25 @@
        "changes/2026-09-13-PKG-ASR-09-explicit-capture.md",
        "baselines/asr-explicit-capture-validation.json"
      ]
+    },
+    {
+      "id": "PKG-DANMUKU-10",
+      "phase": "5 包迁移：artplayer-plugin-danmuku",
+      "title": "修复 issue958 密集热力图过高与曲线裁平",
+      "scope": [
+        "artplayer-plugin-danmuku"
+      ],
+      "dependsOn": [
+        "PKG-DANMUKU-05"
+      ],
+      "status": "done",
+      "risk": "M",
+      "deliverable": "自动密度缩放与曲线边界、历史自定义坐标兼容及真实浏览器红绿证据",
+      "acceptance": "16000条三种分布在两核心三引擎和source/main/legacy不遮挡；显式轴和自定义points保持旧解释，有单独commit",
+      "evidence": [
+        "changes/2026-09-13-PKG-DANMUKU-10-heatmap-density.md",
+        "baselines/danmuku-heatmap-density-validation.json"
+      ]
    }
  ]
 }