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

refactor/changes/2026-09-13-PKG-DANMUKU-10-heatmap-density.md

@@ -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升级和发布复盘按原计划继续。