fix(PKG-AUTO-THUMB-11): isolate frame handler cleanup failures

2026-10-10 21:06:15 -08:00 · 2026-09-14 14:22:45 +08:00
1 parent a8d19ce5ef
commit eb6402fdca
@@ -0,0 +1,55 @@
+# PKG-AUTO-THUMB-11: independent frame cleanup
+
+Baseline: a8d19ce5ef8af8fe4c48424753742e8d78a77962. This task fixes one
+resource boundary under the unfinished task03 implementation; task04 depends on
+both. It does not close AUTO-THUMB-LIFE-01 or AUTO-THUMB-PIXEL-01.
+
+## Defect and implementation
+
+The frame reader invalidated its pending token, then cleared onloadeddata and
+onseeked before entering cleanupAll. A throwing property setter skipped deadline
+and native frame cancellation; outer job cleanup still removed the decoder and
+canvas, leaving those handles registered. Controlled setters reproduce this in
+both destroy and restart, while awaiting loaded data and when completing a frame.
+These are deliberately injected exceptions, not evidence of spontaneous native
+IDL setter failure in an ordinary browser.
+
+frames.ts now submits both handler clears and both handle releases to the same
+cleanupAll operation. It still invalidates identity first, preserves handle zero,
+and propagates the first error through the existing job warning path. A handler
+that cannot be removed remains inert after disposal. A failure while finishing
+prevents drawing/publication, and replacement work can still produce a preview.
+No new abstraction, dependency, lockfile, script or public declaration is needed.
+
+API-04/05/06/09/11 retain event names, registration Promise, result, factory alias,
+options, ten-column layout, sample times, progressive URLs and distribution paths.
+Only the exceptional cleanup path changes; normal behavior has regression coverage.
+The package architecture describes current eight-module ownership and remaining
+acceptance work. This also corrects stale prose predating type/alias tasks08/09.
+
+## Validation
+
+See [fingerprints and native results](../baselines/auto-thumbnail-handler-validation.json).
+
+- Final 27-case frame suite against the exact pre-change main: 19 pass, all eight
+  new fault regressions fail. Current source, actual main and legacy: 27 pass each.
+- Full package suite: 182 pass, including frozen contracts and type regressions.
+- Strict package TypeScript passes; targeted read-only lint passes after fixing
+  a missing test brace. Pinned Node24.21.0/Yarn1.22.22 toolchain passes; core public
+  declarations remain 37 files with zero drift.
+- Normal build regenerates main/legacy/ESM and the corresponding docs copies.
+- Actual main and legacy each pass 21 native lifecycle cases across Windows
+  Chromium, Firefox and WebKit, with zero retries or skips. Native HTTP decoding,
+  seeking, JPEG, complete/restart/destroy, held frame/Blob delivery, encoding
+  timeout and URL cleanup use a stub ArtPlayer host. The throwing-setter cases
+  are controlled Node tests, not native browser fault-injection tests.
+- No first-frame pixel rerun, physical-device acceptance, full old/new core
+  combinations, remote CI or npm publication is claimed. Existing pixel evidence
+  and failure remain unchanged; tasks03/04/05/06 remain unfinished.
+
+## Rollback and next work
+
+Revert this task's dedicated commit and rebuild the package to recover the
+previous behavior; the new regression tests document the restored leak. Continue
+task03 resource-boundary review and obtain a different native backend/device for
+the outstanding first-frame issue rather than relaxing its assertions.
@@ -2,9 +2,9 @@

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

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

-状态：todo 55 / doing 17 / blocked 0 / done 179 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 55 / doing 17 / blocked 0 / done 180 / 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, PKG-AUTO-THUMB-07, PKG-AUTO-THUMB-08, PKG-AUTO-THUMB-09, PKG-AUTO-THUMB-10 |
+| 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, PKG-AUTO-THUMB-08, PKG-AUTO-THUMB-09, PKG-AUTO-THUMB-10, PKG-AUTO-THUMB-11 |
 | 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 |
@@ -176,13 +176,14 @@
 | 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, 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, PKG-AUTO-THUMB-08, PKG-AUTO-THUMB-09, PKG-AUTO-THUMB-10 | 抽帧结果和真实异步插件返回类型兼容 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | H | todo |
+| PKG-AUTO-THUMB-04 | artplayer-plugin-auto-thumbnail<br>迁移自有源码和公开类型 | PKG-AUTO-THUMB-03, ENG-04, ENG-06, CORE-07, PKG-AUTO-THUMB-08, PKG-AUTO-THUMB-09, PKG-AUTO-THUMB-10, PKG-AUTO-THUMB-11 | 抽帧结果和真实异步插件返回类型兼容 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | 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 |
 | PKG-AUTO-THUMB-08 | artplayer-plugin-auto-thumbnail<br>保留旧声明并提供准确异步类型入口 | PKG-AUTO-THUMB-02, ENG-04, ENG-06, CORE-07 | 保留实际 npm 1.1.0 根声明；新增同实现 /runtime 类型、编辑器声明及隔离安装消费者 | 原 Parameters/ReturnType/替代函数不变；准确 Promise 类型正反例、CJS/ESM 条件入口和声明解析通过；不把像素与设备缺口计为通过 | M | done |
 | PKG-AUTO-THUMB-09 | artplayer-plugin-auto-thumbnail<br>兼容旧 CommonJS default 与直接工厂调用 | PKG-AUTO-THUMB-02, PKG-AUTO-THUMB-08 | 同一 callable 上的 default 自别名，保留最新根声明并补准确 runtime 别名类型；旧/新实际包入口证据 | 旧红新绿、直接/default/ESM/legacy/global 调用一致；旧根类型提取不变，公开准确类型与实际别名匹配；不关闭抽帧像素和设备缺口 | M | done |
 | PKG-AUTO-THUMB-10 | artplayer-plugin-auto-thumbnail<br>为渐进 JPEG 编码建立取消时限与独立资源归属 | PKG-AUTO-THUMB-02, PKG-AUTO-THUMB-07 | 拆分私有 canvas 编码模块，一次一帧的30秒编码时限，完成/失败/切源/销毁取消；迟到和重复回调无副作用 | 受控回调未返回的旧红新绿、正常JPEG和前一预览保持、同步重入/清理失败有回归；真实三浏览器编码/取消通过，公开时间公式与入口不变，首帧风险独立保留 | M | done |
+| PKG-AUTO-THUMB-11 | artplayer-plugin-auto-thumbnail<br>保证抽帧事件属性清理异常不截断其他资源释放 | PKG-AUTO-THUMB-02, PKG-AUTO-THUMB-07, PKG-AUTO-THUMB-10 | 独立清除事件属性、抽帧时限和原生帧回调；首个异常保留，过期回调失效，替换任务可继续 | 八个故障注入用例旧红新绿，实际main/legacy抽帧与三浏览器生命周期回归通过；文档和构建同步，首帧及整体资源验收不冒充完成 | M | done |

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

@@ -653,3 +654,4 @@
 - PKG-MULTI-SUB-09: [记录](changes/2026-09-14-PKG-MULTI-SUB-09-switch-order.md) [记录](baselines/multiple-subtitles-switch-validation.json)
 - PKG-MULTI-SUB-10: [记录](changes/2026-09-14-PKG-MULTI-SUB-10-legacy-captions.md) [记录](baselines/multiple-subtitles-legacy-validation.json)
 - PKG-MULTI-SUB-11: [记录](changes/2026-09-14-PKG-MULTI-SUB-11-ass-conversion.md) [记录](baselines/multiple-subtitles-ass-validation.json)
+- PKG-AUTO-THUMB-11: [记录](changes/2026-09-14-PKG-AUTO-THUMB-11-handler-cleanup.md) [记录](baselines/auto-thumbnail-handler-validation.json)
@@ -1,5 +1,16 @@
 # 进度与证据

+## PKG-AUTO-THUMB-11 抽帧清理异常修复完成
+
+事件属性清除现在与定时器、原生帧回调取消分别执行，单个异常不截断剩余清理。
+八个受控故障用例在旧main全部失败，新源码/main/legacy各27项抽帧回归通过；
+完整插件182项通过，实际main/legacy各21项三浏览器生命周期通过。异常属性由测试
+主动注入，不声称浏览器原生setter自行失败；原生验证使用真实解码和桩宿主。
+严格TS、定向lint、固定工具链、37声明零漂移通过，三格式和docs副本已重建。
+见[变更](changes/2026-09-14-PKG-AUTO-THUMB-11-handler-cleanup.md)与[证据](baselines/auto-thumbnail-handler-validation.json)。252项：180 done、17 doing、55 todo。
+任务03仍doing，04/05/06仍todo，首帧像素与完整资源验收风险保持open。下一步继续
+Auto Thumbnail资源边界与剩余插件工作；首帧需要另一原生后端/设备证据，不能靠延时放宽。
+
 ## PKG-MULTI-SUB-05 切源时序诊断检查点（仍未完成）

 新增可选原生属性/事件跟踪和独立恢复事件等待对照。WebKit串行3项、重复9项及
@@ -186,7 +186,7 @@
 | AUTO-THUMB-TYPE-01 | open / 已复现 | Published declarations misdescribe async registration and switch height/number option fields across generations | PKG-AUTO-THUMB-04, PKG-AUTO-THUMB-08 |
 | AUTO-THUMB-EXPORT-01 | open / 已复现 | Published 1.0.1 CommonJS default namespace differs from the direct function exported by 1.1.0 | PKG-AUTO-THUMB-04, PKG-AUTO-THUMB-06, PKG-AUTO-THUMB-09 |
 | AUTO-THUMB-DIST-01 | open / 已复现 | Published 1.0.0 archive lacks declared main and legacy runtimes | PKG-AUTO-THUMB-06 |
-| AUTO-THUMB-LIFE-01 | open / 已复现 | Extraction tasks, decoder handlers and final object URLs lack source-switch and destroy ownership | PKG-AUTO-THUMB-02, PKG-AUTO-THUMB-03, PKG-AUTO-THUMB-05 |
+| AUTO-THUMB-LIFE-01 | open / 已复现 | Extraction tasks, decoder handlers and final object URLs lack source-switch and destroy ownership | PKG-AUTO-THUMB-02, PKG-AUTO-THUMB-03, PKG-AUTO-THUMB-05, PKG-AUTO-THUMB-11 |
 | AUTO-THUMB-ENCODE-01 | open / 已复现 | Unserialized encodes include blank output and lack media/canvas/input failure handling | PKG-AUTO-THUMB-02, PKG-AUTO-THUMB-03, PKG-AUTO-THUMB-05 |
 | AUTO-THUMB-PIXEL-01 | open / 已复现 | Historical auto-thumbnail yields black sampled JPEG cells on Windows WebKit while played native video and static JPEG controls yield color | PKG-AUTO-THUMB-03, PKG-AUTO-THUMB-05 |
 | VTT-THUMB-DIST-01 | open / 已复现 | Historical 1.0.0 main/legacy contain invalid regular expressions and cannot load | PKG-VTT-THUMB-06 |
@@ -4124,7 +4124,8 @@
      "owners": [
        "PKG-AUTO-THUMB-02",
        "PKG-AUTO-THUMB-03",
-        "PKG-AUTO-THUMB-05"
+        "PKG-AUTO-THUMB-05",
+        "PKG-AUTO-THUMB-11"
      ],
      "evidence": [
        "refactor/baselines/auto-thumbnail-release.json",
@@ -4135,11 +4136,14 @@
        "refactor/baselines/auto-thumbnail-failures-validation.json",
        "test/auto-thumbnail-lifecycle.test.js",
        "test/browser/auto-thumbnail-lifecycle.spec.js",
-        "refactor/baselines/auto-thumbnail-lifecycle-checkpoint.json"
+        "refactor/baselines/auto-thumbnail-lifecycle-checkpoint.json",
+        "refactor/changes/2026-09-14-PKG-AUTO-THUMB-11-handler-cleanup.md",
+        "refactor/baselines/auto-thumbnail-handler-validation.json",
+        "test/auto-thumbnail-frames.test.js"
      ],
      "compatibleResolution": "Cancel obsolete work and release owned resources while retaining live options and progressive usable sheet updates.",
      "closureCriteria": "Delayed callbacks, repeated metadata, switching, destroy, multiple instances and failure cleanup are reproduced then pass source/artifacts and native browser checks.",
-      "workspaceState": "Task03 ownership checkpoint: 22 candidate lifecycle regressions fail on frozen source and pass on source/main/legacy; two further explicit-URL short-circuit and duration-snapshot cases preserve historical successes. Final candidate runs have 24 passing cases each; 27 native lifecycle cases verify destroy/restart/completion and URL/decoder cleanup. New index/options/session/extraction modules fix serial encoding, stale callbacks, failure cleanup and selected reentry paths. Pixel/frame correctness, resource budgets and additional boundaries remain for task03; old/final core acceptance remains task05. Risk stays open rather than claiming complete extraction repair."
+      "workspaceState": "Task03 ownership checkpoint: 22 candidate lifecycle regressions fail on frozen source and pass on source/main/legacy; two further explicit-URL short-circuit and duration-snapshot cases preserve historical successes. Final candidate runs have 24 passing cases each; 27 native lifecycle cases verify destroy/restart/completion and URL/decoder cleanup. New index/options/session/extraction modules fix serial encoding, stale callbacks, failure cleanup and selected reentry paths. Pixel/frame correctness, resource budgets and additional boundaries remain for task03; old/final core acceptance remains task05. Risk stays open rather than claiming complete extraction repair. Task11 fixes throwing event-property cleanup skipping deadline/frame cancellation: eight controlled regressions fail on pre-change main and pass source/main/legacy; each actual artifact also passes21 native lifecycle checks. This does not prove spontaneous native setter failure or close remaining resource/pixel/combination gates."
    },
    {
      "id": "AUTO-THUMB-ENCODE-01",
@@ -1820,7 +1820,8 @@
        "CORE-07",
        "PKG-AUTO-THUMB-08",
        "PKG-AUTO-THUMB-09",
-        "PKG-AUTO-THUMB-10"
+        "PKG-AUTO-THUMB-10",
+        "PKG-AUTO-THUMB-11"
      ],
      "status": "todo",
      "risk": "H",
@@ -5222,6 +5223,27 @@
        "changes/2026-09-14-PKG-MULTI-SUB-11-ass-conversion.md",
        "baselines/multiple-subtitles-ass-validation.json"
      ]
+    },
+    {
+      "id": "PKG-AUTO-THUMB-11",
+      "phase": "5 包迁移：artplayer-plugin-auto-thumbnail",
+      "title": "保证抽帧事件属性清理异常不截断其他资源释放",
+      "scope": [
+        "artplayer-plugin-auto-thumbnail"
+      ],
+      "dependsOn": [
+        "PKG-AUTO-THUMB-02",
+        "PKG-AUTO-THUMB-07",
+        "PKG-AUTO-THUMB-10"
+      ],
+      "status": "done",
+      "risk": "M",
+      "deliverable": "独立清除事件属性、抽帧时限和原生帧回调；首个异常保留，过期回调失效，替换任务可继续",
+      "acceptance": "八个故障注入用例旧红新绿，实际main/legacy抽帧与三浏览器生命周期回归通过；文档和构建同步，首帧及整体资源验收不冒充完成",
+      "evidence": [
+        "changes/2026-09-14-PKG-AUTO-THUMB-11-handler-cleanup.md",
+        "baselines/auto-thumbnail-handler-validation.json"
+      ]
    }
  ]
 }