@video-lab/vue 2.0.0 → 3.0.1

package/README.md

@@ -79,3 +79,35 @@ Vue 编译器不参与。
 
 - 完整 API 与接入方式请向项目维护团队获取。
 - 契约定义：[ `@video-lab/protocol` ](https://www.npmjs.com/package/@video-lab/protocol)
+
+## 错误 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。
+
+## 宿主网页全屏
+
+通过 `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)。
+
+## 完整事件与命令失败
+
+`@player-event` 保持交付 raw `PlayerEvent`；需要跨重连排序、去重或识别迟到事件时使用
+`@delivered-player-event`。所有可失败命令都应 `await` 并 `catch`，并同时订阅事件流：命令
+rejection 不保证产生 `error`，播放期 `error` 也不保证对应某个命令 rejection。