refactor(thumbnail): [PKG-TOOL-THUMB-04] type runtime modules and retain emitter attribution

2026-10-17 18:11:20 -08:00 · 2026-09-13 04:45:01 +08:00
1 parent efd9f42fb9
commit 15485b6420
@@ -0,0 +1,22 @@
+{
+  "reviewedAt": "2026-09-12T20:36:43.265Z",
+  "referenceVersion": "2.1.0",
+  "sources": [
+    {
+      "file": "refactor/baselines/thumbnail-vendor/tiny-emitter-2.1.0.txt",
+      "url": "https://raw.githubusercontent.com/scottcorgan/tiny-emitter/2.1.0/index.js",
+      "sha256": "3e3679233f20177d63d253e7c2645024fef51731d05df15621c62a48ba98e0d3"
+    },
+    {
+      "file": "refactor/baselines/thumbnail-vendor/tiny-emitter-license.txt",
+      "url": "https://raw.githubusercontent.com/scottcorgan/tiny-emitter/2.1.0/LICENSE",
+      "sha256": "aada4c7da6a5be46beadf9d4f40d7dba9e222e57180d46289b2bb9112e65daae"
+    },
+    {
+      "file": "refactor/baselines/thumbnail-vendor/tiny-emitter-package.json",
+      "url": "https://raw.githubusercontent.com/scottcorgan/tiny-emitter/2.1.0/package.json",
+      "sha256": "f5328afd1e742ba9b107e316e5fc4c74ec81201bafad8eb8e6dc456ef6d628de"
+    }
+  ],
+  "limitation": "Pinned upstream comparison reference. Structural correspondence and the recovered 3.5.31 dependency establish attribution, not the exact original copy revision or complete npm archive."
+}
@@ -0,0 +1,67 @@
+function E () {
+  // Keep this empty so it's easier to inherit from
+  // (via https://github.com/lipsmack from https://github.com/scottcorgan/tiny-emitter/issues/3)
+}
+
+E.prototype = {
+  on: function (name, callback, ctx) {
+    var e = this.e || (this.e = {});
+
+    (e[name] || (e[name] = [])).push({
+      fn: callback,
+      ctx: ctx
+    });
+
+    return this;
+  },
+
+  once: function (name, callback, ctx) {
+    var self = this;
+    function listener () {
+      self.off(name, listener);
+      callback.apply(ctx, arguments);
+    };
+
+    listener._ = callback
+    return this.on(name, listener, ctx);
+  },
+
+  emit: function (name) {
+    var data = [].slice.call(arguments, 1);
+    var evtArr = ((this.e || (this.e = {}))[name] || []).slice();
+    var i = 0;
+    var len = evtArr.length;
+
+    for (i; i < len; i++) {
+      evtArr[i].fn.apply(evtArr[i].ctx, data);
+    }
+
+    return this;
+  },
+
+  off: function (name, callback) {
+    var e = this.e || (this.e = {});
+    var evts = e[name];
+    var liveEvents = [];
+
+    if (evts && callback) {
+      for (var i = 0, len = evts.length; i < len; i++) {
+        if (evts[i].fn !== callback && evts[i].fn._ !== callback)
+          liveEvents.push(evts[i]);
+      }
+    }
+
+    // Remove event from queue to prevent memory leak
+    // Suggested by https://github.com/lazd
+    // Ref: https://github.com/scottcorgan/tiny-emitter/commit/c6ebfaa9bc973b33d110a84a307742b7cf94c953#commitcomment-5024910
+
+    (liveEvents.length)
+      ? e[name] = liveEvents
+      : delete e[name];
+
+    return this;
+  }
+};
+
+module.exports = E;
+module.exports.TinyEmitter = E;
@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Scott Corgan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
@@ -0,0 +1,53 @@
+{
+  "name": "tiny-emitter",
+  "version": "2.1.0",
+  "description": "A tiny (less than 1k) event emitter library",
+  "main": "index.js",
+  "scripts": {
+    "test-node": "tape test/index.js | tap-format-spec",
+    "test": "testling | tap-format-spec",
+    "bundle": "node_modules/.bin/browserify index.js > dist/tinyemitter.js -s TinyEmitter && echo 'Bundled'",
+    "minify": "node_modules/.bin/uglifyjs dist/tinyemitter.js -o dist/tinyemitter.min.js -m && echo 'Minified'",
+    "build": "npm test && npm run bundle && npm run minify",
+    "size": "node_modules/.bin/uglifyjs index.js -o minified.js -m && ls -l && rm minified.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scottcorgan/tiny-emitter.git"
+  },
+  "keywords": [
+    "event",
+    "emitter",
+    "pubsub",
+    "tiny",
+    "events",
+    "bind"
+  ],
+  "author": "Scott Corgan",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/scottcorgan/tiny-emitter/issues"
+  },
+  "devDependencies": {
+    "@tap-format/spec": "0.2.0",
+    "browserify": "11.2.0",
+    "tape": "4.2.1",
+    "testling": "1.7.1",
+    "uglify-js": "2.5.0"
+  },
+  "testling": {
+    "files": [
+      "test/index.js"
+    ],
+    "browsers": [
+      "iexplore/10.0",
+      "iexplore/9.0",
+      "firefox/16..latest",
+      "chrome/22..latest",
+      "safari/5.1..latest",
+      "ipad/6.0..latest",
+      "iphone/6.0..latest",
+      "android-browser/4.2..latest"
+    ]
+  }
+}
@@ -0,0 +1,70 @@
+# PKG-TOOL-THUMB-04 runtime TypeScript checkpoint
+
+Status: doing. This checkpoint migrates executable source and records emitter
+attribution. It does not complete public declarations, installed entrypoints or
+the task's compatibility policy gate.
+
+## Source and compatibility
+
+Starts at efd9f42fb984302dd061d5cd9f96bd4de74fcccf. Eight runtime JS modules become
+strict TS, with a ninth type-only module for configuration, events, frame points,
+job controls and lifecycle state. The input and source WeakMaps remain private;
+helpers import the facade only as an erased type. Existing runtime validation is
+retained. There are no ts-ignore, ts-nocheck or broad any escape hatches. Local
+assertions and initialization invariants are explained in the package architecture
+map. Unused sleep and serial-promise helpers are removed; neither was reachable
+from the public bundle or used by the owned extraction job.
+
+declare fields preserve the old own-property order and lazy optional fields.
+Normal class exports, historical creat* spellings, synchronous validation,
+Promise<void> completion, cancellation and the workspace 4.4.0 defaults remain.
+Source options accept Element wrappers and unknown extension fields. Known event
+tuples are checked and unknown string/number/symbol events remain possible.
+The source types are internal until the package's declaration entry is supplied.
+
+## Emitter origin
+
+Pinned upstream comparison: tiny-emitter 2.1.0 index.js, package.json and LICENSE,
+fetched from its fixed Git tag and recorded with SHA-256. Its four methods and
+listener registry structure correspond to the local class; the recovered 3.5.31
+manifest also declared tiny-emitter ^2.1.0. This establishes the appropriate
+attribution, not an exact original copied revision or a recovered complete npm
+archive. Changes from that comparison reference are the existing class/ES module
+conversion, rest arguments, local names and loop/style forms, plus this migration's
+erased generic types and equivalent typed local aliases.
+
+The complete upstream MIT notice is retained in package THIRD_PARTY_NOTICES and
+the existing normal build banner includes it in all three standalone artifacts.
+No new runtime dependency is introduced. VENDOR-09 records final packed-content
+verification still outstanding; THUMB-PROVENANCE-01 retains the historical archive
+limit. Source attribution must not be replaced with the repository author's name.
+
+## Validation
+
+The validation JSON for this checkpoint records final commands, file hashes and
+browser outcomes. Six new runtime tests check public descriptors/defaults/unknown
+options/validation and compare upstream, recovered 3.5.31, frozen workspace main
+and legacy, and the selected candidate for emitter snapshot/removal/ctx/symbol/
+exception behavior. Two provenance tests verify fixed upstream bytes and full
+notice retention in package and dist/docs copies. Existing lifecycle/input tests
+remain unchanged. Source type consumers include six negative uses.
+
+Browser runs retain native media controls. Windows WebKit Blob decoding remains
+an unavailable-capability control, not successful thumbnail extraction. No new
+coverage percentage, physical Safari, remote GitHub CI or npm result is claimed.
+
+## Continue / rollback
+
+Continue 04 with the missing public declaration, legacy compiler and isolated
+installed CommonJS/ESM consumers. Resolve or explicitly request a decision for
+THUMB-COMPAT-01 (recovered 3.5.31 delay/fixed height versus workspace 4.4.0 defaults)
+before claiming compatibility closure. Review custom emitter typing and dispatch
+boundaries alongside those consumers. BASE-DIST-01 still covers the missing
+promised .esm.js and types entries; task 06 owns final distribution acceptance.
+05/06 retain supported WebKit/Safari file extraction and core integration/demo
+verification. No manifest entry, version, lockfile or package manager changes in
+this checkpoint. No push, tag or publication.
+
+To roll back, revert this checkpoint commit and rebuild the tool using the normal
+Yarn package build. Preserve upstream provenance/notice records for any retained
+copy of the emitter. Do not revert the separate 03 resource fixes accidentally.
@@ -4,7 +4,7 @@

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

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

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

@@ -358,7 +358,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 | 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-04 | artplayer-tool-thumbnail<br>迁移自有源码和公开类型 | PKG-TOOL-THUMB-03, ENG-04, ENG-06, CORE-07 | 补齐真实 API 声明，自有 emitter/utils TS 化 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容；为 BASE-DIST-01 提供兼容入口/声明及消费者验证 | H | doing |
 | 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 |

@@ -538,4 +538,5 @@
 - 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) [记录](changes/2026-09-13-PKG-TOOL-THUMB-03-lifecycle.md) [记录](baselines/thumbnail-lifecycle-validation.json)
+- PKG-TOOL-THUMB-04: [记录](changes/2026-09-13-PKG-TOOL-THUMB-04-runtime-types.md) [记录](baselines/thumbnail-runtime-types-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-04 运行时 TS 与 emitter 来源检查点（doing）
+
+8个运行时模块已迁为严格TS，新增类型模块明确option/事件/帧/job/资源状态；declare保留
+旧实例字段顺序和按需出现的字段。移除未使用的sleep/serial助手。生成ESM除许可和两个
+等价emitter局部变量外与03运行时相同，默认值和同步/异步行为保持。固定tiny-emitter
+2.1.0上游比较文件及完整MIT通知，登记VENDOR-09；不声称确定原始复制revision。
+新增6项门面/emitter兼容与2项来源/通知检查，源码/main/legacy各110项通过。
+三份浏览器各57通过（34真实工具、3输入、17Blob不可用、3原生媒体对照）。
+完整CI1654通过，339生产TS和3导入通过；保留既有编辑器声明lint警告及Yarn警告记录。
+公开声明/旧编译器/实际安装入口和默认历史差异仍待04继续，05/06保留真实设备/分发门槛。
+见[变更](changes/2026-09-13-PKG-TOOL-THUMB-04-runtime-types.md)和
+[验证](baselines/thumbnail-runtime-types-validation.json)。222项：112 done、11 doing、99 todo。
+
+
 ## PKG-TOOL-THUMB-03 完成：抽帧任务与媒体资源所有权

 增加lifecycle/source/extraction模块，保留公开类形状与工作区默认行为。元数据等待、
@@ -181,3 +181,4 @@
 | 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 |
+| VENDOR-09 | open / 源码/产物事实 | Thumbnail tiny-emitter 改写来源与最终分发许可 | PKG-TOOL-THUMB-04, PKG-TOOL-THUMB-06 |
@@ -3934,6 +3934,25 @@
      ],
      "compatibleResolution": "Preserve independent HTTP/Blob capability controls; obtain actual supported WebKit/Safari file extraction evidence before release acceptance. Do not count the 12 unavailable controls as successful thumbnail generation or silently replace local files with HTTP media.",
      "closureCriteria": "Actual generated PNG/extraction and lifecycle proof in supported Safari/WebKit environments, or explicit supported-environment decision with migration documentation; Windows limitation stays identifiable."
+    },
+    {
+      "id": "VENDOR-09",
+      "title": "Thumbnail tiny-emitter 改写来源与最终分发许可",
+      "confirmation": "source-observed",
+      "status": "open",
+      "owners": [
+        "PKG-TOOL-THUMB-04",
+        "PKG-TOOL-THUMB-06"
+      ],
+      "evidence": [
+        "refactor/baselines/thumbnail-vendor/sources.json",
+        "packages/artplayer-tool-thumbnail/src/emitter.ts",
+        "packages/artplayer-tool-thumbnail/THIRD_PARTY_NOTICES",
+        "test/thumbnail-vendor.test.js"
+      ],
+      "compatibleResolution": "Preserve original attribution, typed local dispatch compatibility and complete MIT notice in source/package/standalone bundles.",
+      "closureCriteria": "Pinned upstream reference and local adaptation reviewed; all bundle and actual packed distribution notices verified. Do not claim the exact original copied revision or a recovered complete historical archive.",
+      "workspaceState": "TS adaptation and pinned 2.1.0 source/license references recorded; normal build includes package notices. Final installed/packed distribution evidence remains with 04/06."
    }
  ]
 }
@@ -3809,11 +3809,14 @@
        "ENG-06",
        "CORE-07"
      ],
-      "status": "todo",
+      "status": "doing",
      "risk": "H",
      "deliverable": "补齐真实 API 声明，自有 emitter/utils TS 化",
      "acceptance": "严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容；为 BASE-DIST-01 提供兼容入口/声明及消费者验证",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-13-PKG-TOOL-THUMB-04-runtime-types.md",
+        "baselines/thumbnail-runtime-types-validation.json"
+      ]
    },
    {
      "id": "PKG-TOOL-THUMB-05",
@@ -1025,6 +1025,39 @@
          "sha256": "e00bbf82bf08c452825690372ded39a9b60f4baf438f0e7ce8300e9bc4629c03"
        }
      ]
+    },
+    {
+      "id": "thumbnail-tiny-emitter",
+      "riskId": "VENDOR-09",
+      "inputs": [
+        "packages/artplayer-tool-thumbnail/src/emitter.ts"
+      ],
+      "owners": [
+        "PKG-TOOL-THUMB-04",
+        "PKG-TOOL-THUMB-06"
+      ],
+      "sourceStatus": "Local on/once/emit/off structurally correspond to the fixed tiny-emitter 2.1.0 reference; recovered 3.5.31 declared ^2.1.0. Exact original copied revision is unknown. This migration adds types while preserving the local class and dispatch behavior.",
+      "licenseStatus": "Pinned upstream MIT notice copied verbatim into package THIRD_PARTY_NOTICES and included by the normal standalone build banner. Final packed distribution verification remains 06.",
+      "upstreamSources": [
+        "https://raw.githubusercontent.com/scottcorgan/tiny-emitter/2.1.0/index.js",
+        "https://raw.githubusercontent.com/scottcorgan/tiny-emitter/2.1.0/LICENSE",
+        "https://raw.githubusercontent.com/scottcorgan/tiny-emitter/2.1.0/package.json"
+      ],
+      "upstreamReviewedAt": "2026-09-13",
+      "updatePolicy": "Keep attribution and pinned upstream comparison. Review observable dispatch changes independently from type migration; run upstream/historical/candidate parity tests and validate all bundle and packed notices.",
+      "fingerprints": [
+        {
+          "path": "packages/artplayer-tool-thumbnail/src/emitter.ts",
+          "algorithm": "sha256-lf",
+          "sha256": "2844fa8d279d35d676f61eef4f8a3e173146548c64b8e49f2dabfc25aec56668"
+        }
+      ],
+      "reviewEvidence": [
+        "refactor/baselines/thumbnail-vendor/sources.json",
+        "test/thumbnail-runtime.test.js",
+        "test/thumbnail-vendor.test.js",
+        "refactor/changes/2026-09-13-PKG-TOOL-THUMB-04-runtime-types.md"
+      ]
    }
  ],
  "integrations": [