兼容性契约

兼容目标是已有合法用法继续工作，包括 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 中明确列出。

5.2 KiB Raw Blame History