refactor(thumbnail): [PKG-TOOL-THUMB-03] own extraction jobs and source cancellation

2026-10-13 07:46:17 -08:00 · 2026-09-13 04:25:22 +08:00
1 parent 426c0c5d42
commit efd9f42fb9
@@ -0,0 +1,88 @@
+# PKG-TOOL-THUMB-03 owned extraction and source lifecycle
+
+Started from 426c0c5d4209aa91be7414b810f1e8dca712c297, following the input/sheet
+checkpoint. This completes the runtime responsibility split for 03; strict TS,
+emitter provenance and public declarations remain in 04. Existing release/core
+integration and Windows WebKit/Safari evidence gates remain in 05/06.
+
+## Implementation and observable behavior
+
+The public class delegates to input, sheet, source, extraction and lifecycle
+modules. Private WeakMap state owns generations, listeners, jobs and generated
+URLs without adding public instance fields. Input setup also guards reentrant
+replacement/destruction. Construction failure marks the instance closed and
+releases its partial media resources.
+
+Source loading keeps synchronous file-before-src-before-video ordering. New
+successful selections revoke superseded source URLs and cancel the old extraction.
+Nested file callbacks and URL-creation hooks cannot overwrite newer selections.
+Native metadata/error listeners belong to their source generation. Errors now
+report through the tool and settle a waiting/running job; stale callbacks do not
+affect the latest source.
+
+Each extraction has one promise, owned metadata timer/listeners and per-frame
+readiness cleanup. It preserves preflight throws, midpoint/grid/footer geometry,
+normal progress/done order, undefined completion and the previous oncanplay owner.
+A start before the first selected file retains its wait and adopts that first
+selection. A replacement of an existing source cancels old work. Existing sheet
+URLs remain available until replaced by a new frame or destruction.
+
+Destruction/replacement rejects cancelled work with AbortError and does not emit
+error for intentional cancellation. An internal rejection handler prevents ignored
+cancelled jobs from becoming orphan rejections; the returned promise still rejects
+for consumers. Native canvas encoding itself has no cancellation operation here:
+the job settles immediately and its eventual callback is ignored. No new URL,
+update/done event or next frame may be published by that callback.
+
+Null Blob, seek/draw/toBlob failures and throwing update/error/done callbacks settle
+the promise after cleanup. Duplicate readiness/Blob callbacks cannot double-publish
+a frame. Completion releases ownership before done so a callback can start another
+job. Reentrant listener/timer installation or URL creation is checked after host
+calls, including handles registered only after destruction returned.
+
+Destroy now pauses the native video, removes its src, calls load to reset media
+state and removes the node. Cleanup continues after individual failures. Private
+URLs are released even if callers changed public URL properties; historical cleanup
+of current public URL values is retained. Closed start returns a rejecting promise;
+closed download retains chaining and allocates no anchor.
+
+Default height and video-event timing remain the workspace 4.4.0 behavior. This
+does not resolve the pre-existing recovered 3.5.31 default differences documented
+in thumbnail-contract.md. No silent default-mode or legacy-CSS decision is made.
+
+## Verification
+
+26 new lifecycle cases plus the previous 14 candidate input cases run on source,
+main and legacy. Frozen workspace running the new lifecycle assertions has 2
+passes and 24 failures. Normal extraction, cancellation/error paths, native media
+errors, late/duplicate callbacks, nested loads/setup, first-selection waiting,
+public URL mutation and decoder-reset failure handling are covered.
+
+Each final browser run has 57 rows: 34 real tool scenarios in Chromium/Firefox,
+3 candidate input/DOM cases across all engines, 17 Windows WebKit Blob-unavailable
+controls and 3 independent native-media comparisons. Candidate cases now require
+error notification, replaced-source URL cleanup and rejected/ignored late encoding;
+historical cases still assert their old defects. A real file is replaced while a
+native PNG callback is held; only the new source produces ten updates and one done.
+Successful extraction also verifies retired video readyState=0 and no src attribute.
+The 17 unavailable controls are not successful file extraction.
+
+Earlier passing source/main probe reports remain archived; final media-reset
+source/main/legacy results and hashes are in thumbnail-lifecycle-validation.json.
+Normal builds regenerate UMD, legacy and ESM plus byte-identical docs copies. The
+new lifecycle file is included in test:thumbnail and the normal unit/CI script.
+The coverage policy still measures core/chapter only; no tool percentage is claimed.
+
+## Completion and continuation
+
+03 completes the runtime split and the reproduced ownership fixes. The package
+ARCHITECTURE.md describes actual dependencies, resources, ordering, tests and
+limits. 04 owns strict TS, the now-unused sleep/serial utility cleanup, emitter
+attribution, installed public declarations and the explicit historical default
+compatibility policy. 05 owns complete old/new-core sheet integration and actual
+Safari/WebKit Blob extraction; 06 owns promised ESM/type paths, README demo and
+candidate tarball validation. Risks stay open until those gates are met.
+
+Rollback by reverting this dedicated completion commit and rebuilding the package;
+the preceding input checkpoint and all frozen historical tests remain available.
+No new dependencies, version bump, push, tag, hosted CI run or npm publication.
@@ -4,7 +4,7 @@

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

-状态：todo 100 / doing 11 / blocked 0 / done 111 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 100 / doing 10 / blocked 0 / done 112 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -357,7 +357,7 @@
 | --- | --- | --- | --- | --- | --- | --- |
 | PKG-TOOL-THUMB-01 | artplayer-tool-thumbnail<br>核对包契约与历史用法 | BASE-05 | 构造/defaults/事件/方法/历史拼写、.esm.js 入口和缺失 types | 源码/声明/README/demo/可恢复发布内容差异已登记；公开形状和版本范围冻结；区分旧 npm 的 main/CSS 与当前工作区无 main、.esm.js/类型缺失，不把工作区状态冒称旧 npm 发布事实 | H | done |
 | PKG-TOOL-THUMB-02 | artplayer-tool-thumbnail<br>建立特有行为与错误测试 | PKG-TOOL-THUMB-01, ENG-03, ENG-05 | 文件输入/拖放、抽帧网格、begin/end、进度/失败/重复任务 | 旧版本行为可重跑，成功/失败/切源/销毁有必要断言 | H | done |
-| PKG-TOOL-THUMB-03 | artplayer-tool-thumbnail<br>整理内部职责与资源 | PKG-TOOL-THUMB-02, CORE-01 | 输入、抽帧队列、网格导出、URL/监听清理分离 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | doing |
+| PKG-TOOL-THUMB-03 | artplayer-tool-thumbnail<br>整理内部职责与资源 | PKG-TOOL-THUMB-02, CORE-01 | 输入、抽帧队列、网格导出、URL/监听清理分离 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | done |
 | PKG-TOOL-THUMB-04 | artplayer-tool-thumbnail<br>迁移自有源码和公开类型 | PKG-TOOL-THUMB-03, ENG-04, ENG-06, CORE-07 | 补齐真实 API 声明，自有 emitter/utils TS 化 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容；为 BASE-DIST-01 提供兼容入口/声明及消费者验证 | H | todo |
 | PKG-TOOL-THUMB-05 | artplayer-tool-thumbnail<br>验证新旧核心和组合 | PKG-TOOL-THUMB-04, CORE-22 | 工具独立浏览器使用，生成缩略图在核心中显示 | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | H | todo |
 | PKG-TOOL-THUMB-06 | artplayer-tool-thumbnail<br>验证分发并同步文档 | PKG-TOOL-THUMB-05, ENG-07 | tool.thumbnail.js、历史 ESM 兼容文件、types 路径和 tarball | tarball 入口/资源、类型、8082 demo 和 README 一致，有回退记录 | H | todo |
@@ -537,5 +537,5 @@
 - PKG-IFRAME-05: [记录](changes/2026-09-13-PKG-IFRAME-05-integration.md) [记录](baselines/iframe-integration-validation.json) [记录](changes/2026-09-13-PKG-IFRAME-05-history.md) [记录](baselines/iframe-history-validation.json)
 - PKG-TOOL-THUMB-01: [记录](baselines/thumbnail-release.json) [记录](baselines/thumbnail-contract.md) [记录](changes/2026-09-13-PKG-TOOL-THUMB-01-contract.md) [记录](baselines/thumbnail-contract-validation.json)
 - PKG-TOOL-THUMB-02: [记录](baselines/thumbnail-behavior-validation.json) [记录](changes/2026-09-13-PKG-TOOL-THUMB-02-behavior.md)
- PKG-TOOL-THUMB-03: [记录](changes/2026-09-13-PKG-TOOL-THUMB-03-input-checkpoint.md) [记录](baselines/thumbnail-input-checkpoint.json)
+- PKG-TOOL-THUMB-03: [记录](changes/2026-09-13-PKG-TOOL-THUMB-03-input-checkpoint.md) [记录](baselines/thumbnail-input-checkpoint.json) [记录](changes/2026-09-13-PKG-TOOL-THUMB-03-lifecycle.md) [记录](baselines/thumbnail-lifecycle-validation.json)
 - PKG-FACTORY-01: [记录](baselines/factory-assignment-gaps.json) [记录](baselines/factory-compatibility-proposals.json) [记录](factory-compatibility-decision.md) [记录](changes/2026-09-12-PKG-FACTORY-01-decision.md)
@@ -1,5 +1,19 @@
 # 进度与证据

+## PKG-TOOL-THUMB-03 完成：抽帧任务与媒体资源所有权
+
+增加lifecycle/source/extraction模块，保留公开类形状与工作区默认行为。元数据等待、
+逐帧回调和URL归属明确；切源/destroy立即取消旧Promise，迟到PNG不能再update或创建URL。
+修复原生错误、null Blob、监听器异常和重入；保留首次选文件前start等待。销毁暂停/清空
+src/load重置媒体，即使部分清理抛错也继续。源码仍为JS，04负责严格TS/声明与来源审查。
+新26项生命周期断言在冻结旧版2通过/24失败；连同输入测试，源码/main/legacy各40通过。
+三份浏览器各57通过：34真实工具场景、3输入场景、17Blob不可用对照、3原生媒体对照。
+实际切源期间持有原生PNG回调验证仅新任务完成，销毁后readyState=0且无src。
+完整CI1646、330生产TS、3导入及候选ESM导入通过。类型/默认历史差异及Safari/分发风险
+仍open。见[变更](changes/2026-09-13-PKG-TOOL-THUMB-03-lifecycle.md)与
+[验证](baselines/thumbnail-lifecycle-validation.json)。222项：112 done、10 doing、100 todo。
+
+
 ## PKG-TOOL-THUMB-03 输入与导出源码检查点（doing）

 生产入口拆出input/sheet模块，修复drop注册、输入切换与wrapper所有权、构造/安装失败
@@ -177,7 +177,7 @@
 | IFRAME-LIFE-01 | open / 已复现 | Iframe timestamp IDs and unowned pending requests/timers lack terminal cleanup | PKG-IFRAME-02, PKG-IFRAME-03, PKG-IFRAME-05 |
 | IFRAME-TRUST-01 | open / 已复现 | Iframe executable commit protocol accepts messages without source/origin validation | PKG-IFRAME-03, PKG-IFRAME-05 |
 | IFRAME-DIST-01 | open / 已复现 | Iframe tool name is unavailable at registry observation and old archive includes distinct helper exports | PKG-IFRAME-04, PKG-IFRAME-06 |
-| THUMB-COMPAT-01 | open / 已复现 | Thumbnail recovered 3.5.31 and workspace 4.4.0 have conflicting height and event timing defaults | PKG-TOOL-THUMB-02, PKG-TOOL-THUMB-03, PKG-TOOL-THUMB-04 |
+| THUMB-COMPAT-01 | open / 已复现 | Thumbnail recovered 3.5.31 and workspace 4.4.0 have conflicting height and event timing defaults | PKG-TOOL-THUMB-04, PKG-TOOL-THUMB-05 |
 | THUMB-LIFE-01 | open / 已复现 | Thumbnail drop binding and repeated destroy fail; pending work and replacement resource ownership need repair | PKG-TOOL-THUMB-02, PKG-TOOL-THUMB-03, PKG-TOOL-THUMB-05 |
 | THUMB-PROVENANCE-01 | open / 源码/产物事实 | Thumbnail local emitter attribution and historical distribution completeness remain unverified | PKG-TOOL-THUMB-04, PKG-TOOL-THUMB-06 |
 | THUMB-MEDIA-01 | open / 已复现 | Windows WebKit native Blob URLs cannot load tested MP4 media despite successful HTTP controls | PKG-TOOL-THUMB-05, PKG-TOOL-THUMB-06 |
@@ -3853,9 +3853,8 @@
      "title": "Thumbnail recovered 3.5.31 and workspace 4.4.0 have conflicting height and event timing defaults",
      "confirmation": "reproduced",
      "owners": [
-        "PKG-TOOL-THUMB-02",
-        "PKG-TOOL-THUMB-03",
-        "PKG-TOOL-THUMB-04"
+        "PKG-TOOL-THUMB-04",
+        "PKG-TOOL-THUMB-05"
      ],
      "compatibleResolution": "Freeze both implementations and derive a concrete compatibility policy before changing defaults; no silent claim that identical calls have identical historical semantics.",
      "closureCriteria": "Explicit documented compatibility decision, old/candidate tests and migration examples covering delay, height, input reset and readiness.",
@@ -3867,7 +3866,8 @@
        "refactor/baselines/thumbnail-behavior-validation.json",
        "refactor/changes/2026-09-13-PKG-TOOL-THUMB-02-behavior.md",
        "test/thumbnail.test.js",
-        "test/browser/thumbnail-tool.spec.js"
+        "test/browser/thumbnail-tool.spec.js",
+        "refactor/changes/2026-09-13-PKG-TOOL-THUMB-03-lifecycle.md"
      ]
    },
    {
@@ -3879,7 +3879,7 @@
        "PKG-TOOL-THUMB-03",
        "PKG-TOOL-THUMB-05"
      ],
-      "compatibleResolution": "03 input checkpoint fixes registered drop, input/wrapper ownership, failed setup/construction cleanup, repeated destroy and temporary download anchors. Candidate input regressions contrast 12 old failures; source/main/legacy verify preserved shape. Pending extraction callbacks, source URL replacement, cancellation and failure reentrancy remain open for the rest of 03 and real integration in 05.",
+      "compatibleResolution": "03 splits input/sheet/source/extraction/lifecycle and fixes reproduced cancellation, Blob URL ownership, native errors, callback failure/reentrancy and decoder reset. Keep risk open for 04 strict types and 05 complete core/Safari integration; Windows WebKit Blob-unavailable controls do not prove extraction.",
      "closureCriteria": "Deterministic old failure/candidate success for replacement, error and destruction plus real media/browser resource validation.",
      "status": "open",
      "evidence": [
@@ -3894,7 +3894,10 @@
        "packages/artplayer-tool-thumbnail/ARCHITECTURE.md",
        "test/thumbnail-input.test.js",
        "test/browser/thumbnail-input.spec.js",
-        "refactor/baselines/thumbnail-input-checkpoint.json"
+        "refactor/baselines/thumbnail-input-checkpoint.json",
+        "refactor/changes/2026-09-13-PKG-TOOL-THUMB-03-lifecycle.md",
+        "test/thumbnail-lifecycle.test.js",
+        "refactor/baselines/thumbnail-lifecycle-validation.json"
      ]
    },
    {
@@ -3785,13 +3785,15 @@
        "PKG-TOOL-THUMB-02",
        "CORE-01"
      ],
-      "status": "doing",
+      "status": "done",
      "risk": "H",
      "deliverable": "输入、抽帧队列、网格导出、URL/监听清理分离",
      "acceptance": "结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过",
      "evidence": [
        "changes/2026-09-13-PKG-TOOL-THUMB-03-input-checkpoint.md",
-        "baselines/thumbnail-input-checkpoint.json"
+        "baselines/thumbnail-input-checkpoint.json",
+        "changes/2026-09-13-PKG-TOOL-THUMB-03-lifecycle.md",
+        "baselines/thumbnail-lifecycle-validation.json"
      ]
    },
    {