ArtPlayer/refactor/thumbnail-compatibility-decision.md

Thumbnail 默认行为兼容决策（已批准，已实施）

状态：approved，源码、类型及本机验证完成。责任任务 PKG-TOOL-THUMB-04，风险 THUMB-COMPAT-01。 2026-09-15 用户明确批准：“接受：npm 行为默认，工作区行为显式选择（推荐）”。 下列方案现在可直接实施，无需再次询问；批准不代替源码、类型和浏览器验证。 实施结果见 完成记录； 05/06、设备和发布门槛仍独立保留，Windows WebKit 能力对照不计截图提取通过。

已复现的冲突

恢复的 3.5.31 CDN main 与固定 Git 源码逐字节相等，但没有完整原 npm 归档。 重构基线中的 4.4.0 是未发布工作区代码；两者对同一调用有不同的默认行为， 见 冻结契约 和对应历史测试。

行为	恢复的 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 形状继续保留。公开声明增加可选模式/延迟类型，旧合法参数继续接受。

// 恢复的 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 用户选择 兼容模式；用户已经选择上面的 npm 默认方案。

批准后实施与验收

• 在独立的内部策略模块集中默认值、校验、尺寸和调度选择；source/input/ extraction 继续各自管理资源，不在各模块散落版本字符串判断。
• 每次 source/job 拥有延迟句柄；切源、失败、销毁后旧 video/update/done 不得 迟到。额外等待期间仍允许现有取消和错误路径完成，不制造悬空 Promise。
• 保留全部历史冻结用例；为两种模式增加同一调用的高度、DEFAULTS、参数校验、 input 重置、video/每帧/done 时序与交错清理测试，比较冻结版本与新实现。
• 运行严格类型/旧消费、源码及 main/legacy/ESM 构建消费，重验隔离安装与 编辑器声明；真实浏览器验证文件选择、像素、事件及清理。Windows WebKit 已记录的原生 Blob 不可用不能算作提取通过，支持设备验收继续保留。
• 同步包内维护文档和迁移示例，再根据实际证据完成 04；05/06 和整体验收 不因本决策自动完成。每个完成任务保持独立提交，无推送或发布授权变化。

需要用户选择的原因是 兼容性契约 明确禁止静默改变已有行为， 且已复现的两套默认语义互斥；并非常规内部结构、依赖或脚本选择需要再次批准。