@video-lab/player-ui 2.0.0 → 3.0.0

package/README.md

@@ -51,7 +51,7 @@ export function onPlayerEvent(event: PlayerEvent): void {
 
 // ③ 重试是 CustomEvent(冒泡),不是回调 prop
 error.addEventListener('sentinel-retry', () => {
-  /* 重建播放器 */
+  /* 调用当前句柄的 retry()，由 playablechange 更新显示 */
 })
 ```
 
@@ -131,3 +131,12 @@ pnpm --filter @video-lab/player-ui test
 ```
 
 Vitest + jsdom,直接测 custom element 的注册 / attribute → DOM / 事件派发。
+
+
+### 统一恢复（契约 v2）
+
+旧 `reconnect({ resetCounter })` 和 `reconnectstart/success/failed` 已移除。命令入口是 `retry(): Promise<void>`；Promise 完成只表示接受或合并请求。恢复中的重复请求共用预算，强播放证据通过 `recovery` 的 `recovered` 回报。
+
+宿主 UI 读取 `playablechange` 的 `playable`、`recoverable`、`action`。`error` 只提供诊断；预算耗尽才给出 `action: 'retry'`，宿主无需按错误原因拼接重试状态。消费组件/iframe 配置 `showErrorOverlay: false` 与 `showLoadingOverlay: false` 控制默认覆盖层；player-ui 本身只负责渲染，不下发媒体命令。静态 iframe URL 没有宿主命令通道，内部按钮仍走同一调度。
+
+更多迁移语义见 [ADR-099](../../docs/adr/ADR-099-unified-recovery-contract.md)。

package/dist/index.d.cts

@@ -48,15 +48,15 @@ declare abstract class SentinelOverlayElement extends HTMLElement {
 //#endregion
 //#region src/elements/error.d.ts
 /**
- * `<sentinel-error>` · 错误(error 事件时显示)
+ * `<sentinel-error>` · 错误（显隐由组合层消费 playablechange 决定）
  *
  * 对应原 `<ErrorOverlay>`,但**文案解析上移了**(spec § 技术方案 ②):
  * 原版在组件内部做 `messages['error.<CODE>'] → error.message` 的回退,
  * 现在由组合层(`video-react` / embed-app)解析好,元素只收一个 `message` 字符串。
  * `code` 仍然保留 —— 它是给消费方做 `::part()` / 属性选择器和埋点用的。
  *
- * **`retryable` 决定给不给重试按钮**:对着一个必然失败的错误
- * (比如 `E_MEDIA_NOT_SUPPORTED`)给用户一个重试按钮是在骗人,点几次都不会好。
+ * `retryable` 是展示属性，由组合层根据 playablechange.action 为 retry/play 设置；
+ * 元素不读取 raw error 的 retryable，也不自行判断恢复预算。
  *
  * 点重试派发 `sentinel-retry`(CustomEvent,冒泡),替代原来的 `onRetry` 回调 prop。
  * 想整块换掉默认 UI,用 `<slot name="retry">`。
@@ -246,6 +246,9 @@ interface OverlayState {
   posterVisible: boolean;
   loadingVisible: boolean;
   error: PlayerError | null;
+  diagnostic?: PlayerError;
+  action?: 'retry' | 'play' | 'replace-source' | 'recreate-frame' | 'none';
+  sessionId?: string;
   /** 暂停图是否显示(契约字段 pauseImage,ADR-043)。`pause` 置起、`play` 撤下 */
   pauseImageVisible: boolean;
   /**

package/dist/index.d.mts

@@ -48,15 +48,15 @@ declare abstract class SentinelOverlayElement extends HTMLElement {
 //#endregion
 //#region src/elements/error.d.ts
 /**
- * `<sentinel-error>` · 错误(error 事件时显示)
+ * `<sentinel-error>` · 错误（显隐由组合层消费 playablechange 决定）
  *
  * 对应原 `<ErrorOverlay>`,但**文案解析上移了**(spec § 技术方案 ②):
  * 原版在组件内部做 `messages['error.<CODE>'] → error.message` 的回退,
  * 现在由组合层(`video-react` / embed-app)解析好,元素只收一个 `message` 字符串。
  * `code` 仍然保留 —— 它是给消费方做 `::part()` / 属性选择器和埋点用的。
  *
- * **`retryable` 决定给不给重试按钮**:对着一个必然失败的错误
- * (比如 `E_MEDIA_NOT_SUPPORTED`)给用户一个重试按钮是在骗人,点几次都不会好。
+ * `retryable` 是展示属性，由组合层根据 playablechange.action 为 retry/play 设置；
+ * 元素不读取 raw error 的 retryable，也不自行判断恢复预算。
  *
  * 点重试派发 `sentinel-retry`(CustomEvent,冒泡),替代原来的 `onRetry` 回调 prop。
  * 想整块换掉默认 UI,用 `<slot name="retry">`。
@@ -246,6 +246,9 @@ interface OverlayState {
   posterVisible: boolean;
   loadingVisible: boolean;
   error: PlayerError | null;
+  diagnostic?: PlayerError;
+  action?: 'retry' | 'play' | 'replace-source' | 'recreate-frame' | 'none';
+  sessionId?: string;
   /** 暂停图是否显示(契约字段 pauseImage,ADR-043)。`pause` 置起、`play` 撤下 */
   pauseImageVisible: boolean;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@video-lab/player-ui",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -28,7 +28,7 @@
     "dist/**/*.css"
   ],
   "dependencies": {
-    "@video-lab/protocol": "2.0.0"
+    "@video-lab/protocol": "3.0.0"
   },
   "devDependencies": {
     "jsdom": "^24.0.0",