@video-lab/protocol 3.1.0 → 4.0.1

package/dist/index.mjs

@@ -24,18 +24,17 @@ const PosterConfigSchema = z.union([z.string(), z.object({
 	]).default("cover").optional()
 })]);
 /**
-* 暂停时盖在画面中央的静态图(ADR-043 / issue #121)。
+* 暂停时盖在画面中央的静态图(ADR-043 / ADR-126)。
 *
 * 形状**刻意与 {@link PosterConfigSchema} 对齐**(同为 `string | { url, fit, … }`),
 * 消费方不用学两套。
 *
-* **渲染在 iframe 内,与封面相反** —— 封面为了抢首帧挪到了宿主侧,暂停图不抢首帧
-*(暂停发生时 iframe 早已 ready),放宿主侧反而让静态 iframe 那条路拿不到,撞 cross-mode-parity。
+* 默认图片在 iframe 内渲染；静态 iframe 由此也能使用。框架组件传入自定义
+* render / slot 时由宿主 DOM 渲染，iframe 配置省略本字段(ADR-127)。
 *
-* **边界(ADR-025 已判的那条线)**:静态图 + 可选关闭按钮进 SDK —— 可序列化、无调度逻辑,
+* **边界(ADR-025 已判的那条线)**:静态图与继续播放按钮进 SDK —— 可序列化、无调度逻辑,
 * 与 `poster` 同性质;**带倒计时 / 跳转 / 推荐列表的不进** —— 那是业务调度,归团队层。
-* inline 模式另有 `<sentinel-pause>` 的默认 slot(能塞任意节点),表达力更强但
-* 过不了 postMessage,所以三条 iframe 路只有本字段有效。
+* 四个框架组件另有具名自定义视觉入口；函数和节点不进入本协议。
 */
 const PauseImageConfigSchema = z.union([z.string(), z.object({
 	url: z.string(),
@@ -51,10 +50,13 @@ const PauseImageConfigSchema = z.union([z.string(), z.object({
 		"cover",
 		"contain",
 		"fill"
-	]).optional(),
-	/** 给图加一个关闭按钮,用户点了本次播放不再显示。默认 `false` */
-	closable: z.boolean().optional()
-})]);
+	]).optional()
+}).strict()]);
+/** 默认错误层动作按钮的配色；跨 iframe 边界传递字面 CSS 颜色值。 */
+const ErrorButtonColorsSchema = z.object({
+	background: z.string().min(1).optional(),
+	foreground: z.string().min(1).optional()
+});
 /** 字幕轨 */
 const SubtitleTrackSchema = z.discriminatedUnion("mode", [z.object({
 	mode: z.literal("url"),
@@ -157,7 +159,7 @@ const SingleSourceObjectSchema = z.object({
 /**
 * 多源对象。直播 FLV + HLS 双路兜底的标准形态。
 *
-* ⚠️ FLV 单源在 iOS / 微信 / UC / 夸克 下必然抛 `E_MEDIA_NOT_SUPPORTED`,
+* ⚠️ 当前 SDK 收到 FLV 单源且运行在 iOS / 微信 / UC / 夸克时会抛 `E_MEDIA_NOT_SUPPORTED`,
 * **FLV 永远和 HLS 一起放进 sources 数组**。
 */
 const MultiSourceObjectSchema = z.object({
@@ -168,9 +170,9 @@ const MultiSourceObjectSchema = z.object({
 * 媒体源。三种写法:URL 字符串(最简)、单源对象、多源对象。
 *
 * **这是 wire schema——只含可 JSON 序列化的字段**。
-* ⛔ **`source.onBeforeRequest` 已废弃(ADR-057),下个 major 删除** ——
-* 它不在这里、也不在任何 Schema 里,而且 player-core 里从来没有消费点(#332)。
-* 认证走签名 URL + 长有效期(ADR-022)。见 {@link SourceRequestHook}。
+* ⛔ **`source.onBeforeRequest` 与其类型已在 4.0.0 移除(ADR-057)** ——
+* 它从来不在任何 Schema 里,player-core 里也没有消费点(#332)。
+* 认证走签名 URL + 长有效期(ADR-022)。
 */
 const MediaSourceSchema = z.union([
 	z.string(),
@@ -182,18 +184,18 @@ const LocaleConfigSchema = z.union([z.string(), z.object({
 	locale: z.string(),
 	fallbackLocales: z.array(z.string()).optional(),
 	/**
-	* 翻译表。**SDK 不内置任何翻译,只提供注入机制** —— 覆盖层文案
-	*(loading / error.* / retry / close)全部由消费方从这里传入。
+	* 翻译表。覆盖层内置中 / 英默认文案，消费方可从这里逐 key 覆盖
+	*(loading / loading.<reason> / play / error.* / retry / reconnect)。
 	* 消费面用 `resolveLocaleMessages` 把它解析成扁平表,再把解析好的**字符串**
-	* 传给覆盖层元素;缺 key 时原样返回 key(可见失败,不抛错)。
+	* 传给覆盖层元素；标准覆盖层缺 key 时使用中 / 英默认值。
 	*
 	* **两个命名空间,同一张表**:
-	* - 覆盖层:`loading` / `retry` / `close` / `error.<CODE>` —— **无内置翻译**
+	* - 覆盖层:`loading.*` / `play` / `retry` / `reconnect` / `error.<CODE>` —— 内置中 / 英
 	* - 播放内核自带控件:`controls.*` —— 内置中 / 英,你传的会**覆盖**(#208 / ADR-051)
 	*
-	* 语言标签本身仍只有中 / 英两档(`zh-*` → 中文,其余 → 英文,见 player-core 的 `toXgLang`),
-	* 但**那不再限制能翻成什么语言**:传 `locale:'vi-VN'` + `messages['vi-VN']['controls.play']`,
-	* 控件就是越南语 —— 标签落在 `en` 那一档,而那一档的文案被换掉了。
+	* xgplayer 的内部槽位只有中 / 英两档(`zh-CN` → 中文,其他 → 英文,见 player-core 的 `toXgLang`),
+	* 但显示语言不限于这两种：`vi-VN` 可使用官方语言包，第三语言的控件文案写入
+	* 当前实例的英文槽位，不污染其他播放器。
 	* `controls.*` 的 key 全集见 USER-GUIDE § 9.4;**表外的静默忽略**。
 	*
 	* ⚠️ 这段从前写着「控件不读 messages」—— 那是 #208 修掉的现状,别照着旧描述下结论。
@@ -201,7 +203,7 @@ const LocaleConfigSchema = z.union([z.string(), z.object({
 	messages: z.record(z.string(), z.record(z.string(), z.string())).optional()
 })]);
 /**
-* 弹幕单条(streaming push 用)。见 ADR-028 / ARCHITECTURE § 8.3.7。
+* 弹幕单条(streaming push 用)。长期取舍见 ADR-028。
 *
 * 直播场景:业务从自己的数据源(WebSocket / 轮询,SDK 不参与)拿到一条,
 * 经 `pushDanmaku` 命令喂进来,到点即显(不绑视频时间)。
@@ -238,7 +240,7 @@ const DanmakuItemSchema = z.object({
 	start: z.number().nonnegative().optional()
 });
 /**
-* 弹幕配置(PlayerConfig.danmaku,默认关闭)。见 ADR-028 / ARCHITECTURE § 8.3.7。
+* 弹幕配置(PlayerConfig.danmaku,默认关闭)。长期取舍见 ADR-028。
 *
 * **两种模式**:`streaming`(直播,`pushDanmaku` 逐条)/ `preload`(点播,挂载时整包给,
 * 引擎按每条的 `start` 排期,见 #275)。ADR-028 当初只做 streaming,preload 是它说的「后续 minor」。
@@ -300,7 +302,7 @@ const DanmakuConfigSchema = z.object({
 *
 * 定义在这里而不是 presets.ts,是为了让 PlayerConfig 能引用它而不产生循环依赖。
 */
-const PresetNameSchema = z.enum(["homepage-preview"]);
+const PresetNameSchema = z.enum(["ambient-preview"]);
 /** 内置控制栏的初始化显示策略。false 隐藏入口；true/省略仍遵守平台能力。 */
 const ControlVisibilityConfigSchema = z.object({
 	play: z.boolean().optional(),
@@ -369,8 +371,12 @@ const PlayerConfigSchema = z.object({
 	controls: z.boolean().optional(),
 	/** 初始化时是否显示默认错误覆盖层。默认开启；关闭不影响错误事件和恢复。 */
 	showErrorOverlay: z.boolean().optional(),
-	/** 运行时 Loading 展示归属；false 仅隐藏视觉/ARIA，恢复仍由 SDK 执行。 */
-	showLoadingOverlay: z.boolean().optional(),
+	/** 是否显示 SDK 默认运行时 Loading；false 仅隐藏内置视觉/ARIA，不影响状态事件和恢复。 */
+	showDefaultLoadingOverlay: z.boolean().optional(),
+	/** 在 SDK 默认 Loading 转圈下显示当前状态文案；默认 false，随默认 Loading 一起隐藏。 */
+	showLoadingText: z.boolean().optional(),
+	/** 默认错误动作按钮配色；不改变状态判断或动作。 */
+	errorButtonColors: ErrorButtonColorsSchema.optional(),
 	/** 独立隐藏内置控件；只在创建时生效，修改后由宿主显式重建。 */
 	controlVisibility: ControlVisibilityConfigSchema.optional(),
 	/** 是否响应用户交互。首页预览卡片用 false,点击透传给外层卡片 */
@@ -398,6 +404,26 @@ const PlayerConfigSchema = z.object({
 	debug: z.boolean().optional()
 });
 //#endregion
+//#region src/delivery.ts
+/**
+* 一次播放器事件的生产端投递证据。
+*
+* `sequence` 只在同一个 `producerSessionId` 内严格递增；`deliveryId` 也只承诺在
+* 该会话内唯一。`occurredAtMs` 是生产端的墙钟，不是宿主接收时间，不能跨设备相减。
+* 消费者可用 `(producerSessionId, sequence)` 排序、用
+* `(producerSessionId, deliveryId)` 去重，并拒绝旧会话的迟到事件。
+*/
+const PlayerEventDeliverySchema = z.object({
+	/** 每次 player/frame producer 生命周期唯一的会话标识。 */
+	producerSessionId: z.string().min(1),
+	/** 在该 producer session 内唯一且重传时保持稳定的投递标识。 */
+	deliveryId: z.string().min(1),
+	/** 生产端创建该事件时读取的 Unix ms 墙钟。 */
+	occurredAtMs: z.number().finite(),
+	/** 在该 producer session 内从 1 开始严格递增的序号。 */
+	sequence: z.number().int().positive()
+});
+//#endregion
 //#region src/errors.ts
 /**
 * 错误分类。player-core 把 xgplayer 的内部错误映射到这几类,
@@ -413,7 +439,7 @@ const ErrorCategorySchema = z.enum([
 ]);
 /**
 * 全部错误码。命名规则 `E_<CATEGORY>_<SPECIFIC>`。
-* 权威来源:ARCHITECTURE.md § 8.6。
+* 权威来源：本文件；人类可读说明见 docs/protocol/errors.md。
 *
 * **每一个码都必须有真实发射点**(ADR-034)。`player-core/tests/contract-coverage.test.ts`
 * 静态扫描全仓库生产代码强制这条 —— 加码不加实现,测试直接红。
@@ -565,6 +591,19 @@ const ErrorCauseSchema = z.object({
 ]));
 /** `String(x)` 的截断上限 —— cause 是旁路信息,不该把 envelope 撑大 */
 const CAUSE_MESSAGE_MAX = 500;
+/** 匹配字符串里出现的 http(s) URL,用于把 query/fragment 剥掉,只留 origin+pathname */
+const URL_PATTERN = /https?:\/\/\S+/g;
+/** 剥掉字符串里每个 URL 的 query 串和 fragment —— 签名 token 常年住在 query 里 */
+function stripUrlQuery(value) {
+	return value.replace(URL_PATTERN, (match) => {
+		const cut = match.search(/[?#]/);
+		return cut === -1 ? match : match.slice(0, cut);
+	});
+}
+/** 对可能非字符串的值套用 {@link stripUrlQuery};非字符串原样返回 */
+function stripUrlQueryIfString(value) {
+	return typeof value === "string" ? stripUrlQuery(value) : value;
+}
 function readNumber(source, key) {
 	const v = source[key];
 	return typeof v === "number" && Number.isFinite(v) ? v : void 0;
@@ -586,20 +625,21 @@ function readNumber(source, key) {
 function serializeCause(cause) {
 	if (cause === null || typeof cause !== "object") return {
 		name: "Unknown",
-		message: String(cause).slice(0, CAUSE_MESSAGE_MAX)
+		message: stripUrlQuery(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 name = stripUrlQueryIfString(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;
+	for (const [k, v] of Object.entries(obj)) if (typeof v === "string") extras[k] = stripUrlQuery(v);
+	else if (typeof v === "number" || typeof v === "boolean") extras[k] = v;
 	return {
 		...extras,
 		name,
-		message: rawMessage.slice(0, CAUSE_MESSAGE_MAX),
+		message: stripUrlQuery(rawMessage).slice(0, CAUSE_MESSAGE_MAX),
 		...code === void 0 ? {} : { code },
 		...status === void 0 ? {} : { status }
 	};
@@ -637,7 +677,7 @@ function makePlayerError(code, message, cause) {
 	const meta = ERROR_META[code];
 	return {
 		code,
-		message,
+		message: stripUrlQuery(message),
 		category: meta.category,
 		retryable: meta.retryable,
 		...cause === void 0 ? {} : { cause: serializeCause(cause) }
@@ -800,8 +840,9 @@ 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];
-	const change = typeof first === "string" ? r : typeof first === "object" && first !== null ? first : null;
+	const rawProps = r.props;
+	const first = (Array.isArray(rawProps) ? rawProps : [])[0];
+	const change = typeof first === "string" ? r : typeof first === "object" && first !== null ? first : rawProps === void 0 && typeof r.prop === "string" ? r : null;
 	return {
 		action,
 		source: typeof r.pluginName === "string" ? r.pluginName : "player",
@@ -1058,7 +1099,11 @@ z.enum([
 	"failed",
 	"cancelled"
 ]);
-/** 策略变化共享 episode，不创建新的预算。 */
+/**
+* 策略变化共享 episode，不创建新的预算。
+* 报的是该次动作**实际执行**的动作：请求时的意图若这一次做不到（如非 hls.js 内核无法做
+* 媒体修复），按实际动作上报（ADR-109）。
+*/
 const RecoveryStrategySchema = z.enum([
 	"reconnect",
 	"media_recovery",
@@ -1070,7 +1115,8 @@ const RecoveryTriggerSchema = z.enum([
 	"manual",
 	"visibility",
 	"stall",
-	"startup_timeout"
+	"startup_timeout",
+	"ended"
 ]);
 const base = {
 	sessionId: z.string().min(1),
@@ -1131,6 +1177,50 @@ const RecoveryPayloadSchema = z.discriminatedUnion("phase", [
 	path: ["attempt"]
 });
 //#endregion
+//#region src/source-switch.ts
+/**
+* 自动授权换源的低频事务事实；只放可安全聚合的闭集枚举与数值。
+*
+* @platform static-iframe unsupported：静态 URL 无法传入 `ResolveSource` 函数，
+* 因而不产生本事务；宿主应在 `error(E_AUTH_EXPIRED)` 后替换整个 iframe。
+*/
+const SourceSwitchPayloadSchema = z.discriminatedUnion("phase", [
+	z.object({
+		phase: z.literal("started"),
+		switchId: z.number().int().positive(),
+		trigger: z.literal("auth_expired"),
+		httpStatus: z.union([z.literal(401), z.literal(403)]).optional()
+	}).strict(),
+	z.object({
+		phase: z.literal("succeeded"),
+		switchId: z.number().int().positive(),
+		strategy: z.enum(["hot_load", "rebuild"]),
+		elapsedMs: z.number().nonnegative()
+	}).strict(),
+	z.object({
+		phase: z.literal("failed"),
+		switchId: z.number().int().positive(),
+		reason: z.enum([
+			"resolver_null",
+			"resolver_rejected",
+			"load_rejected",
+			"replacement_error"
+		]),
+		elapsedMs: z.number().nonnegative(),
+		errorCode: ErrorCodeSchema.optional()
+	}).strict(),
+	z.object({
+		phase: z.literal("cancelled"),
+		switchId: z.number().int().positive(),
+		reason: z.enum([
+			"external_source",
+			"destroyed",
+			"unmounted"
+		]),
+		elapsedMs: z.number().nonnegative()
+	}).strict()
+]);
+//#endregion
 //#region src/events.ts
 /**
 * 清晰度档位。`level` 是索引,传给 `setQuality` 命令用。
@@ -1159,7 +1249,7 @@ const SubtitleTrackInfoSchema = z.object({
 * 「现在能不能正常出画面」的原因枚举({@link PlayerEventSchema} 的 `playablechange`)。
 *
 * 优先级(高的压低的,同时命中时报最严重的那个):
-* `error` > `frame_disconnected` > `autoplay_blocked` > `reconnecting` > `stalled`
+* `error` > `frame_disconnected` > `autoplay_blocked` > `source_switching` > `reconnecting` > `stalled`
 * > `buffering` > `initializing` > `degraded` > `ok`
 *
 * **命名**:枚举值用 `snake_case`,与事件名(全小写连写)是两套命名空间 ——
@@ -1172,6 +1262,7 @@ const PlayableReasonSchema = z.enum([
 	"buffering",
 	"stalled",
 	"reconnecting",
+	"source_switching",
 	"autoplay_blocked",
 	"error",
 	"frame_disconnected",
@@ -1184,18 +1275,22 @@ const PlayableReasonSchema = z.enum([
 * 这是 wire 上的名字;消费面各自映射——Vue emit `time-update`,React prop `onTimeUpdate`。
 * (团队约定里的 `snake.case` 指的是埋点事件名如 `playback.start`,那是另一套命名空间。)
 *
-* 权威来源:docs/protocol/events.md + ARCHITECTURE.md § 8.4。
+* 权威来源：本 Zod schema；docs/protocol/events.md 是人类可读说明。
 */
+const eventObject = (shape) => z.object({
+	...shape,
+	delivery: PlayerEventDeliverySchema.optional()
+});
 const PlayerEventSchema = z.discriminatedUnion("event", [
-	z.object({
+	eventObject({
 		event: z.literal("pagefullscreenchange"),
 		payload: PageFullscreenStateSchema
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("sourceroute"),
 		payload: SourceRoutePayloadSchema
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("ready"),
 		payload: z.object({
 			duration: z.number(),
@@ -1210,19 +1305,19 @@ const PlayerEventSchema = z.discriminatedUnion("event", [
 			subtitles: z.array(SubtitleTrackInfoSchema).optional()
 		})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("play"),
 		payload: z.object({})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("pause"),
 		payload: z.object({})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("ended"),
 		payload: z.object({})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("timeupdate"),
 		/**
 		* ~250ms 一次。
@@ -1236,30 +1331,30 @@ const PlayerEventSchema = z.discriminatedUnion("event", [
 			duration: z.number()
 		})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("volumechange"),
 		payload: z.object({
 			volume: z.number(),
 			muted: z.boolean()
 		})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("seeking"),
 		payload: z.object({ time: z.number() })
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("seeked"),
 		payload: z.object({ time: z.number() })
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("waiting"),
 		payload: z.object({})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("playing"),
 		payload: z.object({})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("qualitychange"),
 		payload: z.object({
 			level: z.number(),
@@ -1267,25 +1362,29 @@ const PlayerEventSchema = z.discriminatedUnion("event", [
 			auto: z.boolean()
 		})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("subtitlechange"),
 		payload: z.object({ 
 		/** 当前激活字幕轨 id(= {@link SubtitleTrackInfo} 的 `id`);`null` = 字幕已关闭 */
 id: z.number().nullable() })
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("error"),
 		payload: PlayerErrorSchema
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("autoplayblocked"),
 		payload: z.object({})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("recovery"),
 		payload: RecoveryPayloadSchema
 	}),
-	z.object({
+	eventObject({
+		event: z.literal("sourceswitch"),
+		payload: SourceSwitchPayloadSchema
+	}),
+	eventObject({
 		event: z.literal("compatwarning"),
 		payload: z.object({
 			code: WarningCodeSchema,
@@ -1315,7 +1414,7 @@ id: z.number().nullable() })
 			rejectedEvent: z.string().optional()
 		})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("stalled"),
 		payload: z.object({
 			phase: z.enum(["start", "end"]),
@@ -1340,7 +1439,7 @@ id: z.number().nullable() })
 			]).optional()
 		})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("playablechange"),
 		payload: z.object({
 			/** 能不能正常出画面。消费方只读这一个字段就够 */
@@ -1368,7 +1467,7 @@ id: z.number().nullable() })
 			]).optional()
 		})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("kernelhealth"),
 		payload: z.object({
 			/**
@@ -1408,7 +1507,7 @@ id: z.number().nullable() })
 			detail: z.string()
 		})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("audiohealth"),
 		payload: z.object({
 			degraded: z.boolean(),
@@ -1416,7 +1515,7 @@ id: z.number().nullable() })
 			durationMs: z.number()
 		})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("bufferhealth"),
 		payload: z.object({
 			/**
@@ -1445,19 +1544,19 @@ id: z.number().nullable() })
 			marginSec: z.number()
 		})
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("contextchange"),
 		payload: PlaybackContextSchema
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("firstframe"),
 		payload: FirstFramePayloadSchema
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("framefreeze"),
 		payload: FrameFreezePayloadSchema
 	}),
-	z.object({
+	eventObject({
 		event: z.literal("useraction"),
 		payload: UserActionPayloadSchema
 	})
@@ -1509,33 +1608,11 @@ function toErrorEvent(err) {
 	};
 }
 //#endregion
-//#region src/delivery.ts
-/**
-* 一次已送达播放器事件的生产端证据。
-*
-* `sequence` 只在同一个 `producerSessionId` 内严格递增；`deliveryId` 也只承诺在
-* 该会话内唯一。`occurredAtMs` 是生产端的墙钟，不是宿主接收时间，不能跨设备相减。
-* 消费者可用 `(producerSessionId, sequence)` 排序、用
-* `(producerSessionId, deliveryId)` 去重，并拒绝旧会话的迟到事件。
-*/
-const DeliveredPlayerEventSchema = z.object({
-	/** 未变形的公开业务事件；旧 raw 出口继续单独交付它。 */
-	event: PlayerEventSchema,
-	/** 每次 player/frame producer 生命周期唯一的会话标识。 */
-	producerSessionId: z.string().min(1),
-	/** 在该 producer session 内唯一且重传时保持稳定的投递标识。 */
-	deliveryId: z.string().min(1),
-	/** 生产端创建该事件时读取的 Unix ms 墙钟。 */
-	occurredAtMs: z.number().finite(),
-	/** 在该 producer session 内从 1 开始严格递增的序号。 */
-	sequence: z.number().int().positive()
-});
-//#endregion
 //#region src/methods.ts
 /**
 * 命令。host → iframe(iframe 模式),或消费方 → player-core(inline 模式)。
 *
-* 权威来源:docs/protocol/methods.md + ARCHITECTURE.md § 8.5。
+* 权威来源：本 Zod schema；docs/protocol/methods.md 是人类可读说明。
 * 每条命令的响应都是 `void`——结果通过事件回来,不通过 response payload。
 */
 const CommandSchema = z.discriminatedUnion("method", [
@@ -1590,9 +1667,9 @@ const CommandSchema = z.discriminatedUnion("method", [
 		* 消费方通常不直接调它 —— 各消费面 watch `locale` prop 后自动下发,
 		* 改 prop 即可切换(见 ADR-035)。
 		*
-		* 作用于两处:①播放内核自带控件的文案(**仅中 / 英**,`zh-*` → 中文,其余 → 英文);
-		* ②player-ui 覆盖层文案(读 `messages`,语言不限)。
-		* 传对象形式可同时换掉两者;传字符串只切控件语言、沿用原有 messages。
+		* 作用于两处:①播放内核自带控件的文案(官方中 / 英或注入的第三语言);
+		* ②player-ui 覆盖层文案(解析官方资源及 `messages`)。
+		* 传字符串可选内置语言；第三语言需传带资源表的对象。
 		*/
 		params: z.object({ locale: LocaleConfigSchema })
 	}),
@@ -1638,7 +1715,7 @@ const CommandSchema = z.discriminatedUnion("method", [
 * 唯一来源是 contract-version.json（ADR-094）；只在真实协议变化时升级。
 * npm 包版本同步不能改变握手与 envelope 的版本。
 */
-const CONTRACT_VERSION = "2.0.0";
+const CONTRACT_VERSION = "4.0.0";
 const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;
 /**
 * 解析 semver 字符串。只接受严格的 `major.minor.patch`,
@@ -1812,77 +1889,249 @@ function errorEnvelope(payload, meta) {
 	};
 }
 //#endregion
-//#region src/locale.ts
+//#region src/error-action.ts
+/** 只接受终态、错误码与组件能力都支持的动作；旧生产者缺 action 时不猜测。 */
+function effectiveErrorAction(input) {
+	const { reason, recoverable, action, errorCode } = input;
+	if (recoverable || !action || action === "none") return "none";
+	if (reason === "autoplay_blocked") return action === "play" && errorCode === "E_AUTOPLAY_BLOCKED" ? "play" : "none";
+	if (reason === "frame_disconnected") return action === "recreate-frame" && input.canRecreateFrame && (errorCode === "E_LOAD_FAILED" || errorCode === "E_HANDSHAKE_TIMEOUT" || errorCode === "E_FRAME_CRASHED") ? "recreate-frame" : "none";
+	if (reason !== "error") return "none";
+	if (action === "replace-source") return errorCode === "E_AUTH_EXPIRED" && input.canResolveSource ? action : "none";
+	if (action === "retry") return errorCode === "E_NETWORK" || errorCode === "E_NETWORK_TIMEOUT" || errorCode === "E_MEDIA_DECODE" || errorCode === "E_MEDIA_ABORTED" ? action : "none";
+	return "none";
+}
+/** 有效动作对应的官方文案 key；网络重连与媒体重试保留不同动词。 */
+function errorActionMessageKey(action, errorCode) {
+	switch (action) {
+		case "play": return "play";
+		case "retry": return errorCode === "E_NETWORK" || errorCode === "E_NETWORK_TIMEOUT" ? "reconnect" : "retry";
+		case "replace-source": return "refreshSource";
+		case "recreate-frame": return "recreatePlayer";
+		default: return null;
+	}
+}
+//#endregion
+//#region src/error-copy.ts
 /**
-* 把 `LocaleConfig` 解析成"当前 locale + 一张扁平翻译表",供覆盖层的 `useT` 直接查。
+* 错误码 → 面向终端用户的英文兜底文案（#116）。另有简体中文表。
 *
-* **为什么住在 protocol**:inline 面(`@video-lab/react`)和 iframe 面
-* (`apps/embed-app`)都要做这件事,而它俩没有别的公共依赖。此前各写了一份
-* `readLocale`,两份逐字相同 —— **四种接入方式行为漂移的经典来源**。
-* 先例:`resolvePreset` 同样是住在 protocol 的纯函数。
+* ## 为什么要有它——这是对「SDK 不自带文案」的一处例外
 *
-* **回退链是逐 key 合并,不是整表取第一个存在的。** 后者会让主语种缺一个 key 就整表
-* 退化成回退语种;而漏翻译通常是零星几条,不是整表缺失。
+* `locale.ts` 立的规矩是「缺 key 就原样露出 key」，理由是漏翻译要一眼可见。那条规矩对
+* 普通 UI 文案成立：露出 `retry` 只是难看。**错误文案不一样**：覆盖层原本回退到
+* `PlayerError.message`，而那个 message 是内核串——实测 403 鉴权失败时，屏幕上显示的是
+* `内核错误:networkError / levelLoadError`：错误码明明是 `E_AUTH_EXPIRED`、category 是
+* `auth`，给用户看的字却在说「网络错误」，还把 hls.js 的内部 `ErrorDetails` 抛给了终端用户。
+* 露 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`,
-* 一眼可见;而静默替换成别的语种只会把问题藏起来。
+* SDK 内置简体中文和英文，其他语言以及品牌语气由宿主通过 `locale.messages` 提供。
 *
-* @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' } }
-* //                                  ↑ 主语种赢          ↑ 主语种没有,从回退链取
+* ## 宿主怎么覆盖
+*
+* 在 `locale.messages` 里提供 `error.<CODE>`（如 `error.E_AUTH_EXPIRED`）即可，优先级高于
+* 本表。四个消费包的 README 有完整 key 清单。
+*
+* ## 写作口径（改文案时照这三条审）
+*
+* 1. **不出现内核术语**（`networkError` / `levelLoadError` / `MediaError` 这类）；
+* 2. **不误导用户去做错的事**——鉴权失效不能说成网络问题；
+* 3. **给得出下一步**，或至少说明这次能不能重试（与 `ERROR_META.retryable` 一致）。
+*/
+const DEFAULT_ERROR_MESSAGES_EN = {
+	E_NETWORK: "Network problem. Check your connection and try again.",
+	E_NETWORK_TIMEOUT: "The connection timed out. Check your network and try again.",
+	E_LOAD_FAILED: "Could not load the video. Check your connection and try again.",
+	E_HANDSHAKE_TIMEOUT: "The player took too long to start. Try again.",
+	E_AUTH_EXPIRED: "Your access to this video has expired. Reload the page to continue.",
+	E_MEDIA_DECODE: "The video could not be decoded. Try again.",
+	E_MEDIA_ABORTED: "Playback was interrupted. Try again.",
+	E_MEDIA_NOT_SUPPORTED: "This video format cannot be played here.",
+	E_MANIFEST_PARSE: "The video could not be read. Try again later.",
+	E_SUBTITLE_LOAD_FAILED: "Subtitles could not be loaded. Playback continues without them.",
+	E_AUTOPLAY_BLOCKED: "Tap play to start the video.",
+	E_ENV_CSP_BLOCKED: "This page blocked the player from loading.",
+	E_METHOD_NOT_SUPPORTED: "This action is not available here.",
+	E_DANMAKU_SEND_FAILED: "Your message could not be sent. Try again.",
+	E_PLAYER_DESTROYED: "The player is no longer available. Reload the page.",
+	E_FRAME_CRASHED: "The player stopped unexpectedly. Reload the page.",
+	E_HANDSHAKE_VERSION_MISMATCH: "The player version does not match. Reload the page.",
+	E_INTERNAL: "Something went wrong in the player. Reload the page.",
+	E_UNKNOWN: "Playback ran into a problem. Try again later."
+};
+/** 简体中文默认错误提示；其他语言可通过 `locale.messages` 覆盖。 */
+const DEFAULT_ERROR_MESSAGES_ZH = {
+	E_NETWORK: "网络连接异常，请检查网络后重试。",
+	E_NETWORK_TIMEOUT: "连接超时，请检查网络后重试。",
+	E_LOAD_FAILED: "视频加载失败，请检查网络后重试。",
+	E_HANDSHAKE_TIMEOUT: "播放器连接超时，请重试。",
+	E_AUTH_EXPIRED: "播放地址已失效，请获取新的播放地址。",
+	E_MEDIA_DECODE: "视频解码失败，请重试播放。",
+	E_MEDIA_ABORTED: "播放已中断，请重试。",
+	E_MEDIA_NOT_SUPPORTED: "当前设备无法播放此视频格式。",
+	E_MANIFEST_PARSE: "视频内容无法读取，请稍后再试或更换播放源。",
+	E_SUBTITLE_LOAD_FAILED: "字幕加载失败，视频仍可继续播放。",
+	E_AUTOPLAY_BLOCKED: "请点击播放以继续。",
+	E_ENV_CSP_BLOCKED: "当前页面阻止了播放器加载。",
+	E_METHOD_NOT_SUPPORTED: "当前无法执行此操作。",
+	E_DANMAKU_SEND_FAILED: "弹幕发送失败，请重试。",
+	E_PLAYER_DESTROYED: "播放器已关闭，请重新打开。",
+	E_FRAME_CRASHED: "播放器连接已断开，请重新打开播放器。",
+	E_HANDSHAKE_VERSION_MISMATCH: "播放器版本不匹配，请刷新页面。",
+	E_INTERNAL: "播放器发生异常，请刷新页面。",
+	E_UNKNOWN: "播放遇到问题，请稍后再试。"
+};
+/**
+* 解析错误文案:宿主翻译 → 当前语言的中 / 英兜底。
+*
+* **不再回退到 `PlayerError.message`** —— 那是内核串,给用户看会误导(见本文件头注释)。
+* 排查需要的原始信息仍在 `PlayerError.cause` 里(`errorType` / `errorDetails` / `status`)。
+*
+* `onFallback` 供消费面在开发构建里提示宿主「这个码你没配翻译」,保住 `locale.ts`
+* 「漏翻译要一眼可见」的原意,又不让线上用户吃这个亏。
 */
+function resolveErrorMessage(messages, code, onFallback, locale = "zh-CN") {
+	const key = `error.${code}`;
+	const translated = messages[key];
+	if (typeof translated === "string" && translated.length > 0) return translated;
+	onFallback?.(key);
+	const defaults = /^en(?:[-_]|$)/i.test(locale) ? DEFAULT_ERROR_MESSAGES_EN : DEFAULT_ERROR_MESSAGES_ZH;
+	return defaults[code] ?? defaults[fallbackCodeFor(code)];
+}
+/** 未知码按 `E_UNKNOWN` 兜底;已知码但没写文案(理论上不会发生)按同类兜底 */
+function fallbackCodeFor(code) {
+	const meta = ERROR_META[code];
+	if (meta === void 0) return "E_UNKNOWN";
+	return meta.category === "network" ? "E_NETWORK" : "E_UNKNOWN";
+}
+//#endregion
+//#region src/official-messages.ts
+const enOverlay = {
+	loading: "Loading…",
+	"loading.initializing": "Starting player…",
+	"loading.buffering": "Buffering…",
+	"loading.stalled": "Restoring playback…",
+	"loading.reconnecting": "Reconnecting…",
+	"loading.source_switching": "Switching video source…",
+	"loading.frame_disconnected": "Connecting to player…",
+	play: "Play video",
+	retry: "Retry playback",
+	reconnect: "Reconnect",
+	refreshSource: "Get a new playback URL",
+	recreatePlayer: "Reconnect player"
+};
+const zhOverlay = {
+	loading: "加载中…",
+	"loading.initializing": "正在初始化播放器…",
+	"loading.buffering": "正在缓冲…",
+	"loading.stalled": "正在恢复播放…",
+	"loading.reconnecting": "正在重新连接…",
+	"loading.source_switching": "正在换源…",
+	"loading.frame_disconnected": "正在连接播放器…",
+	play: "播放视频",
+	retry: "重试播放",
+	reconnect: "重新连接",
+	refreshSource: "重新获取播放地址",
+	recreatePlayer: "重新连接播放器"
+};
+const enControls = {
+	"controls.play": "Play",
+	"controls.pause": "Pause",
+	"controls.replay": "Replay",
+	"controls.fullscreen.enter": "Fullscreen",
+	"controls.fullscreen.exit": "Exit fullscreen",
+	"controls.pageFullscreen.enter": "CSS fullscreen",
+	"controls.pageFullscreen.exit": "Exit CSS fullscreen",
+	"controls.pip": "Picture in picture",
+	"controls.subtitle": "Captions",
+	"controls.subtitle.off": "Off",
+	"controls.live": "Live",
+	"controls.rotate": "Rotate"
+};
+const zhControls = {
+	"controls.play": "播放",
+	"controls.pause": "暂停",
+	"controls.replay": "重播",
+	"controls.fullscreen.enter": "进入全屏",
+	"controls.fullscreen.exit": "退出全屏",
+	"controls.pageFullscreen.enter": "进入样式全屏",
+	"controls.pageFullscreen.exit": "退出样式全屏",
+	"controls.pip": "画中画",
+	"controls.subtitle": "字幕",
+	"controls.subtitle.off": "关闭",
+	"controls.live": "直播",
+	"controls.rotate": "旋转"
+};
+const errorEntries = (table) => Object.fromEntries(Object.entries(table).map(([code, message]) => [`error.${code}`, message]));
+/** 播放器内置的完整简体中文文案，也是官方资源 key 清单的来源。 */
+const zhCN = {
+	...zhOverlay,
+	...errorEntries(DEFAULT_ERROR_MESSAGES_ZH),
+	...zhControls
+};
+/** 播放器内置的完整英文文案。 */
+const enUS = {
+	...enOverlay,
+	...errorEntries(DEFAULT_ERROR_MESSAGES_EN),
+	...enControls
+};
+/** 官方资源必须覆盖的播放器自有文案 key。 */
+const PLAYER_MESSAGE_KEYS = Object.keys(zhCN);
+/** 只归一官方标签及其别名；未知地区变体保留原样。 */
+function normalizeLocaleTag(tag) {
+	const normalized = tag.replaceAll("_", "-").toLowerCase();
+	if (normalized === "zh" || normalized === "zh-cn") return "zh-CN";
+	if (normalized === "en" || normalized === "en-us") return "en-US";
+	if (normalized === "vi" || normalized === "vi-vn") return "vi-VN";
+	return tag;
+}
+/** protocol 不依赖按需语言包；越南语由宿主注入。 */
+function builtInMessages(tag) {
+	const normalized = normalizeLocaleTag(tag);
+	if (normalized === "zh-CN") return zhCN;
+	if (normalized === "en-US") return enUS;
+}
+//#endregion
+//#region src/locale.ts
+/** 覆盖层文案：有效资源表 → 旧版通用 loading → 官方中文。 */
+function resolveOverlayMessage(messages, key, locale = "zh-CN") {
+	if (messages[key]) return messages[key];
+	if (key.startsWith("loading.") && messages.loading) return messages.loading;
+	return builtInMessages(locale)?.[key] ?? zhCN[key] ?? key;
+}
+/** 按当前语言、显式回退链、官方中文的优先级逐 key 合成实例快照。 */
 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]);
+	const tag = normalizeLocaleTag((typeof locale === "string" ? locale : locale?.locale) || "zh-CN");
+	const fallbackLocales = typeof locale === "object" ? locale.fallbackLocales ?? [] : [];
+	const custom = typeof locale === "object" ? locale.messages : void 0;
+	const tables = /* @__PURE__ */ new Map();
+	for (const [key, value] of Object.entries(custom ?? {})) tables.set(normalizeLocaleTag(key), value);
+	const messages = Object.create(null);
+	const chain = [
+		"zh-CN",
+		...fallbackLocales.map(normalizeLocaleTag).reverse(),
+		tag
+	].filter((value, index, entries) => entries.lastIndexOf(value) === index);
+	for (const current of chain) {
+		Object.assign(messages, builtInMessages(current));
+		const entries = tables.get(current);
+		if (!entries) continue;
+		const genericLoading = entries.loading;
+		if (genericLoading) {
+			for (const key of Object.keys(zhCN)) if (key.startsWith("loading.") && !entries[key]) messages[key] = genericLoading;
+		}
+		for (const [key, value] of Object.entries(entries)) if (value) messages[key] = value;
+	}
 	return {
-		locale: locale.locale,
+		locale: tag,
 		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": {
+/** 环境式预览:静音循环自动播,无控件,不响应点击(透传给外层容器) */
+"ambient-preview": {
 	autoplay: true,
 	muted: true,
 	loop: true,
@@ -1899,7 +2148,7 @@ const PRESETS = {
 * @param config 消费方传入的配置(含 source)
 *
 * @example
-* resolvePreset('homepage-preview', { source: 'a.m3u8', autoplay: false })
+* resolvePreset('ambient-preview', { source: 'a.m3u8', autoplay: false })
 * // → autoplay: false(显式值赢),muted: true(来自预设)
 */
 function resolvePreset(preset, config) {
@@ -1909,6 +2158,63 @@ function resolvePreset(preset, config) {
 	return merged;
 }
 //#endregion
-export { CONTRACT_VERSION, CommandEnvelopeSchema, CommandSchema, ControlVisibilityConfigSchema, DanmakuConfigSchema, DanmakuItemSchema, DeliveredPlayerEventSchema, ERROR_META, EnvelopeSchema, EnvelopeTypeSchema, ErrorCategorySchema, ErrorCauseSchema, ErrorCodeSchema, ErrorEnvelopeSchema, EventEnvelopeSchema, FirstFramePayloadSchema, FrameFreezePayloadSchema, HlsConfigSchema, LocaleConfigSchema, MediaMetadataSchema, MediaSourceSchema, MediaTypeSchema, MultiSourceObjectSchema, PLAYER_DESTROYED_MESSAGE, PRESETS, PageFullscreenControlSchema, PageFullscreenMessageSchema, PageFullscreenStateSchema, PauseImageConfigSchema, PlayableReasonSchema, PlaybackContextSchema, PlaybackKernelSchema, PlaybackRuntimeSchema, PlayerConfigSchema, PlayerErrorSchema, PlayerEventSchema, PosterConfigSchema, PresetNameSchema, QualityLevelSchema, RecoveryPayloadSchema, ResponseEnvelopeSchema, SingleSourceObjectSchema, SourceEntrySchema, SourceEntryTypeSchema, SourceRoutePayloadSchema, StreamKindSchema, SubtitleTrackInfoSchema, SubtitleTrackSchema, USER_ACTION_ALLOWLIST, UserActionPayloadSchema, WarningCodeSchema, commandEnvelope, createEnvelopeSchema, errorEnvelope, eventEnvelope, isContractCompatible, makeEventRejectedWarning, makePlayerError, normalizeFrameFreeze, normalizeUserAction, parseVersion, redactSourceUrl, resolveLocaleMessages, resolvePreset, responseEnvelope, serializeCause, toErrorEvent };
+//#region src/provider-config.ts
+function mergeFrameDefaults(parent = {}, child = {}) {
+	const merged = { ...parent };
+	for (const [key, value] of Object.entries(child)) if (value !== void 0) merged[key] = value;
+	return merged;
+}
+const OBJECT_FIELDS = ["errorButtonColors", "controlVisibility"];
+/** 父子 Provider 合成；只有两种配置对象按子字段继承。 */
+function mergePlayerDefaults(parent = {}, child = {}) {
+	const merged = { ...parent };
+	for (const [key, value] of Object.entries(child)) {
+		if (value === void 0) continue;
+		if (OBJECT_FIELDS.includes(key)) merged[key] = {
+			...parent[key],
+			...value
+		};
+		else merged[key] = value;
+	}
+	return merged;
+}
+/** 实例显式值 > 实例 preset > Provider；保留 null 供组件隐藏图片。 */
+function applyPlayerDefaults(instance, defaults = {}) {
+	const preset = instance.preset ? PRESETS[instance.preset] : void 0;
+	const result = { ...defaults };
+	for (const [key, value] of Object.entries(preset ?? {})) if (value !== void 0) result[key] = value;
+	for (const [key, value] of Object.entries(instance)) {
+		if (value === void 0) continue;
+		if (OBJECT_FIELDS.includes(key)) result[key] = {
+			...defaults[key],
+			...value
+		};
+		else result[key] = value;
+	}
+	return result;
+}
+/** 资源按语言和 key 合并，避免内层只覆写一条时丢掉外层其余翻译。 */
+function mergeMessageResources(parent = {}, child = {}) {
+	const merged = Object.create(null);
+	for (const [tag, messages] of [...Object.entries(parent), ...Object.entries(child)]) {
+		const normalized = normalizeLocaleTag(tag);
+		merged[normalized] = {
+			...merged[normalized],
+			...messages
+		};
+	}
+	return merged;
+}
+/** 按 #125 的优先级把 Provider 与单实例资源交给现有 locale 解析器。 */
+function applyProviderLocale(instance, providerLocale, resources = {}, overrides = {}, fallbackLocales = []) {
+	const instanceConfig = typeof instance === "string" ? { locale: instance } : instance;
+	const messages = mergeMessageResources(mergeMessageResources(resources, overrides), instanceConfig?.messages);
+	return {
+		locale: instanceConfig?.locale ?? providerLocale,
+		fallbackLocales: instanceConfig?.fallbackLocales ?? fallbackLocales,
+		messages
+	};
+}
+//#endregion
+export { CONTRACT_VERSION, CommandEnvelopeSchema, CommandSchema, ControlVisibilityConfigSchema, DEFAULT_ERROR_MESSAGES_EN, DEFAULT_ERROR_MESSAGES_ZH, DanmakuConfigSchema, DanmakuItemSchema, ERROR_META, EnvelopeSchema, EnvelopeTypeSchema, ErrorButtonColorsSchema, ErrorCategorySchema, ErrorCauseSchema, ErrorCodeSchema, ErrorEnvelopeSchema, EventEnvelopeSchema, FirstFramePayloadSchema, FrameFreezePayloadSchema, HlsConfigSchema, LocaleConfigSchema, MediaMetadataSchema, MediaSourceSchema, MediaTypeSchema, MultiSourceObjectSchema, PLAYER_DESTROYED_MESSAGE, PLAYER_MESSAGE_KEYS, PRESETS, PageFullscreenControlSchema, PageFullscreenMessageSchema, PageFullscreenStateSchema, PauseImageConfigSchema, PlayableReasonSchema, PlaybackContextSchema, PlaybackKernelSchema, PlaybackRuntimeSchema, PlayerConfigSchema, PlayerErrorSchema, PlayerEventDeliverySchema, PlayerEventSchema, PosterConfigSchema, PresetNameSchema, QualityLevelSchema, RecoveryPayloadSchema, ResponseEnvelopeSchema, SingleSourceObjectSchema, SourceEntrySchema, SourceEntryTypeSchema, SourceRoutePayloadSchema, SourceSwitchPayloadSchema, StreamKindSchema, SubtitleTrackInfoSchema, SubtitleTrackSchema, USER_ACTION_ALLOWLIST, UserActionPayloadSchema, WarningCodeSchema, applyPlayerDefaults, applyProviderLocale, commandEnvelope, createEnvelopeSchema, effectiveErrorAction, enUS, errorActionMessageKey, errorEnvelope, eventEnvelope, isContractCompatible, makeEventRejectedWarning, makePlayerError, mergeFrameDefaults, mergeMessageResources, mergePlayerDefaults, normalizeFrameFreeze, normalizeLocaleTag, normalizeUserAction, parseVersion, redactSourceUrl, resolveErrorMessage, resolveLocaleMessages, resolveOverlayMessage, resolvePreset, responseEnvelope, serializeCause, toErrorEvent, zhCN };
 
-//# sourceMappingURL=index.mjs.map