@vivix-ai/ivi-frontend-sdk 0.2.3 → 0.2.4

package/README.md

@@ -7,27 +7,50 @@
 
 ## 安装依赖
 
-当前包尚未发布到 npm，通过 **GitLab 仓库地址**直接安装：
+当前包发布在公司 Nexus npm 镜像中。使用前请在业务项目根目录添加 `.npmrc`：
+
+```ini
+@vivix:registry=https://nexus.vivi-x.ai/repository/ivi-sdk-npm/
+```
+
+Nexus 仓库需要认证，请先配置只读账号：
+
+Username：ivi-sdk-readonly
+
+Password：ivi-sdk@2026
+
+```bash
+npm login --registry=https://nexus.vivi-x.ai/repository/ivi-sdk-npm/
+# 输入用户名和密码
+```
+
+验证配置是否生效：
+
+```bash
+npm whoami --registry=https://nexus.vivi-x.ai/repository/ivi-sdk-npm/
+```
+
+显示 ivi-sdk-readonly 为成功
+
+然后安装 SDK：
 
 ```bash
 # npm
-npm install git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+npm install @vivix/ivi-frontend-sdk
 
 # pnpm
-pnpm add git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+pnpm add @vivix/ivi-frontend-sdk
 
 # yarn
-yarn add git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+yarn add @vivix/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/ivi-frontend-sdk": "^0.2.2"
   }
 }
 ```
@@ -35,19 +58,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/ivi-frontend-sdk
 
 # pnpm
-pnpm add git+https://gitlab.vivix.work/vinf-2.0/ivi-sdk/ivi-frontend-sdk.git#main
+pnpm update @vivix/ivi-frontend-sdk
 
-# 若 lockfile 固定了旧 commit，可重新安装或删除 lock 中该依赖条目后 install
-npm install
+# yarn
+yarn up @vivix/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"]` 发布。因此发布前必须先完成构建，确保 Nexus 中的包包含可运行、可解析类型的产物。
 
 **协作约定**：修改 `src/` 后必须在本地执行 `npm run build`（或 `pnpm run build`），并将**与本次源码变更对应的一次完整 `dist/` 输出**一并提交：可与功能改动放在**同一提交**，或在必要时单独提交，提交信息示例：`chore: 重新构建 dist`。禁止只改源码而不更新 `dist/`，避免仓库内源码与产物不一致。
 
@@ -64,34 +87,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` 导入。
-
 ---
 
 ## 快速开始
@@ -198,8 +193,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` | 当前会话 |
+| `stage` | `IviStageComposition \| null` | 当前 stage（slot → track 映射） |
 | `tracks` | `Map<string, IviTrack>` | 所有 track |
 | `sources` | `Map<string, IviRuntimeSource>` | 所有 source（含 `status: created \| ready \| failed`） |
 | `conversationItems` | `Map<string, IviRuntimeConversationItem>` | 对话条目映射 |

package/dist/index.cjs

@@ -110,7 +110,7 @@ var SessionEventHandler = class {
     this.callbacks = callbacks;
   }
   handle(event) {
-    if (event instanceof iviSdkTs.SessionCreatedEvent) {
+    if (event instanceof iviSdkTs.ReceiveSessionCreatedEvent) {
       const before = this.sessionManager.getSession();
       this.sessionManager.setSession(event.session);
       logIviStateChange("session", null, event.type, before, this.sessionManager.getSession());
@@ -259,7 +259,7 @@ var SourceEventHandler = class {
         const before = this.sourceManager.get(sourceId);
         this.sourceManager.upsertCreated(source);
         this.sourceManager.applyPreload(sourceId, {
-          autoclearAfterPlay: event.autoclearAfterPlay
+          autoclearAfterPlay: event.autoclearAfterPlay ?? true
         });
         logIviStateChange("source", sourceId, event.type, before, this.sourceManager.get(sourceId));
       }
@@ -301,7 +301,7 @@ var StreamEventHandler = class {
     this.callbacks = callbacks;
   }
   handle(event) {
-    if (event instanceof iviSdkTs.SessionStreamCreatedEvent) {
+    if (event instanceof iviSdkTs.ReceiveSessionStreamCreatedEvent) {
       const streamId = event.stream.stream_id;
       const before = this.streamManager.getAll().get(streamId);
       this.streamManager.upsertCreated(event.stream);
@@ -374,32 +374,37 @@ var ConversationEventHandler = class {
       return { handled: true };
     }
     if (event instanceof iviSdkTs.ReceiveConversationItemAddedEvent) {
-      const before = this.conversationManager.getAllMap().get(event.item.id);
-      this.conversationManager.upsertAdded(event.item);
+      if (!event.item.id) return { handled: true };
+      const item = { ...event.item, id: event.item.id };
+      const before = this.conversationManager.getAllMap().get(item.id);
+      this.conversationManager.upsertAdded(item);
       logIviStateChange(
         "conversationItem",
-        event.item.id,
+        item.id,
         event.type,
         before,
-        this.conversationManager.getAllMap().get(event.item.id)
+        this.conversationManager.getAllMap().get(item.id)
       );
       this.callbacks.onConversationsChanged();
       return { handled: true };
     }
     if (event instanceof iviSdkTs.ReceiveConversationItemDoneEvent) {
-      const before = this.conversationManager.getAllMap().get(event.item.id);
-      this.conversationManager.markDone(event.item);
+      if (!event.item.id) return { handled: true };
+      const item = { ...event.item, id: event.item.id };
+      const before = this.conversationManager.getAllMap().get(item.id);
+      this.conversationManager.markDone(item);
       logIviStateChange(
         "conversationItem",
-        event.item.id,
+        item.id,
         event.type,
         before,
-        this.conversationManager.getAllMap().get(event.item.id)
+        this.conversationManager.getAllMap().get(item.id)
       );
       this.callbacks.onConversationsChanged();
       return { handled: true };
     }
     if (event instanceof iviSdkTs.ReceiveResponseOutputTextDeltaEvent) {
+      if (!event.itemId) return { handled: true };
       const before = this.conversationManager.getAllMap().get(event.itemId);
       this.conversationManager.applyTextDelta(event.itemId, event.delta);
       logIviStateChange(
@@ -413,6 +418,7 @@ var ConversationEventHandler = class {
       return { handled: true };
     }
     if (event instanceof iviSdkTs.ReceiveResponseOutputTextDoneEvent) {
+      if (!event.itemId) return { handled: true };
       const before = this.conversationManager.getAllMap().get(event.itemId);
       this.conversationManager.applyTextDone(event.itemId, event.text);
       logIviStateChange(
@@ -426,6 +432,7 @@ var ConversationEventHandler = class {
       return { handled: true };
     }
     if (event instanceof iviSdkTs.ReceiveResponseOutputAudioTranscriptDeltaEvent) {
+      if (!event.itemId) return { handled: true };
       const before = this.conversationManager.getAllMap().get(event.itemId);
       this.conversationManager.applyTranscriptDelta(event.itemId, event.delta);
       logIviStateChange(
@@ -439,6 +446,7 @@ var ConversationEventHandler = class {
       return { handled: true };
     }
     if (event instanceof iviSdkTs.ReceiveResponseOutputAudioTranscriptDoneEvent) {
+      if (!event.itemId) return { handled: true };
       const before = this.conversationManager.getAllMap().get(event.itemId);
       this.conversationManager.applyTranscriptDone(event.itemId, event.transcript);
       logIviStateChange(
@@ -550,13 +558,13 @@ var TrackManager = class {
     }
     this.patchTrack(trackId, {
       active_source_id: resolvedSourceId,
-      next_source_id: null
+      next_source_id: void 0
     });
   }
   applyTrackCued(trackId, sourceId) {
     this.patchTrack(trackId, {
       active_source_id: sourceId,
-      next_source_id: null
+      next_source_id: void 0
     });
   }
   applyTrackNextSet(trackId, sourceId) {
@@ -853,6 +861,7 @@ var ConversationManager = class {
     const nextItems = /* @__PURE__ */ new Map();
     const nextOrder = [];
     items.forEach((item) => {
+      if (!hasItemId(item)) return;
       const runtimeItem = this.buildRuntimeItem(item, item.status === "in_progress" ? "added" : "done");
       nextItems.set(runtimeItem.id, runtimeItem);
       nextOrder.push(runtimeItem.id);
@@ -1085,6 +1094,9 @@ var ConversationManager = class {
     ];
   }
 };
+function hasItemId(item) {
+  return typeof item.id === "string" && item.id.length > 0;
+}
 
 // src/runtime/managers/trtc-source-manager.ts
 var TAG = "[IVI-TRTC]";
@@ -1529,7 +1541,8 @@ var TrtcSourceManager = class {
   }
 };
 function isRuntimeTrtcSource(source) {
-  return source.status === "ready" && source.playback?.type === "trtc" && Boolean(source.playback.trtc);
+  const trtc = source.playback?.trtc;
+  return source.status === "ready" && source.playback?.type === "trtc" && typeof trtc?.app_id === "string" && typeof trtc.user_id === "string" && typeof trtc.user_sig === "string" && typeof trtc.room_id === "string";
 }
 function isSameTrtcConfig(a, b) {
   return a.app_id === b.app_id && a.user_id === b.user_id && a.user_sig === b.user_sig && a.room_id === b.room_id;
@@ -1960,7 +1973,7 @@ var IviRuntimeCoordinator = class {
       return [];
     }
     const missing = /* @__PURE__ */ new Set();
-    stage.composition.forEach((item) => {
+    stage.composition?.forEach((item) => {
       if (!hasTrack(item.track_id)) {
         missing.add(item.track_id);
       }
@@ -1995,7 +2008,11 @@ var IviRuntimeCoordinator = class {
   }
   progressUserTextToResponseFlows(event) {
     if (event instanceof iviSdkTs.ReceiveConversationItemAddedEvent) {
-      const flow = this.pendingUserTextToResponseFlows.get(event.item.id);
+      const itemId = event.item.id;
+      if (!itemId) {
+        return;
+      }
+      const flow = this.pendingUserTextToResponseFlows.get(itemId);
       if (!flow) {
         return;
       }
@@ -2005,7 +2022,11 @@ var IviRuntimeCoordinator = class {
       return;
     }
     if (event instanceof iviSdkTs.ReceiveConversationItemDoneEvent) {
-      const flow = this.pendingUserTextToResponseFlows.get(event.item.id);
+      const itemId = event.item.id;
+      if (!itemId) {
+        return;
+      }
+      const flow = this.pendingUserTextToResponseFlows.get(itemId);
       if (!flow) {
         return;
       }
@@ -2146,14 +2167,14 @@ function IVIStageView(props) {
 }
 function buildSlotTrackMapFromState(state) {
   const map = /* @__PURE__ */ new Map();
-  state.stage?.composition.forEach((item) => {
+  state.stage?.composition?.forEach((item) => {
     map.set(item.slot, item.track_id);
   });
   return map;
 }
 function buildSlotBindingsFromState(state) {
   const bindings = [];
-  state.stage?.composition.forEach((item) => {
+  state.stage?.composition?.forEach((item) => {
     const track = state.tracks.get(item.track_id);
     const sourceId = track?.active_source_id ?? null;
     const source = sourceId ? state.sources.get(sourceId) : void 0;
@@ -2443,6 +2464,7 @@ function useApplyVolumeToSlot(containerRef, volume, enabled, activeSourceId) {
     return () => observer.disconnect();
   }, [containerRef, volume, enabled, activeSourceId]);
 }
+var ALL_CONVERSATION_ROLES = ["user", "director", "model", "vlm"];
 function useSubtitleEntries(conversations, maxVisible, dismissAfterMs) {
   const [visibleIds, setVisibleIds] = react.useState([]);
   const timersRef = react.useRef(/* @__PURE__ */ new Map());
@@ -2518,26 +2540,82 @@ function useSubtitleEntries(conversations, maxVisible, dismissAfterMs) {
     }).filter((entry) => entry !== null);
   }, [visibleIds, conversationMap]);
 }
+function useSourceWindowSubtitleEntries(conversations, sourceKey) {
+  const normalizedSourceKey = sourceKey ?? null;
+  const [windowState, setWindowState] = react.useState(() => ({
+    sourceKey: normalizedSourceKey,
+    baselineIds: new Set(conversations.map((item) => item.id)),
+    visibleIds: []
+  }));
+  react.useEffect(() => {
+    setWindowState((prev) => {
+      if (prev.sourceKey !== normalizedSourceKey) {
+        return {
+          sourceKey: normalizedSourceKey,
+          baselineIds: new Set(conversations.map((item) => item.id)),
+          visibleIds: []
+        };
+      }
+      if (!normalizedSourceKey) {
+        return prev.visibleIds.length === 0 ? prev : { ...prev, visibleIds: [] };
+      }
+      const nextVisibleIds = conversations.filter((item) => {
+        const displayText = item.text || item.transcript;
+        return Boolean(displayText) && !prev.baselineIds.has(item.id);
+      }).map((item) => item.id);
+      if (nextVisibleIds.length === prev.visibleIds.length && nextVisibleIds.every((id, index) => id === prev.visibleIds[index])) {
+        return prev;
+      }
+      return {
+        ...prev,
+        visibleIds: nextVisibleIds
+      };
+    });
+  }, [conversations, normalizedSourceKey]);
+  const conversationMap = react.useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const item of conversations) {
+      map.set(item.id, item);
+    }
+    return map;
+  }, [conversations]);
+  return react.useMemo(() => {
+    if (windowState.sourceKey !== normalizedSourceKey) {
+      return [];
+    }
+    return windowState.visibleIds.map((id) => {
+      const item = conversationMap.get(id);
+      if (!item) return null;
+      const text = item.text || item.transcript;
+      if (!text) return null;
+      return { id: item.id, role: item.role, text, lifecycle: item.lifecycle };
+    }).filter((entry) => entry !== null);
+  }, [windowState.sourceKey, windowState.visibleIds, conversationMap, normalizedSourceKey]);
+}
 var BREATHE_KEYFRAMES = `@keyframes ivi-subtitle-breathe{0%,100%{opacity:1}50%{opacity:.55}}`;
 function IVISubtitleOverlay(props) {
   const {
     conversations,
-    roles = "user",
+    roles,
     maxVisible = 2,
     dismissAfterMs = 5e3,
+    stickySourceKey,
     subtitleStyle,
     className,
     style
   } = props;
+  const resolvedRoles = roles ?? (stickySourceKey ? ALL_CONVERSATION_ROLES : "user");
   const roleSet = react.useMemo(
-    () => new Set(Array.isArray(roles) ? roles : [roles]),
-    [roles]
+    () => new Set(Array.isArray(resolvedRoles) ? resolvedRoles : [resolvedRoles]),
+    [resolvedRoles]
   );
   const filtered = react.useMemo(
     () => conversations.filter((c) => roleSet.has(c.role)),
     [conversations, roleSet]
   );
-  const entries = useSubtitleEntries(filtered, maxVisible, dismissAfterMs);
+  const queueEntries = useSubtitleEntries(filtered, maxVisible, dismissAfterMs);
+  const sourceWindowEntries = useSourceWindowSubtitleEntries(filtered, stickySourceKey);
+  const entries = stickySourceKey ? sourceWindowEntries : queueEntries;
   if (entries.length === 0) return null;
   const fontFamily = subtitleStyle?.fontFamily ?? "system-ui, -apple-system, sans-serif";
   const fontSize = subtitleStyle?.fontSize ?? 14;
@@ -3082,6 +3160,14 @@ function supportsSubtitleOverlay(source) {
   if (source.source.asset_type === "image") return false;
   return source.source.kind === "stream" || source.source.kind === "generation_stream" || source.source.kind === "generated_clip" || source.source.kind === "static";
 }
+function supportsGeneratedClipStickySubtitles(source) {
+  if (!source) return false;
+  if (source.source.kind !== "generated_clip") return false;
+  if (source.source.asset_type === "image") return false;
+  if (source.playback.type === "trtc") return false;
+  const playbackUrl = source.playback.url;
+  return typeof playbackUrl === "string" && isM3u8Url(playbackUrl);
+}
 function detectMediaVolumeType(source) {
   if (!source) return null;
   if (source.playback.type === "trtc") return "trtc";
@@ -3117,7 +3203,7 @@ function TrackSlotMediaContent(props) {
   const shouldMute = !isActive;
   if (renderMedia) return renderMedia(renderContext);
   if (source.playback.type === "trtc") {
-    if (!source.playback.trtc) return null;
+    if (!isRuntimeTrtcPlayback(source.playback.trtc)) return null;
     if (renderTrtc) return renderTrtc(renderContext);
     const trtcMuted = shouldMute || Boolean(trtcPlayerProps?.muted);
     return /* @__PURE__ */ jsxRuntime.jsx(
@@ -3182,6 +3268,9 @@ function TrackSlotMediaContent(props) {
     }
   );
 }
+function isRuntimeTrtcPlayback(trtc) {
+  return typeof trtc?.app_id === "string" && typeof trtc.user_id === "string" && typeof trtc.user_sig === "string" && typeof trtc.room_id === "string";
+}
 function buildAdaptiveMediaStyle(source, adaptToSourceSize, fitStrategy, background) {
   const objectFitStyle = fitStrategy === "auto" ? {} : {
     objectFit: fitStrategy ?? "contain"
@@ -3278,6 +3367,7 @@ function IVITrackSlot(props) {
     volumeControlProps,
     showSubtitle,
     subtitleProps,
+    keepGeneratedClipSubtitlesUntilEnded = false,
     background = "black"
   } = props;
   const context = useIviStageView();
@@ -3288,6 +3378,7 @@ function IVITrackSlot(props) {
   const preloadEntries = useMultiPreloadSources(context.state.sources, activeSourceId);
   const activeEntry = preloadEntries.find((e) => e.isActive) ?? null;
   const activeSource = activeEntry?.source ?? null;
+  const stickySubtitleSourceKey = keepGeneratedClipSubtitlesUntilEnded && supportsGeneratedClipStickySubtitles(activeSource) ? activeSourceId : null;
   const mediaType = detectMediaVolumeType(activeSource);
   const [volume, setVolume] = useVolumeMemory(showVolumeControl ? mediaType : null);
   useApplyVolumeToSlot(containerRef, volume, !!showVolumeControl && mediaType !== null, activeSourceId);
@@ -3350,7 +3441,8 @@ function IVITrackSlot(props) {
           IVISubtitleOverlay,
           {
             conversations: context.state.conversations,
-            ...subtitleProps
+            ...subtitleProps,
+            stickySourceKey: stickySubtitleSourceKey
           }
         ) }),
         showVolumeControl && mediaType !== null && /* @__PURE__ */ jsxRuntime.jsx("div", { style: VOLUME_OVERLAY_STYLE, children: /* @__PURE__ */ jsxRuntime.jsx(