@video-lab/vue-frame 2.0.0 → 3.0.0

package/README.md

@@ -44,7 +44,7 @@ function onError(err: PlayerError) {
 ```
 
 命令通过 template ref 下发:`await player.value?.play()` / `pause()` / `seek(t)` /
-`setMuted()` / `setVolume()` / `setPlaybackRate()` / `setQuality()` / `reconnect()` /
+`setMuted()` / `setVolume()` / `setPlaybackRate()` / `setQuality()` / `retry()` /
 `destroy()`,以及同步读数 `getCurrentTime()` / `getDuration()` 和逃生舱
 `getPlayerHandle()`。
 
@@ -60,7 +60,7 @@ function onError(err: PlayerError) {
 ## Emits
 
 `ready` `play` `pause` `ended` `timeUpdate` `volumeChange` `error`
-`autoplayBlocked` `reconnectStart` `reconnectSuccess` `reconnectFailed`
+`autoplayBlocked` `playableChange`
 `compatWarning`(模板里用 kebab-case:`@time-update` 等)。
 
 ## SSR(Nuxt)
@@ -68,12 +68,24 @@ function onError(err: PlayerError) {
 组件自带客户端守卫:iframe 只在 `onMounted` 后创建,SSR 阶段渲染
 `#ssr-placeholder` 插槽(默认黑底占位)。消费方无需再包 `<ClientOnly>`。
 
+## 完整事件与命令失败
+
+`@player-event` 保持交付 raw `PlayerEvent`；需要跨重连排序、去重或识别迟到事件时使用
+`@delivered-player-event`。所有可失败命令都应 `await` 并 `catch`，并同时订阅事件流：命令
+rejection 不保证产生 `error`，播放期 `error` 也不保证对应某个命令 rejection。
+
 ## 边界
 
 - 不依赖 `@video-lab/player-core` / `@video-lab/player-ui`。
 - 不直接 import xgplayer。
 - 不内置品牌 UI。
 
+## AI 接入 Skill
+
+安装包包含 `skills/host-integration/SKILL.md`。让宿主 AI 使用前，先确认该文件 front matter
+中的 `supportedPackages` 与已安装版本匹配；它提供接入面选择、错误/恢复和 delivered 事件的边界，
+但具体 API 仍以本 README 与类型定义为准。
+
 ## 相关
 
 - 完整 API 与接入方式请向项目维护团队获取。
@@ -82,3 +94,30 @@ function onError(err: PlayerError) {
 ### iframe 基础路径
 
 `origin` 是宿主提供的完整部署基础 URL，可包含 `/custom/player` 等目录。SDK 只追加 `/v{iframe应用版本}/`，不会自动追加 `/embed`。旧部署仍在 `/embed/v…/` 时，请把 `/embed` 显式保留在 `origin` 中；版本目录不要写进 `origin`。
+
+## 错误 UI 接管
+
+通过 `:show-error-overlay="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)。