docs(thumbnail): [PKG-TOOL-THUMB-04] specify pending default compatibility policy

2026-10-08 10:56:15 -08:00 · 2026-09-15 09:25:59 +08:00
1 parent 11c9fefadd
commit 99c208aeee
@@ -5,6 +5,12 @@ strict TypeScript under PKG-TOOL-THUMB-04. Public declarations and isolated inst
 entrypoints now have checks; the historical default-policy decision and final
 integration/release gates remain open.

+The pending choice is now specified in the
+[compatibility proposal](../../refactor/thumbnail-compatibility-decision.md):
+recovered 3.5.31 defaults versus opt-in workspace 4.4.0 behavior, including the
+class-level DEFAULTS boundary. It is not approved or implemented; do not infer
+permission from the approved VAST or other package decisions.
+
 | File | Responsibility |
 | --- | --- |
 | src/index.ts | Public class, historical method names, construction and destruction entry |
@@ -0,0 +1,21 @@
+# PKG-TOOL-THUMB-04 默认兼容策略提案
+
+修改前 HEAD：11c9fefaddc31316992b7da57b0323baea1f3dcf。
+
+回到剩余源码任务时重新核对当前 TS 实现、恢复的 3.5.31 源码、基线 4.4.0 及
+既有历史测试。工具的源码拆分、公开声明、emitter 与资源修复已有实现；04
+未完成的明确原因之一是 THUMB-COMPAT-01，不能把尚未回答的问题当成已授权。
+
+新增 [具体决策提案](../thumbnail-compatibility-decision.md)，推荐已发布的恢复
+版本语义作为默认，工作区 4.4.0 使用显式模式。方案覆盖 delay/height 校验、
+video/帧/done 时序、input.value 和类级 DEFAULTS 的不可同时兼容边界，以及
+批准后内部策略归属、取消资源和正反测试。没有修改生产默认值或执行这个方案。
+
+重跑冻结契约及行为测试共 62/62，通过；日志为
+refactor/.cache/thumbnail-policy-baselines.log。这些用例还确认了历史缺陷，
+不是宣称新策略已经实现或真实浏览器已验收。本批只有方案与状态说明，
+无需重建未变化的生产产物。计划和本地文档链接检查通过。
+
+PKG-TOOL-THUMB-04 仍 doing，THUMB-COMPAT-01 仍 open，等待用户选择。其他不依赖
+该决定的工作可继续。回退本提交仅移除具体提案及对应状态记录；不回退此前
+源码、类型和资源修复。独立本地 checkpoint 提交，不推送或发布。
@@ -645,7 +645,7 @@
 - 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) [记录](changes/2026-09-13-PKG-TOOL-THUMB-04-public-types.md) [记录](baselines/thumbnail-public-types-validation.json) [记录](changes/2026-09-13-PKG-TOOL-THUMB-04-emitter.md) [记录](baselines/thumbnail-emitter-validation.json)
+- PKG-TOOL-THUMB-04: [记录](changes/2026-09-13-PKG-TOOL-THUMB-04-runtime-types.md) [记录](baselines/thumbnail-runtime-types-validation.json) [记录](changes/2026-09-13-PKG-TOOL-THUMB-04-public-types.md) [记录](baselines/thumbnail-public-types-validation.json) [记录](changes/2026-09-13-PKG-TOOL-THUMB-04-emitter.md) [记录](baselines/thumbnail-emitter-validation.json) [记录](thumbnail-compatibility-decision.md) [记录](changes/2026-09-15-PKG-TOOL-THUMB-04-policy-proposal.md)
 - SITE-01: [记录](site-inventory.md) [记录](baselines/site-inventory.json) [记录](baselines/site-provenance.json) [记录](baselines/demo-additions.json) [记录](changes/2026-09-14-SITE-01-site-inventory.md) [记录](baselines/site-inventory-validation.json)
 - SITE-SMOKE-01: [记录](changes/2026-09-14-SITE-SMOKE-01-documentation-smoke.md) [记录](baselines/docs-smoke-validation.json) [记录](scripts/docs-smoke.test.mjs)
 - SITE-02: [记录](changes/2026-09-14-SITE-02-editor-declarations.md) [记录](baselines/editor-declarations-validation.json) [记录](changes/2026-09-14-SITE-SMOKE-01-documentation-smoke.md)
@@ -1,5 +1,13 @@
 # 进度与证据

+## PKG-TOOL-THUMB-04 默认兼容策略待选择
+
+重新核对恢复的 3.5.31 与工作区 4.4.0，历史契约/行为 62/62 通过。已将先前待答
+问题写成[具体提案](thumbnail-compatibility-decision.md)，包含 delay/height、事件/
+帧时序、input 重置和类级 DEFAULTS 的差异。方案未批准、未实施，04 仍 doing、
+THUMB-COMPAT-01 open；不从 VAST 等其他包的批准推断本工具授权。
+见[记录](changes/2026-09-15-PKG-TOOL-THUMB-04-policy-proposal.md)。
+
 ## SITE-07 Monaco 语言服务许可交付

 七包九份原始许可、两个格式器源码署名和补充说明已加入站点；JSON glob 的 BSD
@@ -4077,9 +4077,11 @@
        "test/thumbnail.test.js",
        "test/browser/thumbnail-tool.spec.js",
        "refactor/changes/2026-09-13-PKG-TOOL-THUMB-03-lifecycle.md",
-        "refactor/changes/2026-09-13-PKG-TOOL-THUMB-04-public-types.md"
+        "refactor/changes/2026-09-13-PKG-TOOL-THUMB-04-public-types.md",
+        "refactor/thumbnail-compatibility-decision.md",
+        "refactor/changes/2026-09-15-PKG-TOOL-THUMB-04-policy-proposal.md"
      ],
-      "workspaceState": "Explicit user question pending: prefer published 3.5.31 defaults with opt-in 4.4 behavior, or accept the documented old-version differences and retain 4.4 defaults. No answer inferred; runtime unchanged."
+      "workspaceState": "Concrete proposal prepared: recovered 3.5.31 runtime defaults and optional workspace-4.4 mode, explicitly including the class-level DEFAULTS difference, delay/height validation, event/frame timing and input reset. Frozen contract/behavior tests rerun 62/62. User choice remains pending; no mode/default change implemented or inferred from other package approvals."
    },
    {
      "id": "THUMB-LIFE-01",
@@ -4195,7 +4195,9 @@
        "changes/2026-09-13-PKG-TOOL-THUMB-04-public-types.md",
        "baselines/thumbnail-public-types-validation.json",
        "changes/2026-09-13-PKG-TOOL-THUMB-04-emitter.md",
-        "baselines/thumbnail-emitter-validation.json"
+        "baselines/thumbnail-emitter-validation.json",
+        "thumbnail-compatibility-decision.md",
+        "changes/2026-09-15-PKG-TOOL-THUMB-04-policy-proposal.md"
      ]
    },
    {
@@ -0,0 +1,72 @@
+# Thumbnail 默认行为兼容决策（待用户确认）
+
+状态：proposal，尚未批准或实施。责任任务 PKG-TOOL-THUMB-04，风险 THUMB-COMPAT-01。
+本文件把已有待答问题具体化；不把其他包的兼容授权推广到本工具。
+
+## 已复现的冲突
+
+恢复的 3.5.31 CDN main 与固定 Git 源码逐字节相等，但没有完整原 npm 归档。
+重构基线中的 4.4.0 是未发布工作区代码；两者对同一调用有不同的默认行为，
+见 [冻结契约](baselines/thumbnail-contract.md) 和对应历史测试。
+
+| 行为 | 恢复的 3.5.31 | 未发布工作区 4.4.0 |
+| --- | --- | --- |
+| DEFAULTS | 含 delay: 300，height: 90 | 不含 delay，height: 90 |
+| delay/height 输入 | 检查 number，限制到 10–1000 | 不检查/钳制这两项，开始时覆盖 height |
+| 最终缩略图高度 | 使用配置的 height | 按视频原始宽高比计算 |
+| file 事件 | 同步，早于 video.src 赋值 | 相同 |
+| video 事件 | src 赋值后等待 delay | src 赋值后同步发出 |
+| 每帧及完成 | seek 后等待 delay；最后额外等 delay * 2 | 等媒体就绪，无这两段固定额外延迟 |
+| 选择文件后 | 不清空 input.value | 清空 input.value |
+
+例如同样传入 width: 160、height: 25，16:9 视频在旧版保留 25 高，在工作区版
+变成 90 高；loadVideo 后同步注册 video 监听器在两版也会得到不同结果。
+不能通过 TS 重命名或内部拆文件同时满足这两种默认值和时序。
+
+## 推荐方案：恢复已发布行为为默认，显式选择工作区模式
+
+1. 根构造器默认选择恢复的 3.5.31 行为，支持旧 delay 参数，DEFAULTS 恢复
+   delay: 300；配置 height 保留原钳制，video 延迟、每帧/完成延迟及 input
+   不重置按上表执行。实际定时器受浏览器调度影响，不承诺精确毫秒时刻。
+2. 新增可选配置 compatibility: 'workspace-4.4'，保留当前工作区的同步 video、
+   按比例高度、无额外固定等待和 input 重置。已有工作区调用只需增加这一字段。
+   显式 compatibility: 'published-3.5' 可表达默认选择。
+3. 类级 DEFAULTS 没有实例上下文，统一表示根默认的 3.5.31 配置。依赖工作区
+   DEFAULTS 精确字段集合的代码需要明确选择/保存自己的配置；不能承诺它同时
+   返回两套对象。这个差异也属于本次待批准范围。
+4. 保留已实现的 URL/监听器/定时器所有权、销毁与切源取消、错误结算、输入
+   清理和 emitter 修复。不会恢复旧版错绑 this、陈旧回调、资源泄漏等缺陷。
+   定时等待不取代真实帧就绪；修复慢解码导致错误截图的路径单独记录和验证。
+5. 原入口、构造器名、事件名、历史 creat* 方法、链式返回、同步错误及 Promise
+   形状继续保留。公开声明增加可选模式/延迟类型，旧合法参数继续接受。
+
+```js
+// 恢复的 3.5.31 调用保持原样：固定高度和 delay 语义。
+const tool = new ArtplayerToolThumbnail({ fileInput, height: 25, delay: 300 })
+
+// 依赖未发布 4.4.0 行为的工作区使用者明确选择原模式。
+const workspaceTool = new ArtplayerToolThumbnail({
+  fileInput,
+  compatibility: 'workspace-4.4',
+})
+```
+
+另一种可选决策是保留工作区 4.4.0 为默认，并接受已发布 3.5.31 用户需要选择
+兼容模式。这会把迁移成本放到已发布旧用户，不作为当前推荐。
+
+## 批准后实施与验收
+
+- 在独立的内部策略模块集中默认值、校验、尺寸和调度选择；source/input/
+  extraction 继续各自管理资源，不在各模块散落版本字符串判断。
+- 每次 source/job 拥有延迟句柄；切源、失败、销毁后旧 video/update/done 不得
+  迟到。额外等待期间仍允许现有取消和错误路径完成，不制造悬空 Promise。
+- 保留全部历史冻结用例；为两种模式增加同一调用的高度、DEFAULTS、参数校验、
+  input 重置、video/每帧/done 时序与交错清理测试，比较冻结版本与新实现。
+- 运行严格类型/旧消费、源码及 main/legacy/ESM 构建消费，重验隔离安装与
+  编辑器声明；真实浏览器验证文件选择、像素、事件及清理。Windows WebKit
+  已记录的原生 Blob 不可用不能算作提取通过，支持设备验收继续保留。
+- 同步包内维护文档和迁移示例，再根据实际证据完成 04；05/06 和整体验收
+  不因本决策自动完成。每个完成任务保持独立提交，无推送或发布授权变化。
+
+需要用户选择的原因是 [兼容性契约](compatibility.md) 明确禁止静默改变已有行为，
+且已复现的两套默认语义互斥；并非常规内部结构、依赖或脚本选择需要再次批准。