@video-lab/protocol 1.0.0

package/dist/index.cjs

@@ -0,0 +1,1909 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let zod = require("zod");
+//#region src/configs.ts
+/** 媒体类型。`auto` = 从 URL 后缀推断 */
+const MediaTypeSchema = zod.z.enum([
+	"mp4",
+	"hls",
+	"flv",
+	"auto"
+]);
+/** 已经完成归一化、可实际路由的媒体类型。`auto` 只允许停留在消费方输入侧。 */
+const SourceEntryTypeSchema = zod.z.enum([
+	"mp4",
+	"hls",
+	"flv"
+]);
+/** 封面配置 */
+const PosterConfigSchema = zod.z.union([zod.z.string(), zod.z.object({
+	url: zod.z.string(),
+	loading: zod.z.enum(["eager", "lazy"]).default("lazy").optional(),
+	fit: zod.z.enum([
+		"cover",
+		"contain",
+		"fill"
+	]).default("cover").optional()
+})]);
+/**
+* 暂停时盖在画面中央的静态图(ADR-043 / issue #121)。
+*
+* 形状**刻意与 {@link PosterConfigSchema} 对齐**(同为 `string | { url, fit, … }`),
+* 消费方不用学两套。
+*
+* **渲染在 iframe 内,与封面相反** —— 封面为了抢首帧挪到了宿主侧,暂停图不抢首帧
+*(暂停发生时 iframe 早已 ready),放宿主侧反而让静态 iframe 那条路拿不到,撞 cross-mode-parity。
+*
+* **边界(ADR-025 已判的那条线)**:静态图 + 可选关闭按钮进 SDK —— 可序列化、无调度逻辑,
+* 与 `poster` 同性质;**带倒计时 / 跳转 / 推荐列表的不进** —— 那是业务调度,归团队层。
+* inline 模式另有 `<sentinel-pause>` 的默认 slot(能塞任意节点),表达力更强但
+* 过不了 postMessage,所以三条 iframe 路只有本字段有效。
+*/
+const PauseImageConfigSchema = zod.z.union([zod.z.string(), zod.z.object({
+	url: zod.z.string(),
+	/**
+	* 默认 `contain` —— 暂停图通常是完整构图,`cover` 会把边裁掉。
+	*
+	* ⚠️ 默认值**由渲染侧兜**,不写成 zod 的 `.default()`:`.default(x).optional()`
+	* 里 optional 会短路,默认值永远不生效(`PosterConfigSchema` 的 `loading` / `fit`
+	* 就是这个形态,parse `{url}` 出来还是 `{url}`)。写在 schema 上会让消费方
+	* 以为 parse 完就有值,反而误导。
+	*/
+	fit: zod.z.enum([
+		"cover",
+		"contain",
+		"fill"
+	]).optional(),
+	/** 给图加一个关闭按钮,用户点了本次播放不再显示。默认 `false` */
+	closable: zod.z.boolean().optional()
+})]);
+/** 字幕轨 */
+const SubtitleTrackSchema = zod.z.discriminatedUnion("mode", [zod.z.object({
+	mode: zod.z.literal("url"),
+	url: zod.z.string(),
+	locale: zod.z.string(),
+	label: zod.z.string(),
+	isDefault: zod.z.boolean().optional()
+}), zod.z.object({
+	mode: zod.z.literal("content"),
+	/**
+	* 内联字幕正文,**必须是 WebVTT**(以 `WEBVTT` 行开头)。
+	*
+	* 字幕能力来自 xgplayer `TextTrack` 插件(wrap `xgplayer-subtitles@3.0.26`),
+	* 那份产物里 `WEBVTT` 出现 1 次、`srt` **0 次** —— 引擎只认这一种格式。
+	*
+	* 这里曾并列一个必填的 `contentType: z.enum(['text/vtt','text/srt'])`,
+	* 但 `'text/srt'` 从来不可能工作,而且没有任何一层读过这个字段。
+	* 既然只剩一个合法值,它就不携带任何信息 —— 已按 ADR-039 删除。
+	*/
+	content: zod.z.string(),
+	locale: zod.z.string(),
+	label: zod.z.string(),
+	isDefault: zod.z.boolean().optional()
+})]);
+/** HLS 协议专属配置 */
+const HlsConfigSchema = zod.z.object({ 
+/**
+* LL-HLS 显式开启(ADR-024)。
+*
+* ⚠️ **所有浏览器都必须显式开**,否则不会启用低延迟模式。
+*
+* 这里从前写的是「非 Safari 必须显式开;Safari 走原生,自动检测 EXT-X-PART-INF」——
+* **那句话被 ADR-056 作废了**:HLS 内核现在按能力选,有 MSE 或 MMS 就走 hls.js,
+* 于是 Safari / iOS 也不再走原生,那条「平台白送的自动低延迟」路径没有了。
+* 后果是**静默的**:不显式开的话,原本靠它的直播只是退回普通 HLS 延迟,不报错。
+*/
+lowLatencyMode: zod.z.boolean().optional() });
+/** 媒体元信息 */
+const MediaMetadataSchema = zod.z.object({
+	title: zod.z.string().optional(),
+	description: zod.z.string().optional(),
+	duration: zod.z.number().optional()
+});
+/**
+* 多源里的单个候选源。`type` 必填——多源场景下不允许靠后缀猜。
+*
+* ⚠️ **这里曾经有 `quality` / `bitrate` / `codec`,已按 #276 删除**(判据见 ADR-039)。
+* 三个都是零消费点:清晰度档位 100% 来自 hls.js 的 `levels`(`readQualityLevels`),
+* 和消费方声明的候选源无关;选源规则只按 `type`(容器格式)走,这三个不参与任何一步。
+*
+* **别看着「候选源没有清晰度信息」好心加回来** —— `sources[]` 是「同一内容的不同封装」,
+* 不是「不同分辨率」。把它重新解释成清晰度候选是**新增能力**,要先回答「声明值和 manifest
+* 实际档位不符时听谁的」(ADR-046 在 `metadata.duration` 上答过同类问题:**听引擎的**),
+* 走 issue + ADR,不是往这里补一个字段。
+*
+* 它们此前没被发现,是因为 `contract-fields` 的数组递归有 bug(zod 3 的
+* `ZodArray._def.type` 装的是元素 schema 不是类型名),**数组元素字段整层从没进过清单**(#275 修)。
+*/
+const SourceEntrySchema = zod.z.object({
+	url: zod.z.string(),
+	type: SourceEntryTypeSchema
+});
+/**
+* 单源 / 多源对象共有的字段。
+*
+* ⚠️ 这里曾经有 `poster`,已按 ADR-049 删除 —— 零消费点,且**顶层 `PlayerConfig.poster`
+* 覆盖同一能力并且真的接到了 xgplayer**。墓碑见 {@link PlayerConfigSchema} 的 JSDoc。
+*/
+const sourceCommonShape = {
+	/**
+	* 直播标记。**SDK 不探测,完全靠消费方传。**
+	*
+	* 它管两件事:① 选源优先级(直播优先 FLV,点播优先 HLS,见 `source-router.ts`);
+	* ② 播放器的 `isLive` —— iOS 后台切回的自愈策略、弹幕模式、进度条能不能拖。
+	*
+	* ⚠️ **写在 source 上,但生效范围是整个 player。** ② 是**构造期**配置,
+	* 运行时改不了 —— 所以 `load()` 换源时新旧 `live` 不一致会抛
+	* `E_METHOD_NOT_SUPPORTED`,要销毁重建(#220)。别被它挂在 source 上的位置误导。
+	*
+	* ⚠️ **漏填是静默失效**:直播不写 `live: true` → 走点播优先级选中 HLS →
+	* 延迟从 ~2s 变 ~8s,不报错不告警(#217)。
+	*/
+	live: zod.z.boolean().optional(),
+	hls: HlsConfigSchema.optional(),
+	subtitles: zod.z.array(SubtitleTrackSchema).optional(),
+	metadata: MediaMetadataSchema.optional()
+};
+/** 单源对象 */
+const SingleSourceObjectSchema = zod.z.object({
+	url: zod.z.string(),
+	/**
+	* 默认 `auto`(从后缀推断)。
+	*
+	* ⚠️ 带 query 的 URL(如 `video.m3u8?token=xxx`)推断不出来,**必须显式传 `type`**,
+	* 否则会走 MP4 处理路径。签名 URL 场景尤其注意(ADR-022)。
+	*/
+	type: MediaTypeSchema.optional(),
+	...sourceCommonShape
+});
+/**
+* 多源对象。直播 FLV + HLS 双路兜底的标准形态。
+*
+* ⚠️ FLV 单源在 iOS / 微信 / UC / 夸克 下必然抛 `E_MEDIA_NOT_SUPPORTED`,
+* **FLV 永远和 HLS 一起放进 sources 数组**。
+*/
+const MultiSourceObjectSchema = zod.z.object({
+	sources: zod.z.array(SourceEntrySchema).min(1),
+	...sourceCommonShape
+});
+/**
+* 媒体源。三种写法:URL 字符串(最简)、单源对象、多源对象。
+*
+* **这是 wire schema——只含可 JSON 序列化的字段**。
+* ⛔ **`source.onBeforeRequest` 已废弃(ADR-057),下个 major 删除** ——
+* 它不在这里、也不在任何 Schema 里,而且 player-core 里从来没有消费点(#332)。
+* 认证走签名 URL + 长有效期(ADR-022)。见 {@link SourceRequestHook}。
+*/
+const MediaSourceSchema = zod.z.union([
+	zod.z.string(),
+	MultiSourceObjectSchema,
+	SingleSourceObjectSchema
+]);
+/** i18n 配置 */
+const LocaleConfigSchema = zod.z.union([zod.z.string(), zod.z.object({
+	locale: zod.z.string(),
+	fallbackLocales: zod.z.array(zod.z.string()).optional(),
+	/**
+	* 翻译表。**SDK 不内置任何翻译,只提供注入机制** —— 覆盖层文案
+	*(loading / error.* / retry / close)全部由消费方从这里传入。
+	* 消费面用 `resolveLocaleMessages` 把它解析成扁平表,再把解析好的**字符串**
+	* 传给覆盖层元素;缺 key 时原样返回 key(可见失败,不抛错)。
+	*
+	* **两个命名空间,同一张表**:
+	* - 覆盖层:`loading` / `retry` / `close` / `error.<CODE>` —— **无内置翻译**
+	* - 播放内核自带控件:`controls.*` —— 内置中 / 英,你传的会**覆盖**(#208 / ADR-051)
+	*
+	* 语言标签本身仍只有中 / 英两档(`zh-*` → 中文,其余 → 英文,见 player-core 的 `toXgLang`),
+	* 但**那不再限制能翻成什么语言**:传 `locale:'vi-VN'` + `messages['vi-VN']['controls.play']`,
+	* 控件就是越南语 —— 标签落在 `en` 那一档,而那一档的文案被换掉了。
+	* `controls.*` 的 key 全集见 USER-GUIDE § 9.4;**表外的静默忽略**。
+	*
+	* ⚠️ 这段从前写着「控件不读 messages」—— 那是 #208 修掉的现状,别照着旧描述下结论。
+	*/
+	messages: zod.z.record(zod.z.string(), zod.z.record(zod.z.string(), zod.z.string())).optional()
+})]);
+/**
+* 弹幕单条(streaming push 用)。见 ADR-028 / ARCHITECTURE § 8.3.7。
+*
+* 直播场景:业务从自己的数据源(WebSocket / 轮询,SDK 不参与)拿到一条,
+* 经 `pushDanmaku` 命令喂进来,到点即显(不绑视频时间)。
+*/
+const DanmakuItemSchema = zod.z.object({
+	/** 唯一 id(去重 / 更新用) */
+	id: zod.z.string(),
+	text: zod.z.string(),
+	/** 滚动 / 顶部固定 / 底部固定;默认 scroll */
+	type: zod.z.enum([
+		"scroll",
+		"top",
+		"bottom"
+	]).optional(),
+	/** hex / rgb 颜色;默认白 */
+	color: zod.z.string().optional(),
+	/**
+	* 这条弹幕出现的时间点,**毫秒**,视频时间轴(#275)。
+	*
+	* **不给 = 立刻出现** —— 所以 `pushDanmaku` 的现有行为一个字节都不变。
+	* 只在 `mode: 'preload'` 下有调度意义:引擎按它排期,seek 时自己重排(实测:
+	* seek 回 0 后整池重放,已放过的标记被清掉 —— 见 `danmaku-preload.spec.ts`)。
+	*
+	* ⚠️ **精度是 ±1 秒,不是精确到点。** 渲染引擎按区间匹配而非到点触发,
+	* `start` 给的是**目标时刻**,实际出现可能提前或延后至多 1 秒。这是引擎行为,
+	* SDK 已把窗口从它的默认 2 秒收到 1 秒(`DANMAKU_PRELOAD_WINDOW_MS`,那里写了为什么
+	* 不能更小)。**要逐帧对齐的字幕型需求请用字幕轨(ADR-027),不要用弹幕。**
+	*
+	* ⚠️ **单位是毫秒,而契约里 `seek` / `startTime` / `currentTime` 都是秒。**
+	* 这处不一致是**故意的**:这个字段直连 danmu.js 的同名同义字段,
+	* 中间不做换算就不会有换算错误。代价是消费方要记住它和别的时间字段单位不同 ——
+	* **这是真的代价,不是「其实没关系」**(见 `archive/docs/specs/danmaku-preload-mode.md`)。
+	*/
+	start: zod.z.number().nonnegative().optional()
+});
+/**
+* 弹幕配置(PlayerConfig.danmaku,默认关闭)。见 ADR-028 / ARCHITECTURE § 8.3.7。
+*
+* **两种模式**:`streaming`(直播,`pushDanmaku` 逐条)/ `preload`(点播,挂载时整包给,
+* 引擎按每条的 `start` 排期,见 #275)。ADR-028 当初只做 streaming,preload 是它说的「后续 minor」。
+* **弹幕渲染是 SDK 技术**(xgplayer Danmu 引擎:轨道调度 / 防重叠);**数据源 / 发送框 / 过滤归团队层**
+* (ADR-025,同字幕菜单)——SDK 关掉 xgplayer 内置弹幕按钮/面板。
+*/
+const DanmakuConfigSchema = zod.z.object({
+	enabled: zod.z.boolean(),
+	/** preload=一次性(点播,配合 `items`);streaming=pushDanmaku 逐条(直播)。默认 streaming */
+	mode: zod.z.enum(["preload", "streaming"]).optional(),
+	/**
+	* 预载弹幕池(**仅 `mode: 'preload'`**)。挂载时整包交给渲染引擎,
+	* 由引擎按每条的 `start` 排期、seek 时重排 —— **SDK 不自己写调度器**
+	* (写了就得自己处理 seek / 倍速 / 轨道冲突,那是渲染引擎的本职)。
+	*
+	* 想在运行时**换掉整包**目前不支持:那需要新增一个契约方法,要在五种接入方式上
+	* 各实现一遍并永久维护。等有「一万条首屏太慢」这类实测需求再加,那是向后兼容的 minor。
+	*/
+	items: zod.z.array(DanmakuItemSchema).optional(),
+	/** 显示配置(透传给渲染引擎) */
+	display: zod.z.object({
+		/** 显示区域高度:顶部 / 半屏 / 全屏 */
+		area: zod.z.enum([
+			"top",
+			"half",
+			"full"
+		]).optional(),
+		opacity: zod.z.number().min(0).max(1).optional(),
+		/** 速度倍率 */
+		speed: zod.z.number().min(.5).max(2).optional(),
+		fontSize: zod.z.number().min(12).max(48).optional(),
+		/**
+		* 最大轨道数(同时最多几行弹幕)。**与 `area` 互斥**,同传整份配置被拒。
+		*
+		* **是「最多」不是「精确」**:设得比播放器高度装得下的还多时,SDK 会把它钳到
+		* 容器装得下的条数 —— 否则多出来的轨道整个落在可视区外,被分配到那些轨道上的
+		* 弹幕会**静默看不见**(渲染引擎只有「精确 N 条」和「按高度算」两种模式,
+		* 「取较小」得靠 SDK 在运行时补,见 player-core 的 `attachDanmakuLineClamp`)。
+		*
+		* 钳制跟随播放器尺寸变化(全屏 / 容器 resize)。
+		*/
+		maxLines: zod.z.number().int().positive().optional()
+	}).optional()
+}).superRefine((cfg, ctx) => {
+	if (cfg.items && cfg.items.length > 0 && cfg.mode !== "preload") ctx.addIssue({
+		code: "custom",
+		path: ["items"],
+		message: `danmaku.items 只在 mode: 'preload' 下有效。当前 mode 是 ${cfg.mode ?? "streaming"}(默认)—— 渲染引擎在直播模式下会忽略每条的 start,整包会一股脑全飘出来。要么设 mode: "preload",要么改用 pushDanmaku 逐条推。`
+	});
+	if (cfg.display?.maxLines !== void 0 && cfg.display.area && cfg.display.area !== "full") ctx.addIssue({
+		code: "custom",
+		path: ["display", "maxLines"],
+		message: `danmaku.display.maxLines 与 area: '${cfg.display.area}' 不能同时用 —— 渲染引擎里两者互斥(给了轨道条数,区域比例就失效),同传只会有一个生效。要限制条数就去掉 area(或用 area: 'full'),要限制区域就去掉 maxLines。`
+	});
+});
+/**
+* 场景预设。预设只是一组默认值,消费方传的单个字段永远覆盖预设
+* (见 {@link resolvePreset})。预设内容见 `presets.ts`。
+*
+* 定义在这里而不是 presets.ts,是为了让 PlayerConfig 能引用它而不产生循环依赖。
+*/
+const PresetNameSchema = zod.z.enum(["homepage-preview"]);
+/**
+* 播放器初始化配置。iframe 模式下握手成功后作为第一条 command 下发,
+* 所以必须整体可 JSON 序列化。
+*
+* ### 曾经存在、已删除的字段(别重新发明)
+*
+* 都是「声明了但全仓没人读」的幽灵字段,判据见 ADR-039。zod 默认 `strip`,
+* 消费方继续传不会报错也不会生效,TS 侧会编译失败 —— 这是期望的:
+* 让「传了没用」从静默失效变成显式失败。
+*
+* | 字段 | 删于 | 为什么 |
+* |---|---|---|
+* | `telemetry`(sessionId / userId / tags / mode) | ADR-037 | 零消费点。埋点由消费方监听契约事件自行上报,SDK 不代发(也发不了 —— 红线禁 HTTP 库)。**替代形态在输出侧,不是把这个字段加回来** —— 见下 |
+* | `crossOrigin` | ADR-037 | 零消费点,且语义与 CORS / 签名 URL(ADR-022)/ CDN 响应头三者耦合,接线前得先想清楚 |
+* | `consent`(analytics / thirdPartyCookies / personalization) | ADR-040 | 零消费点。`analytics` 曾门控 `stalled` 的 emit,但那个门控保护不了隐私(数据从没离开浏览器),只掐死 UI,已按 ADR-026「实现更正」移除;另两个子字段从来就没被读过。**合规过滤属于消费方的上报层** |
+* | `controls.minimal`(连同 `ControlsConfig` / `ControlsConfigSchema`) | ADR-045 | 零消费点 —— 传 `{minimal:true}` 与传 `{}` 效果完全一致(实现只看 `controls !== false`)。声明写的「遥控器 / TV 场景」在 v1.0 范围外,无任何需求在等它。它是那个 schema 唯一的字段,`controls` 一并从 union 收窄为纯布尔 |
+* | `source.poster`(单源 / 多源对象共有) | ADR-049 | 零消费点。`source-normalize` 认真地把它搬进 `NormalizedSource.poster`,而**全仓没有任何一处读那个属性** —— 从来没生效过。**顶层 `poster` 覆盖同一能力且真的接到了 xgplayer**,它也表达不了「每个候选源一张封面」(它挂在 source 对象上,不在 `SourceEntry` 上)。封面要跟着 `load()` 换,消费方改 `poster` prop 即可 |
+*/
+/**
+* ⚠️ **别把 `telemetry` 加回来 —— 它的替代形态在输出侧**(ADR-074)。
+*
+* 上表删 `telemetry` 的论据是「纯粹的透传字段:SDK 收下来什么也不做」,那条论据
+* **仍然成立且永久成立**。ADR-074 加的 {@link PlaybackContext} 方向相反:
+* 它是 SDK **交出去**的、而且**只有 SDK 知道**的那几格(实际选中的内核 / 选中的候选源 /
+* 出错位置 / 当前档位 / 会话 id)。
+*
+* 判据是「消费方能不能在 SDK 外面自己拿到」。`userId` / `tags` 拿得到,所以**永久不进**;
+* 想加请先推翻 ADR-037,不要引用 ADR-074 当依据。
+*/
+const PlayerConfigSchema = zod.z.object({
+	source: MediaSourceSchema,
+	/** 场景预设。会被同名的显式字段覆盖 */
+	preset: PresetNameSchema.optional(),
+	autoplay: zod.z.boolean().optional(),
+	muted: zod.z.boolean().optional(),
+	loop: zod.z.boolean().optional(),
+	/** 初始倍速。运行时改倍速走 `setPlaybackRate` 命令 */
+	playbackRate: zod.z.number().min(.25).max(4).optional(),
+	volume: zod.z.number().min(0).max(1).optional(),
+	playsinline: zod.z.boolean().optional(),
+	preload: zod.z.enum([
+		"none",
+		"metadata",
+		"auto"
+	]).optional(),
+	startTime: zod.z.number().min(0).optional(),
+	/**
+	* 显示/隐藏 xgplayer 自带控件。**只有布尔**。
+	*
+	* 曾经是 `boolean | { minimal?: boolean }`,但 `minimal` 零消费点(传了和没传
+	* 完全一样),已按 ADR-045 删除;它是那个对象里唯一的字段,只剩空对象的 union
+	* 分支不携带任何信息,一并收窄。将来真要做 TV / 遥控器,重新放宽成
+	* `boolean | { minimal?: boolean }` 是 **minor 不是 breaking**,不是单向门。
+	*/
+	controls: zod.z.boolean().optional(),
+	/** 是否响应用户交互。首页预览卡片用 false,点击透传给外层卡片 */
+	interactive: zod.z.boolean().optional(),
+	poster: PosterConfigSchema.optional(),
+	/** 暂停时盖在画面中央的静态图。渲染在 iframe 内(与封面相反),见 ADR-043 */
+	pauseImage: PauseImageConfigSchema.optional(),
+	locale: LocaleConfigSchema.optional(),
+	/** 弹幕配置(默认关闭,ADR-028)。渲染归 SDK,数据源/发送/过滤归团队层 */
+	danmaku: DanmakuConfigSchema.optional(),
+	/**
+	* 打开 **iframe 通信层**日志(Penpal 的握手与消息收发)。
+	*
+	* 透传给 penpal 的 `debug` 选项,gate 的是它自己的 `console.log('[Penpal]', …)`。
+	* 排查「握手超时 / 命令不达 / 事件丢失」时打开,能看到 SYN / SYN-ACK / ACK 的实际往返。
+	*
+	* ⚠️ **inline 模式无作用** —— 那条路没有 iframe、没有 Penpal。
+	* xgplayer 3.0.26 的 `defaultConfig` 也没有任何 debug / logLevel 字段可映射,
+	* 按 ADR-029「无真实需求驱动,不投机造能力」不为 inline 硬造一套日志。
+	*
+	* 实现细节:host 侧(frame-core)读到它后,除了给 `connectToChild` 开 debug,
+	* 还会在 iframe URL 上追加 `?debug=1` —— 因为本字段是**经 Penpal 连接**送进 iframe 的,
+	* 等它到达时连接早已建好,没法再回头配置那条连接。
+	*/
+	debug: zod.z.boolean().optional()
+});
+//#endregion
+//#region src/errors.ts
+/**
+* 错误分类。player-core 把 xgplayer 的内部错误映射到这几类,
+* 映射规则见 `packages/protocol/CLAUDE.md § xgplayer 错误 → PlayerError 映射规则`。
+*/
+const ErrorCategorySchema = zod.z.enum([
+	"manifest",
+	"media",
+	"network",
+	"auth",
+	"env",
+	"autoplay"
+]);
+/**
+* 全部错误码。命名规则 `E_<CATEGORY>_<SPECIFIC>`。
+* 权威来源:ARCHITECTURE.md § 8.6。
+*
+* **每一个码都必须有真实发射点**(ADR-034)。`player-core/tests/contract-coverage.test.ts`
+* 静态扫描全仓库生产代码强制这条 —— 加码不加实现,测试直接红。
+*
+* 原则:**能删不留**。一个我们暂时检测不到的错误码,留在契约里是谎言;
+* 而删掉之后将来能检测了再加回来,是向后兼容的 minor,代价极低。
+*/
+const ErrorCodeSchema = zod.z.enum([
+	"E_MANIFEST_PARSE",
+	"E_MEDIA_DECODE",
+	"E_MEDIA_ABORTED",
+	"E_MEDIA_NOT_SUPPORTED",
+	"E_SUBTITLE_LOAD_FAILED",
+	"E_AUTOPLAY_BLOCKED",
+	"E_NETWORK",
+	"E_NETWORK_TIMEOUT",
+	"E_AUTH_EXPIRED",
+	"E_ENV_CSP_BLOCKED",
+	"E_METHOD_NOT_SUPPORTED",
+	"E_DANMAKU_SEND_FAILED",
+	"E_INTERNAL",
+	"E_UNKNOWN",
+	"E_PLAYER_DESTROYED",
+	"E_HANDSHAKE_TIMEOUT",
+	"E_HANDSHAKE_VERSION_MISMATCH",
+	"E_LOAD_FAILED",
+	"E_FRAME_CRASHED"
+]);
+/**
+* 警告码。命名规则 `W_<CATEGORY>_<SPECIFIC>`。
+* 警告不中断播放,只通过 `compatwarning` 事件上抛给消费方。
+*/
+const WarningCodeSchema = zod.z.enum([
+	"W_BROWSER_INCOMPATIBLE",
+	"W_VERSION_MISMATCH",
+	"W_EVENT_REJECTED"
+]);
+/**
+* 错误码 → 元数据。**唯一真相**:player-core 的 error-mapping、
+* frame-core 的 fallback、消费方的重试 UI 全部读这张表,不要各自硬编码。
+*/
+const ERROR_META = {
+	E_MANIFEST_PARSE: {
+		category: "manifest",
+		retryable: false
+	},
+	E_MEDIA_DECODE: {
+		category: "media",
+		retryable: true
+	},
+	E_MEDIA_ABORTED: {
+		category: "media",
+		retryable: true
+	},
+	E_MEDIA_NOT_SUPPORTED: {
+		category: "media",
+		retryable: false
+	},
+	E_SUBTITLE_LOAD_FAILED: {
+		category: "media",
+		retryable: true
+	},
+	E_AUTOPLAY_BLOCKED: {
+		category: "autoplay",
+		retryable: false
+	},
+	E_NETWORK: {
+		category: "network",
+		retryable: true
+	},
+	E_NETWORK_TIMEOUT: {
+		category: "network",
+		retryable: true
+	},
+	E_AUTH_EXPIRED: {
+		category: "auth",
+		retryable: false
+	},
+	E_ENV_CSP_BLOCKED: {
+		category: "env",
+		retryable: false
+	},
+	E_METHOD_NOT_SUPPORTED: {
+		category: "env",
+		retryable: false
+	},
+	E_DANMAKU_SEND_FAILED: {
+		category: "env",
+		retryable: true
+	},
+	E_INTERNAL: {
+		category: "env",
+		retryable: false
+	},
+	E_UNKNOWN: {
+		category: "env",
+		retryable: false
+	},
+	E_PLAYER_DESTROYED: {
+		category: "env",
+		retryable: false
+	},
+	E_HANDSHAKE_TIMEOUT: {
+		category: "network",
+		retryable: true
+	},
+	E_HANDSHAKE_VERSION_MISMATCH: {
+		category: "env",
+		retryable: false
+	},
+	E_LOAD_FAILED: {
+		category: "network",
+		retryable: true
+	},
+	E_FRAME_CRASHED: {
+		category: "env",
+		retryable: false
+	}
+};
+/**
+* `PlayerError.cause` 的形状。**只用于 debug**,不要在业务逻辑里依赖它 ——
+* 业务判断用 `code` / `category` / `retryable`。
+*
+* **为什么是固定结构而不是 `unknown`(#270)**:错误对象要跨 iframe 传输,
+* 而 `postMessage` 用的是**结构化克隆**。塞进来的原始错误常常挂着 DOM 对象
+* (xgplayer 的错误就带着 `MediaError`),结构化克隆遇到它**直接抛 `DataCloneError`**,
+* 整条 envelope 发不出去 —— 消费方拿不到真正的错误码。
+*
+* ⚠️ **这里曾经写着「必须可 JSON 序列化」,规矩是对的,前提是错的**:
+* `JSON.stringify` 遇到不可序列化的东西**静默丢弃**,`structuredClone` **抛异常**,
+* 两者对同一件事的处理正好相反。契约按 JSON 语义写、传输按克隆语义跑,于是没人执行。
+* 现在字段全是原始类型,**结构化克隆不可能再抛**。
+*
+* **不带 `stack`**:跨 iframe 的 stack 指向 iframe 内部的 bundle 文件,宿主侧看到的是
+* 一串陌生路径,排查价值低而体积不小(embed-app 的全局上报已用 `source`/`lineno` 提供等价信息)。
+*/
+const ErrorCauseSchema = zod.z.object({
+	/** 原始错误的 `name`;取不到时是 `'Unknown'` */
+	name: zod.z.string(),
+	message: zod.z.string(),
+	/** `MediaError.code`(1–4)等结构化码 —— 错误分类本来就是靠它做的,排查时缺它答不了「decode 还是 src_not_supported」 */
+	code: zod.z.number().optional(),
+	/** HTTP 状态码,区分 401 / 403 用 */
+	status: zod.z.number().optional()
+}).catchall(zod.z.union([
+	zod.z.string(),
+	zod.z.number(),
+	zod.z.boolean()
+]));
+/** `String(x)` 的截断上限 —— cause 是旁路信息,不该把 envelope 撑大 */
+const CAUSE_MESSAGE_MAX = 500;
+function readNumber(source, key) {
+	const v = source[key];
+	return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+/**
+* 把任意 `cause` 归一成 wire-safe 的 {@link ErrorCause}。
+*
+* **幂等**:已经是这个形状的再过一遍还是它自己 —— 靠的是下面这段通用读取本身,
+* 不是靠一条「已经合规就原样返回」的快路径。**那条快路径试过,是错的**:
+* 它会把已经合规的对象整个放行,于是 `message` 的截断对它不生效
+* ——而 `new Error('x'.repeat(5000))` 恰好就能通过 schema 校验(`name`/`message`
+* 在 Error 的原型链上,zod 读得到),5000 字符原样进了 envelope。
+* `makePlayerError` 会被嵌套调用(frame-core 解包出 playerError 再重包),幂等是必须的,
+* 但它得由「每次都真的走一遍归一」来保证,不是由「认出来就跳过」。
+*
+* 取值优先级刻意和 `player-core/src/error-mapping.ts` 的分类逻辑对齐:
+* 那边靠 `mediaError.code` 分类,这边就把同一个 code 留下来,否则排查时人要去猜。
+*/
+function serializeCause(cause) {
+	if (cause === null || typeof cause !== "object") return {
+		name: "Unknown",
+		message: String(cause).slice(0, CAUSE_MESSAGE_MAX)
+	};
+	const obj = cause;
+	const media = obj.mediaError ?? void 0;
+	const name = typeof obj.name === "string" ? obj.name : media ? "MediaError" : typeof obj.errorType === "string" ? obj.errorType : "Unknown";
+	const rawMessage = typeof obj.message === "string" ? obj.message : typeof media?.message === "string" ? media.message : String(cause);
+	const code = readNumber(obj, "code") ?? (media ? readNumber(media, "code") : void 0);
+	const status = readNumber(obj, "status") ?? readNumber(obj, "httpCode");
+	const extras = {};
+	for (const [k, v] of Object.entries(obj)) if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") extras[k] = v;
+	return {
+		...extras,
+		name,
+		message: rawMessage.slice(0, CAUSE_MESSAGE_MAX),
+		...code === void 0 ? {} : { code },
+		...status === void 0 ? {} : { status }
+	};
+}
+/**
+* 错误对象。**跨 iframe 传输,所以每个字段都必须能过结构化克隆** ——
+* `cause` 由 {@link makePlayerError} 统一归一成 {@link ErrorCause},见 #270。
+*/
+const PlayerErrorSchema = zod.z.object({
+	code: ErrorCodeSchema,
+	message: zod.z.string(),
+	retryable: zod.z.boolean(),
+	category: ErrorCategorySchema,
+	cause: ErrorCauseSchema.optional()
+});
+/**
+* 构造 PlayerError。category 和 retryable 一律从 {@link ERROR_META} 推出来,
+* 不接受调用方传入——避免同一个 code 在不同包里被标成不同的 retryable。
+*
+* @example
+* makePlayerError('E_NETWORK', '拉流失败', originalError)
+* // → { code: 'E_NETWORK', message: '拉流失败', category: 'network', retryable: true, cause: ... }
+*/
+/**
+* `E_PLAYER_DESTROYED` 的统一文案。
+*
+* **三个包各自发射它**(`frame-core` 的 `send()` 闸、`react` / `vue` 的 prop effect)——
+* 文案分三份写就是三份会漂的副本,而这条需求的标题恰恰是「五面说同一句话」
+*(`archive/docs/specs/destroyed-player-command-signal.md`)。
+*
+* 契约只钉 `code`,不钉 `message`;放在这里是**为了不漂**,不是把文案升级成契约。
+*/
+const PLAYER_DESTROYED_MESSAGE = "播放器已销毁,这条命令没有生效 —— 重挂组件才能继续";
+function makePlayerError(code, message, cause) {
+	const meta = ERROR_META[code];
+	return {
+		code,
+		message,
+		category: meta.category,
+		retryable: meta.retryable,
+		...cause === void 0 ? {} : { cause: serializeCause(cause) }
+	};
+}
+//#endregion
+//#region src/observability.ts
+/**
+* 观测信号(ADR-075 · #490)。**xgplayer 的 `DefaultPreset` 一直在算,而 `player-core`
+* 从来没读过** —— `Stats` / `XGLogger` / `FpsDetect` 三个插件每次播放都在工作,
+* 而 `player-core/src` 对它们的引用数是 0。
+*
+* ─── 为什么归一函数住这里,而不是各消费面各写一份 ───
+*
+* 上游 payload **带原始 DOM 对象**(`player.js:1449` 的 `emitUserAction` 把整个
+* `event` 塞进去)。它过不了 iframe 的 `structuredClone`,Zod 也接不住 ——
+* 照搬会让 **iframe 两条通道当场炸而 inline 两条不炸**,那才是真正的 parity 事故。
+*
+* 所以归一是**纯函数**,四个消费面共用一份。形状逐字沿用 ADR-074 的
+* `redactSourceUrl()`:同样是「上游给的东西不能直接进契约」。
+*
+* ⚠️ **本模块只收上游真的会发的信号。** 原计划的第四条 `bandwidth`
+* (`DOWNLOAD_SPEED_CHANGE`)**被查掉了** —— `TestSpeed` 的 `defaultConfig` 是
+* `openSpeed: false` + `url: ''`,`afterCreate` 直接 return,而剩下唯一入口
+* `real_time_speed` **全 node_modules 没有人发**。进契约就是第二个
+* 「只在注释里存在的 `healthreport`」(#391 抓到的那种)。
+*
+* @see docs/adr/ADR-075-preset-plugin-attribution.md
+*/
+/**
+* 首帧可见耗时(ADR-075 决策②)。来自 `XGLogger` 的 `xglog` / `type: 'firstFrame'`。
+*
+* ⚠️ **和 `pnpm test:e2e:kpi`(#148)量的不是一件事,两者不可互换。**
+* 那条 KPI 量的是**端到端**(含页面加载 / SDK 初始化),本字段是**播放器内部**口径
+* (从内核开始加载到第一帧可见)。**决定是不统一** —— 统一意味着其中一个要放弃
+* 自己的用途,而两个用途都真实存在。
+*/
+const FirstFramePayloadSchema = zod.z.object({ 
+/** 首帧可见耗时,毫秒。上游字段名就叫 `fvt`(first video time) */
+fvt: zod.z.number() });
+/**
+* 画面冻结(ADR-075 决策②)。来自 `FpsDetect` 的 `FPS_STUCK`。
+*
+* ⚠️ **它不叫 `framedrop`,因为它不是掉帧率。** 上游的触发判据是「连续
+* `stuckCount`(默认 3)个 tick 解码帧数 ≤ `reportFrame`(默认 0),**且缓冲够、
+* 没暂停、页面没隐藏**」—— 检出的是**画面冻住**。payload 里确实带
+* `droppedVideoFrames`,但那是附带数据,不是触发判据。
+*
+* ⚠️ **和 `stalled` 不重复。** `stalled` 是**缓冲驱动**的等待,而本信号的前提
+* 恰恰是**缓冲是够的** —— 缓冲够却出不了新帧,指向的是解码侧而不是网络侧。
+*
+* ⚠️ **仅 PC。** `FpsDetect` 在 `presets/default.js` 的 `case 'pc'` 分支才装载,
+* 手机上**结构性不触发**。这不违反 cross-mode-parity(ADR-012)—— 五种接入方式在
+* 同一台设备上表现一致,差异沿的是**平台轴**不是模式轴。但形状正是 ADR-065 那个
+* 陷阱(「这条通道上没有」被读成「这个东西没用」),所以登记在 `upstream-gap-registry`。
+*/
+const FrameFreezePayloadSchema = zod.z.object({
+	/** 冻住了多久(毫秒)= 各次采样 `checkInterval` 之和 */
+	durationMs: zod.z.number(),
+	/** 累计丢帧数(`droppedVideoFrames`,取最后一次采样)。**它不是本事件的触发原因** */
+	droppedFrames: zod.z.number(),
+	/** 累计解码帧数(`totalVideoFrames`,取最后一次采样) */
+	totalFrames: zod.z.number()
+});
+/**
+* 进契约的用户动作白名单(ADR-075 决策③)。
+*
+* ─── 判据是 ADR-039 的「零消费」那一条 ───
+*
+* **消费方在 SDK 外面自己拿不到的才进。** 按这条:
+*
+* - **进**:发生在 SDK 自己控件上的动作。契约里虽然有 `play` / `pause` /
+*   `volumechange` / `seeking` / `qualitychange`,但它们**回答不了「是谁发起的」**
+*   —— 用户点的还是代码调的,而上报侧要区分的正是这个。
+* - **不进**:`click` / `dragstart` / `dragend` / `fragment_focus` —— 这些是进度条上的
+*   **指针级交互**,消费方在自己的容器上监听就有;而且拖动本身还会再发一条 `seek`,
+*   收进来等于同一个动作记两遍。
+*
+* ⚠️ **`switch_cssfullscreen` 和 `switch_css_fullscreen` 两个都要。** 上游自己就有两种拼法
+* (`cssFullScreen` 插件用前者,`keyboard` 插件用后者),**这不是笔误** ——
+* 漏掉一个的表现是「用快捷键切网页全屏收不到事件,点按钮能收到」,而那种差异没人会去查。
+*
+* ⚠️ **护栏保证不了「该进的都进了」。** `check:inventory` 能验「名单里的在上游真实存在」
+* 和「上游删了会红」,但上游**新增**一个内部动作时,这张名单不会自己长出来 ——
+* 那是静默的,已记进 ADR-075 的代价栏。
+*/
+const USER_ACTION_ALLOWLIST = [
+	"switch_play_pause",
+	"switch_fullscreen",
+	"switch_cssfullscreen",
+	"switch_css_fullscreen",
+	"change_definition",
+	"change_rate",
+	"change_volume",
+	"change_muted",
+	"change_pip",
+	"seek",
+	"rotate",
+	"shot",
+	"download",
+	"switch_danmu",
+	"error_retry"
+];
+/**
+* 用户动作(ADR-075 决策③)。来自 `Stats` 收的 `USER_ACTION`,经白名单过滤 + 归一。
+*
+* ⚠️ **可见性依赖 `controls`。** 主要发出方是 xgplayer 自己的控件插件,而本仓
+* `controls: config.controls !== false`(`create-player.ts`)。消费方传
+* `controls: false` 时绝大多数动作不再发出 —— 这是**配置相关的差异**,不是幻影。
+*/
+const UserActionPayloadSchema = zod.z.object({
+	/** 白名单里的动作名。见 {@link USER_ACTION_ALLOWLIST} */
+	action: zod.z.enum(USER_ACTION_ALLOWLIST),
+	/** 哪个插件发起的(上游 `pluginName`);取不到时为 `'player'` */
+	source: zod.z.string(),
+	/** 变化前的值。**只保留原始类型** —— 见 {@link normalizeUserAction} */
+	from: zod.z.union([
+		zod.z.string(),
+		zod.z.number(),
+		zod.z.boolean()
+	]).nullable(),
+	/** 变化后的值。同 `from` */
+	to: zod.z.union([
+		zod.z.string(),
+		zod.z.number(),
+		zod.z.boolean()
+	]).nullable()
+});
+const ALLOWED = new Set(USER_ACTION_ALLOWLIST);
+/** 只让原始类型过去。**其它一律 `null`** —— 挡的就是 DOM 对象 */
+function primitive(v) {
+	const t = typeof v;
+	return t === "string" || t === "number" || t === "boolean" ? v : null;
+}
+/**
+* 把上游 `USER_ACTION` 的原始 payload 归一成契约 payload。
+* **不在白名单里的返回 `null`**(调用方据此不发事件)。
+*
+* ─── 这个函数存在的全部理由 ───
+*
+* 上游发出来的东西长这样(`es/player.js:1449`):
+*
+* ```js
+* this.emit(USER_ACTION, { eventType, action, currentTime, duration, ended, event, ...params })
+* ```
+*
+* 那个 `event` 是**原始 DOM 事件对象**。它:
+* - 过不了 iframe 的 `structuredClone`(postMessage 直接抛 DataCloneError)
+* - 过不了 Zod
+* - 而 **inline 两条路不过这两关**,所以照搬的表现是「iframe 炸、inline 不炸」
+*
+* 所以本函数是**白名单式**的:只挑四个字段出来,其余一律丢掉。
+* 反过来写(黑名单式地 `delete raw.event`)在上游哪天多塞一个对象时会静默漏过去。
+*
+* `from` / `to` 也**不用 `z.unknown()`** —— 那等于给 DOM 对象留了一条后门。
+* 限死原始类型,拿不准的一律 `null`。
+*/
+function normalizeUserAction(raw) {
+	if (typeof raw !== "object" || raw === null) return null;
+	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;
+	return {
+		action,
+		source: typeof r.pluginName === "string" ? r.pluginName : "player",
+		from: primitive(first?.from),
+		to: primitive(first?.to)
+	};
+}
+/**
+* 把上游 `FPS_STUCK` 的原始 payload(**一个采样数组**)归一成契约 payload。
+* 空数组返回 `null`。
+*
+* 上游每个采样长这样(`es/plugins/fpsDetect/index.js`):
+* `{ currentTime, buffers, curDecodedFrames, totalVideoFrames, droppedVideoFrames, checkInterval }`。
+*
+* `buffers` 是缓冲区间明细,**不进契约** —— 那是 `bufferhealth`(ADR-071)的地盘,
+* 在这里再报一份就是第二个描述缓冲的入口。
+*/
+function normalizeFrameFreeze(raw) {
+	if (!Array.isArray(raw) || raw.length === 0) return null;
+	const samples = raw;
+	const last = samples[samples.length - 1];
+	const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : 0;
+	return {
+		durationMs: samples.reduce((sum, s) => sum + num(s.checkInterval), 0),
+		droppedFrames: num(last.droppedVideoFrames),
+		totalFrames: num(last.totalVideoFrames)
+	};
+}
+//#endregion
+//#region src/playback-context.ts
+/**
+* 播放内核 —— **实际选中的那个**,不是消费方声明的。
+*
+* 消费方传 `type: 'auto'` 时压根不知道结果:ADR-056 之后 HLS 按**能力**选
+* (有 MSE 或 MMS 就走 hls.js,两者都没有才回原生),而那台设备的 UA 和别的没区别。
+*
+* **住在契约层,由 player-core 的 `Kernel` 类型引用它**,不是各写一份 ——
+* 两份枚举描述同一件事,漂了没人查得出来(同 ADR-062 ③ 拒绝为 `kernelhealth`
+* 另起一套「重连原因」枚举的理由)。
+*/
+const PlaybackKernelSchema = zod.z.enum([
+	"native",
+	"hls.js",
+	"flv.js"
+]);
+/** 实际路由的直播语义。它来自归一化后的 source，而不是宿主上报时附带的 tag。 */
+const StreamKindSchema = zod.z.enum(["live", "vod"]);
+/** 支持矩阵使用的最小运行环境分桶；禁止加入 UA、版本或任意业务字段。 */
+const PlaybackRuntimeSchema = zod.z.object({
+	platform: zod.z.enum([
+		"ios",
+		"android",
+		"desktop",
+		"unknown"
+	]),
+	browser: zod.z.enum([
+		"webkit",
+		"gecko",
+		"chromium",
+		"embedded",
+		"unknown"
+	]),
+	mse: zod.z.enum([
+		"standard",
+		"managed",
+		"unavailable"
+	])
+});
+const SourceRouteBaseSchema = zod.z.object({
+	/** 与成功 route 后续 PlaybackContext 相同的 SDK 会话标识。 */
+	sessionId: zod.z.string(),
+	/** 本次供给的候选类型集合；不含地址。 */
+	candidateTypes: zod.z.array(SourceEntryTypeSchema).min(1),
+	streamKind: StreamKindSchema,
+	runtime: PlaybackRuntimeSchema
+});
+/** 构造前选源的事实。它与 QoE / 首帧是不同的证据链。 */
+const SourceRoutePayloadSchema = zod.z.discriminatedUnion("outcome", [SourceRouteBaseSchema.extend({
+	outcome: zod.z.literal("selected"),
+	mediaType: SourceEntryTypeSchema,
+	kernel: PlaybackKernelSchema,
+	reason: zod.z.enum([
+		"required_hls",
+		"live_preference",
+		"vod_preference",
+		"native_mp4_fallback"
+	])
+}).strict(), SourceRouteBaseSchema.extend({
+	outcome: zod.z.literal("unsupported"),
+	mediaType: zod.z.null(),
+	kernel: zod.z.null(),
+	reason: zod.z.literal("no_supported_candidate"),
+	errorCode: zod.z.literal("E_MEDIA_NOT_SUPPORTED")
+}).strict()]);
+/**
+* 播放上下文(ADR-074 · #480)。**消费方写上报适配器时,自己在 SDK 外面拿不到的那几格。**
+*
+* ─── 它补的是哪一句话 ─────────────────────────────
+*
+* `error` 的 payload 是 `{ code, message, retryable, category, cause? }` ——
+* **没有一个字段回答「出错时播到哪了 / 用的哪个内核 / 这是哪一次播放」**。
+* 消费方要补齐只有一条路:自己监听 `timeupdate` / `qualitychange` / `ready`
+* 维护一份镜像,在 `error` 到达时读出来。**那正是 ADR-043 花一整条 ADR 消灭掉的形态。**
+*
+* ─── 字段判据:消费方能不能在 SDK 外面自己拿到 ───
+*
+* 拿得到的一律不进。按这条,三个候选**当场出局**:`mode`(消费方自己 import 了哪个包)、
+* `contractVersion`(直接 `import { CONTRACT_VERSION }`)、`live`(**是消费方自己传进来的**)。
+*
+* ⚠️ **`userId` / `tags` 永久不进,且不得引用本类型当加回它们的依据。** 它们逐字命中
+* ADR-037 的判据(「纯粹的透传字段:SDK 收下来什么也不做」)。本类型和 ADR-037 删掉的
+* `telemetry` **方向相反** —— 那个是输入侧透传,这个是输出侧、只有 SDK 知道的。
+*
+* ⚠️ **不要叫它 envelope。** `envelope.ts` 是 host ↔ iframe 的消息外壳,
+* 两者在 wire 上是**里外两层**关系。
+*/
+const PlaybackContextSchema = zod.z.object({
+	/**
+	* 本次播放的 id。**由 SDK 生成,消费方不可写** —— 一旦可写,它就退回成 ADR-037
+	* 杀掉的那个纯透传字段,而这条边界是整个 ADR-074 成立的前提。
+	*
+	* `load()` 换源 = **新会话**(ADR-074 明确不决定的事之一,按此推进):CMCD 的 `cid`
+	* 跟着内容走,换了内容还共用一个 sid 会让 CDN 侧的聚合失真。
+	*/
+	sessionId: zod.z.string(),
+	/** 实际选中的内核。见 {@link PlaybackKernelSchema} */
+	kernel: PlaybackKernelSchema,
+	/**
+	* SourceRouter 实际选中的媒体类型，不从 URL pathname 推断。
+	*
+	* optional 是跨 minor 的 wire 兼容边界：旧 iframe producer 不会携带它；当前
+	* player-core 始终携带。消费方缺失时只能按 unknown 处理，不能从 URL 猜测。
+	*/
+	mediaType: SourceEntryTypeSchema.optional(),
+	/** 实际参与路由的直播/点播语义；旧 producer 缺失时按 unknown 处理。 */
+	streamKind: StreamKindSchema.optional(),
+	/** 闭集运行环境；旧 producer 缺失时按 unknown 处理。 */
+	runtime: PlaybackRuntimeSchema.optional(),
+	/**
+	* 取这个快照那一刻的播放位置(秒)。
+	*
+	* ⚠️ **它不参与 `contextchange` 的触发判据** —— 每 250ms 都在变,按值变化发
+	* 就等于复制一条 `timeupdate`。要「出错那一刻」的位置请在 `error` 回调里
+	* 同步调 `getPlaybackContext()`,不要读 `contextchange` 缓存下来的值。
+	*/
+	position: zod.z.number(),
+	/**
+	* 当前清晰度档位(= `ready.quality[].level` 的索引);单码率源或档位未知时为 `null`。
+	*
+	* `null` 不是错误态 —— MP4 / 单档 HLS 结构上就没有多个 level。
+	*/
+	qualityLevel: zod.z.number().nullable(),
+	/**
+	* 实际在播的那个候选源的 `origin`(如 `https://cdn.example.com`)。
+	*
+	* 多源时消费方**结构性拿不到**这个信息(选取规则在 SDK 内,ADR-017)。
+	*/
+	srcOrigin: zod.z.string(),
+	/**
+	* 实际在播的那个候选源的 `pathname`(如 `/live/room-42/master.m3u8`)。
+	*
+	* ⚠️ **和 `srcOrigin` 刻意分成两个字段,不合成一个字符串**:拼回去的第一件事
+	* 就是有人拿它当 URL 用,然后发现少了 query 于是「顺手补上」——
+	* 而 query 里装的正是签名凭据。分开之后,拼接这个动作必须由消费方显式做一次。
+	*/
+	srcPath: zod.z.string()
+});
+/**
+* 把源地址脱敏成 `origin` + `pathname` 两段。**query string 一个字符都不带出去。**
+*
+* 签名参数**全在 query 里**(ADR-022 认证仅用签名 URL),原样上报等于把凭据交给
+* 第三方 SaaS —— 而「短期有效」不等于「可以外发」。
+*
+* ⚠️ **脱敏发生在 SDK 内,不是「建议消费方自己脱敏」。** 后者等于先把凭据交出去
+* 再请人删掉,而且五个消费面各写一遍 = 五份会漂的副本。
+*
+* ⚠️ **不做正则。** 用 `URL` 的两个属性 —— 正则会漏 `;` 参数、`#` 片段这类形态,
+* 而漏掉的那部分正好是要挡的东西。
+*
+* 解析不了的地址(相对路径 / blob: / 空串)返回两个空串,**不抛** ——
+* 上下文是旁路信息,不该让一个奇怪的 URL 把播放搞崩。
+*/
+function redactSourceUrl(url) {
+	try {
+		const u = new URL(url);
+		return {
+			srcOrigin: u.origin,
+			srcPath: u.pathname
+		};
+	} catch {
+		return {
+			srcOrigin: "",
+			srcPath: ""
+		};
+	}
+}
+//#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",
+	"attempting",
+	"validating",
+	"recovered",
+	"failed",
+	"cancelled"
+]);
+/** SDK 实际执行的恢复策略(ADR-079)。 */
+const RecoveryStrategySchema = zod.z.enum([
+	"reconnect",
+	"media_recovery",
+	"visibility_reload"
+]);
+/** 恢复由错误、用户操作还是可见性变化触发。 */
+const RecoveryTriggerSchema = zod.z.enum([
+	"error",
+	"manual",
+	"visibility"
+]);
+const RecoveryPayloadBase = {
+	/** 同一播放器实例内递增的恢复关联号。 */
+	recoveryId: zod.z.number().int().positive(),
+	strategy: RecoveryStrategySchema,
+	trigger: RecoveryTriggerSchema,
+	/** 当前实际恢复轮次，从 1 开始。 */
+	attempt: zod.z.number().int().positive(),
+	/** 该策略允许的最大恢复轮次。 */
+	maxAttempts: zod.z.number().int().positive(),
+	/** 有错误起因时复用既有契约错误码；手动恢复可省略。 */
+	reason: ErrorCodeSchema.optional()
+};
+/**
+* 可验证恢复的单条生命周期记录(ADR-079)。
+*
+* 终态字段按 `phase` 严格区分：`recovered` 只能声明位置推进这一种验证证据；
+* `failed` / `cancelled` 只能携带各自登记的结束原因。`strict()` 刻意拒绝把终态字段
+* 混入检测或验证阶段，避免上报端把“正在验证”误读成“已经恢复”。
+*/
+const RecoveryPayloadSchema = zod.z.discriminatedUnion("phase", [
+	zod.z.object({
+		...RecoveryPayloadBase,
+		phase: zod.z.literal("detected")
+	}).strict(),
+	zod.z.object({
+		...RecoveryPayloadBase,
+		phase: zod.z.literal("attempting")
+	}).strict(),
+	zod.z.object({
+		...RecoveryPayloadBase,
+		phase: zod.z.literal("validating")
+	}).strict(),
+	zod.z.object({
+		...RecoveryPayloadBase,
+		phase: zod.z.literal("recovered"),
+		validatedBy: zod.z.literal("playing_position_advance")
+	}).strict(),
+	zod.z.object({
+		...RecoveryPayloadBase,
+		phase: zod.z.literal("failed"),
+		outcome: zod.z.enum(["timeout", "attempts_exhausted"])
+	}).strict(),
+	zod.z.object({
+		...RecoveryPayloadBase,
+		phase: zod.z.literal("cancelled"),
+		outcome: zod.z.enum([
+			"source_changed",
+			"destroyed",
+			"superseded"
+		])
+	}).strict()
+]);
+/**
+* 事件。player → host(iframe 模式),或 player-core → 消费方(inline 模式)。
+*
+* **命名:全小写连写**(`timeupdate` / `autoplayblocked`),对齐 HTML5 媒体事件。
+* 这是 wire 上的名字;消费面各自映射——Vue emit `time-update`,React prop `onTimeUpdate`。
+* (团队约定里的 `snake.case` 指的是埋点事件名如 `playback.start`,那是另一套命名空间。)
+*
+* 权威来源:docs/protocol/events.md + ARCHITECTURE.md § 8.4。
+*/
+const PlayerEventSchema = zod.z.discriminatedUnion("event", [
+	zod.z.object({
+		event: zod.z.literal("sourceroute"),
+		payload: SourceRoutePayloadSchema
+	}),
+	zod.z.object({
+		event: zod.z.literal("ready"),
+		payload: zod.z.object({
+			duration: zod.z.number(),
+			/** 可用清晰度档位;单档源(如 MP4)是空数组 */
+			quality: zod.z.array(QualityLevelSchema),
+			/**
+			* 可用字幕轨;无字幕源是空数组。
+			*
+			* **optional**:这是契约冻结(1.0.0)后给已有 `ready` payload 新增的字段(1.2.0,见 ADR-027)。
+			* 设为可选,保证 1.x 跨版本兼容——旧 producer(≤1.1.0)不发这个字段,新 consumer 当作 `[]`。
+			*/
+			subtitles: zod.z.array(SubtitleTrackInfoSchema).optional()
+		})
+	}),
+	zod.z.object({
+		event: zod.z.literal("play"),
+		payload: zod.z.object({})
+	}),
+	zod.z.object({
+		event: zod.z.literal("pause"),
+		payload: zod.z.object({})
+	}),
+	zod.z.object({
+		event: zod.z.literal("ended"),
+		payload: zod.z.object({})
+	}),
+	zod.z.object({
+		event: zod.z.literal("timeupdate"),
+		/**
+		* ~250ms 一次。
+		*
+		* **直播场景 `duration` 是 0**,不是 Infinity —— Infinity 过不了 JSON 序列化
+		* (会变成 null),而契约事件要跨 iframe 传,所以 player-core 在源头就归一成 0。
+		* 直播场景本来也不该读 duration。
+		*/
+		payload: zod.z.object({
+			time: zod.z.number(),
+			duration: zod.z.number()
+		})
+	}),
+	zod.z.object({
+		event: zod.z.literal("volumechange"),
+		payload: zod.z.object({
+			volume: zod.z.number(),
+			muted: zod.z.boolean()
+		})
+	}),
+	zod.z.object({
+		event: zod.z.literal("seeking"),
+		payload: zod.z.object({ time: zod.z.number() })
+	}),
+	zod.z.object({
+		event: zod.z.literal("seeked"),
+		payload: zod.z.object({ time: zod.z.number() })
+	}),
+	zod.z.object({
+		event: zod.z.literal("waiting"),
+		payload: zod.z.object({})
+	}),
+	zod.z.object({
+		event: zod.z.literal("playing"),
+		payload: zod.z.object({})
+	}),
+	zod.z.object({
+		event: zod.z.literal("qualitychange"),
+		payload: zod.z.object({
+			level: zod.z.number(),
+			/** true = ABR 自动切的,false = 用户手动切的 */
+			auto: zod.z.boolean()
+		})
+	}),
+	zod.z.object({
+		event: zod.z.literal("subtitlechange"),
+		payload: zod.z.object({ 
+		/** 当前激活字幕轨 id(= {@link SubtitleTrackInfo} 的 `id`);`null` = 字幕已关闭 */
+id: zod.z.number().nullable() })
+	}),
+	zod.z.object({
+		event: zod.z.literal("error"),
+		payload: PlayerErrorSchema
+	}),
+	zod.z.object({
+		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
+	}),
+	zod.z.object({
+		event: zod.z.literal("compatwarning"),
+		payload: zod.z.object({
+			code: WarningCodeSchema,
+			message: zod.z.string(),
+			/**
+			* ⚠️ 必填,**对 `W_VERSION_MISMATCH` 而言是无关信息**(host 填自己的
+			* `navigator.userAgent`)。留着必填是刻意的:改成可选对已有的 TS 消费方是
+			* breaking(`string` → `string | undefined`),不值得为此升 major。
+			* 版本不匹配真正要被聚合的两个值走下面两个专属字段。
+			* 下次契约 major 时值得把本 payload 拆成判别联合,记在 ADR-070 的开放问题里。
+			*/
+			ua: zod.z.string(),
+			/** 宿主侧契约版本。**仅 `W_VERSION_MISMATCH` 携带**(ADR-070) */
+			hostVersion: zod.z.string().optional(),
+			/** iframe 侧契约版本。**仅 `W_VERSION_MISMATCH` 携带**(ADR-070) */
+			iframeVersion: zod.z.string().optional(),
+			/**
+			* 被丢弃那条事件的名字。**仅 `W_EVENT_REJECTED` 携带**(ADR-087)。
+			*
+			* ⚠️ **类型是 `string` 而不是 `EventName`,这是刻意的** —— 它装的恰恰是
+			* **本地契约不认识的名字**(最常见的成因是 iframe 比 host 新)。
+			* 收窄成 `EventName` 就等于说「只会是我认识的那些」,而那正好是它不成立的场合。
+			* 取不到名字(连 `event` 字段都没有)时缺省。
+			*
+			* 冻结后新增字段(minor,向后兼容:旧消费方读不到它即无影响)。
+			*/
+			rejectedEvent: zod.z.string().optional()
+		})
+	}),
+	zod.z.object({
+		event: zod.z.literal("stalled"),
+		payload: zod.z.object({
+			phase: zod.z.enum(["start", "end"]),
+			/** 卡在哪个播放位置(秒) */
+			position: zod.z.number(),
+			/** phase='end' 时带上:本次卡顿时长(毫秒)。卡顿率 KPI 的核心指标 */
+			durationMs: zod.z.number().optional(),
+			/**
+			* 这次等待属于哪一类(ADR-075 决策④)。**`start` 与 `end` 带同一个值。**
+			*
+			* ⚠️ **只有 `playback` 该进卡顿率。** `firstframe` 是起播等待(它的 KPI 是首帧
+			* 时延,`firstframe` 事件在管),`seek` 是**用户自己拖进度条造成的** ——
+			* 把它算进卡顿率等于把用户的操作记成播放器的故障。三类混在一起正是 #391 说的
+			* 「只有『发生了』,没有分布」里缺的那一刀。
+			*
+			* **可选字段**:老消费方不改代码也不炸。
+			*/
+			kind: zod.z.enum([
+				"playback",
+				"firstframe",
+				"seek"
+			]).optional()
+		})
+	}),
+	zod.z.object({
+		event: zod.z.literal("playablechange"),
+		payload: zod.z.object({
+			/** 能不能正常出画面。消费方只读这一个字段就够 */
+			playable: zod.z.boolean(),
+			/** 为什么。`playable: true` 时为 `'ok'` 或 `'degraded'` */
+			reason: PlayableReasonSchema,
+			/**
+			* 是否可自愈 —— 决定消费方盖 loading(等)还是露重试入口(不等)。
+			*
+			* `buffering` / `stalled` / `reconnecting` / `initializing` 为 `true`;
+			* `error` / `autoplay_blocked` 为 `false`(要用户点一下,自己不会好)。
+			*
+			* **`frame_disconnected` 是唯一随阶段变化的一支**:iframe 正在握手时为 `true`
+			*(正常启动,该等),握手失败降级后为 `false`(连不上了,该露重试入口)。
+			* 两个阶段共用一个 reason,靠这个字段区分 —— 这正是它存在的意义。
+			*/
+			recoverable: zod.z.boolean()
+		})
+	}),
+	zod.z.object({
+		event: zod.z.literal("kernelhealth"),
+		payload: zod.z.object({
+			/**
+			* 内核是不是在挣扎。
+			*
+			* `true` = 本窗口内有诊断;`false` = 安静了一整个窗口(**收尾那一条**)。
+			*
+			* 收尾那一条是硬要求:没有它,消费方要判断「内核安静了」只能自己兜一个超时,
+			* 而「每个消费方各自兜一个超时」正是 ADR-043 花一整条 ADR 消灭的东西。
+			*/
+			degraded: zod.z.boolean(),
+			/**
+			* 成因大类。取本窗口内出现最多的那一类,并列取先出现的。
+			*
+			* 三档的划分判据是「**会不会让消费方做不同的事**」(ADR-061 ②):
+			* `network` 提示检查网络 / 降码率(能自愈的一档)、`media` 换清晰度或换设备
+			* 才可能好、`other` 只能上报。
+			*
+			* 归一复用 `error-mapping.ts` 那份类型表 —— 同一条内核错误在 `error` 和
+			* `kernelhealth` 里给出互相矛盾的分类是没人查得出来的漂移。
+			*/
+			reason: zod.z.enum([
+				"network",
+				"media",
+				"other"
+			]),
+			/** 本窗口内内核报的非致命诊断条数(`degraded: false` 时恒为 0) */
+			count: zod.z.number(),
+			/** 从本段故障的**首条**诊断到现在持续了多久(毫秒)。配合 `count` 得出速率 */
+			durationMs: zod.z.number(),
+			/**
+			* 内核原文(如 `networkError / fragLoadError`),取本窗口最近一条。
+			*
+			* ⚠️ **只给日志看,不许 `switch`。** 它跟着 hls.js 版本走,不是契约的一部分;
+			* 要分支请用 {@link reason}。
+			*/
+			detail: zod.z.string()
+		})
+	}),
+	zod.z.object({
+		event: zod.z.literal("audiohealth"),
+		payload: zod.z.object({
+			degraded: zod.z.boolean(),
+			reason: zod.z.literal("audio_data_gap"),
+			durationMs: zod.z.number()
+		})
+	}),
+	zod.z.object({
+		event: zod.z.literal("bufferhealth"),
+		payload: zod.z.object({
+			/**
+			* 余量是不是在净流失。
+			*
+			* `true` = 连续 3 次采样(1s 间隔)余量严格下降,即「每秒播掉一秒、一秒也没补上」;
+			* `false` = **收尾那一条**,余量重新涨回来了。
+			*
+			* 收尾那一条是硬要求,理由与 `kernelhealth.degraded` 逐字相同:
+			* 没有它,消费方判断「缓冲回来了」只能自己兜一个超时。
+			*/
+			draining: zod.z.boolean(),
+			/**
+			* 当前余量(秒)= `buffered.end(最后一段) - currentTime`。
+			*
+			* ⚠️ **可以是负数,那不是非法值** —— 直播里 hls.js 会把播放头往直播边缘推,
+			* 而缓冲追不上。**负号是「在追但追不上」(带宽不够)与「源头挂了」(余量停在 ~0)
+			* 之间唯一的分叉点**(ADR-068 ②)。任何把负值过滤掉的实现都会删掉这条信息。
+			*
+			* ⚠️ 不要改用「包含播放头的那一段」那个更严谨的公式 —— 实测 100 个采样点
+			* `buffered.length` 恒为 1,它没有对象;而它在播放头跑出缓冲时返回空,
+			* **正好抹掉上面那个分叉点**(ADR-071 ③)。
+			*
+			* SDK **不替消费方判定成因** —— 报符号,归因归团队层(同 ADR-062 ③)。
+			*/
+			marginSec: zod.z.number()
+		})
+	}),
+	zod.z.object({
+		event: zod.z.literal("contextchange"),
+		payload: PlaybackContextSchema
+	}),
+	zod.z.object({
+		event: zod.z.literal("firstframe"),
+		payload: FirstFramePayloadSchema
+	}),
+	zod.z.object({
+		event: zod.z.literal("framefreeze"),
+		payload: FrameFreezePayloadSchema
+	}),
+	zod.z.object({
+		event: zod.z.literal("useraction"),
+		payload: UserActionPayloadSchema
+	})
+]);
+/**
+* 把 `createPlayer` 同步抛出的错误(选源失败等)转成 error 事件。
+*
+* `SentinelError` 带 `.playerError`;其它未知错误兜底成 `E_INTERNAL`。
+*
+* **住在 protocol 而不是各消费面**:inline 和 iframe 内部都要在 `createPlayer` 的
+* try/catch 里做同一件事,此前 `packages/react/src/overlay.ts` 与
+* `apps/embed-app/src/bridge.ts` 各有一份逐字相同的副本 —— 同 `resolveLocaleMessages`
+* 当初被收回来的理由(#120 · PR C)。
+*
+* 这不是 schema 变更:没有新增 / 修改任何 Zod schema,只是把一个纯函数收到 `makePlayerError`
+* 旁边。
+*/
+/**
+* 构造一条 `W_EVENT_REJECTED` 警告(ADR-087 · #728)。
+*
+* **住在 protocol 而不是各传输层**:`frame-core`(react-frame / vue-frame 两面)和
+* `embed-helper`(静态 iframe)都要在入站事件被契约拒绝时发同一条警告,
+* 各写一份就是两份会漂的副本 —— 同 {@link toErrorEvent} 和 `PLAYER_DESTROYED_MESSAGE`
+* 当初被收回来的理由。
+*
+* 还有一条更硬的理由:`embed-helper` 里**不许出现任何硬编码事件名**
+*(`demo-matrix` 的「静态 iframe 那一列」护栏钉着)—— 那一列「事件全绿」正建立在
+* 它靠 `on<K extends EventName>` 泛型覆盖契约全集、没有任何过滤上。
+* 警告构造放这里,那边就一个事件名字面量都不需要。
+*
+* @param rejected 被丢那条事件的名字;连 `event` 字段都取不到时传 `undefined`
+* @param ua 宿主 UA。`ua` 对本警告是无关信息,但契约里它必填(ADR-070 记过这个取舍)
+*/
+function makeEventRejectedWarning(rejected, ua) {
+	return {
+		event: "compatwarning",
+		payload: {
+			code: "W_EVENT_REJECTED",
+			message: `收到一条过不了契约校验的事件(${rejected ?? "(未知)"}),已丢弃。最常见的成因是 iframe 比宿主新 —— 先看两端契约版本差多少,再怀疑 iframe 有 bug。`,
+			ua,
+			...rejected === void 0 ? {} : { rejectedEvent: rejected }
+		}
+	};
+}
+function toErrorEvent(err) {
+	return {
+		event: "error",
+		payload: typeof err === "object" && err !== null && "playerError" in err ? err.playerError : makePlayerError("E_INTERNAL", err instanceof Error ? err.message : "内部错误", err)
+	};
+}
+//#endregion
+//#region src/methods.ts
+/**
+* 命令。host → iframe(iframe 模式),或消费方 → player-core(inline 模式)。
+*
+* 权威来源:docs/protocol/methods.md + ARCHITECTURE.md § 8.5。
+* 每条命令的响应都是 `void`——结果通过事件回来,不通过 response payload。
+*/
+const CommandSchema = zod.z.discriminatedUnion("method", [
+	zod.z.object({
+		method: zod.z.literal("play"),
+		params: zod.z.object({}).optional()
+	}),
+	zod.z.object({
+		method: zod.z.literal("pause"),
+		params: zod.z.object({}).optional()
+	}),
+	zod.z.object({
+		method: zod.z.literal("seek"),
+		params: zod.z.object({
+			/** 目标时间(秒)。负数和超过 duration 的值由 player-core 钳制,不报错 */
+			time: zod.z.number(),
+			/** `keyframe` 更快但不精确;默认 `exact` */
+			type: zod.z.enum(["exact", "keyframe"]).optional()
+		})
+	}),
+	zod.z.object({
+		method: zod.z.literal("setVolume"),
+		params: zod.z.object({ volume: zod.z.number().min(0).max(1) })
+	}),
+	zod.z.object({
+		method: zod.z.literal("setMuted"),
+		params: zod.z.object({ muted: zod.z.boolean() })
+	}),
+	zod.z.object({
+		method: zod.z.literal("setPlaybackRate"),
+		params: zod.z.object({ rate: zod.z.number().min(.25).max(4) })
+	}),
+	zod.z.object({
+		method: zod.z.literal("setQuality"),
+		/** `'auto'` = 交给 ABR 自适应 */
+		params: zod.z.object({ level: zod.z.union([zod.z.number(), zod.z.literal("auto")]) })
+	}),
+	zod.z.object({
+		method: zod.z.literal("setSubtitle"),
+		/**
+		* `'off'` = 关闭字幕;数字 = 切到该 id 轨(见 `ready` payload 的 `subtitles[].id`)。见 ADR-027。
+		*
+		* 切换结果通过 `subtitlechange` 事件回来(同 setQuality → qualitychange)。
+		*/
+		params: zod.z.object({ id: zod.z.union([zod.z.number(), zod.z.literal("off")]) })
+	}),
+	zod.z.object({
+		method: zod.z.literal("setLocale"),
+		/**
+		* 运行时切换语言,**不重建播放器、不丢播放进度**。
+		*
+		* 消费方通常不直接调它 —— 各消费面 watch `locale` prop 后自动下发,
+		* 改 prop 即可切换(见 ADR-035)。
+		*
+		* 作用于两处:①播放内核自带控件的文案(**仅中 / 英**,`zh-*` → 中文,其余 → 英文);
+		* ②player-ui 覆盖层文案(读 `messages`,语言不限)。
+		* 传对象形式可同时换掉两者;传字符串只切控件语言、沿用原有 messages。
+		*/
+		params: zod.z.object({ locale: LocaleConfigSchema })
+	}),
+	zod.z.object({
+		method: zod.z.literal("load"),
+		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()
+	}),
+	zod.z.object({
+		method: zod.z.literal("pushDanmaku"),
+		/** 逐条推送(直播)。渲染归 SDK,数据源归团队层 */
+		params: zod.z.object({ item: DanmakuItemSchema })
+	}),
+	zod.z.object({
+		method: zod.z.literal("setDanmakuEnabled"),
+		/** 开关弹幕渲染(true=start / false=stop) */
+		params: zod.z.object({ enabled: zod.z.boolean() })
+	}),
+	zod.z.object({
+		method: zod.z.literal("clearDanmaku"),
+		params: zod.z.object({}).optional()
+	}),
+	zod.z.object({
+		method: zod.z.literal("destroy"),
+		params: zod.z.object({}).optional()
+	}),
+	zod.z.object({
+		method: zod.z.literal("enterFullscreen"),
+		params: zod.z.object({}).optional()
+	}),
+	zod.z.object({
+		method: zod.z.literal("exitFullscreen"),
+		params: zod.z.object({}).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`。
+*/
+const CONTRACT_VERSION = "1.0.0";
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;
+/**
+* 解析 semver 字符串。只接受严格的 `major.minor.patch`,
+* 不接受 prerelease / build metadata —— 契约版本不需要它们。
+*
+* @returns 解析结果;格式非法时返回 `null`(不 throw,调用方决定怎么降级)
+*
+* @example
+* parseVersion('1.2.3')  // { major: 1, minor: 2, patch: 3 }
+* parseVersion('v1')     // null
+*/
+function parseVersion(version) {
+	const m = SEMVER_RE.exec(version);
+	if (!m) return null;
+	return {
+		major: Number(m[1]),
+		minor: Number(m[2]),
+		patch: Number(m[3])
+	};
+}
+/**
+* 判断两侧契约版本是否兼容。host 和 iframe 必须用**同一个**规则,
+* 所以它定义在 protocol 里,而不是各自实现一遍。
+*
+* 规则(按 semver 语义):
+* - `0.x` 阶段:契约未冻结,minor 变更即为破坏性 → **minor 必须相同**
+* - `>=1.0.0`:minor 是向后兼容的新增 → **major 相同即兼容**
+* - 任一侧版本号格式非法 → 不兼容
+*
+* patch 差异永远兼容。
+*
+* @param hostVersion 宿主侧 CONTRACT_VERSION
+* @param iframeVersion iframe 侧 CONTRACT_VERSION
+*
+* @example
+* isContractCompatible('0.1.0', '0.1.3')  // true  · patch 差异
+* isContractCompatible('0.1.0', '0.2.0')  // false · 0.x 的 minor 是破坏性的
+* isContractCompatible('1.1.0', '1.4.0')  // true  · 1.x 的 minor 向后兼容
+* isContractCompatible('1.0.0', '2.0.0')  // false · major 不同
+*/
+function isContractCompatible(hostVersion, iframeVersion) {
+	const host = parseVersion(hostVersion);
+	const iframe = parseVersion(iframeVersion);
+	if (!host || !iframe) return false;
+	if (host.major !== iframe.major) return false;
+	if (host.major === 0) return host.minor === iframe.minor;
+	return true;
+}
+//#endregion
+//#region src/envelope.ts
+/** 包裹类型 */
+const EnvelopeTypeSchema = zod.z.enum([
+	"command",
+	"event",
+	"response",
+	"error"
+]);
+/**
+* 所有 host ↔ iframe 消息的公共外壳。
+*
+* `id` 用于 request-response 关联:`response` / `error` 包裹**复用**对应
+* `command` 的 id,调用方靠它把响应对上是哪条命令。`event` 是主动上抛的,
+* 它的 id 不对应任何 command。
+*/
+const envelopeShape = {
+	/** 发送方的 CONTRACT_VERSION */
+	version: zod.z.string(),
+	id: zod.z.string(),
+	/** Unix ms */
+	timestamp: zod.z.number()
+};
+/**
+* 用任意 payload schema 组一个 Envelope schema。
+*
+* `TType` 必须是**具体的**字面量类型(`'command'` 而不是 `EnvelopeType`),
+* 否则 {@link EnvelopeSchema} 在 TS 层就没法按 `type` 收窄——
+* 运行时 zod 照样能判别,但消费方写 `if (env.type === 'event')` 拿不到窄化后的 payload。
+*
+* @example
+* const MyEnvelope = createEnvelopeSchema('event', PlayerEventSchema)
+*/
+function createEnvelopeSchema(type, payload) {
+	return zod.z.object({
+		...envelopeShape,
+		type: zod.z.literal(type),
+		payload
+	});
+}
+/** 命令包裹(host → iframe) */
+const CommandEnvelopeSchema = createEnvelopeSchema("command", CommandSchema);
+/** 事件包裹(iframe → host) */
+const EventEnvelopeSchema = createEnvelopeSchema("event", PlayerEventSchema);
+/**
+* 响应包裹(iframe → host)。命令的结果一律是 void——
+* 播放状态通过事件回来,不塞在 response 里。
+*/
+const ResponseEnvelopeSchema = createEnvelopeSchema("response", zod.z.object({}));
+/** 错误包裹(iframe → host)。命令执行失败时替代 response 返回 */
+const ErrorEnvelopeSchema = createEnvelopeSchema("error", PlayerErrorSchema);
+/**
+* 任意包裹。收到消息时先用它 parse,再按 `type` 分支。
+*
+* 用 discriminatedUnion 而不是 union:错误信息能精确到具体分支,
+* 而不是把四个分支的失败原因全列一遍。
+*/
+const EnvelopeSchema = zod.z.discriminatedUnion("type", [
+	CommandEnvelopeSchema,
+	EventEnvelopeSchema,
+	ResponseEnvelopeSchema,
+	ErrorEnvelopeSchema
+]);
+/**
+* id 和 timestamp 由调用方传入,不在这里 `crypto.randomUUID()` / `Date.now()`——
+* protocol 是纯契约层,不产生副作用(见 packages/protocol/CLAUDE.md § 严禁做的)。
+* 好处是这几个函数完全可测,不用 mock 时间。
+*/
+function envelopeBase(meta) {
+	return {
+		version: meta.version ?? CONTRACT_VERSION,
+		id: meta.id,
+		timestamp: meta.timestamp
+	};
+}
+/** 构造命令包裹(host → iframe) */
+function commandEnvelope(payload, meta) {
+	return {
+		...envelopeBase(meta),
+		type: "command",
+		payload
+	};
+}
+/** 构造事件包裹(iframe → host) */
+function eventEnvelope(payload, meta) {
+	return {
+		...envelopeBase(meta),
+		type: "event",
+		payload
+	};
+}
+/** 构造响应包裹。`meta.id` 必须是对应 command 的 id */
+function responseEnvelope(meta) {
+	return {
+		...envelopeBase(meta),
+		type: "response",
+		payload: {}
+	};
+}
+/** 构造错误包裹。`meta.id` 必须是对应 command 的 id */
+function errorEnvelope(payload, meta) {
+	return {
+		...envelopeBase(meta),
+		type: "error",
+		payload
+	};
+}
+//#endregion
+//#region src/locale.ts
+/**
+* 把 `LocaleConfig` 解析成"当前 locale + 一张扁平翻译表",供覆盖层的 `useT` 直接查。
+*
+* **为什么住在 protocol**:inline 面(`@video-lab/react`)和 iframe 面
+* (`apps/embed-app`)都要做这件事,而它俩没有别的公共依赖。此前各写了一份
+* `readLocale`,两份逐字相同 —— **四种接入方式行为漂移的经典来源**。
+* 先例:`resolvePreset` 同样是住在 protocol 的纯函数。
+*
+* **回退链是逐 key 合并,不是整表取第一个存在的。** 后者会让主语种缺一个 key 就整表
+* 退化成回退语种;而漏翻译通常是零星几条,不是整表缺失。
+*
+* **缺 key 时不做任何兜底** —— 链上都没有就让**渲染侧**原样返回 key。
+*
+* ⚠️ 这里曾经写着「见 `use-t.ts`」,而那个文件在 #120 · PR D 就随
+* `I18nProvider` / `useT()` 一起删掉了(player-ui 去 React 那次)。
+* 今天做这件事的是三个消费面各自的 `resolveText`
+*(`react/src/overlay-elements.tsx` / `vue/src/overlay-elements.ts` / `embed-app/src/app.ts`),
+* 实现都是 `messages[key] ?? key`。
+* 那是刻意的设计:漏翻译时界面上明晃晃出现 `error.network`,
+* 一眼可见;而静默替换成别的语种只会把问题藏起来。
+*
+* @example
+* resolveLocaleMessages({
+*   locale: 'th-TH',
+*   fallbackLocales: ['en-US'],
+*   messages: { 'th-TH': { retry: 'ลองใหม่' }, 'en-US': { retry: 'Retry', close: 'Close' } },
+* })
+* // → { locale: 'th-TH', messages: { retry: 'ลองใหม่', close: 'Close' } }
+* //                                  ↑ 主语种赢          ↑ 主语种没有,从回退链取
+*/
+function resolveLocaleMessages(locale) {
+	if (!locale) return {
+		locale: "en-US",
+		messages: {}
+	};
+	if (typeof locale === "string") return {
+		locale,
+		messages: {}
+	};
+	const table = locale.messages;
+	if (!table) return {
+		locale: locale.locale,
+		messages: {}
+	};
+	const chain = [...locale.fallbackLocales ?? []].reverse();
+	chain.push(locale.locale);
+	const messages = {};
+	for (const tag of chain) Object.assign(messages, table[tag]);
+	return {
+		locale: locale.locale,
+		messages
+	};
+}
+//#endregion
+//#region src/presets.ts
+/**
+* 场景预设表。权威来源:ARCHITECTURE.md § 8.7.3。
+*
+* **只保留一个预设 `homepage-preview`(ADR-032)**:预设的价值在于打包一组"不平凡"的字段组合,
+* 而首页/直播预览卡片正是这样的组合(静音循环自动播 + 无控件 + 不响应点击)——高频复用、
+* 手写六个字段易错。其余场景(如房内"自动播 + 静音")字段太少,直接写 prop 即可,不配拥有预设。
+* 曾经的 `sea-mobile` / `sea-tv` / `desktop` / `internal-admin` 已删(首发前收敛,见 ADR-032)。
+*
+* 注意:§ 8.7.3 里预览预设还写了 `danmaku` / `wakeLock` / `visibility` 字段,但**刻意不进 preset 默认**
+* ——弹幕是直播按需能力,由消费方显式开(M1.1 D1 决策:档 C);`wakeLock` / `visibility` 是 P0/P1
+* 插件的内部行为,不走契约配置。故此表只保留通用播放字段。
+*/
+const PRESETS = { 
+/** 首页/直播预览卡片:静音循环自动播,无控件,不响应点击(透传给外层卡片) */
+"homepage-preview": {
+	autoplay: true,
+	muted: true,
+	loop: true,
+	controls: false,
+	interactive: false,
+	playsinline: true
+} };
+/**
+* 应用预设:预设提供默认值,消费方显式传的字段永远覆盖它。
+*
+* 只有 `undefined` 才算"没传"——`false` / `0` 都是有效的显式值,会覆盖预设。
+*
+* @param preset 预设名;`undefined` 时原样返回 config
+* @param config 消费方传入的配置(含 source)
+*
+* @example
+* resolvePreset('homepage-preview', { source: 'a.m3u8', autoplay: false })
+* // → autoplay: false(显式值赢),muted: true(来自预设)
+*/
+function resolvePreset(preset, config) {
+	if (!preset) return config;
+	const merged = { ...PRESETS[preset] };
+	for (const [key, value] of Object.entries(config)) if (value !== void 0) merged[key] = value;
+	return merged;
+}
+//#endregion
+exports.CONTRACT_VERSION = CONTRACT_VERSION;
+exports.CommandEnvelopeSchema = CommandEnvelopeSchema;
+exports.CommandSchema = CommandSchema;
+exports.DanmakuConfigSchema = DanmakuConfigSchema;
+exports.DanmakuItemSchema = DanmakuItemSchema;
+exports.ERROR_META = ERROR_META;
+exports.EnvelopeSchema = EnvelopeSchema;
+exports.EnvelopeTypeSchema = EnvelopeTypeSchema;
+exports.ErrorCategorySchema = ErrorCategorySchema;
+exports.ErrorCauseSchema = ErrorCauseSchema;
+exports.ErrorCodeSchema = ErrorCodeSchema;
+exports.ErrorEnvelopeSchema = ErrorEnvelopeSchema;
+exports.EventEnvelopeSchema = EventEnvelopeSchema;
+exports.FirstFramePayloadSchema = FirstFramePayloadSchema;
+exports.FrameFreezePayloadSchema = FrameFreezePayloadSchema;
+exports.HlsConfigSchema = HlsConfigSchema;
+exports.LocaleConfigSchema = LocaleConfigSchema;
+exports.MediaMetadataSchema = MediaMetadataSchema;
+exports.MediaSourceSchema = MediaSourceSchema;
+exports.MediaTypeSchema = MediaTypeSchema;
+exports.MultiSourceObjectSchema = MultiSourceObjectSchema;
+exports.PLAYER_DESTROYED_MESSAGE = PLAYER_DESTROYED_MESSAGE;
+exports.PRESETS = PRESETS;
+exports.PauseImageConfigSchema = PauseImageConfigSchema;
+exports.PlayableReasonSchema = PlayableReasonSchema;
+exports.PlaybackContextSchema = PlaybackContextSchema;
+exports.PlaybackKernelSchema = PlaybackKernelSchema;
+exports.PlaybackRuntimeSchema = PlaybackRuntimeSchema;
+exports.PlayerConfigSchema = PlayerConfigSchema;
+exports.PlayerErrorSchema = PlayerErrorSchema;
+exports.PlayerEventSchema = PlayerEventSchema;
+exports.PosterConfigSchema = PosterConfigSchema;
+exports.PresetNameSchema = PresetNameSchema;
+exports.QualityLevelSchema = QualityLevelSchema;
+exports.RecoveryPayloadSchema = RecoveryPayloadSchema;
+exports.ResponseEnvelopeSchema = ResponseEnvelopeSchema;
+exports.SingleSourceObjectSchema = SingleSourceObjectSchema;
+exports.SourceEntrySchema = SourceEntrySchema;
+exports.SourceEntryTypeSchema = SourceEntryTypeSchema;
+exports.SourceRoutePayloadSchema = SourceRoutePayloadSchema;
+exports.StreamKindSchema = StreamKindSchema;
+exports.SubtitleTrackInfoSchema = SubtitleTrackInfoSchema;
+exports.SubtitleTrackSchema = SubtitleTrackSchema;
+exports.USER_ACTION_ALLOWLIST = USER_ACTION_ALLOWLIST;
+exports.UserActionPayloadSchema = UserActionPayloadSchema;
+exports.WarningCodeSchema = WarningCodeSchema;
+exports.commandEnvelope = commandEnvelope;
+exports.createEnvelopeSchema = createEnvelopeSchema;
+exports.errorEnvelope = errorEnvelope;
+exports.eventEnvelope = eventEnvelope;
+exports.isContractCompatible = isContractCompatible;
+exports.makeEventRejectedWarning = makeEventRejectedWarning;
+exports.makePlayerError = makePlayerError;
+exports.normalizeFrameFreeze = normalizeFrameFreeze;
+exports.normalizeUserAction = normalizeUserAction;
+exports.parseVersion = parseVersion;
+exports.redactSourceUrl = redactSourceUrl;
+exports.resolveLocaleMessages = resolveLocaleMessages;
+exports.resolvePreset = resolvePreset;
+exports.responseEnvelope = responseEnvelope;
+exports.serializeCause = serializeCause;
+exports.toErrorEvent = toErrorEvent;