@video-lab/react 2.0.0 → 3.0.0

package/README.md

@@ -77,3 +77,35 @@ await ref.current?.enterFullscreen()
 - 契约定义:[`@video-lab/protocol`](https://www.npmjs.com/package/@video-lab/protocol)
 
 MIT
+
+## 错误 UI 接管
+
+通过 `showErrorOverlay={false}` 关闭默认错误文字、背景和 Retry。省略时保持开启，错误事件与恢复能力不受影响；宿主自行决定提示文案和样式。本项仅初始化读取，改变时须重新挂载。iframe 需使用 v1.1.0 或更高的兼容应用，旧应用可能仍显示默认错误 UI。纯 iframe 标签需另接 helper 才能订阅事件。
+
+## 内置控件按需隐藏
+
+初始化 prop `controlVisibility`（Vue 模板写 `:control-visibility`）支持 `{ cssFullscreen: false }` 仅隐藏 CSS 全屏按钮。
+八个可选键为 `play`、`progress`、`time`、`volume`、`playbackRate`、`fullscreen`、`cssFullscreen`、`pip`。
+false 隐藏入口，true/省略保留平台默认；`controls=false` 整体关闭优先。隐藏不禁用既有命令，
+运行时修改须由宿主显式重建，不增加 PiP RPC。
+
+## 宿主网页全屏
+
+通过 `pageFullscreen` 传入宿主布局适配器（`setActive(active)` / `dispose()`），句柄 `setPageFullscreen(active)` 等待布局确认。实际状态事件为 `pagefullscreenchange`；React 使用 `onPageFullscreenChange`，Vue 使用 `@page-fullscreen-change`。
+
+详见[网页全屏接入与完整参考实现](../../docs/guides/PAGE-FULLSCREEN.md)。iframe 需要新版宿主与 iframe 协商支持；未启用时新入口不可用。浏览器原生全屏接口保持独立。
+
+
+### 统一恢复（契约 v2）
+
+旧 `reconnect({ resetCounter })` 和 `reconnectstart/success/failed` 已移除。命令入口是 `retry(): Promise<void>`；Promise 完成只表示接受或合并请求。恢复中的重复请求共用预算，强播放证据通过 `recovery` 的 `recovered` 回报。
+
+宿主 UI 读取 `playablechange` 的 `playable`、`recoverable`、`action`。`error` 只提供诊断；预算耗尽才给出 `action: 'retry'`，宿主无需按错误原因拼接重试状态。使用 `showErrorOverlay={false}` 接管错误样式，使用 `showLoadingOverlay={false}` 接管运行时 Loading；配置在构造时生效，事件仍保留。静态 iframe URL 没有宿主命令通道，内部按钮仍走同一调度。
+
+更多迁移语义见 [ADR-099](../../docs/adr/ADR-099-unified-recovery-contract.md)。
+
+## 完整事件与命令失败
+
+`onPlayerEvent` 保持交付 raw `PlayerEvent`；需要跨重连排序、去重或识别迟到事件时使用
+`onDeliveredPlayerEvent`。所有可失败命令都应 `await` 并 `catch`，并同时订阅事件流：命令
+rejection 不保证产生 `error`，播放期 `error` 也不保证对应某个命令 rejection。

package/dist/index.cjs

@@ -65,7 +65,6 @@ function usePlayer(props) {
 	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;
 	/**
@@ -104,7 +103,13 @@ function usePlayer(props) {
 	*/
 	const reportError = (0, react.useCallback)((err) => {
 		const errorEvent = (0, _video_lab_protocol.toErrorEvent)(err);
-		setOverlay((prev) => (0, _video_lab_player_ui.reduceOverlay)(prev, errorEvent));
+		setOverlay((prev) => handleRef.current ? (0, _video_lab_player_ui.reduceOverlay)(prev, errorEvent) : {
+			...prev,
+			posterVisible: false,
+			loadingVisible: false,
+			error: errorEvent.payload,
+			action: "replace-source"
+		});
 		forward(errorEvent, propsRef.current);
 	}, []);
 	/**
@@ -139,9 +144,15 @@ function usePlayer(props) {
 			handleRef.current = (0, _video_lab_player_core.createPlayer)({
 				el: container,
 				config: toConfig(p),
+				pageFullscreen: p.pageFullscreen,
 				onEvent: (event) => {
 					setOverlay((prev) => (0, _video_lab_player_ui.reduceOverlay)(prev, event));
 					forward(event, propsRef.current);
+				},
+				onDeliveredEvent: (event) => {
+					try {
+						propsRef.current.onDeliveredPlayerEvent?.(event);
+					} catch {}
 				}
 			});
 			setMounted(true);
@@ -156,7 +167,7 @@ function usePlayer(props) {
 			mutedInited.current = false;
 			localeInited.current = false;
 		};
-	}, [rebuildKey]);
+	}, []);
 	(0, react.useEffect)(() => {
 		if (!sourceInited.current) {
 			sourceInited.current = true;
@@ -193,8 +204,9 @@ function usePlayer(props) {
 		overlay,
 		mounted,
 		handleRetry: (0, react.useCallback)(() => {
-			setRebuildKey((k) => k + 1);
-		}, []),
+			const current = handleRef.current;
+			if (current) (overlay.action === "play" ? current.play() : current.retry()).catch(() => {});
+		}, [overlay.action]),
 		dismissPauseImage: (0, react.useCallback)(() => {
 			setOverlay((prev) => ({
 				...prev,
@@ -220,6 +232,9 @@ function toConfig(props) {
 	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.showErrorOverlay !== void 0) config.showErrorOverlay = props.showErrorOverlay;
+	if (props.showLoadingOverlay !== void 0) config.showLoadingOverlay = props.showLoadingOverlay;
+	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;
@@ -232,10 +247,10 @@ function toConfig(props) {
 * 播放器事件 → React 回调。名字从 wire 上的小写换成 `onCamelCase`。
 * 和 react-frame / vue-frame 的 forward 一一对应(cross-mode-parity):同样的事件、同样的 payload。
 *
-* **契约声明的 19 个事件必须一个不少地出现在这里**,由 `protocol/tests/consumer-surface.contract.test.ts`
+* **契约声明的 27 个事件必须一个不少地出现在这里**,由 `protocol/tests/consumer-surface.contract.test.ts`
 * 静态断言。曾经漏过 4 个(seeking / seeked / waiting / playing):前两个有注释说
 * 「团队封装层没用到,需要时再加」,后两个连注释都没有 —— 被 `default: break` 静默吞掉。
-* 而静态 iframe 模式(embed-app 裸广播,无过滤)19 个全发,于是同一份契约在四种接入方式
+* 而静态 iframe 模式(embed-app 裸广播,无过滤)27 个全发,于是同一份契约在四种接入方式
 * 下能收到的事件不一样,parity 红线实际已破。别再以"业务暂时用不到"为由少接一个。
 */
 function forward(event, props) {
@@ -285,18 +300,6 @@ function forward(event, props) {
 		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;
@@ -321,6 +324,9 @@ function forward(event, props) {
 		case "framefreeze":
 			props.onFrameFreeze?.(event.payload);
 			break;
+		case "pagefullscreenchange":
+			props.onPageFullscreenChange?.(event.payload);
+			break;
 		case "useraction":
 			props.onUserAction?.(event.payload);
 			break;
@@ -359,6 +365,8 @@ function forward(event, props) {
 * ref.current?.play()
 */
 const VideoPlayer = (0, react.forwardRef)(function VideoPlayer(props, ref) {
+	const [showErrorOverlay] = (0, react.useState)(() => props.showErrorOverlay !== false);
+	const [showLoadingOverlay] = (0, react.useState)(() => props.showLoadingOverlay !== false);
 	const { containerRef, handleRef, overlay, mounted, handleRetry, dismissPauseImage } = usePlayer(props);
 	(0, react.useImperativeHandle)(ref, () => ({
 		play: () => handleRef.current?.play() ?? Promise.resolve(),
@@ -367,6 +375,7 @@ const VideoPlayer = (0, react.forwardRef)(function VideoPlayer(props, ref) {
 		setMuted: (muted) => handleRef.current?.setMuted(muted),
 		setVolume: (volume) => handleRef.current?.setVolume(volume),
 		setPlaybackRate: (rate) => handleRef.current?.setPlaybackRate(rate),
+		setPageFullscreen: (active) => handleRef.current?.setPageFullscreen(active) ?? Promise.reject(/* @__PURE__ */ new Error("播放器未就绪")),
 		enterFullscreen: () => handleRef.current?.enterFullscreen() ?? Promise.resolve(),
 		exitFullscreen: () => handleRef.current?.exitFullscreen() ?? Promise.resolve(),
 		setQuality: (level) => handleRef.current?.setQuality(level),
@@ -375,7 +384,7 @@ const VideoPlayer = (0, react.forwardRef)(function VideoPlayer(props, ref) {
 		pushDanmaku: (item) => handleRef.current?.pushDanmaku(item),
 		setDanmakuEnabled: (enabled) => handleRef.current?.setDanmakuEnabled(enabled),
 		clearDanmaku: () => handleRef.current?.clearDanmaku(),
-		reconnect: (options) => handleRef.current?.reconnect(options),
+		retry: () => handleRef.current?.retry() ?? Promise.resolve(),
 		destroy: () => handleRef.current?.destroy(),
 		getCurrentTime: () => handleRef.current?.getCurrentTime() ?? 0,
 		getPlaybackContext: () => handleRef.current?.getPlaybackContext() ?? null,
@@ -417,15 +426,15 @@ const VideoPlayer = (0, react.forwardRef)(function VideoPlayer(props, ref) {
 				"onsentinel-close": dismissPauseImage
 			}),
 			overlayElement("sentinel-loading", {
-				visible: overlay.loadingVisible,
+				visible: showLoadingOverlay && overlay.loadingVisible,
 				text: resolveText(messages, "loading")
 			}),
-			overlay.error && overlayElement("sentinel-error", {
+			showErrorOverlay && 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"),
+				retryable: overlay.action === "retry" || overlay.action === "play",
+				"retry-label": resolveText(messages, overlay.action === "play" ? "play" : "retry"),
 				"onsentinel-retry": handleRetry
 			}),
 			!mounted && props.children

package/dist/index.d.cts

@@ -1,5 +1,5 @@
+import { AudioHealthPayload, BufferHealthPayload, ControlVisibilityConfig, DanmakuConfig, DanmakuItem, DeliveredPlayerEvent, FirstFramePayload, FrameFreezePayload, KernelHealthPayload, LocaleConfig, MediaSource, PageFullscreenAdapter, PageFullscreenAdapter as PageFullscreenAdapter$1, PageFullscreenState, PageFullscreenState as PageFullscreenState$1, PauseImageConfig, PlaybackContext, PlaybackContextPayload, PlayerError, PlayerEvent, PosterConfig, PresetName, QualityLevel, SourceRouteEventPayload, SubtitleTrackInfo, UserActionPayload } from "@video-lab/protocol";
 import { PlayerCoreHandle } from "@video-lab/player-core";
-import { AudioHealthPayload, BufferHealthPayload, DanmakuConfig, DanmakuItem, FirstFramePayload, FrameFreezePayload, KernelHealthPayload, LocaleConfig, MediaSource, PauseImageConfig, PlayableReason, PlaybackContext, PlaybackContextPayload, PlayerError, PlayerEvent, PosterConfig, PresetName, QualityLevel, SourceRouteEventPayload, SubtitleTrackInfo, UserActionPayload } from "@video-lab/protocol";
 import { CSSProperties, ReactNode } from "react";
 //#region src/types.d.ts
 /**
@@ -18,12 +18,20 @@ type PlayerHandle = PlayerCoreHandle;
  * payload 形状对齐 protocol 的 PlayerEvent。
  */
 interface VideoPlayerProps {
+  /** 挂载期间保持稳定的宿主网页全屏布局适配器。 */
+  pageFullscreen?: PageFullscreenAdapter$1;
   /** 视频源。字符串按 URL 处理,对象可带 type / live / hls 等 */
   source: MediaSource | string;
   autoplay?: boolean;
   muted?: boolean;
   loop?: boolean;
   controls?: boolean;
+  /** 默认错误覆盖层，省略时开启。仅初始化读取；变更须重新挂载，不影响错误事件。 */
+  showErrorOverlay?: boolean;
+  /** 是否显示 SDK 运行时 Loading；构造期读取，默认 true。 */
+  showLoadingOverlay?: boolean;
+  /** 内置控件初始化显示策略；修改后须由宿主显式重建播放器。 */
+  controlVisibility?: ControlVisibilityConfig;
   /** false 时播放器不接收指针事件(点击穿透到下层,如首页预览卡片) */
   interactive?: boolean;
   playsinline?: boolean;
@@ -88,6 +96,8 @@ interface VideoPlayerProps {
   children?: ReactNode;
   /** 完整的契约事件流，供遥测适配器使用；不裁剪 payload。 */
   onPlayerEvent?: (event: PlayerEvent) => void;
+  /** 完整投递流；旧 onPlayerEvent 保持 raw PlayerEvent。 */
+  onDeliveredPlayerEvent?: (event: DeliveredPlayerEvent) => void;
   /**
    * metadata 就绪。`quality` 是可切档位清单(单码率源为空数组),团队层据此渲染清晰度菜单;
    * `subtitles` 是可切字幕轨清单(无字幕源为空/缺省,契约 1.0.0 起可选,ADR-027),团队层据此渲染字幕菜单。
@@ -137,12 +147,6 @@ interface VideoPlayerProps {
   }) => void;
   onError?: (payload: PlayerError) => void;
   onAutoplayBlocked?: () => void;
-  onReconnectStart?: (payload: {
-    attempt: number;
-    maxAttempts: number;
-  }) => void;
-  onReconnectSuccess?: () => void;
-  onReconnectFailed?: () => void;
   onCompatWarning?: (payload: {
     code: string;
     message: string;
@@ -166,11 +170,9 @@ interface VideoPlayerProps {
    * `recoverable` 决定盖 loading(等)还是露重试入口(不等);`reason='degraded'`
    * 是唯一 `playable` 仍为 `true` 的值(掉帧严重但画面还在动,可以忽略)。
    */
-  onPlayableChange?: (payload: {
-    playable: boolean;
-    reason: PlayableReason;
-    recoverable: boolean;
-  }) => void;
+  onPlayableChange?: (payload: Extract<PlayerEvent, {
+    event: 'playablechange';
+  }>['payload']) => void;
   /**
    * 内核健康 —— **非致命内核诊断的聚合**(契约 4.1.0 / ADR-062 / issue #391)。
    *
@@ -218,6 +220,8 @@ interface VideoPlayerProps {
    * ⚠️ 它不是掉帧率,也不与 `stalled` 重复(后者是缓冲驱动的等待)。
    */
   onFrameFreeze?: (payload: FrameFreezePayload) => void;
+  /** 实际网页全屏状态变化。 */
+  onPageFullscreenChange?: (payload: PageFullscreenState$1) => void;
   /**
    * 用户动作(ADR-075),经白名单过滤,只含**发生在 SDK 内部**的那些。
    *
@@ -242,6 +246,8 @@ interface VideoPlayerHandle {
   setMuted(muted: boolean): void;
   setVolume(volume: number): void;
   setPlaybackRate(rate: number): void;
+  /** 设置网页全屏；必须等宿主布局与 iframe 状态确认。 */
+  setPageFullscreen(active: boolean): Promise<void>;
   /** 进入全屏(容器托管,不碰 video 原生入口,iOS 微信崩溃入口由 FullscreenGuard 中和) */
   enterFullscreen(): Promise<void>;
   /** 退出全屏 */
@@ -257,9 +263,7 @@ interface VideoPlayerHandle {
   setDanmakuEnabled(enabled: boolean): void;
   /** 清空屏上弹幕(ADR-028) */
   clearDanmaku(): void;
-  reconnect(options?: {
-    resetCounter?: boolean;
-  }): void;
+  retry(): Promise<void>;
   destroy(): void;
   getCurrentTime(): number;
   getDuration(): number;
@@ -306,5 +310,5 @@ interface VideoPlayerHandle {
  */
 declare const VideoPlayer: import("react").ForwardRefExoticComponent<VideoPlayerProps & import("react").RefAttributes<VideoPlayerHandle>>;
 //#endregion
-export { type DanmakuConfig, type DanmakuItem, type MediaSource, type PlayerError, type PlayerHandle, type QualityLevel, type SubtitleTrackInfo, VideoPlayer, type VideoPlayerHandle, type VideoPlayerProps };
+export { type DanmakuConfig, type DanmakuItem, type MediaSource, type PageFullscreenAdapter, type PageFullscreenState, type PlayerError, type PlayerHandle, type QualityLevel, type SubtitleTrackInfo, VideoPlayer, type VideoPlayerHandle, type VideoPlayerProps };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactNode } from "react";
-import { AudioHealthPayload, BufferHealthPayload, DanmakuConfig, DanmakuItem, FirstFramePayload, FrameFreezePayload, KernelHealthPayload, LocaleConfig, MediaSource, PauseImageConfig, PlayableReason, PlaybackContext, PlaybackContextPayload, PlayerError, PlayerEvent, PosterConfig, PresetName, QualityLevel, SourceRouteEventPayload, SubtitleTrackInfo, UserActionPayload } from "@video-lab/protocol";
+import { AudioHealthPayload, BufferHealthPayload, ControlVisibilityConfig, DanmakuConfig, DanmakuItem, DeliveredPlayerEvent, FirstFramePayload, FrameFreezePayload, KernelHealthPayload, LocaleConfig, MediaSource, PageFullscreenAdapter, PageFullscreenAdapter as PageFullscreenAdapter$1, PageFullscreenState, PageFullscreenState as PageFullscreenState$1, PauseImageConfig, PlaybackContext, PlaybackContextPayload, PlayerError, PlayerEvent, PosterConfig, PresetName, QualityLevel, SourceRouteEventPayload, SubtitleTrackInfo, UserActionPayload } from "@video-lab/protocol";
 import { PlayerCoreHandle } from "@video-lab/player-core";
 //#region src/types.d.ts
 /**
@@ -18,12 +18,20 @@ type PlayerHandle = PlayerCoreHandle;
  * payload 形状对齐 protocol 的 PlayerEvent。
  */
 interface VideoPlayerProps {
+  /** 挂载期间保持稳定的宿主网页全屏布局适配器。 */
+  pageFullscreen?: PageFullscreenAdapter$1;
   /** 视频源。字符串按 URL 处理,对象可带 type / live / hls 等 */
   source: MediaSource | string;
   autoplay?: boolean;
   muted?: boolean;
   loop?: boolean;
   controls?: boolean;
+  /** 默认错误覆盖层，省略时开启。仅初始化读取；变更须重新挂载，不影响错误事件。 */
+  showErrorOverlay?: boolean;
+  /** 是否显示 SDK 运行时 Loading；构造期读取，默认 true。 */
+  showLoadingOverlay?: boolean;
+  /** 内置控件初始化显示策略；修改后须由宿主显式重建播放器。 */
+  controlVisibility?: ControlVisibilityConfig;
   /** false 时播放器不接收指针事件(点击穿透到下层,如首页预览卡片) */
   interactive?: boolean;
   playsinline?: boolean;
@@ -88,6 +96,8 @@ interface VideoPlayerProps {
   children?: ReactNode;
   /** 完整的契约事件流，供遥测适配器使用；不裁剪 payload。 */
   onPlayerEvent?: (event: PlayerEvent) => void;
+  /** 完整投递流；旧 onPlayerEvent 保持 raw PlayerEvent。 */
+  onDeliveredPlayerEvent?: (event: DeliveredPlayerEvent) => void;
   /**
    * metadata 就绪。`quality` 是可切档位清单(单码率源为空数组),团队层据此渲染清晰度菜单;
    * `subtitles` 是可切字幕轨清单(无字幕源为空/缺省,契约 1.0.0 起可选,ADR-027),团队层据此渲染字幕菜单。
@@ -137,12 +147,6 @@ interface VideoPlayerProps {
   }) => void;
   onError?: (payload: PlayerError) => void;
   onAutoplayBlocked?: () => void;
-  onReconnectStart?: (payload: {
-    attempt: number;
-    maxAttempts: number;
-  }) => void;
-  onReconnectSuccess?: () => void;
-  onReconnectFailed?: () => void;
   onCompatWarning?: (payload: {
     code: string;
     message: string;
@@ -166,11 +170,9 @@ interface VideoPlayerProps {
    * `recoverable` 决定盖 loading(等)还是露重试入口(不等);`reason='degraded'`
    * 是唯一 `playable` 仍为 `true` 的值(掉帧严重但画面还在动,可以忽略)。
    */
-  onPlayableChange?: (payload: {
-    playable: boolean;
-    reason: PlayableReason;
-    recoverable: boolean;
-  }) => void;
+  onPlayableChange?: (payload: Extract<PlayerEvent, {
+    event: 'playablechange';
+  }>['payload']) => void;
   /**
    * 内核健康 —— **非致命内核诊断的聚合**(契约 4.1.0 / ADR-062 / issue #391)。
    *
@@ -218,6 +220,8 @@ interface VideoPlayerProps {
    * ⚠️ 它不是掉帧率,也不与 `stalled` 重复(后者是缓冲驱动的等待)。
    */
   onFrameFreeze?: (payload: FrameFreezePayload) => void;
+  /** 实际网页全屏状态变化。 */
+  onPageFullscreenChange?: (payload: PageFullscreenState$1) => void;
   /**
    * 用户动作(ADR-075),经白名单过滤,只含**发生在 SDK 内部**的那些。
    *
@@ -242,6 +246,8 @@ interface VideoPlayerHandle {
   setMuted(muted: boolean): void;
   setVolume(volume: number): void;
   setPlaybackRate(rate: number): void;
+  /** 设置网页全屏；必须等宿主布局与 iframe 状态确认。 */
+  setPageFullscreen(active: boolean): Promise<void>;
   /** 进入全屏(容器托管,不碰 video 原生入口,iOS 微信崩溃入口由 FullscreenGuard 中和) */
   enterFullscreen(): Promise<void>;
   /** 退出全屏 */
@@ -257,9 +263,7 @@ interface VideoPlayerHandle {
   setDanmakuEnabled(enabled: boolean): void;
   /** 清空屏上弹幕(ADR-028) */
   clearDanmaku(): void;
-  reconnect(options?: {
-    resetCounter?: boolean;
-  }): void;
+  retry(): Promise<void>;
   destroy(): void;
   getCurrentTime(): number;
   getDuration(): number;
@@ -306,5 +310,5 @@ interface VideoPlayerHandle {
  */
 declare const VideoPlayer: import("react").ForwardRefExoticComponent<VideoPlayerProps & import("react").RefAttributes<VideoPlayerHandle>>;
 //#endregion
-export { type DanmakuConfig, type DanmakuItem, type MediaSource, type PlayerError, type PlayerHandle, type QualityLevel, type SubtitleTrackInfo, VideoPlayer, type VideoPlayerHandle, type VideoPlayerProps };
+export { type DanmakuConfig, type DanmakuItem, type MediaSource, type PageFullscreenAdapter, type PageFullscreenState, type PlayerError, type PlayerHandle, type QualityLevel, type SubtitleTrackInfo, VideoPlayer, type VideoPlayerHandle, type VideoPlayerProps };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -64,7 +64,6 @@ function usePlayer(props) {
 	const handleRef = useRef(null);
 	const [overlay, setOverlay] = useState(INITIAL_OVERLAY);
 	const [mounted, setMounted] = useState(false);
-	const [rebuildKey, setRebuildKey] = useState(0);
 	const propsRef = useRef(props);
 	propsRef.current = props;
 	/**
@@ -103,7 +102,13 @@ function usePlayer(props) {
 	*/
 	const reportError = useCallback((err) => {
 		const errorEvent = toErrorEvent(err);
-		setOverlay((prev) => reduceOverlay(prev, errorEvent));
+		setOverlay((prev) => handleRef.current ? reduceOverlay(prev, errorEvent) : {
+			...prev,
+			posterVisible: false,
+			loadingVisible: false,
+			error: errorEvent.payload,
+			action: "replace-source"
+		});
 		forward(errorEvent, propsRef.current);
 	}, []);
 	/**
@@ -138,9 +143,15 @@ function usePlayer(props) {
 			handleRef.current = createPlayer({
 				el: container,
 				config: toConfig(p),
+				pageFullscreen: p.pageFullscreen,
 				onEvent: (event) => {
 					setOverlay((prev) => reduceOverlay(prev, event));
 					forward(event, propsRef.current);
+				},
+				onDeliveredEvent: (event) => {
+					try {
+						propsRef.current.onDeliveredPlayerEvent?.(event);
+					} catch {}
 				}
 			});
 			setMounted(true);
@@ -155,7 +166,7 @@ function usePlayer(props) {
 			mutedInited.current = false;
 			localeInited.current = false;
 		};
-	}, [rebuildKey]);
+	}, []);
 	useEffect(() => {
 		if (!sourceInited.current) {
 			sourceInited.current = true;
@@ -192,8 +203,9 @@ function usePlayer(props) {
 		overlay,
 		mounted,
 		handleRetry: useCallback(() => {
-			setRebuildKey((k) => k + 1);
-		}, []),
+			const current = handleRef.current;
+			if (current) (overlay.action === "play" ? current.play() : current.retry()).catch(() => {});
+		}, [overlay.action]),
 		dismissPauseImage: useCallback(() => {
 			setOverlay((prev) => ({
 				...prev,
@@ -219,6 +231,9 @@ function toConfig(props) {
 	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.showErrorOverlay !== void 0) config.showErrorOverlay = props.showErrorOverlay;
+	if (props.showLoadingOverlay !== void 0) config.showLoadingOverlay = props.showLoadingOverlay;
+	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;
@@ -231,10 +246,10 @@ function toConfig(props) {
 * 播放器事件 → React 回调。名字从 wire 上的小写换成 `onCamelCase`。
 * 和 react-frame / vue-frame 的 forward 一一对应(cross-mode-parity):同样的事件、同样的 payload。
 *
-* **契约声明的 19 个事件必须一个不少地出现在这里**,由 `protocol/tests/consumer-surface.contract.test.ts`
+* **契约声明的 27 个事件必须一个不少地出现在这里**,由 `protocol/tests/consumer-surface.contract.test.ts`
 * 静态断言。曾经漏过 4 个(seeking / seeked / waiting / playing):前两个有注释说
 * 「团队封装层没用到,需要时再加」,后两个连注释都没有 —— 被 `default: break` 静默吞掉。
-* 而静态 iframe 模式(embed-app 裸广播,无过滤)19 个全发,于是同一份契约在四种接入方式
+* 而静态 iframe 模式(embed-app 裸广播,无过滤)27 个全发,于是同一份契约在四种接入方式
 * 下能收到的事件不一样,parity 红线实际已破。别再以"业务暂时用不到"为由少接一个。
 */
 function forward(event, props) {
@@ -284,18 +299,6 @@ function forward(event, props) {
 		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;
@@ -320,6 +323,9 @@ function forward(event, props) {
 		case "framefreeze":
 			props.onFrameFreeze?.(event.payload);
 			break;
+		case "pagefullscreenchange":
+			props.onPageFullscreenChange?.(event.payload);
+			break;
 		case "useraction":
 			props.onUserAction?.(event.payload);
 			break;
@@ -358,6 +364,8 @@ function forward(event, props) {
 * ref.current?.play()
 */
 const VideoPlayer = forwardRef(function VideoPlayer(props, ref) {
+	const [showErrorOverlay] = useState(() => props.showErrorOverlay !== false);
+	const [showLoadingOverlay] = useState(() => props.showLoadingOverlay !== false);
 	const { containerRef, handleRef, overlay, mounted, handleRetry, dismissPauseImage } = usePlayer(props);
 	useImperativeHandle(ref, () => ({
 		play: () => handleRef.current?.play() ?? Promise.resolve(),
@@ -366,6 +374,7 @@ const VideoPlayer = forwardRef(function VideoPlayer(props, ref) {
 		setMuted: (muted) => handleRef.current?.setMuted(muted),
 		setVolume: (volume) => handleRef.current?.setVolume(volume),
 		setPlaybackRate: (rate) => handleRef.current?.setPlaybackRate(rate),
+		setPageFullscreen: (active) => handleRef.current?.setPageFullscreen(active) ?? Promise.reject(/* @__PURE__ */ new Error("播放器未就绪")),
 		enterFullscreen: () => handleRef.current?.enterFullscreen() ?? Promise.resolve(),
 		exitFullscreen: () => handleRef.current?.exitFullscreen() ?? Promise.resolve(),
 		setQuality: (level) => handleRef.current?.setQuality(level),
@@ -374,7 +383,7 @@ const VideoPlayer = forwardRef(function VideoPlayer(props, ref) {
 		pushDanmaku: (item) => handleRef.current?.pushDanmaku(item),
 		setDanmakuEnabled: (enabled) => handleRef.current?.setDanmakuEnabled(enabled),
 		clearDanmaku: () => handleRef.current?.clearDanmaku(),
-		reconnect: (options) => handleRef.current?.reconnect(options),
+		retry: () => handleRef.current?.retry() ?? Promise.resolve(),
 		destroy: () => handleRef.current?.destroy(),
 		getCurrentTime: () => handleRef.current?.getCurrentTime() ?? 0,
 		getPlaybackContext: () => handleRef.current?.getPlaybackContext() ?? null,
@@ -416,15 +425,15 @@ const VideoPlayer = forwardRef(function VideoPlayer(props, ref) {
 				"onsentinel-close": dismissPauseImage
 			}),
 			overlayElement("sentinel-loading", {
-				visible: overlay.loadingVisible,
+				visible: showLoadingOverlay && overlay.loadingVisible,
 				text: resolveText(messages, "loading")
 			}),
-			overlay.error && overlayElement("sentinel-error", {
+			showErrorOverlay && 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"),
+				retryable: overlay.action === "retry" || overlay.action === "play",
+				"retry-label": resolveText(messages, overlay.action === "play" ? "play" : "retry"),
 				"onsentinel-retry": handleRetry
 			}),
 			!mounted && props.children

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@video-lab/react",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -34,9 +34,9 @@
     "react-dom": ">=19.0.0"
   },
   "dependencies": {
-    "@video-lab/protocol": "2.0.0",
-    "@video-lab/player-core": "2.0.0",
-    "@video-lab/player-ui": "2.0.0"
+    "@video-lab/protocol": "3.0.0",
+    "@video-lab/player-core": "3.0.0",
+    "@video-lab/player-ui": "3.0.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.0.0",