test(auto-thumbnail): [PKG-AUTO-THUMB-01] freeze published and workspace contracts

refactor/baselines/auto-thumbnail-contract-validation.json

@@ -0,0 +1,93 @@
+{
+  "schemaVersion": 1,
+  "task": "PKG-AUTO-THUMB-01",
+  "status": "done",
+  "parentCommit": "17befee4b1df7cf4ec29bbda4fd3271567f44223",
+  "checks": [
+    {
+      "command": "node --test refactor/scripts/auto-thumbnail-contract.test.mjs refactor/scripts/contracts.test.mjs refactor/scripts/risk-register.test.mjs",
+      "result": "pass",
+      "tests": 47,
+      "packageContract": 38,
+      "indexValidation": 7,
+      "riskValidation": 2,
+      "log": "refactor/.cache/auto-thumbnail01-focused.log"
+    },
+    {
+      "command": "focused eslint --no-fix",
+      "result": "pass"
+    },
+    {
+      "command": "yarn ci:check",
+      "result": "pass",
+      "tests": {
+        "unit": 1456,
+        "engineering": 14,
+        "baseline": 232,
+        "total": 1702
+      },
+      "strictProductionTypeScriptFiles": 339,
+      "log": "refactor/.cache/auto-thumbnail01-ci.log",
+      "logSha256": "5f47030026c9cfad99830281a0b825bc2247c52bab7368a831e4b86ba914c880",
+      "warnings": [
+        "Existing generated core editor declaration unused eslint suppression",
+        "Existing Yarn DEP0169 url.parse warning"
+      ]
+    }
+  ],
+  "archiveScope": {
+    "publishedVersions": [
+      "1.1.0",
+      "1.0.1",
+      "1.0.0"
+    ],
+    "members": 16,
+    "workspaceFiles": 8,
+    "runnableRootVersions": [
+      "1.1.0",
+      "1.0.1"
+    ],
+    "sourceOnlyFixture": "Actual 1.0.0 tarball source transformed by esbuild; not a runnable npm root entry",
+    "behaviorFixtures": 8,
+    "latestWorkspaceComparison": "All six matching 1.1.0 package members equal frozen workspace after LF normalization",
+    "supportedCoreRange": "Not inferred from Git associations 5.2.2/5.3.1"
+  },
+  "limitations": [
+    "Controlled DOM, seek and toBlob callbacks are not native decoding, pixel, CORS, device or browser evidence.",
+    "The eight fixtures include one explicitly source-only historical package; missing 1.0.0 main/legacy are never fabricated.",
+    "Lifecycle and encoder concerns remain source-observed pending task02 failure reproduction.",
+    "No production source, declarations, examples, versions or build artifacts change in task01.",
+    "Package-family exact case indexing remains incomplete and is not promoted by these frozen baseline results."
+  ],
+  "completedAt": "2026-09-12T21:47:22.218Z",
+  "inputs": [
+    {
+      "file": "refactor/baselines/auto-thumbnail-release.json",
+      "sha256LF": "d87b151ed653dca83047132f1ed3ca474ef52124db7f6a20503204e74ba392ba"
+    },
+    {
+      "file": "refactor/baselines/auto-thumbnail-contract.md",
+      "sha256LF": "dc14c8e51afbd86cedd1da08100812c97e459680b13021269dcb0117ce12a6db"
+    },
+    {
+      "file": "refactor/scripts/auto-thumbnail-contract.mjs",
+      "sha256LF": "53871d5c387152b332f9e337ac23969de227533af8cd3196f8f5a444d2aa4f4d"
+    },
+    {
+      "file": "refactor/scripts/auto-thumbnail-contract.test.mjs",
+      "sha256LF": "df43a7f581aec0dc286383cfe4eb64f5737b38e9b75bac1a410c85fb15e4e461"
+    },
+    {
+      "file": "test/helpers/auto-thumbnail.js",
+      "sha256LF": "6c4fb8a27d5495578fb18df813458b2cb1ae467f0a182de14d75b72f2f760c3a"
+    },
+    {
+      "file": "refactor/contract-policy.json",
+      "sha256LF": "420064c3288adfab9813a6163a6ab294c2dc2459d008cef3c82011293a19c0bb"
+    },
+    {
+      "file": "refactor/scripts/contracts.test.mjs",
+      "sha256LF": "8492e6eafe5fa656cf84a726881a62766a13228f218d9d0894125b59759724e1"
+    }
+  ]
+}

refactor/baselines/auto-thumbnail-contract.md

@@ -0,0 +1,81 @@
+# Auto-thumbnail 历史契约
+
+`PKG-AUTO-THUMB-01` 的基线是实际 npm 归档和固定 Git 输入。
+见 [归档清单](auto-thumbnail-release.json) 与 [验证结果](auto-thumbnail-contract-validation.json)。
+本步没有修改生产源码、公开声明、包版本或 dist；目标版本仍按原计划为 `2.0.0`。
+
+## 发布范围与来源
+
+2026-09-13（北京时间）读取 npm registry，latest 为 `1.1.0`，全部版本是
+`1.0.0`、`1.0.1`、`1.1.0`。三份原始 tarball 共 16 个文件逐一校验
+registry SHA-512、归档 SHA-256、成员 SHA-256；离线缓存缺失时按固定 URL 重新下载并校验。
+归档保存在忽略的 `.cache/releases`，可重跑脚本不依赖可变 latest。
+
+| 版本 | 实际文件与入口 | 声明 | Git 关联核心 |
+| --- | --- | --- | --- |
+| 1.0.0 | 4 文件，只有源码/README/manifest/types；声明的 main、legacy 不存在 | export= / UMD namespace；错写 height、漏写 number | 5.2.2 |
+| 1.0.1 | 6 文件，main/legacy 实际存在；CJS 为 `{ default: function }`；源码随包发布 | 同 1.0.0 | 5.2.2 |
+| 1.1.0 | 6 文件，main/legacy 为直接函数；真实 mjs 仅 default；root/legacy exports | default；number 替换 height；仍误写同步 Result | 5.3.1 |
+| 固定工作区 1.1.0 | 8 个输入，另含源码/demo；六个对应发布文件按 LF 完全一致 | 同 1.1.0 | 另测最终核心 |
+
+registry gitHead 只证明关联仓库状态，不证明构建可重现或该核心组合通过。
+三个 manifest 都没有 peerDependencies、运行依赖或声明支持范围。
+后续05至少验证实际核心 5.2.2、5.3.1、已发布稳定核心 5.4.0 与最终候选核心；
+这些是验证目标，不能称为已支持的整个版本区间。
+
+八份行为夹具包含两份可运行发布包的 main/legacy、三个工作区 source/main/legacy，
+以及 **1.0.0 随包源码经 esbuild 转换的 source-only 夹具**。
+绝不将 source-only 写成可从 npm root 正常导入的 1.0.0。
+1.0.0/1.0.1 随包源码格式化/minify 后相同；1.1.0 去掉无用途的 loadedCount
+以及手写 window 注入，正常运行契约相同；新构建仍有脚本全局入口。
+
+## 必须保留的可用行为
+
+- 函数/global 名 `artplayerPluginAutoThumbnail`；工厂返回注册函数。
+  注册同步安装 `video:loadedmetadata` 监听器，实际返回 Promise，resolve 后仅有
+  `{ name: 'artplayerPluginAutoThumbnail' }`。不会在导入/注册时创建 video。
+- options 是活引用，每次核心 metadata 事件重新读取；url 优先显式 option.url，
+  否则读取 `art.option.url`，不是任意假定的 `art.url`。width/number/scale 使用 `||`
+  默认 160/100/1，旧调用中的 0 和空字符串走默认。声明上 options 必填。
+- 独立 video，`crossOrigin='anonymous'`；高度按视频比例向下取整。
+  永远十列；canvas 宽 width*10，高 height*ceil(number/10)。scale 只传给核心缩略图配置。
+- 帧时间为 duration*index/number（从 0 开始），不是 Thumbnail 工具的中点策略。
+  输出 JPEG，每次更新赋值核心 thumbnails，包含 url/height/column/number/width/scale。
+  保留渐进可用的拼图更新，不偷偷改成整段生成完才更新。
+- 旧声明中的 height 实际从未参与布局。迁移应兼容该参数的旧类型用法并明确它无效；
+  不能突然赋予它改变既有运行结果的新含义。
+
+## 观察到的缺陷与迁移边界
+
+以下是历史对照，**不是要求候选永久保留的缺陷**。
+
+1. 类型把 async 注册写成同步 Result；1.0.x/1.1.0 的 Option 和导出声明不同。
+   04须用实际安装的旧消费者验证，不用 `any` 或仅类型断言伪造 Promise 行为。
+   若完整推导兼容确实冲突，要列出具体旧调用再按用户的兼容决策流程处理。
+2. 1.0.1 CJS 使用者可能调用 `require(name).default`，1.1.0 直接调用 require 结果。
+   04/06须同时验证；不能因最新包不再有 .default 就忽略旧使用者。
+3. 1.0.0 缺运行入口；无需复制坏发布，但新 tarball 必须验证真实 root/legacy/ESM/types
+   和历史源路径的处置。使用 `yarn pack`/仓库外安装，禁止以工作区软链接冒充安装证据。
+4. 没有 destroy/restart 清理，重复 metadata 创建多个解码任务；最终 Blob URL 无人释放。
+   02需复现切源、迟到 metadata/seek/blob、destroy 和跨实例；03明确任务与资源所有权。
+5. 每轮在 seek/draw **之前**排入 toBlob，包含第一个全空快照；第一轮先设 currentTime
+   再装 onseeked。编码回调不串行，可能乱序覆盖；没有处理 null Blob、媒体/画布/核心
+   setter 失败、非有限尺寸。02补可控故障回归和真实浏览器对照，再由03修复。
+   保留有效帧顺序/坐标/渐进更新；空白预览、失效更新、竞态不作为有效 API。
+6. options 省略时注册 Promise 正常 resolve，直到 metadata 回调才抛 TypeError。
+   当前声明不允许省略；修复输入行为需单独说明，不将既有失效调用宣传为可用功能。
+
+## 验证与后续职责
+
+`node --test refactor/scripts/auto-thumbnail-contract.test.mjs` 的38项核对上述版本、
+分发/声明/global/ESM、注册时序、活参数、默认值、帧时间、坐标、JPEG及旧URL替换顺序。
+VM 的 DOM/video/toBlob 可控替身 **不证明真实解码、CORS、画布像素或浏览器兼容性**。
+
+02补失败复现；03在自有入口/任务/抽帧/清理模块落实修复；04迁严格 TS 和消费声明；
+05使用真实核心与原生 video/canvas/Blob 跑三浏览器、切源、销毁、并发实例和故障；
+06再验实际安装、入口、README/demo/编辑器和资源。优先 Chrome，不可用使用内置浏览器；
+Windows WebKit 不能代替受支持 Safari 实机。相关缺证据保持显式待办。
+
+真实示例是 `docs/assets/example/auto.thumbnail.js`，README 链接参数 `example=auto.thumbnail`
+正确；样例视频文件存在。本步只核对文件，8082 demo、Monaco 和像素验证尚未执行。
+不要误改外部 thumbnail 插件示例，也不要混同独立 `artplayer-tool-thumbnail`。

refactor/baselines/auto-thumbnail-release.json

@@ -0,0 +1,197 @@
+{
+  "schemaVersion": 1,
+  "task": "PKG-AUTO-THUMB-01",
+  "capturedAt": "2026-09-12T21:35:30.078Z",
+  "sourceCommit": "17befee4b1df7cf4ec29bbda4fd3271567f44223",
+  "registryObservation": {
+    "url": "https://registry.npmjs.org/artplayer-plugin-auto-thumbnail",
+    "status": 200,
+    "sha256": "52f735ef9be271f06f806995635b7b9a6ba1aedea9c1ad2c307a63788cd28986",
+    "versions": [
+      "1.0.0",
+      "1.0.1",
+      "1.1.0"
+    ],
+    "latest": "1.1.0",
+    "workspaceVersion": "1.1.0"
+  },
+  "release": {
+    "name": "artplayer-plugin-auto-thumbnail",
+    "version": "1.1.0",
+    "metadataUrl": "https://registry.npmjs.org/artplayer-plugin-auto-thumbnail/1.1.0",
+    "tarball": "https://registry.npmjs.org/artplayer-plugin-auto-thumbnail/-/artplayer-plugin-auto-thumbnail-1.1.0.tgz",
+    "integrity": "sha512-ALrcLv+qEDime+R8p4628RZTfMGlrpX6d7PLIQaYWsQEN3lPzVjcVcARCFpqnFI8gvRdqt21w72sJphf50xtVw==",
+    "sha256": "5ea83d4e45d42fdaf42d3e37b6c666857872adaa276ab329c74edcdaa3c1a978",
+    "archiveBytes": 2420,
+    "publishedAt": "2026-03-12T14:21:45.753Z",
+    "registryGitHead": "daf133b22630b4a0eecfa3336bbddab0e9119d96",
+    "files": {
+      "package/README.md": "fb5331337763bf50a3dfafab221dbbb4510cfb89a1816e81a42f6832b99a4546",
+      "package/dist/artplayer-plugin-auto-thumbnail.js": "ce1f1472bf02b836dd85b92eadf2f00786c02cde11a20ac2801136a0f675d12a",
+      "package/dist/artplayer-plugin-auto-thumbnail.legacy.js": "3561e51e0a5f294b56641bf0884a24a4a9e326582d2e99416a04f9526c7d0cc0",
+      "package/dist/artplayer-plugin-auto-thumbnail.mjs": "99da4748422bad54663c669d78963589a64c7cb02102e3544439fec7570a7f8b",
+      "package/package.json": "8d9e186c8767a88cd2f6b7d5fa07d35f9c5dad1a29bf321906d17dab7fc95504",
+      "package/types/artplayer-plugin-auto-thumbnail.d.ts": "33dc298c73da947f17bc3b8a73f3c4f96f4e176097de4f5a274f9d995aaf4e5b"
+    },
+    "manifest": {
+      "name": "artplayer-plugin-auto-thumbnail",
+      "version": "1.1.0",
+      "description": "auto-thumbnail plugin for ArtPlayer",
+      "author": "Harvey Zhao <laozhaochaguan@gmail.com>",
+      "license": "MIT",
+      "homepage": "https://artplayer.org",
+      "repository": {
+        "type": "git",
+        "url": "git+https://github.com/zhw2590582/ArtPlayer.git"
+      },
+      "bugs": {
+        "url": "https://github.com/zhw2590582/ArtPlayer/issues"
+      },
+      "keywords": [
+        "html5",
+        "video",
+        "player"
+      ],
+      "exports": {
+        ".": {
+          "types": "./types/artplayer-plugin-auto-thumbnail.d.ts",
+          "import": "./dist/artplayer-plugin-auto-thumbnail.mjs",
+          "require": "./dist/artplayer-plugin-auto-thumbnail.js"
+        },
+        "./legacy": {
+          "types": "./types/artplayer-plugin-auto-thumbnail.d.ts",
+          "import": "./dist/artplayer-plugin-auto-thumbnail.legacy.js",
+          "require": "./dist/artplayer-plugin-auto-thumbnail.legacy.js"
+        }
+      },
+      "main": "./dist/artplayer-plugin-auto-thumbnail.js",
+      "module": "./dist/artplayer-plugin-auto-thumbnail.mjs",
+      "types": "./types/artplayer-plugin-auto-thumbnail.d.ts",
+      "legacy": "./dist/artplayer-plugin-auto-thumbnail.legacy.js",
+      "browserslist": "last 1 Chrome version"
+    },
+    "missingEntrypoints": {},
+    "historicalCore": {
+      "version": "5.3.1",
+      "commit": "daf133b22630b4a0eecfa3336bbddab0e9119d96",
+      "file": "packages/artplayer/package.json",
+      "sha256LF": "862f3697876fe915dd0ada178da766ce823aae7563ed30b3e5b11b811202929c",
+      "scope": "Git association only; no npm core integration result is implied."
+    }
+  },
+  "previous": [
+    {
+      "name": "artplayer-plugin-auto-thumbnail",
+      "version": "1.0.1",
+      "metadataUrl": "https://registry.npmjs.org/artplayer-plugin-auto-thumbnail/1.0.1",
+      "tarball": "https://registry.npmjs.org/artplayer-plugin-auto-thumbnail/-/artplayer-plugin-auto-thumbnail-1.0.1.tgz",
+      "integrity": "sha512-jewDuGQNqa9e0dDJ3DzC4UghnbJ1+sHgFbTVcVCPzlvh3teHSjjU3/173V5Lq8jaPCRosY3dJWUUi2ZRULf8JQ==",
+      "sha256": "e7e0e09865cf4b46350097137ec292a64e6feedece2c90f724f0498993bfa812",
+      "archiveBytes": 7619,
+      "publishedAt": "2025-03-01T03:23:42.583Z",
+      "registryGitHead": "38ef03d31f4d8c4fcfe1f94009625cfb55eac6c1",
+      "files": {
+        "package/README.md": "e3eddeee9ea9baf00b4df05d9623585f512622a0892aabf1d6636262f9741590",
+        "package/dist/artplayer-plugin-auto-thumbnail.js": "3d9756b7437f24372d34138002b46937bb09e7392b82fb1caf5f09460f151c46",
+        "package/dist/artplayer-plugin-auto-thumbnail.legacy.js": "e8253301c9d6d36bf6623caae52ef4019a8bf30522a52ee20850c2ed3a11769b",
+        "package/package.json": "eb03c9825d5229adc486dee0b560e9dc731fb4b9d4f3cbca45249fe235295dfb",
+        "package/src/index.js": "4bfd833404aa6b3f25594dc4544d62f516df90193e80d82f32bf234d081acfc0",
+        "package/types/artplayer-plugin-auto-thumbnail.d.ts": "2deb15e0e21225809b304b9f84adc1bed6ecce3a016f5b2fd5456bd597d3e7df"
+      },
+      "manifest": {
+        "license": "MIT",
+        "version": "1.0.1",
+        "name": "artplayer-plugin-auto-thumbnail",
+        "types": "types/artplayer-plugin-auto-thumbnail.d.ts",
+        "description": "auto-thumbnail plugin for ArtPlayer",
+        "main": "dist/artplayer-plugin-auto-thumbnail.js",
+        "legacy": "dist/artplayer-plugin-auto-thumbnail.legacy.js",
+        "author": "Harvey Zack <laozhaochaguan@gmail.com>",
+        "browserslist": "last 1 Chrome version",
+        "homepage": "https://artplayer.org",
+        "repository": {
+          "type": "git",
+          "url": "git+https://github.com/zhw2590582/ArtPlayer.git"
+        },
+        "bugs": {
+          "url": "https://github.com/zhw2590582/ArtPlayer/issues"
+        },
+        "keywords": [
+          "html5",
+          "video",
+          "player"
+        ]
+      },
+      "missingEntrypoints": {},
+      "historicalCore": {
+        "version": "5.2.2",
+        "commit": "38ef03d31f4d8c4fcfe1f94009625cfb55eac6c1",
+        "file": "packages/artplayer/package.json",
+        "sha256LF": "59b29c249778ee2ab4fc603a35e5de1509bad5104565315fcfdcb7a5e30944a9",
+        "scope": "Git association only; no npm core integration result is implied."
+      }
+    },
+    {
+      "name": "artplayer-plugin-auto-thumbnail",
+      "version": "1.0.0",
+      "metadataUrl": "https://registry.npmjs.org/artplayer-plugin-auto-thumbnail/1.0.0",
+      "tarball": "https://registry.npmjs.org/artplayer-plugin-auto-thumbnail/-/artplayer-plugin-auto-thumbnail-1.0.0.tgz",
+      "integrity": "sha512-IcGdX3ezuQSu4TtIxaYAu0je2MZYLKRzJiEfszKrnpRuPRqkYSbSioJo9e1dLmw5MpMLezqkuldrsb96FFUwww==",
+      "sha256": "0a907bc8dbf2ef773764645730309b2c95592f84b31f5c4f9cec636d29c0263e",
+      "archiveBytes": 1414,
+      "publishedAt": "2024-12-05T14:09:42.640Z",
+      "registryGitHead": "eb8cc22bf2524482c26187a6f9346fb0137bb9f6",
+      "files": {
+        "package/README.md": "e3eddeee9ea9baf00b4df05d9623585f512622a0892aabf1d6636262f9741590",
+        "package/package.json": "4f43e319293cd970215941476473185c87c67aafab2b027335fd30461310a707",
+        "package/src/index.js": "4bfd833404aa6b3f25594dc4544d62f516df90193e80d82f32bf234d081acfc0",
+        "package/types/artplayer-plugin-auto-thumbnail.d.ts": "2deb15e0e21225809b304b9f84adc1bed6ecce3a016f5b2fd5456bd597d3e7df"
+      },
+      "manifest": {
+        "license": "MIT",
+        "version": "1.0.0",
+        "name": "artplayer-plugin-auto-thumbnail",
+        "types": "types/artplayer-plugin-auto-thumbnail.d.ts",
+        "description": "auto-thumbnail plugin for ArtPlayer",
+        "main": "dist/artplayer-plugin-auto-thumbnail.js",
+        "legacy": "dist/artplayer-plugin-auto-thumbnail.legacy.js",
+        "author": "Harvey Zack <laozhaochaguan@gmail.com>",
+        "browserslist": "last 1 Chrome version",
+        "homepage": "https://artplayer.org",
+        "repository": {
+          "type": "git",
+          "url": "git+https://github.com/zhw2590582/ArtPlayer.git"
+        },
+        "bugs": {
+          "url": "https://github.com/zhw2590582/ArtPlayer/issues"
+        },
+        "keywords": [
+          "html5",
+          "video",
+          "player"
+        ]
+      },
+      "missingEntrypoints": {
+        "main": "dist/artplayer-plugin-auto-thumbnail.js",
+        "legacy": "dist/artplayer-plugin-auto-thumbnail.legacy.js"
+      },
+      "historicalCore": {
+        "version": "5.2.2",
+        "commit": "eb8cc22bf2524482c26187a6f9346fb0137bb9f6",
+        "file": "packages/artplayer/package.json",
+        "sha256LF": "59b29c249778ee2ab4fc603a35e5de1509bad5104565315fcfdcb7a5e30944a9",
+        "scope": "Git association only; no npm core integration result is implied."
+      }
+    }
+  ],
+  "source": {
+    "packages/artplayer-plugin-auto-thumbnail/package.json": "8d9e186c8767a88cd2f6b7d5fa07d35f9c5dad1a29bf321906d17dab7fc95504",
+    "packages/artplayer-plugin-auto-thumbnail/README.md": "fb5331337763bf50a3dfafab221dbbb4510cfb89a1816e81a42f6832b99a4546",
+    "packages/artplayer-plugin-auto-thumbnail/src/index.js": "bc9102c014fbb7b87fe94dc71b779e24a88afb92f5e70a97cf26fcaa2d5a864f",
+    "packages/artplayer-plugin-auto-thumbnail/types/artplayer-plugin-auto-thumbnail.d.ts": "33dc298c73da947f17bc3b8a73f3c4f96f4e176097de4f5a274f9d995aaf4e5b",
+    "packages/artplayer-plugin-auto-thumbnail/dist/artplayer-plugin-auto-thumbnail.js": "ce1f1472bf02b836dd85b92eadf2f00786c02cde11a20ac2801136a0f675d12a",
+    "packages/artplayer-plugin-auto-thumbnail/dist/artplayer-plugin-auto-thumbnail.legacy.js": "3561e51e0a5f294b56641bf0884a24a4a9e326582d2e99416a04f9526c7d0cc0",
+    "packages/artplayer-plugin-auto-thumbnail/dist/artplayer-plugin-auto-thumbnail.mjs": "99da4748422bad54663c669d78963589a64c7cb02102e3544439fec7570a7f8b",
+    "docs/assets/example/auto.thumbnail.js": "e0f706bbbab8e2d0f3201ea6b91f1d5530c6bb65f5c1745dc8ade9acc6d66295"
+  }
+}