diff --git a/packages/artplayer-tool-thumbnail/ARCHITECTURE.md b/packages/artplayer-tool-thumbnail/ARCHITECTURE.md index 9d5aed572..5c3fc8bd9 100644 --- a/packages/artplayer-tool-thumbnail/ARCHITECTURE.md +++ b/packages/artplayer-tool-thumbnail/ARCHITECTURE.md @@ -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 | diff --git a/refactor/changes/2026-09-15-PKG-TOOL-THUMB-04-policy-proposal.md b/refactor/changes/2026-09-15-PKG-TOOL-THUMB-04-policy-proposal.md new file mode 100644 index 000000000..b6c8d77f7 --- /dev/null +++ b/refactor/changes/2026-09-15-PKG-TOOL-THUMB-04-policy-proposal.md @@ -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 提交，不推送或发布。 diff --git a/refactor/plan.md b/refactor/plan.md index c4802b9df..e0a8cfe45 100644 --- a/refactor/plan.md +++ b/refactor/plan.md @@ -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) diff --git a/refactor/progress.md b/refactor/progress.md index c80601e43..bed2fcf36 100644 --- a/refactor/progress.md +++ b/refactor/progress.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 diff --git a/refactor/risks.json b/refactor/risks.json index 5cff925aa..8bb862c17 100644 --- a/refactor/risks.json +++ b/refactor/risks.json @@ -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", diff --git a/refactor/tasks.json b/refactor/tasks.json index f6914993c..1d104f78a 100644 --- a/refactor/tasks.json +++ b/refactor/tasks.json @@ -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" ] }, { diff --git a/refactor/thumbnail-compatibility-decision.md b/refactor/thumbnail-compatibility-decision.md new file mode 100644 index 000000000..618092ed7 --- /dev/null +++ b/refactor/thumbnail-compatibility-decision.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) 明确禁止静默改变已有行为， +且已复现的两套默认语义互斥；并非常规内部结构、依赖或脚本选择需要再次批准。