ArtPlayer/refactor/compatibility.md

# 兼容性契约

兼容目标是已有合法用法继续工作，包括 JS 调用、TS 编译、事件时序、插件集成、页面样式和分发方式。不能仅比较公开方法名。

## 基线来源

BASE 阶段必须同时采集：本分支起点源码、实际 npm 已发布 tarball、CDN/script 用法、官方 demo、历史声明及可获取的代表性第三方插件。当前 package.json 的版本不等于已验证的 npm 内容。历史支持窗口在 BASE-01 中按已有声明、文档、使用情况决定，不在计划中虚构“所有历史版本都支持”。

采集分步进行：BASE-01 先冻结核心与试点的来源，其他包在各自 01 步补齐。BASE-08 记录明确的版本/浏览器/codec/SDK/设备矩阵，未知项保持未知。兼容指已声明支持且合法的用法；内部历史缺陷不自动成为必须永久保留的行为，修正必须单独复现与评估。

| 编号 | 契约 | 必测内容 |
| --- | --- | --- |
| API-01 | 构造与配置 | `new Artplayer(option, ready)`、默认值、合并方式、container、useSSR、调用 this |
| API-02 | 属性与方法 | 可读/可写、同步返回值、Promise 结果和拒绝、可抽取方法的绑定行为 |
| API-03 | 属性描述符 | 实例自身属性与原型属性、enumerable/configurable/writable、getter/setter、静态字段 |
| API-04 | 事件 | 名称、参数、调用上下文、订阅顺序、once/off、重复触发、重入和异常传播 |
| API-05 | 生命周期 | ready/restart/destroy、销毁顺序、removeHtml、互斥、重复销毁、初始化失败 |
| API-06 | 插件注册 | 工厂及返回函数、同步/异步结果、注册名称、重名行为、静态 icons/version 等已有属性 |
| API-07 | 生态集成 | template/controls/setting/layers/contextmenu/events/utils、动态实例扩展、proxy |
| API-08 | DOM/CSS | 模板节点、CSS 类名与变量、全屏/PiP 后节点归属、样式注入时机、用户覆盖样式 |
| API-09 | 包分发 | main/module/exports/types/typesVersions、UMD/AMD/global/require/ESM、legacy、i18n 子路径、历史文件名 |
| API-10 | 浏览器能力 | 保留当前目标语法和能力降级；语法 es2015 不等于补齐所有浏览器 API |
| API-11 | TypeScript | 默认与命名导出、参数推导、模块扩展、第三方消费、已声明的最低 TS 版本 |
| API-12 | 持久状态与协议 | storage key/数据格式、跨窗消息、媒体 URL 语义、worker 消息、公开回调 |

## 差异的处理规则

| 情况 | 处理 |
| --- | --- |
| 内部重排、无可观察变化 | 原样保留契约，增加回归测试 |
| 已公开且正在使用的功能 | 兼容门面转发，保持入口、返回值和时序；不能要求所有调用方改代码 |
| 源码与声明不一致 | 分别记录运行时和 TS 用户影响，先加精确重载或扩展类型；无法兼容时标为待决，不能静默收紧 |
| 文档描述了未实现的行为 | 核实发布包和使用样例，独立修复或明确记录；不把错误描述当作重构任务直接实现 |
| 明确缺陷 | 建立复现、比较旧行为、记录修正差异和发布级别，避免为通过差分测试而永久保留缺陷 |
| 无法验证的历史路径 | 标记缺证据及影响，不能计入兼容通过 |

## 核心特殊边界

- `plugins.add` 不能简单统一成 async；同步插件的同步可见性、返回结果需要保留。
- `play()` 的拒绝不能被公共接口静默吞掉；内部触发播放与外部调用分开验证。
- 保持 `switchUrl` 与 `switchQuality` 的播放位置和恢复行为。并发切源的取消/过期策略先用决策记录明确；新增拒绝可能造成未处理异常。
- 保持 `Artplayer.instances`、公开静态常量、`Emitter`、`utils`、默认导入时样式和 global 副作用。
- 核心 Emitter 不直接替换为 EventTarget；链式返回、ctx 和 once/off 语义不同。
- 原生 video 与 canvas shim 的内部类型可以分开，但不能强制所有用户把 `art.video` 调用改为新接口。
- 不因类型严格化删除插件扩展字段，也不通过全局 `[key: string]: any` 掩盖全部类型问题。

## 新旧版本组合

| 核心 | 插件 | 要求 |
| --- | --- | --- |
| 发布基线 | 发布基线 | 基线用例可运行，记录历史缺陷 |
| 重构核心 | 未改旧插件 | 主要兼容门槛，所有本仓库旧插件与代表性第三方插件验证 |
| 旧支持范围核心 | 重构插件 | 保留原支持范围，或在插件内部使用能力检测与 fallback；不得意外依赖新核心方法 |
| 重构核心 | 重构插件 | 完整功能、组合、清理及类型验证 |

任何内部共享能力如果被插件运行时使用，必须证明旧核心可用；否则放在插件内部或提供兼容实现。不能为减少源码重复悄悄增加消费者安装依赖或最低核心版本。

## 变更登记

每项差异使用 `changes/YYYY-MM-DD-任务ID-主题.md`，写明 API 编号、旧/新示例、受影响消费者、测试、发布策略和回退方式。未经评估的公开接口差异阻止任务完成；需要用户选择的产品行为在 progress 中明确列出。