@video-lab/protocol 1.0.1 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @video-lab/protocol
 
-Video Lab Player 的契约层(L4)。定义 host ↔ iframe 的通信契约,**所有其他包依赖它,它不依赖任何内部包**。
+Video Lab Player 的通信契约层。它定义 host 与 iframe 的消息格式，其他 Video Lab 包依赖它，而它不依赖其他 Video Lab 包。
 
 唯一外部依赖:`zod`。
 
@@ -14,7 +14,7 @@ Video Lab Player 的契约层(L4)。定义 host ↔ iframe 的通信契约,**所
 | `events` | 29 个事件(sourceroute / ready / timeupdate / error / reconnectstart / subtitlechange / stalled / …) |
 | `errors` | 29 个错误码 + 2 个警告码 + `PlayerError` |
 | `configs` | `MediaSource`、`PlayerConfig`、poster / locale / danmaku / controls |
-| `presets` | 1 个场景预设(`homepage-preview`,ADR-032)+ `resolvePreset` |
+| `presets` | 场景预设（如 `homepage-preview`）与 `resolvePreset` |
 
 类型一律从 Zod schema 用 `z.infer` 推导,不手写 interface——避免 schema 和类型变成两套真相。
 
@@ -49,19 +49,19 @@ const config = resolvePreset('homepage-preview', { source: 'a.m3u8', autoplay: f
 
 ## 几个容易踩的点
 
-**事件名是全小写连写**(`timeupdate` / `autoplayblocked`),对齐 HTML5 媒体事件。这是 wire 上的名字;消费面各自映射——Vue emit `time-update`,React prop `onTimeUpdate`。(团队约定里的 `snake.case` 指埋点事件名如 `playback.start`,是另一套命名空间。)
+**事件名是全小写连写**（`timeupdate` / `autoplayblocked`），对齐 HTML5 媒体事件。这是通信层名称；Vue 映射为 `time-update`，React 映射为 `onTimeUpdate`。
 
-**`retryable` 是给自动重连看的信号**,不是"用户能不能点重试按钮"。判断标准是:同样的请求原样再发一次,有没有可能得到不同结果。所以 `E_AUTH_EXPIRED` 是 `false`——SDK 不做签名刷新(ADR-022),原样重试必然再次失败。
+**`retryable` 是给自动重连看的信号**，不是“用户能不能点重试按钮”。判断标准是同一请求原样重发是否可能成功。因此 `E_AUTH_EXPIRED` 为 `false`：SDK 不刷新签名，原样重试必然再次失败。
 
 **`source.onBeforeRequest` 不在 wire 契约里**。函数不可序列化,过不了 iframe 边界;它是宿主侧的 hook,由 inline 模式的 player-core 直接消费。且它在 MP4 和 iOS Safari 播 HLS 时**不生效**。
 
 **带 query 的 URL 推断不出类型**。`video.m3u8?token=xxx` 必须显式传 `type: 'hls'`,否则会走 MP4 路径。签名 URL 场景尤其注意。
 
-**`type DrmConfig = never`**(ADR-014)。v1.0 不做 DRM,消费方传 drm 字段会直接编译报错,而不是运行时才发现没生效。
+**`type DrmConfig = never`。** v1 不提供 DRM；传入 `drm` 字段会直接产生编译错误，而不是运行时静默失效。
 
 ## 版本与冻结
 
-当前 `CONTRACT_VERSION = '1.0.0'` —— **契约已冻结**(2026-07-15,见 ADR-025)。现有 schema 不再破坏兼容。
+当前 `CONTRACT_VERSION = '1.0.0'`。现有 schema 不再进行破坏性兼容变更。
 
 兼容规则(host 和 iframe 用同一个 `isContractCompatible`):
 
@@ -69,7 +69,7 @@ const config = resolvePreset('homepage-preview', { source: 'a.m3u8', autoplay: f
 - `>= 1.0.0`(当前):minor 是向后兼容的新增 → **major 相同即兼容**
 - patch 差异永远兼容
 
-冻结后:新增 method / event / 可选字段走 **minor** bump(1.x 向后兼容);破坏兼容必须走 **ADR + major** bump。
+后续新增 method、event 或可选字段走 **minor** 版本；破坏兼容的变更必须走 **major** 版本。
 
 ## 测试
 
@@ -77,4 +77,4 @@ const config = resolvePreset('homepage-preview', { source: 'a.m3u8', autoplay: f
 pnpm --filter @video-lab/protocol test
 ```
 
-契约测试在 `tests/`(和 `src/` 分开,方便冻结后独立管理)。其中 `consumer-parity.contract.test.ts` 拿 `examples/team-video-vue/` 实际用到的事件 / 命令 / 错误码逐个校验——契约一旦漂移到验收基准用不了,它会先红。
+契约测试覆盖消费包实际使用的事件、命令与错误码，防止通信契约与消费包行为漂移。

package/dist/index.cjs

@@ -1562,36 +1562,11 @@ resetCounter: zod.z.boolean().optional() }).optional()
 //#endregion
 //#region src/version.ts
 /**
-* 契约版本。
-*
-* 注意:这和 iframe URL 里的 `version`(如 `'v1'`,见 ADR-023)不是一回事——
-* 那个是 CDN 路径版本,这个是 host ↔ iframe 的通信契约版本。
-*
-* 冻结策略见 `packages/protocol/CLAUDE.md`:审查清单全过之后才升 1.0.0。
-*
-* **首发即 1.1.0**(2026-07-19):契约从未对外发布,故把首发前迭代出的全部能力面
-* **折叠进首发契约**——与 8 个包的 npm 版本对齐,避免"包版本 1.1.0 却携带 1.0.0
-* 契约常量"的双轴割裂(`tests/index.contract.test.ts` 有断言锁死这一致性)。
-* 首发契约面**已包含**:
-* - `stalled` 事件(HealthMonitor 卡顿测量,设计见 ADR-026)
-* - 字幕控制侧:`setSubtitle` 命令 + `subtitlechange` 事件 + `ready` 的**可选** `subtitles` 字段(ADR-027)
-* - 弹幕 streaming:`pushDanmaku` / `setDanmakuEnabled` / `clearDanmaku` 命令 + `PlayerConfig.danmaku`(可选)(ADR-028)
-* - 场景预设收敛为唯一 `homepage-preview`(ADR-032)
-*
-* 上面几个 ADR 记录的是这些能力的**设计出处**,不是"冻结后独立发布的 minor"——它们在首发前
-* 就已落地,故都是首发契约的一部分。**首发之后**再新增 method/event/字段才走 minor
-* (1.x 向后兼容),破坏性变更须走 ADR + major。
-*
-* 为什么是 1.1.0 而不是 1.0.0:原计划锁 1.0.0(ADR-025),但首发前两项变更
-* (全屏命令补完、preset 收敛)各带一条 minor changeset,changesets 的 `fixed` 组
-* 把 8 个包统一推到 1.1.0。契约面确有变化(删了 4 个 preset),升 minor 名实相符;
-* 且 {@link isContractCompatible} 在 `>=1.0.0` 时只比 major,1.0.0 ↔ 1.1.0 握手仍兼容。
-*
-* 值**从 package.json 派生**,不要改回硬编码 —— 契约常量必须与 npm 包版本
-* 严格相等,而 changesets 只改 package.json。理由与实测数据见
-* `docs/adr/ADR-036-contract-version-derived.md`。
+* host ↔ iframe 通信契约版本，独立于 npm fixed group 和 iframe 应用版本。
+* 唯一来源是 contract-version.json（ADR-094）；只在真实协议变化时升级。
+* npm 包版本同步不能改变握手与 envelope 的版本。
 */
-const CONTRACT_VERSION = "1.0.1";
+const CONTRACT_VERSION = "1.0.2";
 const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;
 /**
 * 解析 semver 字符串。只接受严格的 `major.minor.patch`,

package/dist/index.mjs

@@ -1561,36 +1561,11 @@ resetCounter: z.boolean().optional() }).optional()
 //#endregion
 //#region src/version.ts
 /**
-* 契约版本。
-*
-* 注意:这和 iframe URL 里的 `version`(如 `'v1'`,见 ADR-023)不是一回事——
-* 那个是 CDN 路径版本,这个是 host ↔ iframe 的通信契约版本。
-*
-* 冻结策略见 `packages/protocol/CLAUDE.md`:审查清单全过之后才升 1.0.0。
-*
-* **首发即 1.1.0**(2026-07-19):契约从未对外发布,故把首发前迭代出的全部能力面
-* **折叠进首发契约**——与 8 个包的 npm 版本对齐,避免"包版本 1.1.0 却携带 1.0.0
-* 契约常量"的双轴割裂(`tests/index.contract.test.ts` 有断言锁死这一致性)。
-* 首发契约面**已包含**:
-* - `stalled` 事件(HealthMonitor 卡顿测量,设计见 ADR-026)
-* - 字幕控制侧:`setSubtitle` 命令 + `subtitlechange` 事件 + `ready` 的**可选** `subtitles` 字段(ADR-027)
-* - 弹幕 streaming:`pushDanmaku` / `setDanmakuEnabled` / `clearDanmaku` 命令 + `PlayerConfig.danmaku`(可选)(ADR-028)
-* - 场景预设收敛为唯一 `homepage-preview`(ADR-032)
-*
-* 上面几个 ADR 记录的是这些能力的**设计出处**,不是"冻结后独立发布的 minor"——它们在首发前
-* 就已落地,故都是首发契约的一部分。**首发之后**再新增 method/event/字段才走 minor
-* (1.x 向后兼容),破坏性变更须走 ADR + major。
-*
-* 为什么是 1.1.0 而不是 1.0.0:原计划锁 1.0.0(ADR-025),但首发前两项变更
-* (全屏命令补完、preset 收敛)各带一条 minor changeset,changesets 的 `fixed` 组
-* 把 8 个包统一推到 1.1.0。契约面确有变化(删了 4 个 preset),升 minor 名实相符;
-* 且 {@link isContractCompatible} 在 `>=1.0.0` 时只比 major,1.0.0 ↔ 1.1.0 握手仍兼容。
-*
-* 值**从 package.json 派生**,不要改回硬编码 —— 契约常量必须与 npm 包版本
-* 严格相等,而 changesets 只改 package.json。理由与实测数据见
-* `docs/adr/ADR-036-contract-version-derived.md`。
+* host ↔ iframe 通信契约版本，独立于 npm fixed group 和 iframe 应用版本。
+* 唯一来源是 contract-version.json（ADR-094）；只在真实协议变化时升级。
+* npm 包版本同步不能改变握手与 envelope 的版本。
 */
-const CONTRACT_VERSION = "1.0.1";
+const CONTRACT_VERSION = "1.0.2";
 const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;
 /**
 * 解析 semver 字符串。只接受严格的 `major.minor.patch`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@video-lab/protocol",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "license": "MIT",
   "description": "Video Lab Player 契约层:Zod schema 定义命令 / 事件 / 错误码 / 配置,所有包的唯一事实源",
   "type": "module",