@video-lab/react-frame 4.0.0 → 4.1.0

package/README.md

@@ -121,6 +121,7 @@ MIT
 ## 完整事件与命令失败
 
 `onPlayerEvent` 交付完整 `PlayerEvent`，其顶层 `delivery` 包含生产端排序、去重与迟到事件证据。
+`PlayerEvent` 用 `event` 字段区分类型（如 `e.event === 'ready'`），数据在 `payload`；它没有 `type` 字段。
 旧 iframe 的事件可缺少该字段。宿主主动调用的每次可失败命令都应处理 rejection，可在业务封装层
 集中处理，不必在每个按钮里重复写 `catch`。命令 rejection 不保证产生 `error`，播放期 `error`
 也不保证对应某个命令 rejection。`void ref.current?.play()` 不会处理 Promise rejection。

package/dist/index.cjs

@@ -168,6 +168,10 @@ function useFrameConnection(props, hasCustomPoster = false, hasCustomPause = fal
 		pauseIntentPendingRef.current = false;
 		setHostPauseVisible(false);
 		awaitingNewSourceRef.current = "switching";
+		setLoadingOverlay({
+			phase: firstFrameSeenRef.current ? "runtime" : "initial",
+			reason: "source_switching"
+		});
 		handleRef.current?.setSourceSwitching(true).catch(() => {});
 		forwardWithDelivery({
 			event: "playablechange",
@@ -242,6 +246,7 @@ function useFrameConnection(props, hasCustomPoster = false, hasCustomPause = fal
 		let cancelled = false;
 		const container = containerRef.current;
 		if (!container) return;
+		const handshake = new AbortController();
 		const p = propsRef.current;
 		setHostOwnsOverlays(false);
 		(0, _video_lab_frame_core.createPlayerFrame)({
@@ -249,6 +254,7 @@ function useFrameConnection(props, hasCustomPoster = false, hasCustomPause = fal
 			source: activeSourceRef.current,
 			config: toConfig(p, hasCustomPoster, hasCustomPause),
 			renderDefaultFallback: false,
+			signal: handshake.signal,
 			onHostOverlayOwnershipChange: (owned) => setHostOwnsOverlays(owned),
 			sourceSwitching: sourceSwitchRef.current !== null,
 			pageFullscreen: p.pageFullscreen,
@@ -310,17 +316,18 @@ function useFrameConnection(props, hasCustomPoster = false, hasCustomPause = fal
 					}
 				}
 				if (event.event === "firstframe" || event.event === "timeupdate") if (awaitingNewSourceRef.current === "switching") {} else {
-					if (awaitingNewSourceRef.current === "new-source") awaitingNewSourceRef.current = false;
+					const newSourceArrived = awaitingNewSourceRef.current === "new-source";
+					if (newSourceArrived) awaitingNewSourceRef.current = false;
 					firstFrameSeenRef.current = true;
 					setHostPosterVisible(false);
-					setLoadingOverlay(null);
+					setLoadingOverlay((prev) => newSourceArrived || prev?.phase !== "runtime" ? null : prev);
 				}
 				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 : {
+					if (!(awaitingNewSourceRef.current !== false && (reason === "initializing" || reason === "ok"))) setLoadingOverlay(!firstFrameSeenRef.current ? terminalError || blockingAction ? null : {
 						phase: "initial",
 						reason
 					} : !playable && recoverable && reason !== "initializing" ? {
@@ -350,6 +357,7 @@ function useFrameConnection(props, hasCustomPoster = false, hasCustomPause = fal
 		});
 		return () => {
 			cancelled = true;
+			handshake.abort();
 			handleRef.current?.destroy();
 			handleRef.current = null;
 		};

package/dist/index.d.cts

@@ -301,4 +301,3 @@ interface VideoPlayerFrameHandle {
 declare const VideoPlayerFrame: import("react").ForwardRefExoticComponent<VideoPlayerFrameProps & import("react").RefAttributes<VideoPlayerFrameHandle>>;
 //#endregion
 export { type DanmakuConfig, type DanmakuItem, type LoadingOverlayContext, type MediaSource, type PageFullscreenAdapter, type PageFullscreenState, type PlayerError, type PlayerHandle, PlayerProvider, type PlayerProviderProps, type QualityLevel, type ResolveSource, type SubtitleTrackInfo, VideoPlayerFrame, type VideoPlayerFrameHandle, type VideoPlayerFrameProps, usePlayerI18n };
-//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -301,4 +301,3 @@ interface VideoPlayerFrameHandle {
 declare const VideoPlayerFrame: import("react").ForwardRefExoticComponent<VideoPlayerFrameProps & import("react").RefAttributes<VideoPlayerFrameHandle>>;
 //#endregion
 export { type DanmakuConfig, type DanmakuItem, type LoadingOverlayContext, type MediaSource, type PageFullscreenAdapter, type PageFullscreenState, type PlayerError, type PlayerHandle, PlayerProvider, type PlayerProviderProps, type QualityLevel, type ResolveSource, type SubtitleTrackInfo, VideoPlayerFrame, type VideoPlayerFrameHandle, type VideoPlayerFrameProps, usePlayerI18n };
-//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -167,6 +167,10 @@ function useFrameConnection(props, hasCustomPoster = false, hasCustomPause = fal
 		pauseIntentPendingRef.current = false;
 		setHostPauseVisible(false);
 		awaitingNewSourceRef.current = "switching";
+		setLoadingOverlay({
+			phase: firstFrameSeenRef.current ? "runtime" : "initial",
+			reason: "source_switching"
+		});
 		handleRef.current?.setSourceSwitching(true).catch(() => {});
 		forwardWithDelivery({
 			event: "playablechange",
@@ -241,6 +245,7 @@ function useFrameConnection(props, hasCustomPoster = false, hasCustomPause = fal
 		let cancelled = false;
 		const container = containerRef.current;
 		if (!container) return;
+		const handshake = new AbortController();
 		const p = propsRef.current;
 		setHostOwnsOverlays(false);
 		createPlayerFrame({
@@ -248,6 +253,7 @@ function useFrameConnection(props, hasCustomPoster = false, hasCustomPause = fal
 			source: activeSourceRef.current,
 			config: toConfig(p, hasCustomPoster, hasCustomPause),
 			renderDefaultFallback: false,
+			signal: handshake.signal,
 			onHostOverlayOwnershipChange: (owned) => setHostOwnsOverlays(owned),
 			sourceSwitching: sourceSwitchRef.current !== null,
 			pageFullscreen: p.pageFullscreen,
@@ -309,17 +315,18 @@ function useFrameConnection(props, hasCustomPoster = false, hasCustomPause = fal
 					}
 				}
 				if (event.event === "firstframe" || event.event === "timeupdate") if (awaitingNewSourceRef.current === "switching") {} else {
-					if (awaitingNewSourceRef.current === "new-source") awaitingNewSourceRef.current = false;
+					const newSourceArrived = awaitingNewSourceRef.current === "new-source";
+					if (newSourceArrived) awaitingNewSourceRef.current = false;
 					firstFrameSeenRef.current = true;
 					setHostPosterVisible(false);
-					setLoadingOverlay(null);
+					setLoadingOverlay((prev) => newSourceArrived || prev?.phase !== "runtime" ? null : prev);
 				}
 				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 : {
+					if (!(awaitingNewSourceRef.current !== false && (reason === "initializing" || reason === "ok"))) setLoadingOverlay(!firstFrameSeenRef.current ? terminalError || blockingAction ? null : {
 						phase: "initial",
 						reason
 					} : !playable && recoverable && reason !== "initializing" ? {
@@ -349,6 +356,7 @@ function useFrameConnection(props, hasCustomPoster = false, hasCustomPause = fal
 		});
 		return () => {
 			cancelled = true;
+			handshake.abort();
 			handleRef.current?.destroy();
 			handleRef.current = null;
 		};
@@ -826,4 +834,3 @@ const VideoPlayerFrame = forwardRef(function VideoPlayerFrame(rawProps, ref) {
 //#endregion
 export { PlayerProvider, VideoPlayerFrame, usePlayerI18n };
 
-//# sourceMappingURL=index.mjs.map

package/package.json

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

package/skills/host-integration/SKILL.md

@@ -3,8 +3,8 @@ name: video-lab-host-integration
 skillVersion: 1
 sdkMajor: 4
 supportedPackages:
-  - '@video-lab/react-frame@4.0.0'
-  - '@video-lab/vue-frame@4.0.0'
+  - '@video-lab/react-frame@4.1.0'
+  - '@video-lab/vue-frame@4.1.0'
 description: >-
   在业务宿主项目中接入 Video Lab Player 时使用。选择五种接入面之一，完成可验证 demo，
   并交接 SDK、宿主与服务端责任；不用于修改 SDK 契约或设计品牌 UI。