@video-lab/react-frame 3.0.1 → 4.0.0

package/dist/index.mjs

@@ -1,7 +1,10 @@
-import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from "react";
+import { PlayerProvider, usePlayerI18n, useResolvedPlayerProps } from "@video-lab/react-config";
+import { PRESETS, effectiveErrorAction, errorActionMessageKey, makePlayerError, normalizeLocaleTag, resolveErrorMessage, resolveLocaleMessages, resolveOverlayMessage } from "@video-lab/protocol";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from "react";
 import { createPlayerFrame, toPlayerError } from "@video-lab/frame-core";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/use-frame-connection.ts
+let hostProducerSequence = 0;
 /**
 * 管理 frame-core 连接的整个生命周期,并把 iframe 事件桥接到 React 回调 props。
 *
@@ -12,33 +15,319 @@ import { jsx, jsxs } from "react/jsx-runtime";
 *
 * SSR 安全:`createPlayerFrame` 只在 useEffect(客户端)里跑,iframe 创建天然被挡在 SSR 之外。
 */
-function useFrameConnection(props) {
+function useFrameConnection(props, hasCustomPoster = false, hasCustomPause = false) {
 	const containerRef = useRef(null);
 	const handleRef = useRef(null);
 	const [mounted, setMounted] = useState(false);
+	const [playIntent, setPlayIntent] = useState((props.autoplay ?? (props.preset ? PRESETS[props.preset].autoplay : false)) === true || props.preload === "auto");
+	const [rebuildKey, setRebuildKey] = useState(0);
+	const [sourceOverride, setSourceOverride] = useState(null);
+	const [sourceSwitching, setSourceSwitching] = useState(false);
+	const [hostOwnsOverlays, setHostOwnsOverlays] = useState(false);
+	const [terminalError, setTerminalError] = useState(null);
+	const terminalRef = useRef(null);
+	const diagnosticRef = useRef(null);
+	const actionBusyRef = useRef(false);
 	const [hostPosterVisible, setHostPosterVisible] = useState(true);
+	const [hostPauseVisible, setHostPauseVisible] = useState(false);
+	const pauseIntentPendingRef = useRef(false);
+	const firstFrameSeenRef = useRef(false);
+	const awaitingNewSourceRef = useRef(false);
+	const [loadingOverlay, setLoadingOverlay] = useState({
+		phase: "initial",
+		reason: "frame_disconnected"
+	});
 	const propsRef = useRef(props);
 	propsRef.current = props;
+	const activeSourceRef = useRef(props.source);
+	activeSourceRef.current = sourceOverride ?? props.source;
+	const sourceSwitchRef = useRef(null);
+	const sourceSwitchSequence = useRef(0);
+	const promptSourceGeneration = useRef(0);
+	const playingIntentRef = useRef((props.autoplay ?? (props.preset ? PRESETS[props.preset].autoplay : false)) === true);
+	const hostDeliveryRef = useRef(null);
+	const forwardWithDelivery = useCallback((event, currentProps) => {
+		if (event.delivery) {
+			forward(event, currentProps);
+			return;
+		}
+		hostDeliveryRef.current ??= {
+			sessionId: `react-frame-${Date.now()}-${++hostProducerSequence}`,
+			sequence: 0
+		};
+		const producer = hostDeliveryRef.current;
+		producer.sequence += 1;
+		forward({
+			...event,
+			delivery: {
+				producerSessionId: producer.sessionId,
+				deliveryId: `${producer.sessionId}:${producer.sequence}`,
+				occurredAtMs: Date.now(),
+				sequence: producer.sequence
+			}
+		}, currentProps);
+	}, []);
+	const cancelSourceSwitch = (reason = "unmounted") => {
+		const transaction = sourceSwitchRef.current;
+		transaction?.controller.abort();
+		sourceSwitchRef.current = null;
+		setSourceSwitching(false);
+		if (!transaction) return;
+		handleRef.current?.setSourceSwitching(false).catch(() => {});
+		forwardWithDelivery({
+			event: "sourceswitch",
+			payload: {
+				phase: "cancelled",
+				switchId: transaction.id,
+				reason,
+				elapsedMs: sourceSwitchElapsed(transaction.startedAt)
+			}
+		}, propsRef.current);
+	};
+	const endSourceSwitchAsError = (id, reason, errorCode) => {
+		const transaction = sourceSwitchRef.current;
+		if (transaction?.id !== id) return;
+		sourceSwitchRef.current = null;
+		setSourceSwitching(false);
+		awaitingNewSourceRef.current = false;
+		handleRef.current?.setSourceSwitching(false).catch(() => {});
+		forwardWithDelivery({
+			event: "sourceswitch",
+			payload: {
+				phase: "failed",
+				switchId: transaction.id,
+				reason,
+				elapsedMs: sourceSwitchElapsed(transaction.startedAt),
+				...errorCode === void 0 ? {} : { errorCode }
+			}
+		}, propsRef.current);
+		forwardWithDelivery({
+			event: "playablechange",
+			payload: {
+				playable: false,
+				recoverable: false,
+				reason: "error",
+				action: "replace-source"
+			}
+		}, propsRef.current);
+		const terminal = {
+			error: diagnosticRef.current ?? makePlayerError("E_AUTH_EXPIRED", ""),
+			action: "replace-source",
+			reason: "error",
+			synthetic: true
+		};
+		terminalRef.current = terminal;
+		setTerminalError(terminal);
+	};
+	const restoreSourceSwitchOnReady = () => {
+		const transaction = sourceSwitchRef.current;
+		const current = handleRef.current;
+		if (!transaction?.loadAccepted || !current) return;
+		sourceSwitchRef.current = null;
+		setSourceSwitching(false);
+		handleRef.current?.setSourceSwitching(false).catch(() => {});
+		forwardWithDelivery({
+			event: "sourceswitch",
+			payload: {
+				phase: "succeeded",
+				switchId: transaction.id,
+				strategy: transaction.strategy,
+				elapsedMs: sourceSwitchElapsed(transaction.startedAt)
+			}
+		}, propsRef.current);
+		if (transaction.restorePosition !== null) current.seek(transaction.restorePosition).catch(() => {});
+		if (transaction.wasPlaying) current.play().catch(() => {});
+	};
+	const startSourceSwitch = (cause) => {
+		const resolveSource = propsRef.current.resolveSource;
+		if (cause.code !== "E_AUTH_EXPIRED" || !resolveSource || sourceSwitchRef.current) return false;
+		const id = ++sourceSwitchSequence.current;
+		const controller = new AbortController();
+		const context = handleRef.current?.getPlaybackContext();
+		sourceSwitchRef.current = {
+			controller,
+			id,
+			restorePosition: context?.streamKind === "vod" && Number.isFinite(context.position) ? context.position : null,
+			wasPlaying: playingIntentRef.current,
+			loadAccepted: false,
+			startedAt: sourceSwitchNow(),
+			strategy: "hot_load"
+		};
+		const httpStatus = cause.cause?.status;
+		forwardWithDelivery({
+			event: "sourceswitch",
+			payload: {
+				phase: "started",
+				switchId: id,
+				trigger: "auth_expired",
+				...httpStatus === 401 || httpStatus === 403 ? { httpStatus } : {}
+			}
+		}, propsRef.current);
+		setSourceSwitching(true);
+		pauseIntentPendingRef.current = false;
+		setHostPauseVisible(false);
+		awaitingNewSourceRef.current = "switching";
+		handleRef.current?.setSourceSwitching(true).catch(() => {});
+		forwardWithDelivery({
+			event: "playablechange",
+			payload: {
+				playable: false,
+				recoverable: true,
+				reason: "source_switching",
+				action: "none"
+			}
+		}, propsRef.current);
+		Promise.resolve().then(() => resolveSource({
+			cause,
+			signal: controller.signal
+		})).then((source) => {
+			if (sourceSwitchRef.current?.id !== id || controller.signal.aborted) return;
+			if (source === null || !handleRef.current) return endSourceSwitchAsError(id, "resolver_null");
+			sourceSwitchRef.current.loadAccepted = true;
+			handleRef.current.load(source).then(() => {}, (error) => {
+				const playerError = toPlayerError(error);
+				if (playerError.code !== "E_METHOD_NOT_SUPPORTED") return endSourceSwitchAsError(id, "load_rejected", playerError.code);
+				if (sourceSwitchRef.current?.id !== id || controller.signal.aborted) return;
+				sourceSwitchRef.current.strategy = "rebuild";
+				setSourceOverride(source);
+				setRebuildKey((key) => key + 1);
+			});
+		}).catch(() => {
+			if (!controller.signal.aborted) endSourceSwitchAsError(id, "resolver_rejected");
+		});
+		return true;
+	};
+	const performErrorAction = async () => {
+		if (actionBusyRef.current || sourceSwitchRef.current) return "busy";
+		const current = handleRef.current;
+		const terminal = terminalRef.current;
+		if (!current || !terminal) return "unavailable";
+		const action = effectiveErrorAction({
+			reason: terminal.reason,
+			recoverable: false,
+			action: terminal.action,
+			errorCode: terminal.error.code,
+			canResolveSource: Boolean(propsRef.current.resolveSource),
+			canRecreateFrame: true
+		});
+		if (action === "none") return "unavailable";
+		if (action === "replace-source") return startSourceSwitch(terminal.error) ? "started" : "unavailable";
+		actionBusyRef.current = true;
+		try {
+			if (action === "recreate-frame") {
+				await current.destroy();
+				handleRef.current = null;
+				terminalRef.current = null;
+				setTerminalError(null);
+				diagnosticRef.current = null;
+				setHostOwnsOverlays(false);
+				firstFrameSeenRef.current = false;
+				awaitingNewSourceRef.current = false;
+				setHostPosterVisible(true);
+				setHostPauseVisible(false);
+				setLoadingOverlay({
+					phase: "initial",
+					reason: "frame_disconnected"
+				});
+				setRebuildKey((key) => key + 1);
+			} else if (action === "play") await current.play();
+			else await current.retry();
+			return "started";
+		} finally {
+			actionBusyRef.current = false;
+		}
+	};
 	useEffect(() => {
 		let cancelled = false;
 		const container = containerRef.current;
 		if (!container) return;
 		const p = propsRef.current;
+		setHostOwnsOverlays(false);
 		createPlayerFrame({
 			container,
-			source: p.source,
-			config: toConfig(p),
+			source: activeSourceRef.current,
+			config: toConfig(p, hasCustomPoster, hasCustomPause),
+			renderDefaultFallback: false,
+			onHostOverlayOwnershipChange: (owned) => setHostOwnsOverlays(owned),
+			sourceSwitching: sourceSwitchRef.current !== null,
 			pageFullscreen: p.pageFullscreen,
 			...p.origin !== void 0 ? { origin: p.origin } : {},
-			...p.version !== void 0 ? { version: p.version } : {},
+			...p.iframeVersion !== void 0 ? { iframeVersion: p.iframeVersion } : {},
 			onEvent: (event) => {
-				if (event.event === "play" || event.event === "error") setHostPosterVisible(false);
-				forward(event, propsRef.current);
-			},
-			onDeliveredEvent: (event) => {
-				try {
-					propsRef.current.onDeliveredPlayerEvent?.(event);
-				} catch {}
+				if (cancelled) return;
+				if (event.event === "useraction" && event.payload.action === "switch_play_pause") {
+					if (event.payload.to === false) pauseIntentPendingRef.current = false;
+					else if (event.payload.to === true || event.payload.to === null && playingIntentRef.current) pauseIntentPendingRef.current = true;
+				}
+				if (event.event === "contextchange") {
+					pauseIntentPendingRef.current = false;
+					setHostPauseVisible(false);
+				}
+				if (event.event === "pause") {
+					setHostPauseVisible(pauseIntentPendingRef.current);
+					pauseIntentPendingRef.current = false;
+				}
+				if (event.event === "play" || event.event === "ended") {
+					pauseIntentPendingRef.current = false;
+					setHostPauseVisible(false);
+				}
+				if (event.event === "play" || event.event === "playing") {
+					playingIntentRef.current = true;
+					setPlayIntent(true);
+				}
+				if (event.event === "pause" || event.event === "ended") {
+					playingIntentRef.current = false;
+					setPlayIntent(false);
+				}
+				if (event.event === "error") {
+					diagnosticRef.current = event.payload;
+					const active = sourceSwitchRef.current;
+					if (active?.loadAccepted) endSourceSwitchAsError(active.id, "replacement_error", event.payload.code);
+					startSourceSwitch(event.payload);
+				}
+				if (event.event === "ready") {
+					if (awaitingNewSourceRef.current === "switching") awaitingNewSourceRef.current = "new-source";
+					restoreSourceSwitchOnReady();
+				}
+				if (event.event === "playablechange" && event.payload.reason === "error" && sourceSwitchRef.current) return;
+				if (event.event === "playablechange") {
+					const { playable, recoverable, reason, action = "none" } = event.payload;
+					if (!playable && !recoverable && (reason === "error" || reason === "frame_disconnected" || reason === "autoplay_blocked")) {
+						const terminal = {
+							error: reason === "autoplay_blocked" ? makePlayerError("E_AUTOPLAY_BLOCKED", "") : diagnosticRef.current ?? makePlayerError("E_UNKNOWN", ""),
+							action,
+							reason
+						};
+						terminalRef.current = terminal;
+						setTerminalError(terminal);
+						pauseIntentPendingRef.current = false;
+						setHostPauseVisible(false);
+					} else if (playable || recoverable) {
+						terminalRef.current = null;
+						setTerminalError(null);
+						if (playable) diagnosticRef.current = null;
+					}
+				}
+				if (event.event === "firstframe" || event.event === "timeupdate") if (awaitingNewSourceRef.current === "switching") {} else {
+					if (awaitingNewSourceRef.current === "new-source") awaitingNewSourceRef.current = false;
+					firstFrameSeenRef.current = true;
+					setHostPosterVisible(false);
+					setLoadingOverlay(null);
+				}
+				else if (event.event === "playablechange") {
+					const { playable, recoverable, reason, action = "none" } = event.payload;
+					const terminalError = !playable && !recoverable && reason === "error";
+					const blockingAction = !playable && !recoverable && action !== "none";
+					if (terminalError) setHostPosterVisible(false);
+					setLoadingOverlay(!firstFrameSeenRef.current ? terminalError || blockingAction ? null : {
+						phase: "initial",
+						reason
+					} : !playable && recoverable && reason !== "initializing" ? {
+						phase: "runtime",
+						reason
+					} : null);
+				}
+				forwardWithDelivery(event, propsRef.current);
 			},
 			debug: p.debug ?? false
 		}).then((h) => {
@@ -48,47 +337,124 @@ function useFrameConnection(props) {
 			}
 			handleRef.current = h;
 			setMounted(true);
+			if (propsRef.current.showErrorOverlay !== p.showErrorOverlay || propsRef.current.errorButtonColors !== p.errorButtonColors) h.setOverlayPresentation({
+				showErrorOverlay: propsRef.current.showErrorOverlay !== false,
+				...propsRef.current.errorButtonColors ? { errorButtonColors: propsRef.current.errorButtonColors } : {}
+			}).catch(() => {});
+			const latestLocale = propsRef.current.locale;
+			if (latestLocale !== void 0 && JSON.stringify(latestLocale) !== JSON.stringify(p.locale)) h.setLocale(latestLocale).catch((err) => forwardWithDelivery({
+				event: "error",
+				payload: toPlayerError(err)
+			}, propsRef.current));
 		});
 		return () => {
 			cancelled = true;
 			handleRef.current?.destroy();
 			handleRef.current = null;
 		};
-	}, []);
+	}, [rebuildKey]);
+	useEffect(() => cancelSourceSwitch, []);
 	const sourceKey = JSON.stringify(props.source);
 	useEffect(() => {
-		handleRef.current?.load(props.source).catch((err) => forward({
-			event: "error",
-			payload: toPlayerError(err)
-		}, propsRef.current));
+		cancelSourceSwitch("external_source");
+		setSourceOverride(null);
+		const generation = ++promptSourceGeneration.current;
+		handleRef.current?.load(props.source).catch((err) => {
+			const playerError = toPlayerError(err);
+			if (promptSourceGeneration.current !== generation) {
+				forwardWithDelivery({
+					event: "error",
+					payload: playerError
+				}, propsRef.current);
+				return;
+			}
+			diagnosticRef.current = playerError;
+			const terminal = {
+				error: playerError,
+				action: "replace-source",
+				reason: "error",
+				synthetic: true
+			};
+			terminalRef.current = terminal;
+			setTerminalError(terminal);
+			awaitingNewSourceRef.current = false;
+			setHostPosterVisible(false);
+			setHostPauseVisible(false);
+			setLoadingOverlay(null);
+			forwardWithDelivery({
+				event: "error",
+				payload: playerError
+			}, propsRef.current);
+		});
 	}, [sourceKey]);
 	useEffect(() => {
-		if (props.muted !== void 0) handleRef.current?.setMuted(props.muted).catch((err) => forward({
+		if (props.muted !== void 0) handleRef.current?.setMuted(props.muted).catch((err) => forwardWithDelivery({
 			event: "error",
 			payload: toPlayerError(err)
 		}, propsRef.current));
-	}, [props.muted]);
+	}, [props.muted, forwardWithDelivery]);
 	useEffect(() => {
-		if (props.locale !== void 0) handleRef.current?.setLocale(props.locale).catch((err) => forward({
+		if (props.locale !== void 0) handleRef.current?.setLocale(props.locale).catch((err) => forwardWithDelivery({
 			event: "error",
 			payload: toPlayerError(err)
 		}, propsRef.current));
-	}, [props.locale]);
+	}, [props.locale, forwardWithDelivery]);
+	useEffect(() => {
+		if (!hostOwnsOverlays) return;
+		handleRef.current?.setOverlayPresentation({
+			showErrorOverlay: props.showErrorOverlay !== false,
+			...props.errorButtonColors ? { errorButtonColors: props.errorButtonColors } : {}
+		}).catch(() => {});
+	}, [
+		hostOwnsOverlays,
+		props.showErrorOverlay,
+		props.errorButtonColors
+	]);
+	const previousSourceKeyRef = useRef(sourceKey);
 	useEffect(() => {
+		if (previousSourceKeyRef.current === sourceKey) return;
+		previousSourceKeyRef.current = sourceKey;
 		setHostPosterVisible(true);
+		pauseIntentPendingRef.current = false;
+		setHostPauseVisible(false);
+		firstFrameSeenRef.current = false;
+		awaitingNewSourceRef.current = "switching";
+		setLoadingOverlay({
+			phase: "initial",
+			reason: "initializing"
+		});
 	}, [sourceKey]);
 	return {
 		containerRef,
 		handleRef,
 		mounted,
-		hostPosterVisible
+		hostPosterVisible,
+		hostPauseVisible,
+		pause: useCallback(async () => {
+			const current = handleRef.current;
+			if (!current) return;
+			pauseIntentPendingRef.current = true;
+			try {
+				await current.pause();
+			} catch (error) {
+				pauseIntentPendingRef.current = false;
+				throw error;
+			}
+		}, []),
+		playIntent,
+		loadingOverlay,
+		terminalError,
+		hostOwnsOverlays,
+		performErrorAction,
+		sourceSwitching,
+		cancelSourceSwitch
 	};
 }
 /**
 * 只把"显式传了的"字段带上;undefined 交给 iframe 侧走 preset / xgplayer 默认。
 * 和 vue-frame 的 toConfig 语义一致(resolvePreset 的语义就是 undefined = 没传)。
 */
-function toConfig(props) {
+function toConfig(props, hasCustomPoster = false, hasCustomPause = false) {
 	const config = {};
 	if (props.preset !== void 0) config.preset = props.preset;
 	if (props.autoplay !== void 0) config.autoplay = props.autoplay;
@@ -101,23 +467,32 @@ function toConfig(props) {
 	if (props.preload !== void 0) config.preload = props.preload;
 	if (props.controls !== void 0) config.controls = props.controls;
 	if (props.showErrorOverlay !== void 0) config.showErrorOverlay = props.showErrorOverlay;
-	if (props.showLoadingOverlay !== void 0) config.showLoadingOverlay = props.showLoadingOverlay;
+	if (props.renderLoading !== void 0) config.showDefaultLoadingOverlay = false;
+	else if (props.showDefaultLoadingOverlay !== void 0) config.showDefaultLoadingOverlay = props.showDefaultLoadingOverlay;
+	if (props.showLoadingText !== void 0) config.showLoadingText = props.showLoadingText;
+	if (props.errorButtonColors !== void 0) config.errorButtonColors = props.errorButtonColors;
 	if (props.controlVisibility !== void 0) config.controlVisibility = props.controlVisibility;
 	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 (!hasCustomPoster && props.poster != null) config.poster = props.poster;
+	if (!hasCustomPause && props.pauseImage != null) 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;
 }
+function sourceSwitchNow() {
+	return globalThis.performance?.now?.() ?? Date.now();
+}
+function sourceSwitchElapsed(startedAt) {
+	return Math.max(0, sourceSwitchNow() - startedAt);
+}
 /**
 * iframe 事件 → React 回调。名字从 wire 上的小写拼写换成 `onCamelCase`。
 * 和 vue-frame 的 forward 一一对应(cross-mode-parity):同样的事件、同样的 payload 裁剪。
 *
-* **契约声明的 27 个事件必须一个不少地出现在这里**,由 `protocol/tests/consumer-surface.contract.test.ts`
+* **契约声明的 28 个事件必须一个不少地出现在这里**,由 `protocol/tests/consumer-surface.contract.test.ts`
 * 静态断言。曾经漏过 seeking / seeked / waiting / playing 四个,理由是"团队封装层没用到" ——
-* 但静态 iframe 模式是裸广播、27 个全发,于是同一份契约在四种接入方式下能收到的事件
+* 但静态 iframe 模式是裸广播、28 个全发,于是同一份契约在四种接入方式下能收到的事件
 * 不一样,parity 红线实际已破。别再以"业务暂时用不到"为由少接一个。
 */
 function forward(event, props) {
@@ -203,7 +578,8 @@ function forward(event, props) {
 		case "audiohealth":
 			props.onAudioHealth?.(event.payload);
 			break;
-		case "recovery": break;
+		case "recovery":
+		case "sourceswitch": break;
 		default: break;
 	}
 }
@@ -217,7 +593,7 @@ function forward(event, props) {
 * `loading="lazy"` 在这里不影响抢首帧:它只推迟**视口外**的图,而封面天然在视口内。
 */
 function HostPoster({ poster }) {
-	if (poster === void 0) return null;
+	if (poster == null) return null;
 	const url = typeof poster === "string" ? poster : poster.url;
 	if (!url) return null;
 	const fit = typeof poster === "string" ? void 0 : poster.fit;
@@ -233,7 +609,8 @@ function HostPoster({ poster }) {
 			height: "100%",
 			display: "block",
 			objectFit: fit ?? "cover",
-			zIndex: 10
+			zIndex: 10,
+			pointerEvents: "none"
 		}
 	});
 }
@@ -253,11 +630,16 @@ function HostPoster({ poster }) {
 * <VideoPlayerFrame ref={ref} source="https://cdn/a.m3u8" muted onReady={...} />
 * ref.current?.play()
 */
-const VideoPlayerFrame = forwardRef(function VideoPlayerFrame(props, ref) {
-	const { containerRef, handleRef, mounted, hostPosterVisible } = useFrameConnection(props);
+const VideoPlayerFrame = forwardRef(function VideoPlayerFrame(rawProps, ref) {
+	const props = useResolvedPlayerProps(rawProps, true);
+	const [hasCustomPoster] = useState(() => props.renderPoster !== void 0);
+	const [hasCustomPause] = useState(() => props.renderPause !== void 0);
+	const [localeOverride, setLocaleOverride] = useState();
+	useEffect(() => setLocaleOverride(void 0), [JSON.stringify(props.locale)]);
+	const { containerRef, handleRef, mounted, hostPosterVisible, hostPauseVisible, pause, playIntent, loadingOverlay, terminalError, hostOwnsOverlays, performErrorAction, cancelSourceSwitch } = useFrameConnection(props, hasCustomPoster, hasCustomPause);
 	useImperativeHandle(ref, () => ({
 		play: () => handleRef.current?.play() ?? Promise.resolve(),
-		pause: () => handleRef.current?.pause() ?? Promise.resolve(),
+		pause,
 		seek: (time) => handleRef.current?.seek(time) ?? Promise.resolve(),
 		setMuted: (muted) => handleRef.current?.setMuted(muted) ?? Promise.resolve(),
 		setVolume: (volume) => handleRef.current?.setVolume(volume) ?? Promise.resolve(),
@@ -267,39 +649,181 @@ const VideoPlayerFrame = forwardRef(function VideoPlayerFrame(props, ref) {
 		exitFullscreen: () => handleRef.current?.exitFullscreen() ?? Promise.resolve(),
 		setQuality: (level) => handleRef.current?.setQuality(level) ?? Promise.resolve(),
 		setSubtitle: (id) => handleRef.current?.setSubtitle(id) ?? Promise.resolve(),
-		setLocale: (locale) => handleRef.current?.setLocale(locale) ?? Promise.resolve(),
+		setLocale: (locale) => {
+			setLocaleOverride(locale);
+			return handleRef.current?.setLocale(locale) ?? Promise.resolve();
+		},
 		pushDanmaku: (item) => handleRef.current?.pushDanmaku(item) ?? Promise.resolve(),
 		setDanmakuEnabled: (enabled) => handleRef.current?.setDanmakuEnabled(enabled) ?? Promise.resolve(),
 		clearDanmaku: () => handleRef.current?.clearDanmaku() ?? Promise.resolve(),
 		retry: () => handleRef.current?.retry() ?? Promise.resolve(),
-		destroy: () => handleRef.current?.destroy() ?? Promise.resolve(),
+		performErrorAction,
+		destroy: () => {
+			cancelSourceSwitch("destroyed");
+			return handleRef.current?.destroy() ?? Promise.resolve();
+		},
 		getCurrentTime: () => handleRef.current?.getCurrentTime() ?? 0,
 		getPlaybackContext: () => handleRef.current?.getPlaybackContext() ?? null,
 		getDuration: () => handleRef.current?.getDuration() ?? 0,
 		getPlayerHandle: () => handleRef.current
-	}), [handleRef]);
+	}), [
+		handleRef,
+		cancelSourceSwitch,
+		pause,
+		performErrorAction
+	]);
 	const style = {
 		position: "relative",
+		display: "block",
+		margin: 0,
 		width: "100%",
 		height: "100%",
-		...props.interactive === false ? { pointerEvents: "none" } : {},
+		...(props.interactive ?? (props.preset ? PRESETS[props.preset].interactive : void 0)) === false ? { pointerEvents: "none" } : {},
 		...props.style
 	};
+	const className = ["sentinel-video-frame", props.className].filter(Boolean).join(" ");
+	const effectiveLocale = localeOverride ?? props.locale;
+	const lang = normalizeLocaleTag((typeof effectiveLocale === "string" ? effectiveLocale : effectiveLocale?.locale) || "zh-CN");
+	const loadingContext = loadingOverlay && !((loadingOverlay.reason === "initializing" || loadingOverlay.reason === "ok") && !playIntent) ? {
+		...loadingOverlay,
+		text: resolveOverlayMessage(resolveLocaleMessages(effectiveLocale).messages, `loading.${loadingOverlay.reason}`, lang)
+	} : null;
+	const { messages } = resolveLocaleMessages(effectiveLocale);
+	const showHostLoading = loadingContext && !props.renderLoading && props.showDefaultLoadingOverlay !== false && (loadingContext.reason === "frame_disconnected" || hostOwnsOverlays);
+	const showHostError = terminalError && props.showErrorOverlay !== false && (terminalError.reason === "frame_disconnected" || terminalError.synthetic === true || hostOwnsOverlays && terminalError.reason === "error");
+	const errorActionKey = errorActionMessageKey(terminalError ? effectiveErrorAction({
+		reason: terminalError.reason,
+		recoverable: false,
+		action: terminalError.action,
+		errorCode: terminalError.error.code,
+		canResolveSource: Boolean(props.resolveSource),
+		canRecreateFrame: true
+	}) : "none", terminalError?.error.code);
 	return /* @__PURE__ */ jsxs("div", {
 		ref: containerRef,
-		className: ["sentinel-video-frame", props.className].filter(Boolean).join(" "),
+		className,
 		style,
-		children: [!mounted && (props.children ?? /* @__PURE__ */ jsx("div", {
-			className: "sentinel-video-frame__placeholder",
-			style: {
-				width: "100%",
-				height: "100%",
-				background: "#000"
-			}
-		})), hostPosterVisible && /* @__PURE__ */ jsx(HostPoster, { poster: props.poster })]
+		lang,
+		children: [
+			!mounted && (props.children ?? /* @__PURE__ */ jsx("div", {
+				className: "sentinel-video-frame__placeholder",
+				style: {
+					width: "100%",
+					height: "100%",
+					background: "#000"
+				}
+			})),
+			!hasCustomPoster && hostPosterVisible && /* @__PURE__ */ jsx(HostPoster, { poster: props.poster }),
+			hasCustomPoster && hostPosterVisible && /* @__PURE__ */ jsx("div", {
+				"data-sentinel-overlay": "custom-poster",
+				style: {
+					position: "absolute",
+					inset: 0,
+					zIndex: 10
+				},
+				children: props.renderPoster?.()
+			}),
+			hasCustomPause && hostPauseVisible && /* @__PURE__ */ jsx("div", {
+				"data-sentinel-overlay": "custom-pause",
+				style: {
+					position: "absolute",
+					inset: 0,
+					zIndex: 13,
+					display: "flex",
+					alignItems: "center",
+					justifyContent: "center"
+				},
+				children: props.renderPause?.()
+			}),
+			props.renderLoading && loadingContext && /* @__PURE__ */ jsx("div", {
+				className: "sentinel-video-frame__custom-loading",
+				"data-sentinel-overlay": "custom-loading",
+				style: {
+					position: "absolute",
+					inset: 0,
+					zIndex: 12,
+					display: "flex",
+					alignItems: "center",
+					justifyContent: "center",
+					pointerEvents: "none"
+				},
+				children: props.renderLoading(loadingContext)
+			}),
+			showHostLoading && /* @__PURE__ */ jsxs("div", {
+				"data-sentinel-overlay": "loading",
+				role: "status",
+				"aria-label": loadingContext.text,
+				style: {
+					position: "absolute",
+					inset: 0,
+					zIndex: 12,
+					display: "flex",
+					alignItems: "center",
+					justifyContent: "center",
+					flexDirection: "column",
+					gap: 8,
+					color: "#fff",
+					background: "rgba(0,0,0,.5)",
+					pointerEvents: "none"
+				},
+				children: [
+					/* @__PURE__ */ jsx("style", { children: "@keyframes sentinel-frame-spin{to{transform:rotate(360deg)}}@media(prefers-reduced-motion:reduce){.sentinel-frame-spinner{animation:none!important}}" }),
+					/* @__PURE__ */ jsx("span", {
+						className: "sentinel-frame-spinner",
+						"aria-hidden": "true",
+						style: {
+							width: 24,
+							height: 24,
+							border: "2px solid rgba(255,255,255,.35)",
+							borderTopColor: "#fff",
+							borderRadius: "50%",
+							animation: "sentinel-frame-spin .8s linear infinite"
+						}
+					}),
+					props.showLoadingText === true && /* @__PURE__ */ jsx("span", {
+						part: "text",
+						children: loadingContext.text
+					})
+				]
+			}),
+			showHostError && /* @__PURE__ */ jsxs("div", {
+				"data-sentinel-overlay": "error",
+				role: "alert",
+				style: {
+					position: "absolute",
+					inset: 0,
+					zIndex: 15,
+					display: "flex",
+					alignItems: "center",
+					justifyContent: "center",
+					flexDirection: "column",
+					gap: 12,
+					padding: 16,
+					color: "#fff",
+					background: "rgba(0,0,0,.8)",
+					textAlign: "center"
+				},
+				children: [/* @__PURE__ */ jsx("span", {
+					part: "message",
+					children: resolveErrorMessage(messages, terminalError.error.code, void 0, lang)
+				}), errorActionKey && /* @__PURE__ */ jsx("button", {
+					type: "button",
+					onClick: () => void performErrorAction().catch(() => {}),
+					style: {
+						border: 0,
+						borderRadius: 6,
+						padding: "8px 16px",
+						background: props.errorButtonColors?.background ?? "#3B82F6",
+						color: props.errorButtonColors?.foreground ?? "#fff",
+						cursor: "pointer"
+					},
+					children: resolveOverlayMessage(messages, errorActionKey, lang)
+				})]
+			})
+		]
 	});
 });
 //#endregion
-export { VideoPlayerFrame };
+export { PlayerProvider, VideoPlayerFrame, usePlayerI18n };
 
 //# sourceMappingURL=index.mjs.map