@video-lab/vue-frame 1.0.1 → 3.0.0

package/README.md

@@ -1,10 +1,10 @@
 # @video-lab/vue-frame
 
-Vue 3 iframe 薄壳(L7 · 消费面)。Video Lab Player 的 Vue 接入方式——
+Video Lab Player 的 Vue 3 iframe 接入方式。
 
 **只做技术**:创建 iframe 播放器、把 props 桥接成命令、把 iframe 事件桥接成 Vue emits。
-不含任何团队品牌 UI(团队 UI 在业务封装层 `examples/team-video-vue`,ADR-021)。
-**不再是 Vue 唯一的接入方式** —— Vue inline 是 [`@video-lab/vue`](https://www.npmjs.com/package/@video-lab/vue)(ADR-052)。
+不含任何品牌 UI，品牌 UI 由消费应用提供。
+Vue inline 接入可使用 [`@video-lab/vue`](https://www.npmjs.com/package/@video-lab/vue)。
 需要隔离 / 宿主是 SSR 框架的仍然走本包;要首帧最快、要摸 `<video>` 的用 inline。
 
 ## 安装
@@ -13,7 +13,9 @@ Vue 3 iframe 薄壳(L7 · 消费面)。Video Lab Player 的 Vue 接入方式—
 pnpm add @video-lab/vue-frame
 ```
 
-peer: `vue >= 3.5`。
+peer: `vue ^3.4.0`（支持 Vue 3.4 / 3.5，最低 3.4.0）。
+
+宿主无需升级 Vue 或相关工具链；组件复用宿主 Vue，不内嵌第二份运行时。
 
 ## 用法
 
@@ -33,7 +35,7 @@ function onError(err: PlayerError) {
 <template>
   <VideoPlayerFrame
     ref="player"
-    :source="'https://cdn.example.com/live.m3u8'"
+    :source="'https://media.example.com/live.m3u8'"
     preset="homepage-preview"
     @ready="() => console.log('ready')"
     @error="onError"
@@ -42,15 +44,15 @@ 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()`。
 
 ## Props
 
 `source` 必填,其余可选:`autoplay` `muted` `loop` `controls` `interactive`
-`playsinline` `poster` `preset` `locale` `debug`,加 URL 覆盖 `origin` / `version`
-(ADR-023,私有化 / 版本锁定 / 本地 dev 指向 embed-app dev server)。
+`playsinline` `poster` `preset` `locale` `debug`，以及 iframe 部署配置 `origin` / `version`。
+实际部署地址由内部配置提供，本包不声明公共播放器地址。
 
 **布尔 prop 不传就是 undefined**(不是 false),这样 `preset` 才能生效——比如
 `preset="homepage-preview"` 会带上 `muted: true`,只要你没显式传 `:muted="false"` 覆盖它。
@@ -58,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)
@@ -66,14 +68,56 @@ function onError(err: PlayerError) {
 组件自带客户端守卫:iframe 只在 `onMounted` 后创建,SSR 阶段渲染
 `#ssr-placeholder` 插槽(默认黑底占位)。消费方无需再包 `<ClientOnly>`。
 
+## 完整事件与命令失败
+
+`@player-event` 保持交付 raw `PlayerEvent`；需要跨重连排序、去重或识别迟到事件时使用
+`@delivered-player-event`。所有可失败命令都应 `await` 并 `catch`，并同时订阅事件流：命令
+rejection 不保证产生 `error`，播放期 `error` 也不保证对应某个命令 rejection。
+
 ## 边界
 
-- ❌ 不依赖 player-core / player-ui(那些在 iframe 内的 embed-app)
-- ❌ 不直接 import xgplayer(薄壳不接触播放技术)
-- ❌ 无团队品牌 UI
+- 不依赖 `@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 与类型定义为准。
 
 ## 相关
 
-- **ADR-052**(Vue inline 开门,取代 ADR-002)· ADR-023(iframe URL 覆盖)
-- 五种接入方式与完整 API 请联系项目维护团队获取内部使用手册。
-- 宿主、服务端与业务 UI 的责任边界请联系项目维护团队获取。
+- 完整 API 与接入方式请向项目维护团队获取。
+- 宿主、服务端与业务 UI 的责任边界请向项目维护团队获取。
+
+### 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)。