@video-lab/protocol 1.0.1 → 3.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`。
 
@@ -10,11 +10,12 @@ Video Lab Player 的契约层(L4)。定义 host ↔ iframe 的通信契约,**所
 |:---|:---|
 | `version` | `CONTRACT_VERSION` + 版本兼容判定 |
 | `envelope` | 通信包裹:`command` / `event` / `response` / `error` |
-| `methods` | 16 条命令(play / pause / seek / load / setSubtitle / pushDanmaku / …) |
-| `events` | 29 个事件(sourceroute / ready / timeupdate / error / reconnectstart / subtitlechange / stalled / …) |
+| `methods` | 17 条命令(play / pause / seek / load / setSubtitle / pushDanmaku / …) |
+| `events` | 27 个事件(sourceroute / ready / timeupdate / error / recovery / subtitlechange / stalled / …) |
+| `delivery` | `DeliveredPlayerEvent`：带生产端 session、稳定 ID、发生时间与序号的完整事件投递证据 |
 | `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 +50,21 @@ 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),原样重试必然再次失败。
+**完整事件流优先使用 `DeliveredPlayerEvent`**。它在兼容的新增 outlet 上提供 `producerSessionId`、`deliveryId`、`occurredAtMs`、`sequence`，适合跨重连排序与去重；旧 `PlayerEvent` 回调保持原样。旧版 iframe 可以省略该证据，宿主仍会收到 raw 事件。
+
+**`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 +72,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 +80,8 @@ 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/` 实际用到的事件 / 命令 / 错误码逐个校验——契约一旦漂移到验收基准用不了,它会先红。
+契约测试覆盖消费包实际使用的事件、命令与错误码，防止通信契约与消费包行为漂移。
+
+## 宿主网页全屏
+
+导出 `PageFullscreenAdapter` / `PageFullscreenState` 类型、实际状态事件 `pagefullscreenchange`，以及专用通道的 `PageFullscreenMessageSchema` / `PageFullscreenControlSchema` / `PageFullscreenStateSchema`。宿主函数与 DOM 不进入 PlayerConfig。消费面调用和升级边界见[网页全屏接入](../../docs/guides/PAGE-FULLSCREEN.md)。

package/dist/index.cjs

@@ -302,6 +302,17 @@ const DanmakuConfigSchema = zod.z.object({
 * 定义在这里而不是 presets.ts,是为了让 PlayerConfig 能引用它而不产生循环依赖。
 */
 const PresetNameSchema = zod.z.enum(["homepage-preview"]);
+/** 内置控制栏的初始化显示策略。false 隐藏入口；true/省略仍遵守平台能力。 */
+const ControlVisibilityConfigSchema = zod.z.object({
+	play: zod.z.boolean().optional(),
+	progress: zod.z.boolean().optional(),
+	time: zod.z.boolean().optional(),
+	volume: zod.z.boolean().optional(),
+	playbackRate: zod.z.boolean().optional(),
+	fullscreen: zod.z.boolean().optional(),
+	cssFullscreen: zod.z.boolean().optional(),
+	pip: zod.z.boolean().optional()
+}).strict();
 /**
 * 播放器初始化配置。iframe 模式下握手成功后作为第一条 command 下发,
 * 所以必须整体可 JSON 序列化。
@@ -357,6 +368,12 @@ const PlayerConfigSchema = zod.z.object({
 	* `boolean | { minimal?: boolean }` 是 **minor 不是 breaking**,不是单向门。
 	*/
 	controls: zod.z.boolean().optional(),
+	/** 初始化时是否显示默认错误覆盖层。默认开启；关闭不影响错误事件和恢复。 */
+	showErrorOverlay: zod.z.boolean().optional(),
+	/** 运行时 Loading 展示归属；false 仅隐藏视觉/ARIA，恢复仍由 SDK 执行。 */
+	showLoadingOverlay: zod.z.boolean().optional(),
+	/** 独立隐藏内置控件；只在创建时生效，修改后由宿主显式重建。 */
+	controlVisibility: ControlVisibilityConfigSchema.optional(),
 	/** 是否响应用户交互。首页预览卡片用 false,点击透传给外层卡片 */
 	interactive: zod.z.boolean().optional(),
 	poster: PosterConfigSchema.optional(),
@@ -784,12 +801,13 @@ function normalizeUserAction(raw) {
 	const r = raw;
 	const action = r.action;
 	if (typeof action !== "string" || !ALLOWED.has(action)) return null;
-	const first = (Array.isArray(r.props) ? r.props : [])[0] ?? null;
+	const first = (Array.isArray(r.props) ? r.props : [])[0];
+	const change = typeof first === "string" ? r : typeof first === "object" && first !== null ? first : null;
 	return {
 		action,
 		source: typeof r.pluginName === "string" ? r.pluginName : "player",
-		from: primitive(first?.from),
-		to: primitive(first?.to)
+		from: primitive(change?.from),
+		to: primitive(change?.to)
 	};
 }
 /**
@@ -814,6 +832,57 @@ function normalizeFrameFreeze(raw) {
 	};
 }
 //#endregion
+//#region src/page-fullscreen.ts
+/** 专用网页全屏传输，不接收普通播放器命令；版本独立协商，旧端不会假定支持。 */
+const base$1 = {
+	channel: zod.z.literal("video-lab:page-fullscreen"),
+	version: zod.z.literal(1),
+	session: zod.z.string().min(1)
+};
+/** 静态 iframe 的受限双向消息，接收方还必须校验 origin 与 source。 */
+const PageFullscreenMessageSchema = zod.z.discriminatedUnion("type", [
+	zod.z.object({
+		...base$1,
+		type: zod.z.literal("hello")
+	}),
+	zod.z.object({
+		...base$1,
+		type: zod.z.literal("ready"),
+		instance: zod.z.string().min(1)
+	}),
+	zod.z.object({
+		...base$1,
+		type: zod.z.literal("request"),
+		instance: zod.z.string().min(1),
+		id: zod.z.number().int().positive(),
+		active: zod.z.boolean()
+	}),
+	zod.z.object({
+		...base$1,
+		type: zod.z.literal("state"),
+		instance: zod.z.string().min(1),
+		revision: zod.z.number().int().nonnegative(),
+		active: zod.z.boolean()
+	}),
+	zod.z.object({
+		...base$1,
+		type: zod.z.literal("ack"),
+		instance: zod.z.string().min(1),
+		revision: zod.z.number().int().nonnegative()
+	}),
+	zod.z.object({
+		...base$1,
+		type: zod.z.literal("disconnect")
+	})
+]);
+/** Penpal 控制面确认；仅在独立网页全屏能力协商后调用。 */
+const PageFullscreenControlSchema = zod.z.object({
+	available: zod.z.boolean(),
+	active: zod.z.boolean()
+});
+/** 宿主布局确认后的实际网页全屏状态。 */
+const PageFullscreenStateSchema = zod.z.object({ active: zod.z.boolean() });
+//#endregion
 //#region src/playback-context.ts
 /**
 * 播放内核 —— **实际选中的那个**,不是消费方声明的。
@@ -981,124 +1050,133 @@ function redactSourceUrl(url) {
 		};
 	}
 }
-//#endregion
-//#region src/events.ts
-/**
-* 清晰度档位。`level` 是索引,传给 `setQuality` 命令用。
-*/
-const QualityLevelSchema = zod.z.object({
-	level: zod.z.number(),
-	label: zod.z.string().optional(),
-	height: zod.z.number().optional(),
-	bitrate: zod.z.number().optional()
-});
-/**
-* 可用字幕轨(player 加载后暴露给消费方)。`id` 是索引,传给 `setSubtitle` 命令用。
-*
-* 和输入侧的 {@link SubtitleTrack}(url/content 两种 `mode`)分开:那个是**消费方喂进来**的
-* 原始字幕描述,这个是 player **加载后回报**的、可切换的轨道清单(同 QualityLevel 之于 quality)。
-*/
-const SubtitleTrackInfoSchema = zod.z.object({
-	/** 索引(= source.subtitles 数组下标),`setSubtitle({ id })` 用它引用轨道 */
-	id: zod.z.number(),
-	/** BCP-47,如 `'en'` / `'zh-CN'` / `'th'` */
-	locale: zod.z.string(),
-	/** 展示名,如 `'English'` / `'中文'` */
-	label: zod.z.string()
-});
-/**
-* 「现在能不能正常出画面」的原因枚举({@link PlayerEventSchema} 的 `playablechange`)。
-*
-* 优先级(高的压低的,同时命中时报最严重的那个):
-* `error` > `frame_disconnected` > `autoplay_blocked` > `reconnecting` > `stalled`
-* > `buffering` > `initializing` > `degraded` > `ok`
-*
-* **命名**:枚举值用 `snake_case`,与事件名(全小写连写)是两套命名空间 ——
-* 事件名对齐 HTML5 媒体事件,枚举值是 payload 里的数据,`autoplay_blocked`
-* 比 `autoplayblocked` 好读。既有的 `phase: 'start' | 'end'` 是单词故看不出区别。
-*/
-const PlayableReasonSchema = zod.z.enum([
-	"ok",
-	"initializing",
-	"buffering",
-	"stalled",
-	"reconnecting",
-	"autoplay_blocked",
-	"error",
-	"frame_disconnected",
-	"degraded"
-]);
 zod.z.enum([
 	"detected",
+	"backoff",
 	"attempting",
 	"validating",
 	"recovered",
 	"failed",
 	"cancelled"
 ]);
-/** SDK 实际执行的恢复策略(ADR-079)。 */
+/** 策略变化共享 episode，不创建新的预算。 */
 const RecoveryStrategySchema = zod.z.enum([
 	"reconnect",
 	"media_recovery",
 	"visibility_reload"
 ]);
-/** 恢复由错误、用户操作还是可见性变化触发。 */
+/** 触发原因与实际执行策略分别记录。 */
 const RecoveryTriggerSchema = zod.z.enum([
 	"error",
 	"manual",
-	"visibility"
+	"visibility",
+	"stall",
+	"startup_timeout"
 ]);
-const RecoveryPayloadBase = {
-	/** 同一播放器实例内递增的恢复关联号。 */
+const base = {
+	sessionId: zod.z.string().min(1),
 	recoveryId: zod.z.number().int().positive(),
 	strategy: RecoveryStrategySchema,
 	trigger: RecoveryTriggerSchema,
-	/** 当前实际恢复轮次，从 1 开始。 */
-	attempt: zod.z.number().int().positive(),
-	/** 该策略允许的最大恢复轮次。 */
+	attempt: zod.z.number().int().nonnegative(),
 	maxAttempts: zod.z.number().int().positive(),
-	/** 有错误起因时复用既有契约错误码；手动恢复可省略。 */
+	/** 从 detected 起，源端用单调时钟测量的毫秒数。 */
+	elapsedMs: zod.z.number().finite().nonnegative(),
 	reason: ErrorCodeSchema.optional()
 };
-/**
-* 可验证恢复的单条生命周期记录(ADR-079)。
-*
-* 终态字段按 `phase` 严格区分：`recovered` 只能声明位置推进这一种验证证据；
-* `failed` / `cancelled` 只能携带各自登记的结束原因。`strict()` 刻意拒绝把终态字段
-* 混入检测或验证阶段，避免上报端把“正在验证”误读成“已经恢复”。
-*/
+const issued = {
+	...base,
+	attempt: zod.z.number().int().positive()
+};
+/** 统一恢复的单条事实；取消不伪报成功，跨会话归属不依赖相邻事件猜测。 */
 const RecoveryPayloadSchema = zod.z.discriminatedUnion("phase", [
 	zod.z.object({
-		...RecoveryPayloadBase,
+		...base,
 		phase: zod.z.literal("detected")
 	}).strict(),
 	zod.z.object({
-		...RecoveryPayloadBase,
+		...base,
+		phase: zod.z.literal("backoff")
+	}).strict(),
+	zod.z.object({
+		...issued,
 		phase: zod.z.literal("attempting")
 	}).strict(),
 	zod.z.object({
-		...RecoveryPayloadBase,
+		...issued,
 		phase: zod.z.literal("validating")
 	}).strict(),
 	zod.z.object({
-		...RecoveryPayloadBase,
+		...issued,
 		phase: zod.z.literal("recovered"),
 		validatedBy: zod.z.literal("playing_position_advance")
 	}).strict(),
 	zod.z.object({
-		...RecoveryPayloadBase,
+		...base,
 		phase: zod.z.literal("failed"),
 		outcome: zod.z.enum(["timeout", "attempts_exhausted"])
 	}).strict(),
 	zod.z.object({
-		...RecoveryPayloadBase,
+		...base,
 		phase: zod.z.literal("cancelled"),
 		outcome: zod.z.enum([
 			"source_changed",
 			"destroyed",
-			"superseded"
+			"superseded",
+			"user_paused",
+			"natural_recovery"
 		])
 	}).strict()
+]).refine((value) => value.attempt <= value.maxAttempts, {
+	message: "attempt exceeds episode budget",
+	path: ["attempt"]
+});
+//#endregion
+//#region src/events.ts
+/**
+* 清晰度档位。`level` 是索引,传给 `setQuality` 命令用。
+*/
+const QualityLevelSchema = zod.z.object({
+	level: zod.z.number(),
+	label: zod.z.string().optional(),
+	height: zod.z.number().optional(),
+	bitrate: zod.z.number().optional()
+});
+/**
+* 可用字幕轨(player 加载后暴露给消费方)。`id` 是索引,传给 `setSubtitle` 命令用。
+*
+* 和输入侧的 {@link SubtitleTrack}(url/content 两种 `mode`)分开:那个是**消费方喂进来**的
+* 原始字幕描述,这个是 player **加载后回报**的、可切换的轨道清单(同 QualityLevel 之于 quality)。
+*/
+const SubtitleTrackInfoSchema = zod.z.object({
+	/** 索引(= source.subtitles 数组下标),`setSubtitle({ id })` 用它引用轨道 */
+	id: zod.z.number(),
+	/** BCP-47,如 `'en'` / `'zh-CN'` / `'th'` */
+	locale: zod.z.string(),
+	/** 展示名,如 `'English'` / `'中文'` */
+	label: zod.z.string()
+});
+/**
+* 「现在能不能正常出画面」的原因枚举({@link PlayerEventSchema} 的 `playablechange`)。
+*
+* 优先级(高的压低的,同时命中时报最严重的那个):
+* `error` > `frame_disconnected` > `autoplay_blocked` > `reconnecting` > `stalled`
+* > `buffering` > `initializing` > `degraded` > `ok`
+*
+* **命名**:枚举值用 `snake_case`,与事件名(全小写连写)是两套命名空间 ——
+* 事件名对齐 HTML5 媒体事件,枚举值是 payload 里的数据,`autoplay_blocked`
+* 比 `autoplayblocked` 好读。既有的 `phase: 'start' | 'end'` 是单词故看不出区别。
+*/
+const PlayableReasonSchema = zod.z.enum([
+	"ok",
+	"initializing",
+	"buffering",
+	"stalled",
+	"reconnecting",
+	"autoplay_blocked",
+	"error",
+	"frame_disconnected",
+	"degraded"
 ]);
 /**
 * 事件。player → host(iframe 模式),或 player-core → 消费方(inline 模式)。
@@ -1110,6 +1188,10 @@ const RecoveryPayloadSchema = zod.z.discriminatedUnion("phase", [
 * 权威来源:docs/protocol/events.md + ARCHITECTURE.md § 8.4。
 */
 const PlayerEventSchema = zod.z.discriminatedUnion("event", [
+	zod.z.object({
+		event: zod.z.literal("pagefullscreenchange"),
+		payload: PageFullscreenStateSchema
+	}),
 	zod.z.object({
 		event: zod.z.literal("sourceroute"),
 		payload: SourceRoutePayloadSchema
@@ -1200,43 +1282,6 @@ id: zod.z.number().nullable() })
 		event: zod.z.literal("autoplayblocked"),
 		payload: zod.z.object({})
 	}),
-	zod.z.object({
-		event: zod.z.literal("reconnectstart"),
-		payload: zod.z.object({
-			attempt: zod.z.number(),
-			maxAttempts: zod.z.number(),
-			/**
-			* 触发这一轮重连的**契约错误码**;手动 `reconnect()` 时缺省(没有触发它的错误)。
-			*
-			* ⚠️ **这里曾经是 `z.string()`,而那让它在服务端聚合不了**(ADR-069)——
-			* 消费方拿到的类型是 `string`,`switch` 不了、也没有任何东西挡住将来漂成别的写法。
-			* **而源头从来就是一个契约错误码**:`plugins/reconnect.ts` 传的是
-			* `mapXgplayerError(err).code`,没有第二个发射点。
-			*
-			* **复用 `ErrorCodeSchema`,不新起一套「重连原因」枚举** —— 理由同 ADR-062 ③:
-			* 两套表会让同一条内核错误在 `error` 和 `reconnectstart` 两条通道上给出**互相矛盾**的分类,
-			* 而那种漂移没人查得出来。
-			*
-			* ⚠️ **不要照着「今天实际只会出现哪几个码」去收窄。** 那要复刻
-			* `ReconnectPlugin` 的两道过滤(`retryable === true` 且 `category !== 'media'`),
-			* 而那两道闸是**实现细节**,改一行就和契约对不上了 —— 那正是第二份会漂的副本。
-			*/
-			reason: ErrorCodeSchema.optional(),
-			nextDelayMs: zod.z.number().optional()
-		})
-	}),
-	zod.z.object({
-		event: zod.z.literal("reconnectsuccess"),
-		payload: zod.z.object({ attempts: zod.z.number() })
-	}),
-	zod.z.object({
-		event: zod.z.literal("reconnectfailed"),
-		payload: zod.z.object({
-			attempts: zod.z.number(),
-			/** 最后一轮的触发错误码。语义与取值同 `reconnectstart.reason`(ADR-069) */
-			reason: ErrorCodeSchema.optional()
-		})
-	}),
 	zod.z.object({
 		event: zod.z.literal("recovery"),
 		payload: RecoveryPayloadSchema
@@ -1313,7 +1358,15 @@ id: zod.z.number().nullable() })
 			*(正常启动,该等),握手失败降级后为 `false`(连不上了,该露重试入口)。
 			* 两个阶段共用一个 reason,靠这个字段区分 —— 这正是它存在的意义。
 			*/
-			recoverable: zod.z.boolean()
+			recoverable: zod.z.boolean(),
+			/** 下一步动作能力；宿主无须按错误类型自行推断。 */
+			action: zod.z.enum([
+				"retry",
+				"play",
+				"replace-source",
+				"recreate-frame",
+				"none"
+			]).optional()
 		})
 	}),
 	zod.z.object({
@@ -1457,6 +1510,28 @@ function toErrorEvent(err) {
 	};
 }
 //#endregion
+//#region src/delivery.ts
+/**
+* 一次已送达播放器事件的生产端证据。
+*
+* `sequence` 只在同一个 `producerSessionId` 内严格递增；`deliveryId` 也只承诺在
+* 该会话内唯一。`occurredAtMs` 是生产端的墙钟，不是宿主接收时间，不能跨设备相减。
+* 消费者可用 `(producerSessionId, sequence)` 排序、用
+* `(producerSessionId, deliveryId)` 去重，并拒绝旧会话的迟到事件。
+*/
+const DeliveredPlayerEventSchema = zod.z.object({
+	/** 未变形的公开业务事件；旧 raw 出口继续单独交付它。 */
+	event: PlayerEventSchema,
+	/** 每次 player/frame producer 生命周期唯一的会话标识。 */
+	producerSessionId: zod.z.string().min(1),
+	/** 在该 producer session 内唯一且重传时保持稳定的投递标识。 */
+	deliveryId: zod.z.string().min(1),
+	/** 生产端创建该事件时读取的 Unix ms 墙钟。 */
+	occurredAtMs: zod.z.number().finite(),
+	/** 在该 producer session 内从 1 开始严格递增的序号。 */
+	sequence: zod.z.number().int().positive()
+});
+//#endregion
 //#region src/methods.ts
 /**
 * 命令。host → iframe(iframe 模式),或消费方 → player-core(inline 模式)。
@@ -1527,10 +1602,8 @@ const CommandSchema = zod.z.discriminatedUnion("method", [
 		params: zod.z.object({ source: MediaSourceSchema })
 	}),
 	zod.z.object({
-		method: zod.z.literal("reconnect"),
-		params: zod.z.object({ 
-		/** true = 把重连计数清零,重新获得完整的 maxRetries 次机会 */
-resetCounter: zod.z.boolean().optional() }).optional()
+		method: zod.z.literal("retry"),
+		params: zod.z.object({}).strict().optional()
 	}),
 	zod.z.object({
 		method: zod.z.literal("pushDanmaku"),
@@ -1562,36 +1635,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 = "2.0.0";
 const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;
 /**
 * 解析 semver 字符串。只接受严格的 `major.minor.patch`,
@@ -1682,8 +1730,18 @@ function createEnvelopeSchema(type, payload) {
 }
 /** 命令包裹(host → iframe) */
 const CommandEnvelopeSchema = createEnvelopeSchema("command", CommandSchema);
-/** 事件包裹(iframe → host) */
-const EventEnvelopeSchema = createEnvelopeSchema("event", PlayerEventSchema);
+const LegacyEventEnvelopeSchema = createEnvelopeSchema("event", PlayerEventSchema).extend({
+	/** Older iframe builds omit all delivery evidence. */
+	producerSessionId: zod.z.undefined().optional(),
+	sequence: zod.z.undefined().optional()
+});
+const DeliveredEventEnvelopeSchema = createEnvelopeSchema("event", PlayerEventSchema).extend({
+	/** Producer-side delivery evidence is atomic: both fields are required together. */
+	producerSessionId: zod.z.string().min(1),
+	sequence: zod.z.number().int().positive()
+});
+/** 事件包裹(iframe → host)：旧包省略证据，新包同时携带 session 和 sequence。 */
+const EventEnvelopeSchema = zod.z.union([LegacyEventEnvelopeSchema, DeliveredEventEnvelopeSchema]);
 /**
 * 响应包裹(iframe → host)。命令的结果一律是 void——
 * 播放状态通过事件回来,不塞在 response 里。
@@ -1694,10 +1752,10 @@ const ErrorEnvelopeSchema = createEnvelopeSchema("error", PlayerErrorSchema);
 /**
 * 任意包裹。收到消息时先用它 parse,再按 `type` 分支。
 *
-* 用 discriminatedUnion 而不是 union:错误信息能精确到具体分支,
-* 而不是把四个分支的失败原因全列一遍。
+* event 分支自身要区分旧包和带 delivery evidence 的新包，因此这里用 union。
+* 每个分支的 `type` 仍是具体字面量，TypeScript 仍可按 `type` 窄化。
 */
-const EnvelopeSchema = zod.z.discriminatedUnion("type", [
+const EnvelopeSchema = zod.z.union([
 	CommandEnvelopeSchema,
 	EventEnvelopeSchema,
 	ResponseEnvelopeSchema,
@@ -1725,6 +1783,13 @@ function commandEnvelope(payload, meta) {
 }
 /** 构造事件包裹(iframe → host) */
 function eventEnvelope(payload, meta) {
+	if (meta.producerSessionId !== void 0 && meta.sequence !== void 0) return {
+		...envelopeBase(meta),
+		type: "event",
+		payload,
+		producerSessionId: meta.producerSessionId,
+		sequence: meta.sequence
+	};
 	return {
 		...envelopeBase(meta),
 		type: "event",
@@ -1848,8 +1913,10 @@ function resolvePreset(preset, config) {
 exports.CONTRACT_VERSION = CONTRACT_VERSION;
 exports.CommandEnvelopeSchema = CommandEnvelopeSchema;
 exports.CommandSchema = CommandSchema;
+exports.ControlVisibilityConfigSchema = ControlVisibilityConfigSchema;
 exports.DanmakuConfigSchema = DanmakuConfigSchema;
 exports.DanmakuItemSchema = DanmakuItemSchema;
+exports.DeliveredPlayerEventSchema = DeliveredPlayerEventSchema;
 exports.ERROR_META = ERROR_META;
 exports.EnvelopeSchema = EnvelopeSchema;
 exports.EnvelopeTypeSchema = EnvelopeTypeSchema;
@@ -1868,6 +1935,9 @@ exports.MediaTypeSchema = MediaTypeSchema;
 exports.MultiSourceObjectSchema = MultiSourceObjectSchema;
 exports.PLAYER_DESTROYED_MESSAGE = PLAYER_DESTROYED_MESSAGE;
 exports.PRESETS = PRESETS;
+exports.PageFullscreenControlSchema = PageFullscreenControlSchema;
+exports.PageFullscreenMessageSchema = PageFullscreenMessageSchema;
+exports.PageFullscreenStateSchema = PageFullscreenStateSchema;
 exports.PauseImageConfigSchema = PauseImageConfigSchema;
 exports.PlayableReasonSchema = PlayableReasonSchema;
 exports.PlaybackContextSchema = PlaybackContextSchema;