@video-lab/embed-helper 4.1.2 → 4.1.4

package/README.md

@@ -8,6 +8,12 @@ iframe 里播放器广播出来的契约事件。宿主页面必须允许 `<scri
 
 只依赖 [`@video-lab/protocol`](https://www.npmjs.com/package/@video-lab/protocol),无框架依赖。
 
+安装包附带[宿主接入 AI Skill](./skills/host-integration/SKILL.md)和
+[静态 iframe URL 参考](./skills/host-integration/references/static-iframe.md)。若使用 npm 包，
+复制整个 `skills/host-integration/` 到宿主 AI 的 Skill 目录并核对版本；纯 URL 用户可由部署方
+离线取得与已部署 iframe 应用版本匹配的整套资料。画中画、封面、Loading、QoE 和 403 的
+模式限制见[功能配方](./skills/host-integration/references/feature-recipes.md)。具体 API 以本 README、导出类型和部署版本为准。
+
 ## 两种用法
 
 ### 1. `<script>` 标签(无构建工具)
@@ -162,4 +168,4 @@ iframe 须使用支持该功能、已部署的精确版本；旧 iframe 可能
 
 静态 iframe 使用 `createPageFullscreenController({ iframe, origin, adapter, onChange? })`；宿主提供 `setActive(active)` / `dispose()`，销毁时调用控制器 `destroy()`。此通道只处理网页全屏。
 
-详见[网页全屏接入与完整参考实现](../../docs/guides/PAGE-FULLSCREEN.md)。iframe 需要新版宿主与 iframe 协商支持；未启用时新入口不可用。浏览器原生全屏接口保持独立。
+网页全屏的宿主责任与接口见[包内 API 参考](./skills/host-integration/references/offline-api.md#网页全屏)。iframe 需要新版宿主与 iframe 协商支持；未启用时新入口不可用。浏览器原生全屏接口保持独立。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@video-lab/embed-helper",
-  "version": "4.1.2",
+  "version": "4.1.4",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -27,11 +27,12 @@
     "dist/**/*.d.ts",
     "dist/**/*.d.cts",
     "dist/**/*.d.mts",
-    "dist/**/*.css"
+    "dist/**/*.css",
+    "skills/**"
   ],
   "sideEffects": false,
   "dependencies": {
-    "@video-lab/protocol": "4.1.2"
+    "@video-lab/protocol": "4.1.4"
   },
   "devDependencies": {
     "tsdown": "^0.22.9",
@@ -43,7 +44,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsdown",
+    "build": "node ../../scripts/sync-public-host-skill.mjs embed-helper && tsdown",
     "dev": "tsdown --watch --no-clean",
     "test": "vitest run",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit"

package/skills/host-integration/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: host-integration
+description: >-
+  在业务宿主中接入 Video Lab Player 时使用。按 React/Vue inline、React/Vue iframe
+  或静态 iframe URL 选择接入面，完成可验证的播放器 demo 与责任交接。
+metadata:
+  skillVersion: '3'
+  sdkMajor: '4'
+  embedApp: '4.0.5'
+  contract: '4.0.0'
+  supportedPackages: >-
+    @video-lab/react@4.1.4, @video-lab/vue@4.1.4,
+    @video-lab/react-frame@4.1.4, @video-lab/vue-frame@4.1.4,
+    @video-lab/embed-helper@4.1.4
+---
+
+# Video Lab Player · 宿主接入
+
+## 取得资料
+
+五个直接接入包均附带 `skills/host-integration/`。从**已安装版本**复制整个目录到宿主 AI
+的 Skill 目录，核对 `supportedPackages`；不要只复制 `SKILL.md` 而漏掉 `references/`。
+纯静态 URL、未安装 npm 包的宿主，请部署方离线提供整个 Skill 目录、受控 origin、媒体源与
+该部署的 `release.json`。核对清单中的 `embedApp`、`contract` 与上方同名元数据相等，
+不相等时向部署方索取对应版本资料；有文档站时也可从站点取得同版本资料。
+不要从示例地址猜生产配置。
+Skill 是宿主 AI 的资料，不是浏览器运行时代码或 iframe 部署物。
+
+## 只读当前接入面
+
+| 宿主条件 | 接入方式 | 必读参考 |
+| --- | --- | --- |
+| React 页面，需要直连内核 | `@video-lab/react` | [React inline](references/react-inline.md) |
+| Vue 页面，需要直连内核 | `@video-lab/vue` | [Vue inline](references/vue-inline.md) |
+| React 页面，需要 iframe 隔离及命令 | `@video-lab/react-frame` | [React iframe](references/react-iframe.md) |
+| Vue 页面，需要 iframe 隔离及命令 | `@video-lab/vue-frame` | [Vue iframe](references/vue-iframe.md) |
+| CMS、Markdown 或纯 HTML，只能嵌 URL | 静态 iframe URL，`@video-lab/embed-helper` 可选 | [静态 iframe URL](references/static-iframe.md) |
+
+选定一种后，先读该模式参考；按功能词查[共用 API 索引](references/api-index.md)，
+需要画中画、品牌覆盖层、QoE 或 403 换源时读[常见功能配方](references/feature-recipes.md)。
+无法访问文档站时，[离线 API 参考](references/offline-api.md)覆盖媒体源、Provider、语言、
+网页全屏、命令、事件与错误的查找入口。
+参考页给出起步示例和差异；**参数含义、完整签名与可用范围以已安装包 README、导出类型及实际部署的 iframe 版本为准**。
+不要从另一个版本或另一个接入面的示例猜测 API。静态 URL 没有命令通道；需要宿主下发播放、
+不重建 iframe 的换源、字幕或弹幕命令时，选框架组件。
+
+回答接入问题时按“功能词 → 所选模式参考 → 对应配方或离线 API 参考 → 该版本包 README 的具体章节 → 导出类型”查找。
+这些包内资料覆盖公开接入面；只有文档与类型互相矛盾或缺失时才交还维护者核实源码，不要把扫描
+SDK 源码当成宿主接入的默认步骤。不要把仓库维护者的 `.claude/` 或 `CLAUDE.md` 复制给宿主。
+
+## 实施与验收
+
+1. 取得业务服务签发的完整媒体源；iframe 模式还需部署方提供受控 origin 和可用版本。鉴权、权益、CORS、字幕资源、弹幕审核与限流由宿主或服务端负责；不要传业务请求头、token 或身份给 SDK。
+2. 用所选参考页建立最小 demo；有事件能力时接入 `ready`、完整事件、`playablechange` 与 `error`。纯 iframe 标签拿不到事件，不能把 `iframe.onload` 当作 `ready`。命令失败和播放期错误分别处理；品牌 UI、业务 CTA、焦点与页面布局由宿主负责。
+3. 验证首次加载、首帧、人工暂停、自动播放受阻、可恢复与终态错误、签名换源、卸载清理。运行时 Loading 仅在 `!playable && recoverable` 时盖住画面；`retry()` 接受请求不等于已经恢复。
+4. 若做遥测，只记录允许的播放器事实；不要上传完整媒体 URL、签名、token、cookie、身份或弹幕正文，也不要逐条上传高频 `timeupdate`。
+
+交接时说明：所选方式和版本、已验证的行为、SDK 已完成的能力、宿主与服务端待办、模式限制及尚未验证的真实环境。宿主需要隐藏单个内置控件时使用初始化 `controlVisibility`（静态 URL 为 `controlPlay` 等参数）；网页全屏需要宿主布局适配器。具体字段见所选模式参考和包 README。

package/skills/host-integration/references/api-index.md

@@ -0,0 +1,47 @@
+# 共用 API 索引
+
+这页是查找入口，不是第二份类型定义。先选模式，再读[离线 API 参考](offline-api.md)与所选包 README 的配置、事件、命令章节；完整字段以该版本包的导出类型和 `@video-lab/protocol` 为准。
+
+## 用功能词找配置
+
+| 接入方的问题 | 四个框架组件的入口 | 静态 iframe URL | 继续读哪里 |
+| --- | --- | --- | --- |
+| 只隐藏画中画或某个内置控件 | 初始化 `controlVisibility.pip=false` 等 | `controlPip=0` 等八个 URL 键 | [常见功能配方](feature-recipes.md)、包 README“内置控件按需隐藏” |
+| 内置封面 / 暂停图 | `poster` / `pauseImage` | `poster` / `pauseImage` 及各自 `Fit` | [常见功能配方](feature-recipes.md)、包 README“Poster 上叠自定义 Loading” |
+| 宿主自定义封面、暂停、Loading | React `renderPoster` / `renderPause` / `renderLoading`；Vue `#poster` / `#pause` / `#loading` | URL 无 renderer / slot；有脚本时由宿主自行覆盖 | [常见功能配方](feature-recipes.md)、所选模式参考 |
+| 自动播放被阻止 | React `onAutoplayBlocked`；Vue `@autoplay-blocked` | 有脚本时订阅事件；纯 iframe 标签无事件 | 包 README“Events”或“完整事件与命令失败” |
+| 403 / 签名过期 | `resolveSource`，返回完整新源或 `null` | 有脚本时监听 `E_AUTH_EXPIRED` 并替换 iframe URL | [常见功能配方](feature-recipes.md) |
+| QoE / 用户行为 | React `onPlayerEvent`；Vue `@player-event` → `@video-lab/telemetry` | 有脚本时 helper `onAny()`；纯 iframe 标签无事件 | [常见功能配方](feature-recipes.md)；安装遥测包后读其自带 README |
+| 运行时换源、静音、语言 | `source` prop、`muted` / `locale` prop；相应句柄方法 | 重建 iframe URL | 所选包 README“Props”“Template ref”或“用法” |
+| 清晰度、字幕菜单 | `ready.quality` / `ready.subtitles` 建菜单；`setQuality` / `setSubtitle` 切换 | URL 无轨列表和命令 | 所选包 README“Events”“Template ref”或“完整事件与命令失败” |
+| 弹幕渲染 | `danmaku` + `pushDanmaku` 等公开方法；服务由宿主提供 | URL 无弹幕输入 / 命令 | 所选组件包 README 的“相关”中的业务接入场景；静态模式明确不支持 |
+| 原生全屏 / 网页全屏 | 句柄方法；网页全屏另传 `pageFullscreen` 布局适配器 | 有脚本时使用 helper controller | 所选包 README 的“宿主网页全屏” |
+| 终态错误、重试和卸载 | `playablechange` 决策；`performErrorAction()`；组件卸载清理 | helper 可收事件；重试只能重建 URL；退订并 `destroy()` | 包 README“统一恢复”或“生命周期”，[常见功能配方](feature-recipes.md) |
+
+上表给出**查找路径**，不宣称所有字段都可在运行时修改。四个组件的业务需求应先看所选包
+README：React 是“用法”“完整事件与命令失败”，Vue 是“Props”“Events”“Template ref”；
+静态 URL 看 `@video-lab/embed-helper/README.md` 的“API”“边界”。公开类型只用于确认精确签名，
+不必打开 SDK 的 `src/`。
+
+| 问题 | 四个框架组件 | 静态 iframe URL |
+| --- | --- | --- |
+| 媒体与起播 | `source` / `resolveSource`、`autoplay`、`muted`、`loop`、`playsinline`、`preload`、`startTime` | `src` 必填；`type`、`live`、`lowLatency`、`autoplay`、`muted`、`loop`、`playsinline`、`preload`、`startTime` 可选；不支持宿主函数 `resolveSource` |
+| 画面与控件 | `poster`、`pauseImage`、`controls`、`controlVisibility`、`showDefaultLoadingOverlay`、`showLoadingText`、`showErrorOverlay`、`errorButtonColors`、`interactive` | `poster` / `posterFit` / `posterLoading`、`pauseImage` / `pauseImageFit`、`controls`、八个 `control*`、`showDefaultLoadingOverlay`、`showLoadingText`、`showErrorOverlay`、`errorButtonBackground` / `errorButtonForeground`、`interactive` |
+| 初始播放参数 | `volume`、`playbackRate`、`preset`、`locale` | 同名 URL 参数；仅内置语言，不传自定义 `messages` |
+| 功能扩展 | `source.subtitles`、`danmaku`、`pageFullscreen`、`debug`；iframe 组件另有 `origin`、`iframeVersion` | `debug` 仅供排查；URL 不接收字幕/弹幕数据，网页全屏需宿主 helper/controller |
+| 命令 | 组件句柄的公开方法；iframe 命令异步 | 无命令通道；`embed-helper` 只监听事件 |
+| 完整事件 | React `onPlayerEvent`；Vue `@player-event` | `createEmbedListener({ origin, iframe }).onAny()`；只有订阅后的未来事件 |
+
+八个控件名为 `play`、`progress`、`time`、`volume`、`playbackRate`、`fullscreen`、`cssFullscreen`、`pip`；静态 URL 对应 `controlPlay`、`controlProgress`、`controlTime`、`controlVolume`、`controlPlaybackRate`、`controlFullscreen`、`controlCssFullscreen`、`controlPip`。`controls=false` 整体关闭优先。
+
+React 组件还可传容器 `className`、`style`、`children`；Vue 组件有对应的模板与插槽用法。它们是框架视图接口，不是 `PlayerConfig`，须看所选包的导出类型。`debug` 在 inline 无通信层，因此不会产生日志；只有 iframe 模式用来排查握手与消息。
+
+还可按需查[离线 API 参考](offline-api.md)的媒体源、Provider、语言、网页全屏、事件与错误：
+
+- **媒体源、字幕、源候选**：所选包 README 的 `source` 说明及公开 `MediaSource` 类型。媒体封装候选不表达会员权益。
+- **Loading、错误、恢复**：所选包 README 的场景表；UI 以 `playablechange` 的 `playable`、`recoverable`、`action` 决策，`error` 用于诊断。`firstframe` 每个播放会话都可能再次发生。
+- **完整事件与错误码**：`PlayerEvent` 用 `event` 区分、数据在 `payload`，没有 `type` 字段；错误码以 `@video-lab/protocol` 的导出类型和 README 为准。
+- **签名失效**：四个组件可提供 `resolveSource`，由服务端给完整新源或返回 `null`；静态 URL 要由宿主替换整个 iframe URL。
+- **生命周期**：框架组件卸载自动清理；静态 helper 必须退订并 `destroy()`。iframe `load` 事件不证明播放器 `ready`。
+
+不要从这个索引推断某字段可以在挂载后热更新。初始化参数、动态更新方式和平台限制由所选包 README 说明；不确定时查导出类型与运行时验证，不私发 `postMessage` 或直接使用内核私有 API。

package/skills/host-integration/references/feature-recipes.md

@@ -0,0 +1,167 @@
+# 常见功能配方 · 五种接入方式
+
+先从 Skill 入口选一种模式。本页只回答经常被问到的接法；复制代码时使用**已安装包**
+的对应 import 和已部署的 iframe 版本。媒体 URL、封面 URL、`origin` 与业务服务函数都由宿主提供。
+若需求不在本页，用[共用 API 索引](api-index.md)定位所选包 README 的章节和导出类型。
+
+## 隐藏画中画按钮
+
+| 模式 | 创建播放器时的配置 |
+| --- | --- |
+| React inline / React iframe | `controlVisibility={ { pip: false } }` |
+| Vue inline / Vue iframe | `:control-visibility="{ pip: false }"` |
+| 静态 iframe URL | `controlPip=0` |
+
+只隐藏内置控制栏入口，其他控件照常显示；`controls=false` 会隐藏整个控制栏。
+`controlVisibility` 是初始化配置，修改时重建组件；静态模式重新导航 iframe。
+iframe 模式还须确认部署的播放器应用支持此字段。它不负责禁止浏览器或宿主自己的画中画入口。
+
+## 封面与 Loading
+
+| 模式 | 内置封面 | 自定义封面 | 自定义首次与运行时 Loading |
+| --- | --- | --- | --- |
+| React inline | `poster="…"` | `renderPoster={() => <BrandPoster />}` | `renderLoading={({ phase, reason, text }) => <BrandLoading phase={phase} reason={reason} text={text} />}` |
+| Vue inline | `poster="…"` | `<template #poster>…</template>` | `<template #loading="{ phase, reason, text }">…</template>` |
+| React iframe | 同 React inline；自定义内容在宿主 DOM | `renderPoster` | `renderLoading`，覆盖 iframe 创建与握手空档 |
+| Vue iframe | 同 Vue inline；插槽在宿主 DOM | `#poster` | `#loading`，覆盖 iframe 创建与握手空档 |
+| 静态 iframe URL | `poster=<编码后的图片 URL>` | 不支持 renderer / slot | 只支持内置层；有脚本的宿主可在 iframe 外自己渲染 |
+
+四个组件由 SDK 控制 Poster 到首帧、Loading 的首次加载与可恢复等待；renderer / slot
+只负责视觉。提供自定义 Loading 后，默认 Loading 自动让位，不必再设置
+`showDefaultLoadingOverlay=false`。只有把覆盖层完全放到组件外，才关闭默认视觉并消费
+`playablechange`。自定义暂停画面同理使用 React `renderPause` 或 Vue `#pause`，静态模式只能给
+`pauseImage` 图片；明确的人工暂停才应显示暂停画面。Frame 需搭配支持宿主展示桥的 iframe
+版本验收；旧版可能仍显示 iframe 内媒体层。完整可复制的组件写法见所选模式参考页。
+
+## 403 与签名过期
+
+四个框架组件把 `resolveSource` 交给**宿主**。SDK 仅在 `E_AUTH_EXPIRED` 时调用它；401 / 403
+可能映射到此错误，但宿主不能把所有 403 都猜成“还能续签”。业务服务判断权益并返回**完整新
+`MediaSource`**；确定没有替代源时返回 `null`。`signal` 用于取消过期请求，不要重连旧签名 URL。
+
+```ts
+import type { MediaSource, ResolveSource } from '@video-lab/react'
+
+// 宿主实现：向业务服务获取完整新源；无替代源时返回 null。
+declare function requestAuthorizedSource(signal: AbortSignal): Promise<MediaSource | null>
+
+const resolveSource: ResolveSource = ({ signal }) => requestAuthorizedSource(signal)
+```
+
+上例的 import 改成所选的 `@video-lab/react-frame`、`@video-lab/vue` 或
+`@video-lab/vue-frame` 即可；四个包都重导出 `MediaSource` 和 `ResolveSource`。
+React 传 `resolveSource={resolveSource}`，Vue 传 `:resolve-source="resolveSource"`。
+`onError` / `@error` 用于诊断，`onPlayerEvent` / `@player-event` 中的 `sourceswitch` 用于观测；
+不要再在错误回调里并行刷新同一个旧源。
+
+静态 iframe URL 不能传函数。只有宿主允许脚本时，才能用
+`createEmbedListener({ origin, iframe })` 在设置 iframe `src` 前订阅 `error`；收到
+`E_AUTH_EXPIRED` 后由宿主向业务服务取得新 URL，并**替换整个 iframe URL**。仅能嵌入 iframe
+标签的页面无法自动续签，也无法取得可信错误事件。
+
+有 npm 构建的静态宿主可按下面接线；`requestAuthorizedUrl()` 与 `showUnavailable()` 是宿主业务函数。
+无构建工具但允许脚本时，使用同一部署根的 `helper.js` 和全局
+`SentinelEmbed.createEmbedListener`，事件及换 URL 的顺序相同。
+
+```bash
+pnpm add @video-lab/embed-helper
+```
+
+```ts
+import { createEmbedListener } from '@video-lab/embed-helper'
+
+declare const initialSource: string
+declare function requestAuthorizedUrl(): Promise<string | null>
+declare function showUnavailable(): void
+
+const iframe = document.querySelector('#article-player')
+if (!(iframe instanceof HTMLIFrameElement)) throw new Error('iframe 未找到')
+const embedBase = 'https://player.example.internal/' // 换成部署方提供的完整根路径，含版本目录
+const origin = new URL(embedBase).origin
+const listener = createEmbedListener({ origin, iframe })
+let refreshing = false
+let lastFailedIframeUrl = ''
+const offError = listener.on('error', async ({ code }) => {
+  if (code !== 'E_AUTH_EXPIRED' || refreshing || iframe.src === lastFailedIframeUrl) return
+  lastFailedIframeUrl = iframe.src
+  refreshing = true
+  try {
+    const replacement = await requestAuthorizedUrl()
+    if (replacement === null) return showUnavailable()
+    const next = new URL(iframe.src)
+    next.searchParams.set('src', replacement)
+    iframe.src = next.href
+  } catch {
+    showUnavailable()
+  } finally {
+    refreshing = false
+  }
+})
+
+const embedUrl = new URL(embedBase)
+embedUrl.searchParams.set('src', initialSource)
+embedUrl.searchParams.set('controlPip', '0')
+iframe.src = embedUrl.href // 先订阅，后导航；事件不会回放
+window.addEventListener('pagehide', () => {
+  offError()
+  listener.destroy()
+}, { once: true })
+```
+
+## QoE 与行为上报
+
+需要会话 QoE 时另装 `@video-lab/telemetry`。它只把完整 `PlayerEvent` 转成记录和摘要，
+**不发送 HTTP**。`sink` 是宿主的有界队列入口；批量、并发、有限重试和上传失败监控由宿主实现。
+
+```bash
+pnpm add @video-lab/telemetry
+```
+
+```ts
+import { createTelemetrySession } from '@video-lab/telemetry'
+
+// 宿主实现：构建版本与有界队列；不能把这三个声明直接当成传输实现。
+declare const hostRelease: string
+declare function enqueueRecord(input: unknown): void
+declare function enqueueSummary(input: unknown): void
+
+const telemetry = createTelemetrySession({
+  application: { name: 'business-web', release: hostRelease },
+  sink: { onRecord: enqueueRecord, onSummary: enqueueSummary },
+})
+
+// 在宿主自定义按钮的真实点击处理器中调用；内置控件动作已在完整事件中。
+function onRetryClick() {
+  telemetry.recordIntent({ type: 'retry', origin: 'user' })
+  // 接着调用所选组件句柄的 retry()，并处理 Promise rejection。
+}
+// 组件卸载时调用 telemetry.finish({ reason: 'destroyed' })；
+// 页面退出时调用 telemetry.finish({ reason: 'page_unload' })。
+```
+
+| 模式 | 完整事件接线 |
+| --- | --- |
+| React inline / React iframe | `onPlayerEvent={(event) => telemetry.record(event)}` |
+| Vue inline / Vue iframe | `@player-event="telemetry.record"` |
+| 静态 iframe URL，有 npm 构建与页面脚本 | `const off = listener.onAny((event) => telemetry.record(event))`；卸载时 `off()`、`listener.destroy()` |
+| 静态 iframe URL，只有 `helper.js` 脚本 | 可订阅完整事件；`@video-lab/telemetry` 没有独立 IIFE，需宿主构建链或自有上报实现 |
+| 只有 iframe 标签 | 无宿主事件出口，不能做这一套会话上报 |
+
+静态模式要先绑定具体 iframe 与精确 `origin`、订阅 `onAny()`，再设置 `src`；事件不回放。
+不要把 `timeupdate` 等完整事件逐条 `fetch()`，也不要把完整媒体 URL、签名、token、身份或
+弹幕正文放进上报。精确记录类型、频率与会话完成时机见已安装的
+`@video-lab/telemetry/README.md`“最小接入”“高频与网络安全”。
+
+## 其他常见问题
+
+| 想做的事 | 接入入口与边界 |
+| --- | --- |
+| 只隐藏 CSS 全屏 | 四个组件 `controlVisibility.cssFullscreen=false`；静态 URL `controlCssFullscreen=0`。 |
+| 自动播放被拒 | React `onAutoplayBlocked`；Vue `@autoplay-blocked`；向用户显示可点击播放按钮并在手势中调用 `play()`。静态模式只有允许脚本时才能收事件。 |
+| 运行时换源 | 四个组件更新 `source` prop；静态模式重建 URL。不要调用内部 `load()`。 |
+| 清晰度 / 字幕菜单 | 从 `ready.quality` / `ready.subtitles ?? []` 生成菜单，再调用 `setQuality` / `setSubtitle`；静态模式没有命令。 |
+| 终态错误 / 重试 | UI 读取 `playablechange`；四个组件的自定义 CTA 可调用 `performErrorAction()`；Promise 完成不代表已恢复，等待 `recovery` / 播放证据。 |
+| 暂停画面与网络缓冲 | React `renderPause`、Vue `#pause` 或五种模式共用 `pauseImage`；只有明确人工暂停显示 Pause，缓冲显示 Loading。 |
+
+所有初始化参数、事件 payload、命令返回值与平台限制都以所选版本的**包 README 与导出类型**
+为准。iframe 的 `origin` 和可用版本由部署方提供，不从示例地址推断生产配置。

package/skills/host-integration/references/offline-api.md

@@ -0,0 +1,46 @@
+# 离线 API 参考 · 五种接入方式
+
+本页随五个直接接入包一起发布，供无法访问文档站的宿主按功能查入口。先读所选[模式参考](../SKILL.md)和[功能配方](feature-recipes.md)，再用**已安装版本**的包 README 与导出 `.d.ts` 核对精确类型；这里不替代类型声明。iframe 的可用能力还取决于实际部署版本。
+
+## 配置入口与生效时机
+
+| 功能 | React / Vue inline 与 iframe 组件 | 静态 iframe URL |
+| --- | --- | --- |
+| 媒体与起播 | 必填 `source`；可选 `resolveSource`、`autoplay`、`muted`、`loop`、`playsinline`、`preload`、`startTime`、`volume`、`playbackRate` | 必填 `src`；可选 `type`、`live`、`lowLatency` 及同名起播参数；无函数型续签 |
+| 内置画面 | `poster`、`pauseImage`、`controls`、`controlVisibility`、`interactive` | `poster`、`posterFit`、`posterLoading`、`pauseImage`、`pauseImageFit`、`controls`、八个 `control*`、`interactive` |
+| 覆盖层 | `showErrorOverlay`、`showDefaultLoadingOverlay`、`showLoadingText`、`errorButtonColors`；React `renderPoster/Pause/Loading`；Vue `#poster/#pause/#loading` | 同名布尔 URL 键；`errorButtonBackground/Foreground`；没有 renderer / slot |
+| 语言与扩展 | `locale`、`preset`、`danmaku`；组件还可传 `pageFullscreen` | `locale`、`preset`、`title`、`description`；无字幕、弹幕输入或宿主函数 |
+| iframe 专属 | `origin`、`iframeVersion`、`debug` | 部署方给完整 URL；`debug=1` 只用于通信排障 |
+
+`source` 改变可换源；`muted`、`locale`、`interactive` 与 inline 默认覆盖层视觉可原地更新。`controlVisibility`、renderer/slot 是否存在、`preload`、初始音量/倍速/时间属于创建策略；切换这些策略时显式重挂。Frame 内层覆盖层配置由 iframe 创建时读取，宿主显示层的动态行为须用实际部署版本验收。`controls=false` 优先于单个 `controlVisibility` 开关。`debug` 在 inline 没有通信层，因此不产生日志。
+
+### 媒体源、字幕与弹幕
+
+四个组件的 `source` 接受 URL 字符串、`{ url, type?, live?, hls?, subtitles?, metadata? }`，或 `{ sources: [{ url, type }, …], live?, hls?, subtitles?, metadata? }`。多源候选是**同一内容的不同封装**，不是清晰度档位；签名 URL 应显式写 `type`。直播务必设置 `live: true`；更换直播/点播模式需要重建播放器。`hls.lowLatencyMode: true` 才启用低延迟 HLS。字幕轨可用 `{ mode: 'url', url, locale, label }` 或 `{ mode: 'content', content, locale, label }`，内联正文须是 WebVTT；`ready.subtitles` 给轨道 id，交给 `setSubtitle(id)`，关闭传 `'off'`。静态 URL 没有字幕轨输入或切换命令。
+
+`danmaku` 默认关闭；`{ enabled: true, mode: 'streaming' }` 配合 `pushDanmaku({ id, text, type?, color?, start? })`。点播可用 `{ enabled: true, mode: 'preload', items: [...] }`，`start` 是**毫秒**；`seek` 和 `startTime` 是秒。弹幕内容、审核和业务传输由宿主负责。静态 URL 不接受弹幕输入。
+
+`poster` 可传图片 URL 或 `{ url, fit?, loading? }`，`pauseImage` 可传 URL 或 `{ url, fit? }`；组件还可传 `null` 清除 Provider 继承的图片。自定义视觉的最小代码见各[模式参考](../SKILL.md)；Loading 的 `phase` 为 `initial` / `runtime`。明确人工暂停显示 Pause，网络缓冲显示 Loading。静态 URL 要在 `URLSearchParams` 中编码图片 URL 和颜色值。
+
+### 应用级默认值与语言
+
+四个框架包都导出 `PlayerProvider` / `usePlayerI18n`。React：`<PlayerProvider defaultLocale="zh-CN" defaults={ { showLoadingText: true } }>…</PlayerProvider>`；受控语言用 `locale` + `onLocaleChange`。Vue：`<PlayerProvider v-model:locale="language" :defaults="defaults">…</PlayerProvider>`。Provider 还接受 `resources`、`messageOverrides`、`fallbackLocales`；`frameDefaults` 可给新建 iframe 统一设置 `origin`、`iframeVersion`、`debug`。单实例显式值优先，`false` / `0` 会覆盖默认；`source`、`resolveSource`、回调与自定义视觉始终逐实例提供。`usePlayerI18n` 只能在 Provider 内调用。默认中/英；越南语按需从 `@video-lab/locales/vi-VN` 引入 `viVN`。静态 URL 无 Provider 或自定义消息表，切换 `locale` 要替换 URL。
+
+### 网页全屏
+
+四个组件的 `pageFullscreen` 接受挂载期间稳定的 `{ setActive(active): void | Promise<void>, dispose(): void }`。宿主在 `setActive` 中调整容器、滚动与焦点，调用句柄 `await setPageFullscreen(true | false)`，监听 React `onPageFullscreenChange` 或 Vue `@page-fullscreen-change`。浏览器原生全屏仍由 `enterFullscreen()` / `exitFullscreen()` 控制。静态 iframe 只有带脚本且安装 `@video-lab/embed-helper` 时可用 `createPageFullscreenController({ iframe, origin, adapter, onChange? })`，先建控制器再设置 iframe `src`，离开时 `destroy()`；纯 iframe 标签无法铺满宿主页面。iframe 侧须部署支持该能力的版本。
+
+## 命令、事件与错误
+
+四个框架组件通过 ref 暴露 `play`、`pause`、`seek`、`setMuted`、`setVolume`、`setPlaybackRate`、`setPageFullscreen`、`enterFullscreen`、`exitFullscreen`、`setQuality`、`setSubtitle`、`setLocale`、`pushDanmaku`、`setDanmakuEnabled`、`clearDanmaku`、`retry`、`performErrorAction`、`destroy`、`getCurrentTime`、`getDuration`、`getPlaybackContext`、`getPlayerHandle`。**iframe 命令除本地 getter 均异步**；inline 只有可失败的 `play`、全屏、`retry`、`performErrorAction` 等返回 Promise，精确签名看包的导出类型。静态 URL 无播放命令通道；helper 的 `on/onAny/off/destroy` 用于订阅，换源须生成新 URL。
+
+完整事件：React `onPlayerEvent(event)`，Vue `@player-event`，静态脚本 `createEmbedListener({ origin, iframe }).onAny(handler)`；仅 iframe 标签没有事件出口。`PlayerEvent` 以 `event` 区分、`payload` 承载数据、`delivery` 提供排序/去重证据。常用事实：`ready` 给时长/清晰度/字幕清单；`firstframe` 表示本次播放会话画面出现；`playablechange` 的 `playable/recoverable/action` 决定页面级 Loading 与终态；`error` 给错误诊断；`recovery` 给恢复结果；`contextchange`、`stalled`、`kernelhealth`、`bufferhealth`、`audiohealth`、`framefreeze`、`useraction` 供观测。React 对应 `onReady`、`onFirstFrame`、`onPlayableChange` 等，Vue 对应 `@ready`、`@first-frame`、`@playable-change` 等；全部事件名和 payload 以导出的 `PlayerEvent` 为准。
+
+播放器错误码包括 `E_AUTH_EXPIRED`、`E_NETWORK`、`E_NETWORK_TIMEOUT`、`E_MANIFEST_PARSE`、`E_MEDIA_DECODE`、`E_MEDIA_NOT_SUPPORTED`、`E_AUTOPLAY_BLOCKED`、`E_SUBTITLE_LOAD_FAILED`、`E_ENV_CSP_BLOCKED` 等；iframe 组件另可能出现握手/加载/崩溃错误。**不要只凭错误码自己拼接最终 UI 状态**：`error` 用于诊断，`playablechange` 用于呈现。`E_AUTH_EXPIRED` 的续签由宿主提供完整新源；`retry()` 完成仅表示请求已接受，恢复成功仍看后续事件。命令 rejection 和播放期 `error` 需分别处理。
+
+## 包内资料查找顺序
+
+1. [Skill 入口](../SKILL.md)选模式；所选模式参考给最小示例与差异。
+2. [功能配方](feature-recipes.md)回答画中画、封面、Loading、403、QoE；本页回答其余公开能力。
+3. 同版本包的 `README.md` 给完整接入叙述；安装 `@video-lab/telemetry` 时另看**该包自己的 README**。
+4. 需要精确字段/返回类型，读安装包 `dist/*.d.ts` 及依赖包 `@video-lab/protocol` 的导出类型。不要读取 `src/`、猜私有 `postMessage` 或把仓库维护者文档复制到宿主。

package/skills/host-integration/references/react-iframe.md

@@ -0,0 +1,62 @@
+# React iframe
+
+适用 React 19+ 页面，需要样式、脚本或故障隔离，同时仍需公开命令与事件时。安装 `@video-lab/react-frame`；播放器样式在 iframe 内，无需引入 inline 包的 CSS。
+
+## 最小接入
+
+```tsx
+import { VideoPlayerFrame } from '@video-lab/react-frame'
+
+export function LessonPlayer() {
+  return (
+    <VideoPlayerFrame
+      origin="https://player.example.internal"
+      source="https://media.example.com/lesson.m3u8"
+      muted
+      onReady={({ duration }) => console.info('ready', duration)}
+      onError={({ code }) => console.error(code)}
+    />
+  )
+}
+```
+
+`origin` 和可用 `iframeVersion` 必须来自部署方；示例地址只是占位符。需要锁定应用构建物时才传 `iframeVersion`，并确认该目录已部署。句柄命令跨 iframe，全部异步，宿主主动调用时都处理 rejection。
+
+## 常见视觉配置
+
+下例的 renderer 在**宿主 DOM**，可覆盖 iframe 创建和握手空档；`origin` 要换成部署方给出的地址。
+
+```tsx
+import { VideoPlayerFrame } from '@video-lab/react-frame'
+
+export function BrandedPlayer() {
+  return (
+    <VideoPlayerFrame
+      origin="https://player.example.internal"
+      source="https://media.example.com/lesson.m3u8"
+      poster="https://media.example.com/lesson-poster.jpg"
+      controlVisibility={{ pip: false }}
+      renderPoster={() => (
+        <img src="/brand-poster.jpg" alt="课程视频封面" style={{ width: '100%', height: '100%', objectFit: 'cover' }} />
+      )}
+      renderLoading={({ phase, text }) => (
+        <div role="status">{text ?? (phase === 'initial' ? '正在加载' : '正在恢复')}</div>
+      )}
+    />
+  )
+}
+```
+
+配套 iframe 版本中自定义 Loading 替换默认层，不必再设 `showDefaultLoadingOverlay={false}`；
+旧版 iframe 可能保留内部媒体层，须在目标部署验收。
+renderer 是否存在与 `controlVisibility` 属构造期策略；切换时重新挂载，并确认部署版 iframe 支持配置。
+403 换源与 QoE 接线见[常见功能配方](feature-recipes.md)。
+
+## 按需读取的 API
+
+- 配置、命令、错误与恢复：已安装 `@video-lab/react-frame/README.md` 的“用法”“配置 iframe 地址”“完整事件与命令失败”“统一恢复”；props 与句柄准确签名见 `VideoPlayerFrameProps`、`VideoPlayerFrameHandle`。
+- 完整事件使用 `onPlayerEvent`；用户可见状态用 `onPlayableChange`，错误码用 `onError`。命令 resolve 不证明画面已恢复；等待 `recovery`、`playablechange` 或首帧证据。
+- 宿主视觉用 `renderLoading` / `renderPoster` / `renderPause`；iframe 内覆盖层不能直接接受宿主 DOM、renderer 或 CSS。初次握手阶段需要宿主 Loading，失联后不能继续在旧句柄上循环下命令。
+- `source` prop 更新可换源；签名过期由宿主 `resolveSource` 提供新完整源。React 组件卸载会释放连接，宿主仍需结束自己的遥测会话。
+
+按需读[共用索引](api-index.md)；不要将 `origin` 当媒体源 URL，也不要手工向 iframe 发 `postMessage`。

package/skills/host-integration/references/react-inline.md

@@ -0,0 +1,62 @@
+# React inline
+
+适用 React 19+ 页面，需要最小首帧开销或与页面直接组合时。安装 `@video-lab/react`，并引入一次 `@video-lab/react/style.css`；无需 iframe origin。
+
+## 最小接入
+
+```tsx
+import { VideoPlayer } from '@video-lab/react'
+import '@video-lab/react/style.css'
+
+export function LessonPlayer() {
+  return (
+    <VideoPlayer
+      source="https://media.example.com/lesson.m3u8"
+      muted
+      onReady={({ duration }) => console.info('ready', duration)}
+      onError={({ code }) => console.error(code)}
+    />
+  )
+}
+```
+
+真实媒体 URL 由宿主服务签发；示例域名不能直接用于生产。要控制播放，给组件 `VideoPlayerHandle` ref，调用 `play()` 时 `await` / `catch`；`seek()` 等同步命令以事件确认实际状态。换源改 `source` prop，不调用内部 `load()`。
+
+## 常见视觉配置
+
+以下例子只隐藏内置画中画按钮，并把封面与首次/恢复 Loading 交给宿主渲染；
+renderer 的显隐由 SDK 管理。
+
+```tsx
+import { VideoPlayer } from '@video-lab/react'
+import '@video-lab/react/style.css'
+
+export function BrandedPlayer() {
+  return (
+    <VideoPlayer
+      source="https://media.example.com/lesson.m3u8"
+      poster="https://media.example.com/lesson-poster.jpg"
+      controlVisibility={{ pip: false }}
+      renderPoster={() => (
+        <img src="/brand-poster.jpg" alt="课程视频封面" style={{ width: '100%', height: '100%', objectFit: 'cover' }} />
+      )}
+      renderLoading={({ phase, text }) => (
+        <div role="status">{text ?? (phase === 'initial' ? '正在加载' : '正在恢复')}</div>
+      )}
+    />
+  )
+}
+```
+
+自定义 Loading 已替换默认层，不必再传 `showDefaultLoadingOverlay={false}`。
+`controlVisibility` 与 renderer 是否存在是构造期策略；要切换时重新挂载组件。
+403 换源与 QoE 接线见[常见功能配方](feature-recipes.md)。
+
+## 按需读取的 API
+
+- 配置与默认值：已安装 `@video-lab/react/README.md` 的“安装”“用法”“错误 UI 接管”“内置控件按需隐藏”“统一恢复”；所有 props、renderer 与句柄签名见包导出的 `VideoPlayerProps`、`VideoPlayerHandle`。
+- 完整事件：`onPlayerEvent`；UI 使用 `onPlayableChange`，诊断使用 `onError`。`onWaiting` / `onPlaying` 是瞬时信号，不应直接作为整个错误层的状态。`PlayerEvent.event` 才是事件辨别字段。
+- Poster、Pause、Loading：`poster` / `pauseImage` 是内置图片；`renderPoster` / `renderPause` / `renderLoading` 是宿主自定义视觉。明确暂停才显示 Pause，缓冲或被动暂停不应显示 Pause；`renderLoading` 自动替换默认 Loading。
+- 恢复与销毁：`retry()` 的 Promise 只表示请求已接收；等待 `recovery` / `playablechange` 判断结果。组件卸载自动清理；宿主遥测另行收口。
+
+需要精确字段、参数取值、事件 payload 或错误码时读已安装包 README 与导出类型，再读[共用索引](api-index.md)对应项；不要根据 iframe 包的全 Promise 句柄推断 inline 签名。

package/skills/host-integration/references/static-iframe.md

@@ -0,0 +1,35 @@
+# 静态 iframe URL
+
+适用只能嵌 URL 的 CMS、Markdown 或纯 HTML。宿主无命令 RPC；如允许页面脚本，可用部署根的 `helper.js` 或 `@video-lab/embed-helper` 订阅事件。仅允许 iframe 标签时，不能取得宿主侧事件。
+
+## 最小接入
+
+```html
+<iframe
+  id="article-player"
+  title="文章视频播放器"
+  src="https://player.example.internal/?src=https%3A%2F%2Fmedia.example.com%2Flesson.m3u8&amp;muted=1"
+  allow="autoplay; fullscreen; picture-in-picture; encrypted-media; screen-wake-lock"
+  allowfullscreen
+></iframe>
+```
+
+实际 iframe origin、路径和应用版本必须由部署方提供。宿主用 `URL` / `URLSearchParams` 对媒体 URL 编码；示例地址不能直接生产使用。只允许简单配置：`src`、`type`、`live`、`lowLatency`、起播和视觉参数；不能把 JSON、token 或业务身份塞入 query。
+
+只隐藏内置画中画按钮时，在已部署 URL 上加 `controlPip=0`，例如
+`?src=https%3A%2F%2Fmedia.example.com%2Flesson.m3u8&controlPip=0`。
+自定义封面 renderer / Vue slot 不能放进 URL；可用 `poster=<编码后的图片 URL>` 指定内置图。
+首次与恢复 Loading 只支持内置层，或由有脚本的宿主在 iframe 外接事件自行渲染。
+403 换源与 QoE 的脚本边界见[常见功能配方](feature-recipes.md)。
+
+## URL 与事件
+
+- `src` 是必需的媒体 URL；`type` / `live` / `lowLatency` 描述流，`title` / `description` 用于媒体会话元信息。`poster` / `posterFit` / `posterLoading` 和 `pauseImage` / `pauseImageFit` 控制内置图片。
+- `autoplay`、`muted`、`loop`、`controls`、`playsinline`、`interactive`、`showErrorOverlay`、`showDefaultLoadingOverlay`、`showLoadingText` 是布尔参数；使用 `1` / `0`，不要传任意字符串。`volume` 范围 0–1，`playbackRate` 范围 0.25–4；`startTime`、`preload`、`preset`、`locale` 的可用值按部署版本校验。
+- 单独控件参数为 `controlPlay`、`controlProgress`、`controlTime`、`controlVolume`、`controlPlaybackRate`、`controlFullscreen`、`controlCssFullscreen`、`controlPip`；默认错误按钮颜色可用 `errorButtonBackground` / `errorButtonForeground`。取值与边界见[离线 API 参考](offline-api.md)和本包 README，部署版本仍须核对。
+- `debug=1` 只用于 iframe 通信排障；旧的 `pauseImageClosable` 已拒绝，不能继续传。
+- 需要事件时，先用 `createEmbedListener({ origin, iframe })` 创建**绑定具体 iframe 和精确 origin**的监听器，先 `on('ready', ...)` / `on('error', ...)` 或 `onAny()` 订阅，再设置 iframe `src`。离开页面时退订并 `destroy()`；订阅之前的事件不会回放。
+
+上面的最小 `<iframe src="…">` 例子只适合不收事件的页面。要收事件，先渲染没有 `src` 的 iframe，完成 helper 订阅后再设置 `src`；完整脚本见 `@video-lab/embed-helper/README.md`。
+
+静态模式不能下发播放、暂停、字幕、弹幕或重试命令；换源和切语言均需替换整个 iframe URL。需要可信的现态或命令时改用 React/Vue iframe 组件。`iframe.onload` 不等于播放器 `ready`。详见已安装 `@video-lab/embed-helper/README.md` 与[共用索引](api-index.md)；纯 URL 用户须取得部署方提供的同版本离线资料。

package/skills/host-integration/references/vue-iframe.md

@@ -0,0 +1,63 @@
+# Vue iframe
+
+适用 Vue 3.4+ 页面，需要 iframe 隔离并保留完整命令与事件时。安装 `@video-lab/vue-frame`；无需安装 inline 包或引入播放器 CSS。
+
+## 最小接入
+
+```vue
+<script setup lang="ts">
+import { VideoPlayerFrame } from '@video-lab/vue-frame'
+</script>
+
+<template>
+  <VideoPlayerFrame
+    origin="https://player.example.internal"
+    source="https://media.example.com/lesson.m3u8"
+    muted
+    @ready="({ duration }) => console.info('ready', duration)"
+    @error="({ code }) => console.error(code)"
+  />
+</template>
+```
+
+`origin`、可用 `iframeVersion` 和媒体源由部署方与业务服务提供；示例地址只作占位。iframe 句柄方法全部跨通信通道，宿主主动调用时均需 `await` / `catch`，并等待事件确认播放结果。
+
+## 常见视觉配置
+
+插槽在宿主 DOM 渲染，可覆盖 iframe 创建和握手空档；`origin` 要换成部署方给出的地址。
+
+```vue
+<script setup lang="ts">
+import { VideoPlayerFrame } from '@video-lab/vue-frame'
+</script>
+
+<template>
+  <VideoPlayerFrame
+    origin="https://player.example.internal"
+    source="https://media.example.com/lesson.m3u8"
+    poster="https://media.example.com/lesson-poster.jpg"
+    :control-visibility="{ pip: false }"
+  >
+    <template #poster>
+      <img src="/brand-poster.jpg" alt="课程视频封面" style="width: 100%; height: 100%; object-fit: cover" />
+    </template>
+    <template #loading="{ phase, text }">
+      <div role="status">{{ text ?? (phase === 'initial' ? '正在加载' : '正在恢复') }}</div>
+    </template>
+  </VideoPlayerFrame>
+</template>
+```
+
+配套 iframe 版本中 `#loading` 替换默认层；旧版 iframe 可能保留内部媒体层，须在目标部署验收。
+插槽是否存在与 `controlVisibility` 属构造期策略。
+切换时重新挂载，并确认部署版 iframe 支持配置。403 换源与 QoE 接线见
+[常见功能配方](feature-recipes.md)。
+
+## 按需读取的 API
+
+- 参数、事件和命令：已安装 `@video-lab/vue-frame/README.md` 的“Props”“Events”“Template ref”；准确类型为 `VideoPlayerFrameProps`、`VideoPlayerFrameEmits`、`VideoPlayerFrameExpose`。
+- 完整事实流为 `@player-event`；`@playable-change` 管 Loading 与终态 CTA，`@error` 提供诊断。事件模板名用 kebab-case。
+- 品牌 Loading / Poster / Pause 分别使用 `#loading` / `#poster` / `#pause`；slot 渲染在宿主侧，须覆盖 iframe 初始化空档。明确暂停与缓冲时的被动暂停不同。
+- 失联时读取 README 的“iframe 特有生命周期”；使用公开 `performErrorAction()` 或重建入口，不循环调用旧句柄。换源改 `source` prop；签名过期由宿主 `resolveSource` 获取新完整源。卸载自动清理连接。
+
+按需读[共用索引](api-index.md)。`iframe.onload` 只表示文档导航完成，不能当作播放器 `ready`。

package/skills/host-integration/references/vue-inline.md

@@ -0,0 +1,60 @@
+# Vue inline
+
+适用 Vue 3.4+ 页面，需要直连播放核心时。安装 `@video-lab/vue`，并引入一次 `@video-lab/vue/style.css`；不需要在 Vite 配置 `isCustomElement`。
+
+## 最小接入
+
+```vue
+<script setup lang="ts">
+import { VideoPlayer } from '@video-lab/vue'
+import '@video-lab/vue/style.css'
+</script>
+
+<template>
+  <VideoPlayer
+    source="https://media.example.com/lesson.m3u8"
+    muted
+    @ready="({ duration }) => console.info('ready', duration)"
+    @error="({ code }) => console.error(code)"
+  />
+</template>
+```
+
+真实媒体 URL 由宿主服务签发。需要命令时使用 `VideoPlayerExpose` 的 template ref：`play()`、全屏与 `retry()` 要处理 Promise rejection，其余多数命令同步。换源改 `source` prop。
+
+## 常见视觉配置
+
+```vue
+<script setup lang="ts">
+import { VideoPlayer } from '@video-lab/vue'
+import '@video-lab/vue/style.css'
+</script>
+
+<template>
+  <VideoPlayer
+    source="https://media.example.com/lesson.m3u8"
+    poster="https://media.example.com/lesson-poster.jpg"
+    :control-visibility="{ pip: false }"
+  >
+    <template #poster>
+      <img src="/brand-poster.jpg" alt="课程视频封面" style="width: 100%; height: 100%; object-fit: cover" />
+    </template>
+    <template #loading="{ phase, text }">
+      <div role="status">{{ text ?? (phase === 'initial' ? '正在加载' : '正在恢复') }}</div>
+    </template>
+  </VideoPlayer>
+</template>
+```
+
+`#poster` / `#loading` 由 SDK 管显隐；`#loading` 已替换默认层。
+插槽是否存在与 `controlVisibility` 属于构造期策略，切换时重新挂载。
+403 换源与 QoE 接线见[常见功能配方](feature-recipes.md)。
+
+## 按需读取的 API
+
+- 配置、默认值、完整事件、句柄：已安装 `@video-lab/vue/README.md` 的“Props”“Events”“Template ref”三节；准确类型为包导出的 `VideoPlayerProps`、`VideoPlayerEmits`、`VideoPlayerExpose`。
+- 事件在模板中使用 kebab-case，例如 `@playable-change`、`@first-frame`、`@player-event`；完整事实流只走 `@player-event`。UI 以 `playable`、`recoverable`、`action` 决策，不把 `waiting` 当成不可恢复错误。
+- Poster、Pause、Loading：内置图片用 `poster` / `pauseImage`；宿主视觉用 `#poster` / `#pause` / `#loading`。`#loading` 负责首次和运行时恢复视觉；明确暂停与被动暂停语义不同。
+- 签名失效时 `resolveSource` 由宿主获取完整新源；`retry()` 接受请求不等于媒体恢复。普通组件卸载自动清理；宿主遥测独立收口。
+
+需要精确参数值或复杂业务示例时读该包 README 的“生产场景示例”与[共用索引](api-index.md)。不要把 React custom element 事件 prop 写法复制到 Vue 模板。