refactor(auto-thumbnail): [PKG-AUTO-THUMB-04] verify source and installed type migration

2026-10-11 22:06:17 -08:00 · 2026-09-15 12:39:13 +08:00
1 parent 42ddead0cd
commit 8dcbe9441e
@@ -157,11 +157,12 @@ historical missing 1.0.0 main/legacy files without substituting source-only code
 Historical contract/failure tests remain separate and continue to reproduce old
 defects; their passing status does not mean those defects should remain.

-The public type entry is tracked independently as `PKG-AUTO-THUMB-08`, split from
-04 so that declaration work can proceed without weakening the unfinished 03
-pixel gate. Task04 still depends on both 03 and 08. The source/runtime remains an
-intermediate `PKG-AUTO-THUMB-03` implementation. Native lifecycle
-validation does not prove correct pixels. The attached renderer now has native
+The public type entry originated in `PKG-AUTO-THUMB-08`; task09 restored the
+historical factory alias. Task04 has verified the complete strict source and
+installed public type/module surfaces using those changes and resource fixes
+07/10/11/12. Task03 remains unfinished; task05 depends directly on both 03 and 04,
+so type completion cannot waive its pixel gate. Native lifecycle validation does
+not prove correct pixels. The attached renderer now has native
 pixel checks for all five cells when native frame callbacks are available,
 including the unique first frame, real black content, changing colors, spatial
 detail and presentation timestamps. The callback-less fallback still only has
@@ -224,8 +225,9 @@ annotations describe the nominal options; no runtime casts or
 normalization were added, so historical coercible JS inputs retain the same
 validation/arithmetic and raw values. Missing options retain the existing behavior.
 Tasks08/09 supplied the compatible public declarations, implementation assignment
-fixtures and historical CommonJS alias. Task04 still requires the completed task03
-implementation and final migration acceptance. Task05 verifies old/final cores and actual
+fixtures and historical CommonJS alias. Task04's migration acceptance is recorded
+in `refactor/changes/2026-09-15-PKG-AUTO-THUMB-04-migration.md`; unresolved runtime
+behavior remains with task03. Task05 requires both and verifies old/final cores and actual
 devices; task06 covers installed package entries and the real demo/editor. The
 package version remains unchanged. Use
 `refactor/baselines/auto-thumbnail-contract.md` and `auto-thumbnail-failures.md` as
@@ -0,0 +1,78 @@
+# PKG-AUTO-THUMB-04: complete source and public type migration acceptance
+
+Checked source/artifact commit: 42ddead0cd7dbc254837262ae59a2016b2321413.
+
+## Delivered implementation
+
+All eight owned production modules are TypeScript. `index` owns registration and
+subscriptions; `options` preserves historical option reads and arithmetic;
+`session` owns job identity, cleanup and Blob URLs; `video` owns the private media
+element; `extraction` orchestrates metadata and sheets; `frames` and `encoding`
+own their respective pending operations; `types` defines their minimal internal
+contracts. Only the entry receives the ArtPlayer host. There is no remaining
+production JS exception or replacement of the public API by an internal type.
+
+The implementation was delivered incrementally in the task03 TS checkpoint and
+tasks07-12; this acceptance commit consolidates their actual scope, rather than
+claiming to migrate them a second time. The package's strict configuration covers
+all source files and the actual-core host assignment fixture. It inherits strict,
+noUncheckedIndexedAccess, isolatedModules and skipLibCheck:false, with allowJs:false.
+
+Task08 retained the npm1.1.0 root declaration and added the optional accurate
+`/runtime` view. Task09 restored the writable recursive `.default` alias without
+changing the old root type extraction. Root and legacy declaration bytes remain
+equal to npm1.1.0 after newline normalization. The optional runtime API describes
+the real registration Promise, required options object, ignored historical height,
+and Factory/RuntimeFactory distinction. All entrypoints use the same existing
+runtime artifacts. No public type or runtime change is made in this final audit.
+
+## Current evidence
+
+- Package strict compilation and source/declaration lint pass on Node24.21.0 and
+  Yarn1.22.22. Eight source modules are included, with no allowJs or skipLibCheck
+  escape. The implementation fixture assigns the real export to both runtime
+  factory contracts and accepts the real core instance.
+- `yarn test:auto-thumbnail-types-package` packs current core and plugin, installs
+  outside the workspace, verifies installed bytes and frozen reinstall locks, and
+  runs 10 compiler profiles: npm1.1.0 and candidate with TS5.9.3 Node10, NodeNext
+  CJS/ESM, Bundler, and TS4.3.5 Node10. Positive consumers and exact negative-line
+  diagnostics pass, including no-interop CommonJS runtime imports. Historical
+  npm Node10 legacy resolution failures remain explicitly expected, not hidden.
+- Actual installed npm1.0.1 default calls and 1.1.0 direct calls retain their
+  historical identities. The old1.0.0 package's missing main/legacy is confirmed
+  as a distribution defect, not counted as runnable compatibility. Candidate
+  root/legacy/runtime module identities, Promise registration and cleanup pass.
+- `yarn check:editor-types` verifies24 existing outputs with both compilers without
+  rewriting declarations or assets. Packed manifests/files and all declaration
+  hashes are captured in the [machine record](../baselines/auto-thumbnail-migration-validation.json).
+- The prescribed whole-repository `yarn lint` scope passes. An additional direct
+  lint of `refactor/scripts/plan.mjs` reports17 existing style/import diagnostics,
+  identical on HEAD and the candidate; that file is outside the root lint range.
+  No new diagnostic is introduced by the dependency assertion. Plan and risk
+  validators pass. An in-memory negative dependency check confirms that removing
+  the task03 prerequisite from task05 is rejected without editing workspace files.
+- Unchanged-runtime evidence from task12 remains applicable:189 source tests,
+  main/legacy82 each, and36 native browser cases per artifact. This audit compares
+  current artifact hashes to that record instead of rerunning unchanged playback.
+  The recorded Windows WebKit first-cell limitation remains in force.
+
+## Dependency correction and retained requirements
+
+The original linear dependency made type acceptance wait for task03's native
+pixel investigation, although the type and source work was already implemented
+and independently testable. Task04 now depends on the completed contract/type/
+resource prerequisites. Task05 directly depends on BOTH task03 and task04, and
+the plan validator enforces the task03 ancestor. Task03's status, acceptance,
+pixel risk and device requirements are unchanged. Final integration, task06 and
+release still require it; only independent source/type and version preparation
+can advance. This is scheduling within the authorized plan, not a browser waiver.
+
+Task04 is complete. Task03 and AUTO-THUMB-PIXEL-01 stay open; no whole-package,
+remote CI, final installed-browser matrix, physical-device or npm readiness claim
+is made. Package versions, dependencies, lockfile and distribution bytes are
+unchanged. Maintenance commands and module ownership live in the package README
+and ARCHITECTURE, rather than requiring future maintainers to reconstruct history.
+
+Reverting this acceptance commit restores the prior dependency/status and docs.
+Implementation remains in its original independently revertible commits; changing
+those contents requires fresh relevant acceptance. No push, publish or deployment.
@@ -15,6 +15,8 @@

 复杂包可以把任一步拆成新子任务并保留依赖。每步不要求一次提交解决全部；默认按一个可回退行为边界切分。

+Auto-thumbnail 的 04 现基于已完成的类型、入口及资源修复子任务独立验收；03 的首帧像素和剩余抽帧问题仍保持原验收要求，由 05 直接依赖 03 和 04。这样类型和版本准备可以继续，整包集成、分发及发布仍不能越过未完成的 03；计划校验器强制保留这条依赖。此调整不修改任何浏览器支持或像素断言。
+
 六步同时受 quality-contract.md 约束：步骤 03 交付清楚的职责与依赖，步骤 04 不能仅改扩展名，步骤 05 验证有风险的真实行为，步骤 06 验收包内实现地图与维护命令。包内架构文档从实现开始同步维护，不能只在最后一步补写。

 chapter 作为早期试点，03/04 在已有核心上完成，不使用候选核心内部能力；随后 PILOT-01 先完成一次类型、浏览器、tarball 与维护文档闭环。05/06 仍在最终候选核心上重新验收，其他包的旧版本基线仍由各自 01 步负责。
@@ -4,7 +4,7 @@

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

-状态：todo 44 / doing 22 / blocked 0 / done 200 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 43 / doing 22 / blocked 0 / done 201 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -178,8 +178,8 @@
 | 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, PKG-AUTO-THUMB-11 | 抽帧结果和真实异步插件返回类型兼容 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | H | todo |
-| PKG-AUTO-THUMB-05 | artplayer-plugin-auto-thumbnail<br>验证新旧核心和组合 | PKG-AUTO-THUMB-04, CORE-22, PKG-AUTO-THUMB-12 | 旧核心/候选核心预览、多次加载无过期缩略图覆盖 | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | H | todo |
+| PKG-AUTO-THUMB-04 | artplayer-plugin-auto-thumbnail<br>迁移自有源码和公开类型 | PKG-AUTO-THUMB-02, CORE-09, CORE-19, PKG-AUTO-THUMB-07, PKG-AUTO-THUMB-12, ENG-04, ENG-06, CORE-07, PKG-AUTO-THUMB-08, PKG-AUTO-THUMB-09, PKG-AUTO-THUMB-10, PKG-AUTO-THUMB-11 | 抽帧结果和真实异步插件返回类型兼容 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | H | done |
+| PKG-AUTO-THUMB-05 | artplayer-plugin-auto-thumbnail<br>验证新旧核心和组合 | PKG-AUTO-THUMB-04, CORE-22, PKG-AUTO-THUMB-12, PKG-AUTO-THUMB-03 | 旧核心/候选核心预览、多次加载无过期缩略图覆盖 | 最终核心与原支持范围核心分别通过；设备/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 |
@@ -558,6 +558,7 @@
 - PKG-AUTO-THUMB-01: [记录](baselines/auto-thumbnail-release.json) [记录](baselines/auto-thumbnail-contract.md) [记录](changes/2026-09-13-PKG-AUTO-THUMB-01-contract.md) [记录](baselines/auto-thumbnail-contract-validation.json)
 - PKG-AUTO-THUMB-02: [记录](baselines/auto-thumbnail-failures.md) [记录](baselines/auto-thumbnail-failures-validation.json) [记录](changes/2026-09-13-PKG-AUTO-THUMB-02-failures.md)
 - PKG-AUTO-THUMB-03: [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-lifecycle-checkpoint.md) [记录](baselines/auto-thumbnail-lifecycle-checkpoint.json) [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-hidden-renderer.md) [记录](baselines/auto-thumbnail-hidden-renderer.json) [记录](baselines/auto-thumbnail-timeline-media.json) [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-frame-presentation.md) [记录](baselines/auto-thumbnail-frame-presentation.json) [记录](changes/2026-09-14-PKG-AUTO-THUMB-03-rendering-readiness.md) [记录](baselines/auto-thumbnail-rendering-readiness.json) [记录](changes/2026-09-14-PKG-AUTO-THUMB-03-first-seek.md) [记录](baselines/auto-thumbnail-first-seek.json) [记录](changes/2026-09-14-PKG-AUTO-THUMB-03-native-decoder.md) [记录](baselines/auto-thumbnail-native-decoder.json)
+- PKG-AUTO-THUMB-04: [记录](changes/2026-09-15-PKG-AUTO-THUMB-04-migration.md) [记录](baselines/auto-thumbnail-migration-validation.json) [记录](changes/2026-09-13-PKG-AUTO-THUMB-03-internal-types.md) [记录](baselines/auto-thumbnail-metadata-validation.json)
 - PKG-VTT-THUMB-01: [记录](baselines/vtt-thumbnail-release.json) [记录](baselines/vtt-thumbnail-contract.md) [记录](changes/2026-09-13-PKG-VTT-THUMB-01-contract.md)
 - PKG-VTT-THUMB-02: [记录](baselines/vtt-thumbnail-failures.json) [记录](changes/2026-09-13-PKG-VTT-THUMB-02-failures.md)
 - PKG-VTT-THUMB-03: [记录](changes/2026-09-13-PKG-VTT-THUMB-03-resources.md) [记录](baselines/vtt-thumbnail-resources.json) [记录](changes/2026-09-13-PKG-VTT-THUMB-03-parser.md) [记录](baselines/vtt-thumbnail-parser.json)
@@ -1,5 +1,12 @@
 # 进度与证据

+## PKG-AUTO-THUMB-04 完成源码与公开类型迁移验收
+
+八个自有模块均为严格 TS，当前包及真实核心接入 fixture 编译/lint 通过；当前 tarball 与 npm 旧包在仓库外完成 10 组 TS/模块解析、精确负例、导出身份和 Promise 注册检查，编辑器 24 个声明输出只读检查通过。运行字节未改，与任务12的189项源码、两份产物各82项及各36项浏览器证据指纹相同。见[记录](changes/2026-09-15-PKG-AUTO-THUMB-04-migration.md)及[证据](baselines/auto-thumbnail-migration-validation.json)。
+
+04 基于已完成子任务独立验收；05 直接依赖03与04，校验器保护03门槛。03原验收、首帧风险与设备要求未降低，完整包仍不能标完成。状态201/266 done、22 doing、43 todo。Thumbnail工具的默认兼容选择仍待用户答复，后续独立工作继续。
+
+
 ## PKG-AUTO-THUMB-12 元数据加载超时与资源回收

 修复隐藏视频在未收到 metadata/error 时永久等待：独立 30 秒期限归 extraction/job 所有，成功/取消后旧期限失效，超时保留上一张可用图。旧 main 的 7 项回归全红；源码 189/189、main/legacy 各 82/82，重建后三引擎各 36/36。首版 WebKit 请求拦截等待失败已保留，最终用真实 HTTP 挂起端点及服务端到达证据验证。期限回调由测试显式触发，不声称等待了真实 30 秒。见[变更](changes/2026-09-15-PKG-AUTO-THUMB-12-metadata.md)与[证据](baselines/auto-thumbnail-metadata-validation.json)。
@@ -81,6 +81,7 @@ for (const device of ['PKG-CAST-05', 'PKG-VAST-05', 'PKG-DPIP-05', 'PKG-MASK-05'
  requireAncestor('REVIEW-02', device)
 }
 requireAncestor('REL-02', 'REL-09')
+requireAncestor('PKG-AUTO-THUMB-05', 'PKG-AUTO-THUMB-03')
 for (const release of ['REL-05', 'REL-06']) {
  for (const gate of ['REVIEW-01', 'REVIEW-02', 'REVIEW-03', 'CI-04', 'REL-03', 'REL-04', 'REL-09']) {
    requireAncestor(release, gate)
@@ -1848,7 +1848,11 @@
        "artplayer-plugin-auto-thumbnail"
      ],
      "dependsOn": [
-        "PKG-AUTO-THUMB-03",
+        "PKG-AUTO-THUMB-02",
+        "CORE-09",
+        "CORE-19",
+        "PKG-AUTO-THUMB-07",
+        "PKG-AUTO-THUMB-12",
        "ENG-04",
        "ENG-06",
        "CORE-07",
@@ -1857,11 +1861,16 @@
        "PKG-AUTO-THUMB-10",
        "PKG-AUTO-THUMB-11"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "H",
      "deliverable": "抽帧结果和真实异步插件返回类型兼容",
      "acceptance": "严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-15-PKG-AUTO-THUMB-04-migration.md",
+        "baselines/auto-thumbnail-migration-validation.json",
+        "changes/2026-09-13-PKG-AUTO-THUMB-03-internal-types.md",
+        "baselines/auto-thumbnail-metadata-validation.json"
+      ]
    },
    {
      "id": "PKG-AUTO-THUMB-05",
@@ -1873,7 +1882,8 @@
      "dependsOn": [
        "PKG-AUTO-THUMB-04",
        "CORE-22",
-        "PKG-AUTO-THUMB-12"
+        "PKG-AUTO-THUMB-12",
+        "PKG-AUTO-THUMB-03"
      ],
      "status": "todo",
      "risk": "H",