@vivix-ai/ivi-frontend-sdk 0.2.2 → 0.3.0

package/README.md

@@ -2,32 +2,32 @@
 
 用于前端应用集成 IVI 实时能力的 TypeScript SDK，包含：
 
-- 基于 `@vivix/ivi-sdk-ts` 的 runtime 协调层
+- 基于 `@vivix-ai/ivi-sdk-ts` 的 runtime 协调层
 - 面向舞台渲染的 React 组件与 hooks
 
 ## 安装依赖
 
-当前包尚未发布到 npm，通过 **GitLab 仓库地址**直接安装：
+当前包发布到 npm 官方仓库，包名为 `@vivix-ai/ivi-frontend-sdk`。
+
+安装 SDK：
 
 ```bash
 # npm
-npm install git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+npm install @vivix-ai/ivi-frontend-sdk
 
 # pnpm
-pnpm add git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+pnpm add @vivix-ai/ivi-frontend-sdk
 
 # yarn
-yarn add git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+yarn add @vivix-ai/ivi-frontend-sdk
 ```
 
-> **推荐使用 `#main` 分支。** `dev` 分支可能引入尚未稳定的新特性，不保证向后兼容；`main` 分支仅包含经过验证的变更。如需锁定到更精确的版本，可替换为具体 tag 或 commit hash。
-
 安装后 `package.json` 中会出现类似条目：
 
 ```json
 {
   "dependencies": {
-    "@vivix/ivi-frontend-sdk": "git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main"
+    "@vivix-ai/ivi-frontend-sdk": "^0.3.0"
   }
 }
 ```
@@ -35,19 +35,19 @@ yarn add git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#mai
 **更新到最新版本**：
 
 ```bash
-# npm（Git 依赖建议显式指定分支、tag 或 commit）
-npm install git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+# npm
+npm update @vivix-ai/ivi-frontend-sdk
 
 # pnpm
-pnpm add git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+pnpm update @vivix-ai/ivi-frontend-sdk
 
-# 若 lockfile 固定了旧 commit，可重新安装或删除 lock 中该依赖条目后 install
-npm install
+# yarn
+yarn up @vivix-ai/ivi-frontend-sdk
 ```
 
-### `dist` 与 Git 直装
+### `dist` 与 npm 发布
 
-`package.json` 的 `main` / `module` / `types` / `exports` 均指向 `dist/`，且 npm 包通过 `"files": ["dist"]` 发布。从 **Git 引用安装**（如 `git+https://…#dev`）时，npm 只会打包 `files` 所列内容；因此 **`dist/` 已纳入版本库**，克隆默认分支即可得到可运行、可解析类型的产物。
+`package.json` 的 `main` / `module` / `types` / `exports` 均指向 `dist/`，且 npm 包通过 `"files": ["dist"]` 发布到 npm 官方仓库。因此发布前必须先完成构建，确保 npm 包包含可运行、可解析类型的产物。
 
 **协作约定**：修改 `src/` 后必须在本地执行 `npm run build`（或 `pnpm run build`），并将**与本次源码变更对应的一次完整 `dist/` 输出**一并提交：可与功能改动放在**同一提交**，或在必要时单独提交，提交信息示例：`chore: 重新构建 dist`。禁止只改源码而不更新 `dist/`，避免仓库内源码与产物不一致。
 
@@ -64,34 +64,6 @@ React 为可选 peer dependency，仅使用 React 组件时需要：
 
 如果只使用 runtime 能力、不接入 React 组件与 hooks，可忽略本文中的 React 用法部分。
 
-## 包导出与导入方式
-
-当前仅支持单一主入口：
-
-| 入口 | 路径 | 说明 |
-|------|------|------|
-| 主入口 | `@vivix/ivi-frontend-sdk` | 导出 runtime 能力、`IviFrontendSdk`、以及当前公开的 React API：`IVIStageView`、`IVITrackSlot`、`useManagedIviRuntime`、`useIviStageView` |
-
-**导入示例**：
-
-```ts
-// 底层 client 由 @vivix/ivi-sdk-ts 提供
-import { IviClient } from "@vivix/ivi-sdk-ts";
-
-// 本包主入口
-import {
-  IviRuntimeCoordinator,
-  IviRuntimeDispatcher,
-  IviFrontendSdk,
-  IVIStageView,
-  IVITrackSlot,
-  useManagedIviRuntime,
-  useIviStageView
-} from "@vivix/ivi-frontend-sdk";
-```
-
-> 当前包没有 `@vivix/ivi-frontend-sdk/core` / `@vivix/ivi-frontend-sdk/react` 子入口；底层 WebSocket client、事件解析与协议类型请直接从 `@vivix/ivi-sdk-ts` 导入。
-
 ---
 
 ## 快速开始
@@ -99,12 +71,15 @@ import {
 ### 1）创建 client + runtime
 
 ```ts
-import { IviClient } from "@vivix/ivi-sdk-ts";
-import { IviRuntimeCoordinator } from "@vivix/ivi-frontend-sdk";
+import { IviClient } from "@vivix-ai/ivi-sdk-ts";
+import { IviRuntimeCoordinator } from "@vivix-ai/ivi-frontend-sdk";
+import { LiveKitBrowserTransport } from "@vivix-ai/ivi-sdk-ts/transports/livekit-browser";
 
 const client = new IviClient({
-  url: "wss://your-domain/v1/realtime",
-  sessionId: "sess_xxx",
+  transport: new LiveKitBrowserTransport({
+    url: "wss://livekit.example.com",
+    token: "livekit_access_token"
+  }),
   onParseError: (error, raw) => {
     console.error("parse error", error, raw);
   }
@@ -120,17 +95,42 @@ const runtime = new IviRuntimeCoordinator(client, {
 await runtime.start();
 ```
 
+也可以使用 `IviFrontendSdk` 创建 client/runtime：
+
+```ts
+import { IviFrontendSdk } from "@vivix-ai/ivi-frontend-sdk";
+import { LiveKitBrowserTransport } from "@vivix-ai/ivi-sdk-ts/transports/livekit-browser";
+
+const sdk = new IviFrontendSdk();
+const runtime = sdk.createRuntimeCoordinator(
+  {
+    transport: new LiveKitBrowserTransport({
+      url: "wss://livekit.example.com",
+      token: "livekit_access_token"
+    })
+  },
+  {
+    syncStageOnSessionCreated: true
+  }
+);
+
+await runtime.start();
+```
+
 **使用自定义 WebSocket 运行时**（Node.js / 自定义环境）：
 
 ```ts
 import WebSocket from "ws"; // Node.js 环境
-import { IviClient } from "@vivix/ivi-sdk-ts";
-import { IviRuntimeCoordinator } from "@vivix/ivi-frontend-sdk";
+import { IviClient } from "@vivix-ai/ivi-sdk-ts";
+import { WebSocketTransport } from "@vivix-ai/ivi-sdk-ts/transports/websocket";
+import { IviRuntimeCoordinator } from "@vivix-ai/ivi-frontend-sdk";
 
 const client = new IviClient({
-  url: "wss://your-domain/v1/realtime",
-  sessionId: "sess_xxx",
-  socketFactory: (url, protocols) => new WebSocket(url, protocols),
+  transport: new WebSocketTransport({
+    url: "wss://your-domain/v1/realtime",
+    sessionId: "sess_xxx",
+    socketFactory: (url, protocols) => new WebSocket(url, protocols)
+  }),
   onParseError: (error, raw) => {
     console.error("parse error", error, raw);
   }
@@ -140,15 +140,13 @@ const runtime = new IviRuntimeCoordinator(client);
 await runtime.start();
 ```
 
-`IviClientConfig` 关键配置：
+`IviFrontendClientConfig` 等同于 `@vivix-ai/ivi-sdk-ts` 的 `IviClientConfig`，需要直接传入通用 `transport`。
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `protocols` | `string \| string[]` | WebSocket 子协议 |
-| `sessionId` | `string` | 会话 ID，连接时自动追加到 URL query `session_id=<id>` |
-| `socketFactory` | `(url, protocols?) => WebSocket` | 自定义 Socket 工厂，用于替换默认 WebSocket 构造 |
+| `transport` | `IviRealtimeTransport` | 通用 transport，直接透传给 `@vivix-ai/ivi-sdk-ts`；浏览器 LiveKit 场景可传 `LiveKitBrowserTransport` |
 | `onParseError` | `(error, rawMessage) => void` | 事件解析失败回调 |
-| `onLog` | `(entry) => void` | `IviClient` 链路日志回调，包含发送、WebSocket 状态和重连链路 |
+| `onLog` | `(entry) => void` | `IviClient` 链路日志回调，包含发送、transport 状态和重连链路 |
 | `reconnect` | `IviClientReconnectOptions` | 自动重连配置；默认启用，指数退避 |
 | `sendWaitTimeoutMs` | `number` | 发送时等待连接恢复的超时，默认 `30000` ms，`<=0` 表示无限等待 |
 
@@ -172,14 +170,14 @@ runtime.stop();
 ### 3）发送用户文本并触发模型回复
 
 ```ts
-const result = await runtime.sendUserTextAndTriggerStreamResponse({
+const result = await runtime.sendUserTextAndTriggerResponse({
   streamId: "stream_001",
   text: "你好",
   callbacks: {
     onConversationItemAdded: (event) => console.log("item added"),
     onConversationItemDone: (event) => console.log("item done"),
     onConversationItemReady: ({ itemId }) => console.log("item ready:", itemId),
-    onStreamResponseCreated: (event) => console.log("response created")
+    onResponseCreated: (event) => console.log("response created")
   }
 });
 console.log("完成:", result.itemId, result.streamId);
@@ -198,8 +196,8 @@ runtime.sendSessionSourcePlaybackCompleted("source_001", "track_001");
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `status` | `"idle" \| "connecting" \| "syncing" \| "running" \| "stopped"` | 生命周期状态 |
-| `session` | `IviRealtimeSession \| null` | 当前会话 |
-| `stage` | `IviStage \| null` | 当前 stage（slot → track 映射） |
+| `session` | `IviRealtimeSessionConfig \| null` | 当前会话（来自 `@vivix-ai/ivi-sdk-ts`） |
+| `stage` | `IviStageComposition \| null` | 当前 stage（slot → track 映射，来自 `@vivix-ai/ivi-sdk-ts`） |
 | `tracks` | `Map<string, IviTrack>` | 所有 track |
 | `sources` | `Map<string, IviRuntimeSource>` | 所有 source（含 `status: created \| ready \| failed`） |
 | `conversationItems` | `Map<string, IviRuntimeConversationItem>` | 对话条目映射 |
@@ -212,11 +210,17 @@ runtime.sendSessionSourcePlaybackCompleted("source_001", "track_001");
 ### 方式 A：传入外部 runtime
 
 ```tsx
-import { IviClient } from "@vivix/ivi-sdk-ts";
-import { IviRuntimeCoordinator, IVIStageView, IVITrackSlot, useIviStageView } from "@vivix/ivi-frontend-sdk";
+import { IviClient } from "@vivix-ai/ivi-sdk-ts";
+import { IviRuntimeCoordinator, IVIStageView, IVITrackSlot, useIviStageView } from "@vivix-ai/ivi-frontend-sdk";
+import { LiveKitBrowserTransport } from "@vivix-ai/ivi-sdk-ts/transports/livekit-browser";
 
 // 初始化 runtime（参考上方 Core 用法）
-const client = new IviClient({ url: "wss://your-domain/v1/realtime", sessionId: "sess_xxx" });
+const client = new IviClient({
+  transport: new LiveKitBrowserTransport({
+    url: "wss://livekit.example.com",
+    token: "livekit_access_token"
+  })
+});
 const runtime = new IviRuntimeCoordinator(client);
 await runtime.start();
 
@@ -244,16 +248,19 @@ export function StagePage() {
 ### 方式 B：使用 `useManagedIviRuntime` 管理 runtime
 
 ```tsx
-import { IVIStageView, IVITrackSlot, useManagedIviRuntime } from "@vivix/ivi-frontend-sdk";
+import { IVIStageView, IVITrackSlot, useManagedIviRuntime } from "@vivix-ai/ivi-frontend-sdk";
+import { LiveKitBrowserTransport } from "@vivix-ai/ivi-sdk-ts/transports/livekit-browser";
 
-export function AutoStagePage({ sessionId }: { sessionId: string }) {
+export function AutoStagePage({ livekitToken }: { livekitToken: string }) {
   const runtime = useManagedIviRuntime({
     clientConfig: {
-      url: "https://your-domain.com/v1/realtime",
-      sessionId
+      transport: new LiveKitBrowserTransport({
+        url: "wss://livekit.example.com",
+        token: livekitToken
+      })
     },
     onLog: (entry) => {
-      // 统一收集 client / runtime / TRTC 的 IVI 链路日志
+      // 统一收集 client / runtime / TRTC / LiveKit 的 IVI 链路日志
       console.log(entry.tag, entry.message, entry.data);
     },
     onRuntimeInitError: (err) => console.error("runtime init failed", err)
@@ -267,14 +274,12 @@ export function AutoStagePage({ sessionId }: { sessionId: string }) {
 }
 ```
 
-`useManagedIviRuntime` 的地址规则：
+`useManagedIviRuntime` 的连接规则：
 
-1. 使用 `clientConfig.url`
-2. 若 `clientConfig.url` 为 `https://` / `http://`，内部会自动确保为 `wss://` / `ws://`
-3. 若 `clientConfig.sessionId` 为空，则不创建 runtime
-4. 若 `clientConfig.url` 为空，会通过 `onRuntimeInitError` 抛出初始化错误；若未提供回调，则直接抛错
-
-连接时自动追加 query：`?session_id=<sessionId>`。
+1. 使用 `clientConfig.transport`
+2. 若 `clientConfig.transport` 为空，则不创建 runtime
+3. 浏览器 LiveKit 场景可传 `LiveKitBrowserTransport`
+4. WebSocket、测试 fake transport 或其它 transport 也通过同一个 `transport` 字段传入
 
 ---
 
@@ -292,17 +297,17 @@ function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRuntimeCoordi
 - `autoStart` 为 `true` 时自动调用 `runtime.start()`
 - 卸载时自动 `runtime.stop()`
 - 初始化错误通过 `onRuntimeInitError` 上抛
-- 通过 `onLog` 统一收集 `IviClient`、runtime 状态变更、TRTC 管理器等 IVI 链路日志
+- 通过 `onLog` 统一收集 `IviClient`、runtime 状态变更、TRTC / LiveKit 管理器等 IVI 链路日志
 
 `IviManagedRuntimeConfig` 关键字段：
 
 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `clientConfig` | `IviClientConfig` | — | `IviClient` 配置；其中 `url` 用于建立连接，`sessionId` 用于决定是否创建 runtime |
+| `clientConfig` | `Partial<IviFrontendClientConfig>` | — | `IviClient` 配置；`transport` 为空时不创建 runtime |
 | `autoStart` | `boolean` | `true` | 是否自动启动 runtime |
 | `runtimeConfig` | `IviRuntimeCoordinatorConfig` | — | 透传给 `IviRuntimeCoordinator` |
 | `onRuntimeInitError` | `(error) => void` | — | 初始化或启动失败回调 |
-| `onLog` | `(entry) => void` | — | 统一日志回调，覆盖 `[IVI-SEND]`、`[IVI-WS]`、`[IVI-RECONNECT]`、`[IVI-EVT]`、`[IVI-STATE]`、`[IVI-TRTC]` |
+| `onLog` | `(entry) => void` | — | 统一日志回调，覆盖 `[IVI-SEND]`、`[IVI-TRANSPORT]`、`[IVI-RECONNECT]`、`[IVI-EVT]`、`[IVI-STATE]`、`[IVI-TRTC]`、`[IVI-LIVEKIT]` |
 
 `onLog` 的统一入参格式：
 
@@ -310,7 +315,7 @@ function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRuntimeCoordi
 interface IviManagedRuntimeLogEntry {
   level: "info" | "warn" | "error";
   source: "client" | "runtime";
-  tag: string;          // 例如 "[IVI-WS]"、"[IVI-STATE]"
+  tag: string;          // 例如 "[IVI-TRANSPORT]"、"[IVI-STATE]"
   message: string;      // 带 tag 的可读日志
   args: unknown[];      // 接近原 console 调用的参数
   data?: unknown;       // 结构化数据
@@ -341,7 +346,50 @@ function MyOverlay() {
 }
 ```
 
-以下 hooks 为 `IVITrackSlot` 内部实现，当前不属于公开导出 API。
+### `useRuntimeState`
+
+```ts
+function useRuntimeState(runtime: IviRuntimeCoordinator | null): IviRuntimeState;
+```
+
+订阅 runtime 状态变化。`runtime` 为 `null` 时返回 `EMPTY_RUNTIME_STATE`。
+
+### `useIviSubtitles`
+
+```ts
+function useIviSubtitles(
+  runtime: IviRuntimeCoordinator | null,
+  options?: IviUseSubtitlesOptions
+): IviSubtitleItem[];
+```
+
+基于 runtime 的 conversation / response 事件维护字幕队列，不负责渲染，也不按时间自动消失。
+
+| Option | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `roles` | `IviSubtitleRole \| IviSubtitleRole[]` | `"user"` | 要收集的发言人角色 |
+| `maxItems` | `number` | `2` | 最多保留的字幕条数，超过后清理最旧条目 |
+
+`IviSubtitleItem` 包含 `id`、`role`、`lifecycle`、`status`、`text`、`transcript`、`displayText`、`timestamp`、`updatedAt`、`content`、`item`。
+
+```tsx
+function CustomSubtitles({ runtime }: { runtime: IviRuntimeCoordinator | null }) {
+  const subtitles = useIviSubtitles(runtime, {
+    roles: ["user", "model"],
+    maxItems: 5
+  });
+
+  return (
+    <div>
+      {subtitles.map((item) => (
+        <span key={item.id}>{item.displayText}</span>
+      ))}
+    </div>
+  );
+}
+```
+
+以下 hooks 为 `IVITrackSlot` 内部实现，当前不属于包根公开导出 API。
 
 ### `useVolumeMemory`
 
@@ -349,7 +397,7 @@ function MyOverlay() {
 function useVolumeMemory(mediaType: IviMediaVolumeType | null): [number, (v: number) => void];
 ```
 
-按媒体类型（`"trtc" | "video" | "hls"`）在 `localStorage` 中持久化音量（0–100）。`mediaType` 为 `null` 时不持久化。
+按媒体类型（`"trtc" | "livekit" | "video" | "hls"`）在 `localStorage` 中持久化音量（0–100）。`mediaType` 为 `null` 时不持久化。
 
 ### `useApplyVolumeToSlot`
 
@@ -362,13 +410,13 @@ function useApplyVolumeToSlot(
 ): void;
 ```
 
-将音量同步应用到容器内带 `data-ivi-slot-role="active"` 属性的 `<video>` / `<audio>` 元素，通过 `MutationObserver` 监听异步插入的媒体（如 TRTC 远端流）。
+将音量同步应用到容器内带 `data-ivi-slot-role="active"` 属性的 `<video>` / `<audio>` 元素，通过 `MutationObserver` 监听异步插入的媒体（如 TRTC / LiveKit 远端流）。
 
 ---
 
 ## React 组件
 
-当前公开导出的 React 组件只有 `IVIStageView` 与 `IVITrackSlot`；当前公开导出的 React hooks 只有 `useManagedIviRuntime` 与 `useIviStageView`。
+当前公开导出的 React 组件包括 `IVIStageView`、`IVITrackSlot`、`IVITrtcPlayer`、`IVILivekitPlayer` 与 `IVISubtitleOverlay`；当前公开导出的 React hooks 包括 `useManagedIviRuntime`、`useRuntimeState`、`useIviStageView` 与 `useIviSubtitles`。
 
 ### `IVIStageView`
 
@@ -392,20 +440,19 @@ function useApplyVolumeToSlot(
 | `trackId` | `string` | — | 直接绑定 trackId |
 | `emptyFallback` | `ReactNode` | — | 无 source 时的兜底内容 |
 | `renderTrtc` | `(ctx: IviTrackSlotRenderContext) => ReactNode` | — | 自定义 TRTC 渲染 |
-| `renderMedia` | `(ctx: IviTrackSlotRenderContext) => ReactNode` | — | 自定义非 TRTC 媒体渲染 |
+| `renderLivekit` | `(ctx: IviTrackSlotRenderContext) => ReactNode` | — | 自定义 LiveKit 远端流渲染 |
+| `renderMedia` | `(ctx: IviTrackSlotRenderContext) => ReactNode` | — | 自定义非 TRTC / LiveKit 媒体渲染 |
 | `fitStrategy` | `"contain" \| "cover" \| "auto"` | — | 媒体适配策略 |
 | `adaptToSourceSize` | `boolean` | — | 是否根据 source 尺寸自适应 |
-| `background` | `IviTrackSlotBackground` | `"black"` | 媒体空白区域（letterbox/pillarbox）背景模式 |
 | `showVolumeControl` | `boolean` | — | 是否显示音量控制浮层 |
 | `volumeControlProps` | — | — | 音量控制自定义配置 |
 | `showSubtitle` | `boolean` | — | 是否显示字幕浮层 |
-| `subtitleProps` | — | — | 字幕自定义配置 |
+| `subtitleProps` | `Omit<IVISubtitleOverlayProps, "runtime">` | — | 字幕自定义配置 |
 | `trtcPlayerProps` | — | — | TRTC 播放器自定义配置 |
+| `livekitPlayerProps` | — | — | LiveKit 播放器自定义配置 |
 | `videoProps` / `imageProps` | — | — | 透传给原生 `<video>` / `<img>` |
 | `className` / `style` | — | — | 容器样式 |
 
-`IviTrackSlotBackground` 支持的值：`"black"` | `"white"` | `"transparent"` | `{ color: string }` | `"blur"` | `{ blur: "live" | "static" }`
-
 `IviTrackSlotRenderContext`：
 
 ```ts
@@ -417,7 +464,7 @@ interface IviTrackSlotRenderContext {
 }
 ```
 
-以下组件为 `IVITrackSlot` 依赖的内部实现，当前不属于公开导出 API。
+以下远端播放器可由 `IVITrackSlot` 默认使用，也可在业务侧按需直接使用。
 
 ### `IVITrtcPlayer`
 
@@ -425,7 +472,21 @@ TRTC 远端流播放器，自动以 audience 身份入会并订阅远端流。
 
 | Prop | 类型 | 说明 |
 |------|------|------|
-| `trtc` | TRTC 实例 | TRTC SDK 实例 |
+| `trtc` | `IviSourcePlaybackTrtc` | TRTC 拉流配置 |
+| `sourceId` | `string` | source ID |
+| `runtime` | `IviRuntimeCoordinator` | runtime 实例 |
+| `loadingFallback` | `ReactNode` | 加载中兜底 |
+| `errorFallback` | `ReactNode` | 错误兜底 |
+| `muted` | `boolean` | 是否静音 |
+| `className` / `style` | — | 容器样式 |
+
+### `IVILivekitPlayer`
+
+LiveKit 远端音视频播放器，挂载后加入房间并订阅远端 tracks。`ivi-frontend-sdk` 只负责拉取和播放远端音视频流，不再发布用户麦克风；麦克风采集 / ASR 数据链路请使用 `@vivix-ai/ivi-sdk-ts/transports/livekit-browser` 或业务侧 transport。
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `livekit` | LiveKit playback 配置 | 包含 `ws_url`、`token`，以及可选 `room` / `identity` |
 | `sourceId` | `string` | source ID |
 | `runtime` | `IviRuntimeCoordinator` | runtime 实例 |
 | `loadingFallback` | `ReactNode` | 加载中兜底 |
@@ -433,9 +494,9 @@ TRTC 远端流播放器，自动以 audience 身份入会并订阅远端流。
 | `muted` | `boolean` | 是否静音 |
 | `className` / `style` | — | 容器样式 |
 
-### `IVIHlsVideo`
+### `IVIHlsVideo`（内部组件）
 
-HLS 流播放器（基于 `hls.js`），用于 `.m3u8` 地址播放。辅助函数 `isM3u8Url(url)` 可判断 URL 是否为 m3u8。
+HLS 流播放器（基于 `hls.js`），由 `IVITrackSlot` 内部用于 `.m3u8` 地址播放；当前不从包根公开导出。
 
 | Prop | 类型 | 说明 |
 |------|------|------|
@@ -445,18 +506,17 @@ HLS 流播放器（基于 `hls.js`），用于 `.m3u8` 地址播放。辅助函
 | `aggressivePreload` | `boolean` | 激进预加载模式 |
 | `paused` | `boolean` | 是否暂停 |
 
-> 隐藏原生控件（包括进度条）：SDK 未提供单独隐藏进度条的开关，HTML5 `<video>` 也不支持只隐藏 timeline。可通过 `videoProps.controls = false` 关闭整套原生控件，适用于 `IVIHlsVideo` 与 `IVITrackSlot`：
+> 隐藏原生控件（包括进度条）：SDK 未提供单独隐藏进度条的开关，HTML5 `<video>` 也不支持只隐藏 timeline。可通过 `videoProps.controls = false` 关闭整套原生控件，适用于 `IVITrackSlot`：
 >
 > ```tsx
-> <IVIHlsVideo url={url} videoProps={{ controls: false }} />
 > <IVITrackSlot slot="main" videoProps={{ controls: false }} />
 > ```
 >
 > 若需“保留播放/音量，仅隐藏进度条”，请在上层自行渲染自定义控制栏。
 
-### `IVIVolumeControl`
+### `IVIVolumeControl`（内部组件）
 
-音量控制浮层组件。
+音量控制浮层组件，由 `IVITrackSlot` 在 `showVolumeControl` 开启时内部使用；当前不从包根公开导出。
 
 | Prop | 类型 | 说明 |
 |------|------|------|
@@ -468,13 +528,14 @@ HLS 流播放器（基于 `hls.js`），用于 `.m3u8` 地址播放。辅助函
 
 ### `IVISubtitleOverlay`
 
-字幕浮层组件，展示对话条目流式字幕。
+预制字幕浮层组件，内部通过 `useIviSubtitles` 监听 runtime 的 conversation / response 事件并展示字幕。
 
 | Prop | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `conversations` | `IviRuntimeConversationItem[]` | — | 会话条目列表 |
-| `maxVisible` | `number` | `2` | 同时可见的最大条目数 |
-| `dismissAfterMs` | `number` | `5000` | 条目完成后自动消失毫秒数 |
+| `runtime` | `IviRuntimeCoordinator \| null` | — | 字幕来源 runtime |
+| `roles` | `IviSubtitleRole \| IviSubtitleRole[]` | `"user"` | 要展示的发言人角色 |
+| `maxItems` | `number` | `2` | 最多保留的字幕条数，超过后清理最旧条目 |
+| `maxVisible` | `number` | — | 已废弃，兼容旧字段；请使用 `maxItems` |
 | `subtitleStyle` | `IVISubtitleOverlayStyle` | — | 样式配置 |
 | `className` / `style` | — | — | 样式 |
 
@@ -493,7 +554,7 @@ HLS 流播放器（基于 `hls.js`），用于 `.m3u8` 地址播放。辅助函
 | `sendSessionSourcePlaybackCompleted(sourceId, trackId?)` | 上报 source 播放完成 |
 | `sendConversationList()` | 请求对话列表 |
 | `sendConversationItemCreate(item)` | 创建对话条目 |
-| `sendConversationUserText(text, itemId?)` | 发送用户文本，返回 `Promise<string>`，resolve 为最终 itemId |
+| `sendUserText(text, itemId?)` | 发送用户文本 |
 | `sendResponseCreate(streamId?, response?)` | 触发模型回复；`streamId` 可选，省略时使用 session 级配置 |
 | `sendResponseCreateByItemId(itemId, streamId?, response?)` | 基于条目 ID 触发模型回复 |
 
@@ -549,13 +610,13 @@ npm run test
 仓库提供版本提升脚本，执行前要求工作区干净：
 
 ```bash
-npm run release:version -- 0.2.2
+npm run release:version -- 0.3.0
 ```
 
 脚本会同步更新 `package.json` / `package-lock.json`，提交：
 
 ```text
-chore: update package version to 0.2.2
+chore: update package version to 0.3.0
 ```
 
-并创建 tag：`v0.2.2`。
+并创建 tag：`v0.3.0`。