fix(auto-thumbnail): [PKG-AUTO-THUMB-07] release terminal canvas storage

2026-10-18 19:01:20 -08:00 · 2026-09-14 03:48:00 +08:00
1 parent e93d3cbb67
commit 7be628a983
@@ -0,0 +1,67 @@
+# PKG-AUTO-THUMB-07 私有抽帧画布清理
+
+状态：该独立任务完成；PKG-AUTO-THUMB-03 的剩余工作继续。
+
+从 PKG-AUTO-THUMB-03 的资源审查拆出独立修复；基线为
+`e93d3cbb67a937a94e3979f36efe16ee39cadb33`。03 增加对 07 的完成依赖，原来的
+WebKit 首两格像素、公共类型和后续完整包验收范围保持不变。
+
+## 已复现问题与实现
+
+抽帧任务只清理隐藏 video、监听和定时器，没有主动清空已分配的私有 canvas。
+编码回调或宿主观测保留该 canvas 时，任务完成/取消后其整张表的尺寸仍然存在。
+六项受控回归在基线全部失败；冻结正常 main 产物的原生完成用例也保持 800×45，
+未达到清理预期。这里确认的是可观察的画布尺寸/像素存储生命周期，不是测量泄漏
+了多少系统 RAM/VRAM，也不声称浏览器永远不会回收不可达对象。
+
+`src/extraction.ts` 在创建 canvas 后立即将宽、高复位加入 job 的既有资源清理。
+两个动作独立执行，任意一个抛错仍继续另一个以及 decoder 清理；正常完成、
+destroy、restart、提取失败复用同一条清理路径。尺寸赋值后重新核对 job 身份，
+避免用户覆写的 DOM setter 同步销毁任务后又分配下一维度。没有引入新抽象、
+共享全局状态、依赖或公开配置。
+
+编码后的 JPEG 是独立 Blob，保留既有最终预览 URL，不因清空 canvas 撤销它。
+后续任务拥有自己的新 canvas，旧回调不能发布或重新分配旧任务的画布。
+宽高归零不保证异步编码器或 GPU 驱动已经归还全部底层内存；它不代替整体预算
+或浏览器耐久测试。
+
+## 兼容边界与测试
+
+工厂/异步注册结果、原始配置及可强制转换数字、number 的分数行为、目标时间公式、
+更新次数、JPEG MIME、URL 所有权、错误通道和公开声明均不变。仅更改不可通过
+插件 API 取得的内部画布终态。ARCHITECTURE.md 随源码同步资源归属。
+
+新增 `test/auto-thumbnail-canvas.test.js` 覆盖保留编码回调时 destroy/restart、
+正常完成后仍持有预览、context 失败、单个 reset 抛错，以及分配中的销毁重入。
+已加入 test:unit/test:auto-thumbnail。首次联合 160 项为 159 通过/1 失败：旧
+数字兼容测试在完成后检查 canvas 宽度。现在在抽帧开始时检查原尺寸计算，并
+额外要求完成后归零；未删除原配置透传和次数断言。修正后联合 160 项通过。
+初次定向 lint 的单行语句格式错误也已修正。
+
+真实浏览器生命周期用例保留 canvas 引用和原生 Blob/帧回调，验证三引擎中各
+终止路径尺寸为零；完成时通过最终 URL 解码 JPEG，确认其仍为 800×45。使用
+受控播放器宿主和保留的原生回调，不能称为全部核心组合/未经拦截的生产时序。
+现有像素用例同时回归：有原生帧回调时仍要求五格准确，Windows WebKit 的前两格
+仍为诊断、只验收后面三格，AUTO-THUMB-PIXEL-01 不因本修复关闭。
+
+正常 main/legacy/ESM 经仓库 build 再生，docs 副本来自构建；公共声明与包版本
+未变。具体命令、基线/候选 hash、源码和产物回归、原生报告及范围见
+[验证记录](../baselines/auto-thumbnail-canvas-validation.json)。原失败及第一次
+159/1 中间结果保留在缓存日志；机器摘要保存关键结论与指纹。
+
+最终联合 160 项、main/legacy 各 58 项受控检查通过；main/legacy 各 21 项三
+浏览器检查通过（每组 15 生命周期、6 像素，后者保留既有 WebKit 局部范围）。
+严格包 TS、定向 lint、固定 Yarn 工具链和 ESM 原生导入通过；三种正式构建与
+docs 副本逐字节一致。只关闭 AUTO-THUMB-CANVAS-01 的可观察画布终态缺陷。
+
+```sh
+yarn test:auto-thumbnail
+node node_modules/typescript/bin/tsc -p packages/artplayer-plugin-auto-thumbnail/tsconfig.json --noEmit
+yarn build artplayer-plugin-auto-thumbnail
+yarn test:browser test/browser/auto-thumbnail-lifecycle.spec.js test/browser/auto-thumbnail-pixels.spec.js --workers=1
+```
+
+通过 ARTPLAYER_AUTO_THUMBNAIL_ARTIFACT 分别选择 main/legacy，归档共享报告后再
+运行下一组；未设置该变量则测试源码编译结果。没有重复执行全部无关包测试或
+全仓安装类型矩阵。07 只负责该独立资源缺陷，不等于 03-06、包大版本升级、
+远程 CI 或发布验收完成。回退本提交并正常重建即可恢复原画布终态；不 push/publish。
@@ -2,9 +2,9 @@

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

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

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

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

@@ -19,7 +19,7 @@
 | artplayer-plugin-ambilight | 1.1.0 | PKG-AMBILIGHT-01, PKG-AMBILIGHT-02, PKG-AMBILIGHT-03, PKG-AMBILIGHT-04, PKG-AMBILIGHT-PROXY-01, PKG-AMBILIGHT-05, PKG-AMBILIGHT-06, PKG-FACTORY-01 |
 | artplayer-plugin-asr | 2.1.0 | PKG-ASR-01, PKG-ASR-02, PKG-ASR-03, PKG-ASR-04, PKG-ASR-05, PKG-ASR-06, PKG-ASR-07, PKG-ASR-08, PKG-ASR-09 |
 | artplayer-plugin-audio-track | 1.1.0 | PKG-AUDIO-01, PKG-AUDIO-02, PKG-AUDIO-03, PKG-AUDIO-04, PKG-AUDIO-05, PKG-AUDIO-06 |
-| 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-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, PKG-AUTO-THUMB-07 |
 | 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, PKG-DANMUKU-12 |
@@ -174,10 +174,11 @@
 | --- | --- | --- | --- | --- | --- | --- |
 | PKG-AUTO-THUMB-01 | artplayer-plugin-auto-thumbnail<br>核对包契约与历史用法 | BASE-05 | url/width/number/scale、异步工厂和渐进缩略图更新 | 源码/声明/README/demo/发布包差异已登记；公开形状和版本范围冻结 | H | done |
 | PKG-AUTO-THUMB-02 | artplayer-plugin-auto-thumbnail<br>建立特有行为与错误测试 | PKG-AUTO-THUMB-01, ENG-03, ENG-05 | 抽帧边界、短视频、失败、连续来源和销毁中的抽帧 | 旧版本行为可重跑，成功/失败/切源/销毁有必要断言 | H | done |
-| PKG-AUTO-THUMB-03 | artplayer-plugin-auto-thumbnail<br>整理内部职责与资源 | PKG-AUTO-THUMB-02, CORE-09, CORE-19 | 隐藏 video、seek 队列、canvas 编码与 Blob URL 清理 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | doing |
+| PKG-AUTO-THUMB-03 | artplayer-plugin-auto-thumbnail<br>整理内部职责与资源 | PKG-AUTO-THUMB-02, CORE-09, CORE-19, PKG-AUTO-THUMB-07 | 隐藏 video、seek 队列、canvas 编码与 Blob URL 清理 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | doing |
 | PKG-AUTO-THUMB-04 | artplayer-plugin-auto-thumbnail<br>迁移自有源码和公开类型 | PKG-AUTO-THUMB-03, ENG-04, ENG-06, CORE-07 | 抽帧结果和真实异步插件返回类型兼容 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | H | todo |
 | PKG-AUTO-THUMB-05 | artplayer-plugin-auto-thumbnail<br>验证新旧核心和组合 | PKG-AUTO-THUMB-04, CORE-22 | 旧核心/候选核心预览、多次加载无过期缩略图覆盖 | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | H | todo |
 | PKG-AUTO-THUMB-06 | artplayer-plugin-auto-thumbnail<br>验证分发并同步文档 | PKG-AUTO-THUMB-05, ENG-07 | auto.thumbnail.js、三种产物和内存/URL 证据 | tarball 入口/资源、类型、8082 demo 和 README 一致，有回退记录 | H | todo |
+| PKG-AUTO-THUMB-07 | artplayer-plugin-auto-thumbnail<br>终止抽帧时清空私有画布像素尺寸 | PKG-AUTO-THUMB-02, CORE-09, CORE-19 | 将私有 canvas 尺寸归入 job 清理；完成、取消、失败及分配重入均有回归，保留已编码 JPEG | 旧红新绿证明保留回调时画布归零，单项清理失败不阻断其他资源；原生取消和完成后 JPEG 仍可解码，原 API/时间公式/类型不变 | M | done |

 ## 5 包迁移：artplayer-plugin-vtt-thumbnail

@@ -606,3 +607,4 @@
 - PKG-DANMUKU-12: [记录](changes/2026-09-13-PKG-DANMUKU-12-frame-sampling.md) [记录](baselines/danmuku-frame-sampling-validation.json)
 - PKG-JASSUB-08: [记录](changes/2026-09-14-PKG-JASSUB-08-offscreen.md) [记录](baselines/jassub-offscreen-validation.json) [记录](baselines/jassub-offscreen-patch.json)
 - PKG-JASSUB-09: [记录](changes/2026-09-14-PKG-JASSUB-09-hybrid.md) [记录](baselines/jassub-hybrid-validation.json) [记录](baselines/jassub-hybrid-patch.json) [记录](changes/2026-09-14-PKG-JASSUB-09-firefox-diagnostics.md) [记录](changes/2026-09-14-PKG-JASSUB-09-display.md) [记录](baselines/jassub-display-validation.json)
+- PKG-AUTO-THUMB-07: [记录](changes/2026-09-14-PKG-AUTO-THUMB-07-canvas.md) [记录](baselines/auto-thumbnail-canvas-validation.json)
@@ -1,5 +1,18 @@
 # 进度与证据

+## PKG-AUTO-THUMB-07 私有画布清理完成
+
+抽帧 canvas 现由 job 清理宽高；取消、失败和正常完成后归零，单个 reset 抛错
+仍继续其他清理，分配期间销毁不会继续分配另一维。已编码 JPEG 和最终预览 URL
+保留。六项受控回归旧实现全部失败、新实现全部通过；冻结 main 的原生完成检查
+同样先失败。联合 160 项通过，main/legacy 各 58 项受控检查和各 21 项原生检查
+通过，完成后的 JPEG 仍可解码为 800×45。严格包 TS、lint、正常三格式构建及
+docs 副本一致性通过。关闭 AUTO-THUMB-CANVAS-01；不声称精确 GPU/内存回收量。
+[变更](changes/2026-09-14-PKG-AUTO-THUMB-07-canvas.md)和
+[红绿记录](baselines/auto-thumbnail-canvas-validation.json)含中间测试调整。
+03 依赖该独立修复，仍继续前两格 WebKit 像素和其他迁移工作；04-06、版本及
+发布验收未完成。VAST 的初始化决定仍待答复。下一步继续未完成源码/类型迁移。
+
 ## PKG-CHAPTER-05 时序取证继续（doing）

 复核旧失败 ZIP：一次 restart 数组读取耗时 9956.244 ms，返回时已含目标 URL；
@@ -252,3 +252,4 @@
 | JASSUB-OFFSCREEN-01 | resolved / 已复现 | Default offscreen initialization lets queued resize render before Worker canvas ownership, raising clearRect on false context | PKG-JASSUB-08, PKG-JASSUB-05 |
 | JASSUB-HYBRID-01 | open / 已复现 | Late hybrid frames mutate the new offscreen canvas or throw; terminal track calls recreate transferred canvases | PKG-JASSUB-09, PKG-JASSUB-05 |
 | JASSUB-FIREFOX-OFFSCREEN-01 | open / 已复现 | Windows Firefox offscreen readback and asynchronous ImageBitmap creation can stall through seek/layout, including a minimal Worker control | PKG-JASSUB-09, PKG-JASSUB-05 |
+| AUTO-THUMB-CANVAS-01 | resolved / 已复现 | Private thumbnail canvas retains sheet dimensions after completion or cancellation while callbacks retain the element | PKG-AUTO-THUMB-07 |
@@ -5662,6 +5662,30 @@
      ],
      "compatibleResolution": "Isolate native media/compositor/readback and sequence effects without globally disabling default offscreen or deleting assertions. The pre-09 artifact also fails in the same sequence; do not claim the new hybrid guard caused or fixed this separate failure.",
      "closureCriteria": "Identify and verify a compatible fix or a reviewed precise platform boundary with native controls. Preserve known red sequence and successful standalone comparison; candidate playback/fullscreen pixels and lifetime must be justified, not merely rerun to green."
+    },
+    {
+      "id": "AUTO-THUMB-CANVAS-01",
+      "title": "Private thumbnail canvas retains sheet dimensions after completion or cancellation while callbacks retain the element",
+      "confirmation": "reproduced",
+      "status": "resolved",
+      "owners": [
+        "PKG-AUTO-THUMB-07"
+      ],
+      "evidence": [
+        "refactor/changes/2026-09-14-PKG-AUTO-THUMB-07-canvas.md",
+        "refactor/baselines/auto-thumbnail-canvas-validation.json",
+        "test/auto-thumbnail-canvas.test.js",
+        "test/browser/auto-thumbnail-lifecycle.spec.js"
+      ],
+      "compatibleResolution": "Own width/height reset in the extraction job and guard allocation reentry; retain completed JPEG URLs.",
+      "closureCriteria": "Controlled old/new and native retained-callback checks demonstrate terminal zero dimensions, independent cleanup and still-decodable completed JPEGs.",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-14-PKG-AUTO-THUMB-07-canvas.md",
+        "refactor/baselines/auto-thumbnail-canvas-validation.json",
+        "test/auto-thumbnail-canvas.test.js",
+        "test/browser/auto-thumbnail-lifecycle.spec.js"
+      ],
+      "resolutionRationale": "Six controlled regressions fail before and pass after. The frozen main native complete control fails dimensions; candidate main/legacy native lifecycle checks reset the retained canvas and decode final JPEGs after reset. No public options, types, sample positions or caller URLs changed; WebKit early-frame pixels remain separately open."
    }
  ]
 }
@@ -1783,7 +1783,8 @@
      "dependsOn": [
        "PKG-AUTO-THUMB-02",
        "CORE-09",
-        "CORE-19"
+        "CORE-19",
+        "PKG-AUTO-THUMB-07"
      ],
      "status": "doing",
      "risk": "H",
@@ -4816,6 +4817,27 @@
        "changes/2026-09-14-PKG-JASSUB-09-display.md",
        "baselines/jassub-display-validation.json"
      ]
+    },
+    {
+      "id": "PKG-AUTO-THUMB-07",
+      "phase": "5 包迁移：artplayer-plugin-auto-thumbnail",
+      "title": "终止抽帧时清空私有画布像素尺寸",
+      "scope": [
+        "artplayer-plugin-auto-thumbnail"
+      ],
+      "dependsOn": [
+        "PKG-AUTO-THUMB-02",
+        "CORE-09",
+        "CORE-19"
+      ],
+      "status": "done",
+      "risk": "M",
+      "deliverable": "将私有 canvas 尺寸归入 job 清理；完成、取消、失败及分配重入均有回归，保留已编码 JPEG",
+      "acceptance": "旧红新绿证明保留回调时画布归零，单项清理失败不阻断其他资源；原生取消和完成后 JPEG 仍可解码，原 API/时间公式/类型不变",
+      "evidence": [
+        "changes/2026-09-14-PKG-AUTO-THUMB-07-canvas.md",
+        "baselines/auto-thumbnail-canvas-validation.json"
+      ]
    }
  ]
 }