@video-lab/react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Video Lab Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @video-lab/react
+
+Video Lab Player 的 **React inline 消费面(L7)**。直连 player-core + player-ui,不走 iframe,首帧最快。
+
+对外只有一个组件 `<VideoPlayer />` + 一个命令句柄。见 ADR-001。
+
+## 什么时候用它
+
+| 场景 | 选这个包 |
+|:---|:---|
+| 追求首帧速度、宿主同为 React | ✅ 本包 |
+| 需要和宿主页面样式/状态深度联动 | ✅ 本包 |
+| 要把播放器和宿主隔离(第三方内容、CSS 冲突) | ❌ 用 [`@video-lab/react-frame`](https://www.npmjs.com/package/@video-lab/react-frame) |
+| 宿主是 Vue | ❌ 用 [`@video-lab/vue`](https://www.npmjs.com/package/@video-lab/vue)(inline,本包的镜像)或 [`@video-lab/vue-frame`](https://www.npmjs.com/package/@video-lab/vue-frame)(iframe) |
+
+## 安装
+
+```bash
+pnpm add @video-lab/react
+```
+
+peer:`react >=19`、`react-dom >=19`。React 18 不支持当前 custom element 覆盖层所需的 property / CustomEvent 绑定；仍在 React 18 的项目请停在上一个 major。
+
+## 用法
+
+```tsx
+import { VideoPlayer, type VideoPlayerHandle } from '@video-lab/react'
+// 别漏 —— 少了它播放器照样能播,但控件是散的。引擎样式和覆盖层样式都拼在这一份里,
+// 不需要另外装 xgplayer
+import '@video-lab/react/style.css'
+import { useRef } from 'react'
+
+function Player() {
+  const ref = useRef<VideoPlayerHandle>(null)
+
+  return (
+    <VideoPlayer
+      ref={ref}
+      source="https://cdn.example.com/live/master.m3u8"
+      autoplay
+      muted
+      onReady={({ duration, quality, subtitles }) => {
+        // quality / subtitles 是可切档位与字幕轨清单,团队层据此渲染菜单
+      }}
+      onError={(err) => {
+        // err.code 是 protocol 注册的 E_* 错误码,err.retryable 指示是否可重试
+      }}
+    />
+  )
+}
+```
+
+命令走句柄,不走 props:
+
+<!-- doc-snippet-preamble
+import type { VideoPlayerHandle } from '@video-lab/react'
+declare const ref: { current: VideoPlayerHandle | null }
+-->
+```tsx
+await ref.current?.play()
+ref.current?.seek(30)
+ref.current?.setQuality('auto')
+ref.current?.setSubtitle(1)       // id 来自 onReady 的 subtitles[]
+await ref.current?.enterFullscreen()
+```
+
+## 边界
+
+- **只做技术**——播放能力、事件、命令、容错。品牌 UI(结束覆盖层、清晰度菜单、皮肤)归团队封装层,不在本包(ADR-021)
+- **props 面刻意和 `react-frame` 对齐**(去掉 iframe 专属的 `origin` / `version`),团队封装层在 inline / iframe 间切换成本最低(cross-mode-parity 测试保障)
+- **认证只支持签名 URL**,不接受自定义请求头(ADR-022)
+- `getPlayerHandle()` 是逃生舱,返回底层 player-core 句柄,给需要绕过 React 直接下命令的高级场景
+
+## 相关
+
+- 完整 props / 事件 / 句柄清单:[USER-GUIDE](https://mgit.lgroup.co/hqdf/web/x9-live-player/blob/main/docs/guides/USER-GUIDE.md)
+- 契约定义:[`@video-lab/protocol`](https://www.npmjs.com/package/@video-lab/protocol)
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,447 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let react = require("react");
+let _video_lab_player_ui = require("@video-lab/player-ui");
+let _video_lab_protocol = require("@video-lab/protocol");
+let _video_lab_player_core = require("@video-lab/player-core");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/overlay.ts
+/**
+* 从 LocaleConfig 里取翻译表。实现住在 protocol —— iframe 面要做同样的事,
+* 此前两边各有一份逐字相同的副本,是四面行为漂移的经典来源。
+*/
+const readLocale = _video_lab_protocol.resolveLocaleMessages;
+//#endregion
+//#region src/overlay-elements.tsx
+/**
+* `createElement` 要求 tag 是 `keyof JSX.IntrinsicElements`,而 `@types/react@19`
+* **仍然不认识** custom element(实测:`Property 'sentinel-poster' does not exist on type
+* 'JSX.IntrinsicElements'`)。
+*
+* **不做全局 JSX 命名空间增补** —— 那会污染所有消费方的类型环境,库不该干这事
+* (对照:media-chrome 也不增补,它另外发一套 `/react` 包装)。
+* 逃逸收敛在这一行,外面全是有类型的。
+*/
+const createOverlayElement = react.createElement;
+/**
+* 渲染一个覆盖层元素。
+*
+* 这不是"包装组件",只是一个带类型的 `createElement` 调用 + 一次幂等注册 ——
+* React 19 之后没有别的事要做了。
+*/
+function overlayElement(tag, props) {
+	(0, _video_lab_player_ui.defineSentinelOverlays)();
+	const { children, ...rest } = props;
+	return createOverlayElement(tag, rest, children);
+}
+/**
+* 取文案。**语义和原 `useT()` 逐字一致:key 找不到就返回 key 本身。**
+*
+* 不 throw 也不返回空串 —— 漏翻译时界面上会明晃晃出现 `error.E_NETWORK` 这种字样,一眼能发现;
+* throw 会白屏,空串是静默失败,最难排查。
+*
+* i18n 解析在 PR B 里上移到了这一层(spec § 技术方案 ②):元素只收解析好的字符串,
+* 于是 player-ui 不再需要任何状态注入机制。
+*/
+function resolveText(messages, key) {
+	return messages[key] ?? key;
+}
+//#endregion
+//#region src/use-player.ts
+/**
+* 管理 player-core 的整个生命周期,并把播放器事件同时喂给覆盖层状态机和 React 回调 props。
+*
+* 和 react-frame 的 `useFrameConnection` 结构对齐,差别在于 inline 直连 player-core:
+* - `createPlayer` 是**同步**的(不像 `createPlayerFrame` 返回 Promise),但会**同步抛错**
+*   (选源失败,比如 iOS 只给了 FLV)——必须 try/catch 转成 error 覆盖层 + onError。
+* - 覆盖层(Poster / Loading / Error)由本包渲染,所以事件要先更新 overlay 再转发回调
+*   (iframe 系的覆盖层在 embed-app 内,薄壳不管)。
+*
+* **事件桥接关键**:onEvent 闭包只在挂载时建一次,但要调**最新**回调 props——用 `propsRef`
+* 存最新 props,`forward` 从 `propsRef.current` 取,而不是闭包里捕获的旧值。
+* SSR 安全:`createPlayer` 只在 useEffect(客户端)里跑。
+*/
+function usePlayer(props) {
+	const containerRef = (0, react.useRef)(null);
+	const handleRef = (0, react.useRef)(null);
+	const [overlay, setOverlay] = (0, react.useState)(_video_lab_player_ui.INITIAL_OVERLAY);
+	const [mounted, setMounted] = (0, react.useState)(false);
+	const [rebuildKey, setRebuildKey] = (0, react.useState)(0);
+	const propsRef = (0, react.useRef)(props);
+	propsRef.current = props;
+	/**
+	* 三条 prop effect 的 skip-first-run 标志位。
+	*
+	* **必须在 build effect 的 cleanup 里复位**(#720):StrictMode dev 下 React 对整棵子树
+	* 做 setup → cleanup → setup,而这三个 ref **此前没有任何复位点**。第二遍 setup 时
+	* build effect 先重建出一个新 player,紧接着这三条 effect 看到标志位已是 `true`,
+	* 于是对一个**刚建好、config 里已带同样值**的播放器再下发一次
+	* `load()` / `setMuted()` / `setLocale()`。
+	*
+	* 后果不只是「画面闪、缓冲白扔」—— `load()` 成功会开**新 session**(ADR-074),
+	* dev 下每次挂载都在遥测里多出一段幽灵会话,`contextchange` 的 `sessionId` 对不上。
+	*
+	* ⚠️ **Vue 无此形态**(`watch` 默认不 immediate),**react-frame 也免疫**
+	* (`createPlayerFrame` 异步,第二遍 setup 时句柄仍是 null)。
+	* inline 因为 `createPlayer` 是**同步**的才需要这三个标志位,也因此才有这个洞。
+	*/
+	const sourceInited = (0, react.useRef)(false);
+	const mutedInited = (0, react.useRef)(false);
+	const localeInited = (0, react.useRef)(false);
+	/**
+	* 错误出口。**建 player 失败(同步抛)和换源失败(异步 reject)必须走同一条路**:
+	* 错误覆盖层 + `onError`。分成两条会出现"换源失败时组件毫无反应"的静默失败。
+	*
+	* ⚠️ **必须走 `forward()`,不能直接调 `onError`。** 这里曾经是
+	* `propsRef.current.onError?.(payload)` —— 于是这条 error **进不了 `onPlayerEvent`**,
+	* 而两个 iframe 面的同一条失败路径走的就是 `forward(...)`(见
+	* `react-frame/src/use-frame-connection.ts` 的 `.catch(err => forward(...))`)。
+	*
+	* 后果是 parity 破口:消费方按 ADR-080 接 `onPlayerEvent` 做遥测时,
+	* **iframe 两面收得到这条 error,inline 两面一条都收不到** —— 而 `types.ts` 对那个 prop
+	* 的原话是「完整的契约事件流,供遥测适配器使用;不裁剪 payload」。
+	*
+	* 命中的两条真实路径:`createPlayer` 同步抛(iOS 只给 FLV)、ADR-083 的构造期签名拒绝。
+	*/
+	const reportError = (0, react.useCallback)((err) => {
+		const errorEvent = (0, _video_lab_protocol.toErrorEvent)(err);
+		setOverlay((prev) => (0, _video_lab_player_ui.reduceOverlay)(prev, errorEvent));
+		forward(errorEvent, propsRef.current);
+	}, []);
+	/**
+	* **prop 驱动**的命令统一出口(ADR-067 · #416)。
+	*
+	* 只多做一件事:句柄**已销毁**就报错、不下发 —— 因为 `create-player.ts` 里
+	* 每个命令开头的 `if (destroyed) return` 会让它**静默空转**。那个 `return` 是对的
+	*(坑 #3:destroy 之后不许再有事件出去),错的是上一层从来不说话:实测消费方
+	* 调完 `destroy()` 再改 `source`,inline 面 **0 条事件**,而 iframe 面报了一条。
+	*
+	* ⚠️ **句柄为 `null` 时静默是对的**,别顺手也报 —— `null` 意味着「还没建成 / 已卸载」,
+	* 不是「被拆了」(ADR-066 事实 ③:卸载先 `destroy()` 再置 `null`)。
+	*
+	* ⚠️ **三条 prop effect 都要走它**,别只管 `load`。只 gate 一条会造出新的 parity 差异:
+	* `setMuted` 在 iframe 有声、在 inline 静默 —— 用一个洞换另一个洞。
+	*/
+	const dispatch = (0, react.useCallback)((run) => {
+		const handle = handleRef.current;
+		if (!handle) return;
+		if (handle.destroyed) {
+			reportError({ playerError: (0, _video_lab_protocol.makePlayerError)("E_PLAYER_DESTROYED", _video_lab_protocol.PLAYER_DESTROYED_MESSAGE) });
+			return;
+		}
+		run(handle);
+	}, [reportError]);
+	(0, react.useEffect)(() => {
+		const container = containerRef.current;
+		if (!container) return;
+		const p = propsRef.current;
+		setOverlay(_video_lab_player_ui.INITIAL_OVERLAY);
+		try {
+			handleRef.current = (0, _video_lab_player_core.createPlayer)({
+				el: container,
+				config: toConfig(p),
+				onEvent: (event) => {
+					setOverlay((prev) => (0, _video_lab_player_ui.reduceOverlay)(prev, event));
+					forward(event, propsRef.current);
+				}
+			});
+			setMounted(true);
+		} catch (err) {
+			reportError(err);
+		}
+		return () => {
+			handleRef.current?.destroy();
+			handleRef.current = null;
+			setMounted(false);
+			sourceInited.current = false;
+			mutedInited.current = false;
+			localeInited.current = false;
+		};
+	}, [rebuildKey]);
+	(0, react.useEffect)(() => {
+		if (!sourceInited.current) {
+			sourceInited.current = true;
+			return;
+		}
+		setOverlay(_video_lab_player_ui.resetOverlayForNewSource);
+		dispatch((handle) => {
+			handle.load(props.source).catch(reportError);
+		});
+	}, [
+		JSON.stringify(props.source),
+		reportError,
+		dispatch
+	]);
+	(0, react.useEffect)(() => {
+		if (!mutedInited.current) {
+			mutedInited.current = true;
+			return;
+		}
+		const muted = props.muted;
+		if (muted !== void 0) dispatch((handle) => handle.setMuted(muted));
+	}, [props.muted, dispatch]);
+	(0, react.useEffect)(() => {
+		if (!localeInited.current) {
+			localeInited.current = true;
+			return;
+		}
+		const locale = props.locale;
+		if (locale !== void 0) dispatch((handle) => handle.setLocale(locale));
+	}, [props.locale, dispatch]);
+	return {
+		containerRef,
+		handleRef,
+		overlay,
+		mounted,
+		handleRetry: (0, react.useCallback)(() => {
+			setRebuildKey((k) => k + 1);
+		}, []),
+		dismissPauseImage: (0, react.useCallback)(() => {
+			setOverlay((prev) => ({
+				...prev,
+				pauseImageVisible: false,
+				pauseImageDismissed: true
+			}));
+		}, [])
+	};
+}
+/**
+* props → PlayerConfig。只带"显式传了的"字段;undefined 交给 player-core 走 preset / xgplayer 默认
+*(resolvePreset 的语义就是 undefined = 没传)。source 直接进 config(createPlayer 的 config 含 source)。
+*/
+function toConfig(props) {
+	const config = { source: props.source };
+	if (props.preset !== void 0) config.preset = props.preset;
+	if (props.autoplay !== void 0) config.autoplay = props.autoplay;
+	if (props.muted !== void 0) config.muted = props.muted;
+	if (props.loop !== void 0) config.loop = props.loop;
+	if (props.playsinline !== void 0) config.playsinline = props.playsinline;
+	if (props.playbackRate !== void 0) config.playbackRate = props.playbackRate;
+	if (props.volume !== void 0) config.volume = props.volume;
+	if (props.startTime !== void 0) config.startTime = props.startTime;
+	if (props.preload !== void 0) config.preload = props.preload;
+	if (props.controls !== void 0) config.controls = props.controls;
+	if (props.interactive !== void 0) config.interactive = props.interactive;
+	if (props.poster !== void 0) config.poster = props.poster;
+	if (props.pauseImage !== void 0) config.pauseImage = props.pauseImage;
+	if (props.locale !== void 0) config.locale = props.locale;
+	if (props.danmaku !== void 0) config.danmaku = props.danmaku;
+	if (props.debug !== void 0) config.debug = props.debug;
+	return config;
+}
+/**
+* 播放器事件 → React 回调。名字从 wire 上的小写换成 `onCamelCase`。
+* 和 react-frame / vue-frame 的 forward 一一对应(cross-mode-parity):同样的事件、同样的 payload。
+*
+* **契约声明的 19 个事件必须一个不少地出现在这里**,由 `protocol/tests/consumer-surface.contract.test.ts`
+* 静态断言。曾经漏过 4 个(seeking / seeked / waiting / playing):前两个有注释说
+* 「团队封装层没用到,需要时再加」,后两个连注释都没有 —— 被 `default: break` 静默吞掉。
+* 而静态 iframe 模式(embed-app 裸广播,无过滤)19 个全发,于是同一份契约在四种接入方式
+* 下能收到的事件不一样,parity 红线实际已破。别再以"业务暂时用不到"为由少接一个。
+*/
+function forward(event, props) {
+	try {
+		props.onPlayerEvent?.(event);
+	} catch {}
+	switch (event.event) {
+		case "ready":
+			props.onReady?.(event.payload);
+			break;
+		case "play":
+			props.onPlay?.();
+			break;
+		case "pause":
+			props.onPause?.();
+			break;
+		case "ended":
+			props.onEnded?.();
+			break;
+		case "timeupdate":
+			props.onTimeUpdate?.(event.payload);
+			break;
+		case "volumechange":
+			props.onVolumeChange?.(event.payload);
+			break;
+		case "seeking":
+			props.onSeeking?.(event.payload);
+			break;
+		case "seeked":
+			props.onSeeked?.(event.payload);
+			break;
+		case "waiting":
+			props.onWaiting?.();
+			break;
+		case "playing":
+			props.onPlaying?.();
+			break;
+		case "qualitychange":
+			props.onQualityChange?.(event.payload);
+			break;
+		case "subtitlechange":
+			props.onSubtitleChange?.(event.payload);
+			break;
+		case "error":
+			props.onError?.(event.payload);
+			break;
+		case "autoplayblocked":
+			props.onAutoplayBlocked?.();
+			break;
+		case "reconnectstart":
+			props.onReconnectStart?.({
+				attempt: event.payload.attempt,
+				maxAttempts: event.payload.maxAttempts
+			});
+			break;
+		case "reconnectsuccess":
+			props.onReconnectSuccess?.();
+			break;
+		case "reconnectfailed":
+			props.onReconnectFailed?.();
+			break;
+		case "compatwarning":
+			props.onCompatWarning?.(event.payload);
+			break;
+		case "stalled":
+			props.onStalled?.(event.payload);
+			break;
+		case "playablechange":
+			props.onPlayableChange?.(event.payload);
+			break;
+		case "bufferhealth":
+			props.onBufferHealth?.(event.payload);
+			break;
+		case "contextchange":
+			props.onContextChange?.(event.payload);
+			break;
+		case "sourceroute":
+			props.onSourceRoute?.(event.payload);
+			break;
+		case "firstframe":
+			props.onFirstFrame?.(event.payload);
+			break;
+		case "framefreeze":
+			props.onFrameFreeze?.(event.payload);
+			break;
+		case "useraction":
+			props.onUserAction?.(event.payload);
+			break;
+		case "kernelhealth":
+			props.onKernelHealth?.(event.payload);
+			break;
+		case "audiohealth":
+			props.onAudioHealth?.(event.payload);
+			break;
+		case "recovery": break;
+		default: break;
+	}
+}
+//#endregion
+//#region src/VideoPlayer.tsx
+/**
+* VideoPlayer · React inline 高性能模式(SDK 消费面之一)
+*
+* 直连 player-core + player-ui,不走 iframe——首帧最快(~200ms),数据路径和 iframe 系不同。
+*
+* **覆盖层用 player-ui 的 `<sentinel-*>` custom elements**(#120 · R1 · PR B),不再是 React 组件。
+* 消费方 API 一个都没变 —— props / 事件 / 句柄全部原样。变的只有两件内部事:
+* ① i18n 解析上移到这一层(元素只收解析好的字符串,player-ui 不再需要状态注入机制);
+* ② 覆盖层的样式钩子从全局 class 变成 shadow DOM 的 `::part()`(见 USER-GUIDE)。
+* 只做技术:组装播放器、把 props 桥接成命令、把事件桥接成 `onXxx` 回调、渲染 SDK 自带的
+* Poster / Loading / Error 覆盖层。不含任何团队品牌 UI(ADR-021)——那些在业务封装层。
+* props / 事件面和 react-frame 对齐(cross-mode-parity)。
+*
+* 【关于默认值】刻意不给 autoplay / muted / loop / controls / playsinline / interactive
+* 设默认值:这些字段同时受 preset 控制,一旦在这里强塞就变成"显式值"把 preset 覆盖掉
+*(resolvePreset 的语义是 undefined 才回落到 preset)。没传的 prop 保持 undefined。
+*
+* @example
+* const ref = useRef<VideoPlayerHandle>(null)
+* <VideoPlayer ref={ref} source="https://cdn/a.m3u8" muted onReady={...} />
+* ref.current?.play()
+*/
+const VideoPlayer = (0, react.forwardRef)(function VideoPlayer(props, ref) {
+	const { containerRef, handleRef, overlay, mounted, handleRetry, dismissPauseImage } = usePlayer(props);
+	(0, react.useImperativeHandle)(ref, () => ({
+		play: () => handleRef.current?.play() ?? Promise.resolve(),
+		pause: () => handleRef.current?.pause(),
+		seek: (time) => handleRef.current?.seek(time),
+		setMuted: (muted) => handleRef.current?.setMuted(muted),
+		setVolume: (volume) => handleRef.current?.setVolume(volume),
+		setPlaybackRate: (rate) => handleRef.current?.setPlaybackRate(rate),
+		enterFullscreen: () => handleRef.current?.enterFullscreen() ?? Promise.resolve(),
+		exitFullscreen: () => handleRef.current?.exitFullscreen() ?? Promise.resolve(),
+		setQuality: (level) => handleRef.current?.setQuality(level),
+		setSubtitle: (id) => handleRef.current?.setSubtitle(id),
+		setLocale: (locale) => handleRef.current?.setLocale(locale),
+		pushDanmaku: (item) => handleRef.current?.pushDanmaku(item),
+		setDanmakuEnabled: (enabled) => handleRef.current?.setDanmakuEnabled(enabled),
+		clearDanmaku: () => handleRef.current?.clearDanmaku(),
+		reconnect: (options) => handleRef.current?.reconnect(options),
+		destroy: () => handleRef.current?.destroy(),
+		getCurrentTime: () => handleRef.current?.getCurrentTime() ?? 0,
+		getPlaybackContext: () => handleRef.current?.getPlaybackContext() ?? null,
+		getDuration: () => handleRef.current?.getDuration() ?? 0,
+		getPlayerHandle: () => handleRef.current
+	}), [handleRef]);
+	const { messages } = readLocale(props.locale);
+	const poster = props.poster;
+	const posterUrl = typeof poster === "string" ? poster : poster?.url;
+	const pauseImage = props.pauseImage;
+	const pauseImageUrl = typeof pauseImage === "string" ? pauseImage : pauseImage?.url;
+	const style = {
+		position: "relative",
+		width: "100%",
+		height: "100%",
+		...props.interactive === false ? { pointerEvents: "none" } : {},
+		...props.style
+	};
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: ["sentinel-video", props.className].filter(Boolean).join(" "),
+		style,
+		children: [
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				ref: containerRef,
+				className: "sentinel-video__player",
+				style: {
+					width: "100%",
+					height: "100%"
+				}
+			}),
+			posterUrl && overlayElement("sentinel-poster", {
+				visible: overlay.posterVisible,
+				poster
+			}),
+			pauseImageUrl && overlayElement("sentinel-pause", {
+				visible: overlay.pauseImageVisible,
+				pauseImage,
+				"close-label": resolveText(messages, "close"),
+				"onsentinel-close": dismissPauseImage
+			}),
+			overlayElement("sentinel-loading", {
+				visible: overlay.loadingVisible,
+				text: resolveText(messages, "loading")
+			}),
+			overlay.error && overlayElement("sentinel-error", {
+				visible: true,
+				code: overlay.error.code,
+				message: resolveErrorText(messages, overlay.error.code, overlay.error.message),
+				retryable: overlay.error.retryable,
+				"retry-label": resolveText(messages, "retry"),
+				"onsentinel-retry": handleRetry
+			}),
+			!mounted && props.children
+		]
+	});
+});
+/**
+* 错误文案:`messages['error.<CODE>']` → `error.message`。
+*
+* `resolveText` 的语义是「找不到就返回 key」,所以这里要拿返回值和 key 比,
+* 以此判断「消费方没注入这条翻译」—— 和原 `ErrorOverlay` 里那段逐字同构。
+*/
+function resolveErrorText(messages, code, fallback) {
+	const key = `error.${code}`;
+	const translated = resolveText(messages, key);
+	return translated === key ? fallback : translated;
+}
+//#endregion
+exports.VideoPlayer = VideoPlayer;