@video-lab/react-frame 1.0.1 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @video-lab/react-frame
 
-Video Lab Player 的 **React iframe 消费面(L7)**。播放器跑在独立 iframe 里,通过 frame-core 收发契约消息。
+Video Lab Player 的 React iframe 接入方式。播放器运行在独立 iframe 中，并通过通信契约收发命令与事件。
 
 对外只有一个组件 `<VideoPlayerFrame />` + 一个命令句柄。和 [`@video-lab/vue-frame`](https://www.npmjs.com/package/@video-lab/vue-frame) 行为对齐。
 
@@ -33,7 +33,7 @@ function Player() {
   return (
     <VideoPlayerFrame
       ref={ref}
-      source="https://cdn.example.com/live/master.m3u8"
+      source="https://media.example.com/live/master.m3u8"
       autoplay
       muted
       onReady={({ duration, quality, subtitles }) => {}}
@@ -55,27 +55,33 @@ ref.current?.seek(30)
 await ref.current?.enterFullscreen()
 ```
 
-### 私有化部署
+### 配置 iframe 地址
 
-iframe 默认指向官方 CDN。自建时用 `origin` 覆盖(ADR-023):
+`origin` 与 `version` 应由内部部署配置提供；本包不声明公共播放器地址。以下值仅为占位符：
 
 <!-- doc-snippet-preamble
 import { VideoPlayerFrame } from '@video-lab/react-frame'
 -->
 ```tsx
 <VideoPlayerFrame
-  origin="https://player.your-domain.com"
-  version="v3"
-  source="https://cdn.example.com/master.m3u8"
+  origin="https://player.example.com"
+  version="v1"
+  source="https://media.example.com/master.m3u8"
 />
 ```
 
 ## 边界
 
-- **薄壳**——本包不含播放逻辑,只负责建 iframe、握手、转发命令与事件。播放能力在 iframe 内的 embed-app
-- **props 面和 `@video-lab/react` 对齐**,多出 `origin` / `version` 两个 iframe 专属项(cross-mode-parity 测试保障)
-- **不做团队品牌 UI**(ADR-021);**认证只支持签名 URL**(ADR-022)
-- 业务代码通常不直接 import 本包,而是经团队封装层接入
+- **薄壳**——本包不含播放逻辑，只负责创建 iframe、握手及转发命令与事件。
+- **props 与 `@video-lab/react` 对齐**，另有 iframe 专属的 `origin` / `version`。
+- **不内置品牌 UI；认证只支持签名 URL**，不接受自定义请求头。
+- 业务应用可直接使用本组件，也可在自己的业务组件中封装它。
+
+## AI 接入 Skill
+
+安装包包含 `skills/host-integration/SKILL.md`。让宿主 AI 使用前，先确认该文件 front matter
+中的 `supportedPackages` 与已安装版本匹配；它提供接入面选择、错误/恢复和 delivered 事件的边界，
+但具体 API 仍以本 README 与类型定义为准。
 
 ## 相关
 
@@ -83,3 +89,40 @@ import { VideoPlayerFrame } from '@video-lab/react-frame'
 - 契约定义:[`@video-lab/protocol`](https://www.npmjs.com/package/@video-lab/protocol)
 
 MIT
+
+## 完整事件与命令失败
+
+`onPlayerEvent` 保持交付 raw `PlayerEvent`；需要跨重连排序、去重或识别迟到事件时使用
+`onDeliveredPlayerEvent`。所有可失败命令都应 `await` 并 `catch`，并同时订阅事件流：命令
+rejection 不保证产生 `error`，播放期 `error` 也不保证对应某个命令 rejection。
+
+### iframe 基础路径
+
+`origin` 是宿主提供的完整部署基础 URL，可包含 `/custom/player` 等目录。SDK 只追加 `/v{iframe应用版本}/`，不会自动追加 `/embed`。旧部署仍在 `/embed/v…/` 时，请把 `/embed` 显式保留在 `origin` 中；版本目录不要写进 `origin`。
+
+## 错误 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。
+iframe 须使用支持该功能、已部署的精确版本 `/v1.2.0/`；旧 iframe 可能忽略新配置。
+
+## 宿主网页全屏
+
+通过 `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)。

package/dist/index.cjs

@@ -29,12 +29,18 @@ function useFrameConnection(props) {
 			container,
 			source: p.source,
 			config: toConfig(p),
+			pageFullscreen: p.pageFullscreen,
 			...p.origin !== void 0 ? { origin: p.origin } : {},
 			...p.version !== void 0 ? { version: p.version } : {},
 			onEvent: (event) => {
 				if (event.event === "play" || event.event === "error") setHostPosterVisible(false);
 				forward(event, propsRef.current);
 			},
+			onDeliveredEvent: (event) => {
+				try {
+					propsRef.current.onDeliveredPlayerEvent?.(event);
+				} catch {}
+			},
 			debug: p.debug ?? false
 		}).then((h) => {
 			if (cancelled) {
@@ -95,6 +101,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;
@@ -107,9 +116,9 @@ function toConfig(props) {
 * iframe 事件 → React 回调。名字从 wire 上的小写拼写换成 `onCamelCase`。
 * 和 vue-frame 的 forward 一一对应(cross-mode-parity):同样的事件、同样的 payload 裁剪。
 *
-* **契约声明的 19 个事件必须一个不少地出现在这里**,由 `protocol/tests/consumer-surface.contract.test.ts`
+* **契约声明的 27 个事件必须一个不少地出现在这里**,由 `protocol/tests/consumer-surface.contract.test.ts`
 * 静态断言。曾经漏过 seeking / seeked / waiting / playing 四个,理由是"团队封装层没用到" ——
-* 但静态 iframe 模式是裸广播、19 个全发,于是同一份契约在四种接入方式下能收到的事件
+* 但静态 iframe 模式是裸广播、27 个全发,于是同一份契约在四种接入方式下能收到的事件
 * 不一样,parity 红线实际已破。别再以"业务暂时用不到"为由少接一个。
 */
 function forward(event, props) {
@@ -159,18 +168,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;
@@ -195,6 +192,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;
@@ -263,6 +263,7 @@ const VideoPlayerFrame = (0, react.forwardRef)(function VideoPlayerFrame(props,
 		setMuted: (muted) => handleRef.current?.setMuted(muted) ?? Promise.resolve(),
 		setVolume: (volume) => handleRef.current?.setVolume(volume) ?? Promise.resolve(),
 		setPlaybackRate: (rate) => handleRef.current?.setPlaybackRate(rate) ?? Promise.resolve(),
+		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) ?? Promise.resolve(),
@@ -271,7 +272,7 @@ const VideoPlayerFrame = (0, react.forwardRef)(function VideoPlayerFrame(props,
 		pushDanmaku: (item) => handleRef.current?.pushDanmaku(item) ?? Promise.resolve(),
 		setDanmakuEnabled: (enabled) => handleRef.current?.setDanmakuEnabled(enabled) ?? Promise.resolve(),
 		clearDanmaku: () => handleRef.current?.clearDanmaku() ?? Promise.resolve(),
-		reconnect: (options) => handleRef.current?.reconnect(options) ?? Promise.resolve(),
+		retry: () => handleRef.current?.retry() ?? Promise.resolve(),
 		destroy: () => handleRef.current?.destroy() ?? Promise.resolve(),
 		getCurrentTime: () => handleRef.current?.getCurrentTime() ?? 0,
 		getPlaybackContext: () => handleRef.current?.getPlaybackContext() ?? null,

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 { PlayerFrameHandle } from "@video-lab/frame-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 = PlayerFrameHandle;
  * protocol 的 PlayerEvent —— 和 vue-frame 的 emits 一一对应(cross-mode-parity)。
  */
 interface VideoPlayerFrameProps {
+  /** 挂载期间保持稳定的宿主网页全屏布局适配器。 */
+  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;
@@ -57,9 +65,9 @@ interface VideoPlayerFrameProps {
    */
   pauseImage?: string | PauseImageConfig;
   preset?: PresetName;
-  /** iframe URL origin 覆盖(私有化 / dev)。默认官方 CDN */
+  /** iframe 部署基础 URL，可包含自定义目录；SDK 只追加版本目录，不追加 embed。 */
   origin?: string;
-  /** iframe URL 版本段覆盖。默认跟随契约 major(`DEFAULT_VERSION`,ADR-053) */
+  /** iframe 版本目录；默认使用 DEFAULT_VERSION 指定的 iframe 应用精确版本。 */
   version?: string;
   /** 传给 iframe 内 xgplayer 的 i18n 配置 */
   locale?: LocaleConfig;
@@ -78,6 +86,7 @@ interface VideoPlayerFrameProps {
   children?: ReactNode;
   /** 完整的契约事件流，供遥测适配器使用；不裁剪 iframe 转发的 payload。 */
   onPlayerEvent?: (event: PlayerEvent) => void;
+  onDeliveredPlayerEvent?: (event: DeliveredPlayerEvent) => void;
   /**
    * metadata 就绪。`quality` 是可切档位清单(单码率源为空数组),团队层据此渲染清晰度菜单;
    * `subtitles` 是可切字幕轨清单(无字幕源为空/缺省,契约 1.0.0 起可选,ADR-027),团队层据此渲染字幕菜单。
@@ -127,12 +136,6 @@ interface VideoPlayerFrameProps {
   }) => void;
   onError?: (payload: PlayerError) => void;
   onAutoplayBlocked?: () => void;
-  onReconnectStart?: (payload: {
-    attempt: number;
-    maxAttempts: number;
-  }) => void;
-  onReconnectSuccess?: () => void;
-  onReconnectFailed?: () => void;
   onCompatWarning?: (payload: {
     code: string;
     message: string;
@@ -156,11 +159,9 @@ interface VideoPlayerFrameProps {
    * `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)。
    *
@@ -203,6 +204,8 @@ interface VideoPlayerFrameProps {
    * ⚠️ 它不是掉帧率,也不与 `stalled` 重复(后者是缓冲驱动的等待)。
    */
   onFrameFreeze?: (payload: FrameFreezePayload) => void;
+  /** 实际网页全屏状态变化。 */
+  onPageFullscreenChange?: (payload: PageFullscreenState$1) => void;
   /**
    * 用户动作(ADR-075),经白名单过滤,只含**发生在 SDK 内部**的那些。
    *
@@ -225,6 +228,8 @@ interface VideoPlayerFrameHandle {
   setMuted(muted: boolean): Promise<void>;
   setVolume(volume: number): Promise<void>;
   setPlaybackRate(rate: number): Promise<void>;
+  /** 设置网页全屏；必须等宿主布局与 iframe 状态确认。 */
+  setPageFullscreen(active: boolean): Promise<void>;
   /** 进入全屏(容器托管,不碰 video 原生入口,iOS 微信崩溃入口由 FullscreenGuard 中和) */
   enterFullscreen(): Promise<void>;
   /** 退出全屏 */
@@ -240,9 +245,7 @@ interface VideoPlayerFrameHandle {
   setDanmakuEnabled(enabled: boolean): Promise<void>;
   /** 清空屏上弹幕(ADR-028) */
   clearDanmaku(): Promise<void>;
-  reconnect(options?: {
-    resetCounter?: boolean;
-  }): Promise<void>;
+  retry(): Promise<void>;
   destroy(): Promise<void>;
   getCurrentTime(): number;
   getDuration(): number;
@@ -280,5 +283,5 @@ interface VideoPlayerFrameHandle {
  */
 declare const VideoPlayerFrame: import("react").ForwardRefExoticComponent<VideoPlayerFrameProps & import("react").RefAttributes<VideoPlayerFrameHandle>>;
 //#endregion
-export { type DanmakuConfig, type DanmakuItem, type MediaSource, type PlayerError, type PlayerHandle, type QualityLevel, type SubtitleTrackInfo, VideoPlayerFrame, type VideoPlayerFrameHandle, type VideoPlayerFrameProps };
+export { type DanmakuConfig, type DanmakuItem, type MediaSource, type PageFullscreenAdapter, type PageFullscreenState, type PlayerError, type PlayerHandle, type QualityLevel, type SubtitleTrackInfo, VideoPlayerFrame, type VideoPlayerFrameHandle, type VideoPlayerFrameProps };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { CSSProperties, ReactNode } from "react";
 import { PlayerFrameHandle } from "@video-lab/frame-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 { 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";
 //#region src/types.d.ts
 /**
  * 消费方拿到的播放器句柄(逃生舱)。
@@ -18,12 +18,20 @@ type PlayerHandle = PlayerFrameHandle;
  * protocol 的 PlayerEvent —— 和 vue-frame 的 emits 一一对应(cross-mode-parity)。
  */
 interface VideoPlayerFrameProps {
+  /** 挂载期间保持稳定的宿主网页全屏布局适配器。 */
+  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;
@@ -57,9 +65,9 @@ interface VideoPlayerFrameProps {
    */
   pauseImage?: string | PauseImageConfig;
   preset?: PresetName;
-  /** iframe URL origin 覆盖(私有化 / dev)。默认官方 CDN */
+  /** iframe 部署基础 URL，可包含自定义目录；SDK 只追加版本目录，不追加 embed。 */
   origin?: string;
-  /** iframe URL 版本段覆盖。默认跟随契约 major(`DEFAULT_VERSION`,ADR-053) */
+  /** iframe 版本目录；默认使用 DEFAULT_VERSION 指定的 iframe 应用精确版本。 */
   version?: string;
   /** 传给 iframe 内 xgplayer 的 i18n 配置 */
   locale?: LocaleConfig;
@@ -78,6 +86,7 @@ interface VideoPlayerFrameProps {
   children?: ReactNode;
   /** 完整的契约事件流，供遥测适配器使用；不裁剪 iframe 转发的 payload。 */
   onPlayerEvent?: (event: PlayerEvent) => void;
+  onDeliveredPlayerEvent?: (event: DeliveredPlayerEvent) => void;
   /**
    * metadata 就绪。`quality` 是可切档位清单(单码率源为空数组),团队层据此渲染清晰度菜单;
    * `subtitles` 是可切字幕轨清单(无字幕源为空/缺省,契约 1.0.0 起可选,ADR-027),团队层据此渲染字幕菜单。
@@ -127,12 +136,6 @@ interface VideoPlayerFrameProps {
   }) => void;
   onError?: (payload: PlayerError) => void;
   onAutoplayBlocked?: () => void;
-  onReconnectStart?: (payload: {
-    attempt: number;
-    maxAttempts: number;
-  }) => void;
-  onReconnectSuccess?: () => void;
-  onReconnectFailed?: () => void;
   onCompatWarning?: (payload: {
     code: string;
     message: string;
@@ -156,11 +159,9 @@ interface VideoPlayerFrameProps {
    * `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)。
    *
@@ -203,6 +204,8 @@ interface VideoPlayerFrameProps {
    * ⚠️ 它不是掉帧率,也不与 `stalled` 重复(后者是缓冲驱动的等待)。
    */
   onFrameFreeze?: (payload: FrameFreezePayload) => void;
+  /** 实际网页全屏状态变化。 */
+  onPageFullscreenChange?: (payload: PageFullscreenState$1) => void;
   /**
    * 用户动作(ADR-075),经白名单过滤,只含**发生在 SDK 内部**的那些。
    *
@@ -225,6 +228,8 @@ interface VideoPlayerFrameHandle {
   setMuted(muted: boolean): Promise<void>;
   setVolume(volume: number): Promise<void>;
   setPlaybackRate(rate: number): Promise<void>;
+  /** 设置网页全屏；必须等宿主布局与 iframe 状态确认。 */
+  setPageFullscreen(active: boolean): Promise<void>;
   /** 进入全屏(容器托管,不碰 video 原生入口,iOS 微信崩溃入口由 FullscreenGuard 中和) */
   enterFullscreen(): Promise<void>;
   /** 退出全屏 */
@@ -240,9 +245,7 @@ interface VideoPlayerFrameHandle {
   setDanmakuEnabled(enabled: boolean): Promise<void>;
   /** 清空屏上弹幕(ADR-028) */
   clearDanmaku(): Promise<void>;
-  reconnect(options?: {
-    resetCounter?: boolean;
-  }): Promise<void>;
+  retry(): Promise<void>;
   destroy(): Promise<void>;
   getCurrentTime(): number;
   getDuration(): number;
@@ -280,5 +283,5 @@ interface VideoPlayerFrameHandle {
  */
 declare const VideoPlayerFrame: import("react").ForwardRefExoticComponent<VideoPlayerFrameProps & import("react").RefAttributes<VideoPlayerFrameHandle>>;
 //#endregion
-export { type DanmakuConfig, type DanmakuItem, type MediaSource, type PlayerError, type PlayerHandle, type QualityLevel, type SubtitleTrackInfo, VideoPlayerFrame, type VideoPlayerFrameHandle, type VideoPlayerFrameProps };
+export { type DanmakuConfig, type DanmakuItem, type MediaSource, type PageFullscreenAdapter, type PageFullscreenState, type PlayerError, type PlayerHandle, type QualityLevel, type SubtitleTrackInfo, VideoPlayerFrame, type VideoPlayerFrameHandle, type VideoPlayerFrameProps };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -28,12 +28,18 @@ function useFrameConnection(props) {
 			container,
 			source: p.source,
 			config: toConfig(p),
+			pageFullscreen: p.pageFullscreen,
 			...p.origin !== void 0 ? { origin: p.origin } : {},
 			...p.version !== void 0 ? { version: p.version } : {},
 			onEvent: (event) => {
 				if (event.event === "play" || event.event === "error") setHostPosterVisible(false);
 				forward(event, propsRef.current);
 			},
+			onDeliveredEvent: (event) => {
+				try {
+					propsRef.current.onDeliveredPlayerEvent?.(event);
+				} catch {}
+			},
 			debug: p.debug ?? false
 		}).then((h) => {
 			if (cancelled) {
@@ -94,6 +100,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;
@@ -106,9 +115,9 @@ function toConfig(props) {
 * iframe 事件 → React 回调。名字从 wire 上的小写拼写换成 `onCamelCase`。
 * 和 vue-frame 的 forward 一一对应(cross-mode-parity):同样的事件、同样的 payload 裁剪。
 *
-* **契约声明的 19 个事件必须一个不少地出现在这里**,由 `protocol/tests/consumer-surface.contract.test.ts`
+* **契约声明的 27 个事件必须一个不少地出现在这里**,由 `protocol/tests/consumer-surface.contract.test.ts`
 * 静态断言。曾经漏过 seeking / seeked / waiting / playing 四个,理由是"团队封装层没用到" ——
-* 但静态 iframe 模式是裸广播、19 个全发,于是同一份契约在四种接入方式下能收到的事件
+* 但静态 iframe 模式是裸广播、27 个全发,于是同一份契约在四种接入方式下能收到的事件
 * 不一样,parity 红线实际已破。别再以"业务暂时用不到"为由少接一个。
 */
 function forward(event, props) {
@@ -158,18 +167,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;
@@ -194,6 +191,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;
@@ -262,6 +262,7 @@ const VideoPlayerFrame = forwardRef(function VideoPlayerFrame(props, ref) {
 		setMuted: (muted) => handleRef.current?.setMuted(muted) ?? Promise.resolve(),
 		setVolume: (volume) => handleRef.current?.setVolume(volume) ?? Promise.resolve(),
 		setPlaybackRate: (rate) => handleRef.current?.setPlaybackRate(rate) ?? Promise.resolve(),
+		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) ?? Promise.resolve(),
@@ -270,7 +271,7 @@ const VideoPlayerFrame = forwardRef(function VideoPlayerFrame(props, ref) {
 		pushDanmaku: (item) => handleRef.current?.pushDanmaku(item) ?? Promise.resolve(),
 		setDanmakuEnabled: (enabled) => handleRef.current?.setDanmakuEnabled(enabled) ?? Promise.resolve(),
 		clearDanmaku: () => handleRef.current?.clearDanmaku() ?? Promise.resolve(),
-		reconnect: (options) => handleRef.current?.reconnect(options) ?? Promise.resolve(),
+		retry: () => handleRef.current?.retry() ?? Promise.resolve(),
 		destroy: () => handleRef.current?.destroy() ?? Promise.resolve(),
 		getCurrentTime: () => handleRef.current?.getCurrentTime() ?? 0,
 		getPlaybackContext: () => handleRef.current?.getPlaybackContext() ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@video-lab/react-frame",
-  "version": "1.0.1",
+  "version": "3.0.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -25,7 +25,8 @@
     "dist/**/*.d.ts",
     "dist/**/*.d.cts",
     "dist/**/*.d.mts",
-    "dist/**/*.css"
+    "dist/**/*.css",
+    "skills/**"
   ],
   "sideEffects": false,
   "peerDependencies": {
@@ -33,8 +34,8 @@
     "react-dom": ">=19.0.0"
   },
   "dependencies": {
-    "@video-lab/protocol": "1.0.1",
-    "@video-lab/frame-core": "1.0.1"
+    "@video-lab/protocol": "3.0.0",
+    "@video-lab/frame-core": "3.0.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.0.0",
@@ -53,7 +54,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsdown src/index.ts --format esm,cjs --dts --clean",
+    "build": "node ../../scripts/sync-public-host-skill.mjs react-frame && tsdown src/index.ts --format esm,cjs --dts --clean",
     "dev": "tsdown src/index.ts --format esm,cjs --dts --watch --no-clean",
     "test": "vitest run",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit"

package/skills/host-integration/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: video-lab-host-integration
+skillVersion: 1
+sdkMajor: 2
+supportedPackages:
+  - '@video-lab/react-frame@2.0.0'
+  - '@video-lab/vue-frame@2.0.0'
+description: >-
+  在业务宿主项目中接入 Video Lab Player 时使用。选择五种接入面之一，完成可验证 demo，
+  并交接 SDK、宿主与服务端责任；不用于修改 SDK 契约或设计品牌 UI。
+---
+
+# Video Lab Player · 宿主接入
+
+## 取得与版本绑定
+
+在已安装的 `@video-lab/react-frame` 或 `@video-lab/vue-frame` 中读取
+`skills/host-integration/SKILL.md`，再将该目录复制到宿主项目的 AI Skill 目录。先核对
+front matter 的 `supportedPackages` 与安装版本；它是**宿主 AI 的公开接入资料**，不是 npm
+运行时文件，也不是 iframe 部署目录的一部分。
+
+API 以已安装包的类型定义和对应 README 为准；本 Skill 只负责选择接入面与交接流程，不能替代类型。
+
+## 先选接入面
+
+| 宿主条件 | 选择 | 不能承诺 |
+| --- | --- | --- |
+| React/Vue 页面，追求性能与深度组合 | `@video-lab/react` / `@video-lab/vue` | 直接操作 xgplayer 私有实例。 |
+| 需要样式、脚本或故障隔离，仍要命令和事件 | `@video-lab/react-frame` / `@video-lab/vue-frame` | 同步读取 iframe DOM 或媒体元素。 |
+| CMS、Markdown、无构建工具，只需嵌入与事件订阅 | 静态 iframe URL，可选 `@video-lab/embed-helper` | 播放命令、换源、字幕、弹幕和实例级握手。 |
+
+若静态 iframe 的能力不够，升级到 React/Vue inline 或 iframe。不要私发 `postMessage`、把 JSON 塞进 query，或猜测未在类型中出现的 SDK API。
+
+## 实施顺序
+
+1. 在宿主项目建立独立 demo 页面，使用服务端提供的完整、已授权 `MediaSource`。不要传 headers、token 刷新回调或业务 ID 给 SDK。
+2. 以公开 `ready`、`PlayerEvent`、错误码和 `playablechange` 驱动业务状态。runtime Loading 只从 `!playable && recoverable` 派生。跨重连 telemetry、排序、去重和迟到事件识别使用 delivered outlet：React iframe 是 `onDeliveredPlayerEvent`，Vue iframe 是 `@delivered-player-event`；旧 iframe 只能提供 raw `PlayerEvent`。
+3. 业务服务负责签名 URL、CORS、权益、字幕资源、弹幕审核与限流；品牌 UI、CTA、菜单和无障碍交互留在宿主。
+4. 业务 telemetry 只记录允许的播放器事实：不要发送完整媒体 URL、query、签名、token、cookie、身份或弹幕正文。
+5. 用真实或受控媒体覆盖首次加载、自动播放拒绝、可恢复/不可恢复错误、签名换源、字幕失败与卸载清理；恢复必须有时间或画面推进证据。
+6. 所有可失败命令都 `await` 并 `catch`；命令 rejection 不保证触发 `error`，播放期 `error` 也不保证对应某个命令 rejection。
+
+## 交接模板
+
+```md
+### Video Lab 宿主接入结论
+
+- 接入面：<React inline / Vue inline / React iframe / Vue iframe / 静态 iframe>
+- 选择原因：<隔离、性能或无构建工具约束>
+- 已验证：<源、事件、Loading、恢复、销毁>
+- SDK 已完成：<实际使用的公开能力>
+- 宿主待完成：<UI、状态、telemetry、无障碍、验收>
+- 服务端/CDN 待完成：<签名 URL、CORS、内容、互动治理>
+- 不支持/风险：<模式限制与明确的产品决定>
+```
+
+## 使用资料的优先级
+
+1. 已安装 `@video-lab/*` 包的 README 和类型定义是 API 的最终事实。
+2. 接入交接单提供当前的 iframe origin、版本路径、媒体源和部署边界；不得猜测或硬编码内部地址。
+3. 宿主项目的安全、品牌 UI、业务 telemetry 与服务端约束优先于本 Skill 的通用示例。
+
+## 宿主要求隐藏单个内置控件
+
+使用初始化 `controlVisibility`，例如 `{ cssFullscreen: false }`；静态 iframe 使用 `controlCssFullscreen=0`。
+保留 `controls` 布尔总开关，不覆盖内部 CSS、不访问私有插件。八字段与重建语义见
+[控件显示指南](../../guides/PLAYER-CONTROL-VISIBILITY.md)。先确认安装版本实际包含该字段，
+iframe 同时核实支持此功能的精确应用版本已部署；旧 iframe 可能忽略新字段。
+
+## 网页全屏交接
+
+iframe CSS 全屏必须由宿主布局。四个框架组件传稳定的 `pageFullscreen` 适配器（`setActive`、`dispose`），静态 URL 用 `createPageFullscreenController` 绑定精确 origin 与 iframe。确认、Esc 和销毁清理由 SDK 编排；宿主负责层级、滚动、焦点恢复，不移动 iframe。未接适配器的新 iframe 隐藏入口。旧 iframe 需配套升级，浏览器原生全屏仍独立。以对应包 README 和 `docs/guides/PAGE-FULLSCREEN.md` 为准。