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

package/dist/index.d.cts

@@ -1,12 +1,21 @@
-import { IviRealtimeSession, IviStage, IviTrack, IviSource, IviSourcePlayback, IviSessionSourceFailedPayload, IviStream, IviStreamStatus, IviConversationItemRole, IviConversationItem, IviConversationItemContent, ReceiveSessionEndedEvent, ParsedIviEvent, IviRealtimeResponseCreateParams, ReceiveConversationItemAddedEvent, ReceiveConversationItemDoneEvent, ReceiveResponseCreatedEvent, IviSourcePlaybackTrtc, IviClient, IviClientConfig } from '@vivix/ivi-sdk-ts';
+import { IviRealtimeSessionConfig, IviStageComposition, IviTrack, IviSourceAsset, IviReceiveSessionSourceReadyPayload, IviReceiveSessionSourceFailedPayload, IviStream, IviConversationItem, IviConversationItemContent, ReceiveSessionEndedEvent, ParsedIviEvent, IviRealtimeResponseCreateParams, ReceiveConversationItemAddedEvent, ReceiveConversationItemDoneEvent, ReceiveResponseCreatedEvent, IviClient, IviClientConfig } from '@vivix/ivi-sdk-ts';
 import { ReactNode, CSSProperties, ReactElement, VideoHTMLAttributes, ImgHTMLAttributes } from 'react';
 import { IviClientLogEntry } from '@vivix/ivi-sdk-ts/client';
 
 type IviRuntimeStatus = "idle" | "connecting" | "syncing" | "running" | "stopped";
+type IviRuntimeConversationRole = NonNullable<IviConversationItem["role"]>;
+type IviRuntimeSourcePlayback = IviReceiveSessionSourceReadyPayload["playback"];
+type IviRuntimeTrtcPlayback = NonNullable<NonNullable<IviRuntimeSourcePlayback>["trtc"]> & {
+    app_id: string;
+    user_id: string;
+    user_sig: string;
+    room_id: string;
+};
+type IviRuntimeStreamStatus = IviStream["status"];
 interface IviRuntimeState {
     status: IviRuntimeStatus;
-    session: IviRealtimeSession | null;
-    stage: IviStage | null;
+    session: IviRealtimeSessionConfig | null;
+    stage: IviStageComposition | null;
     tracks: Map<string, IviTrack>;
     sources: Map<string, IviRuntimeSource>;
     streams: Map<string, IviRuntimeStream>;
@@ -18,7 +27,7 @@ interface IviRuntimeState {
  */
 interface IviRuntimeStream {
     stream: IviStream;
-    status: IviStreamStatus;
+    status: IviRuntimeStreamStatus;
     /** stream.started 事件携带的关联 track ID。 */
     trackId?: string;
     error?: unknown;
@@ -32,14 +41,14 @@ interface IviRuntimeSourcePreloadState {
     autoclearAfterPlay: boolean;
 }
 interface IviRuntimeSource {
-    source: IviSource;
+    source: IviSourceAsset;
     status: "created" | "ready" | "failed";
-    playback?: IviSourcePlayback;
+    playback?: IviRuntimeSourcePlayback;
     width?: number;
     height?: number;
     durationMs?: number;
     hasAudio?: boolean;
-    error?: IviSessionSourceFailedPayload["error"];
+    error?: IviReceiveSessionSourceFailedPayload["error"];
     /**
      * 预加载状态：
      * - 存在：渲染层应对该 source 进行预加载；
@@ -60,7 +69,7 @@ type IviRuntimeConversationLifecycle = "added" | "done";
 type IviRuntimeConversationStatus = "in_progress" | "completed" | "incomplete";
 interface IviRuntimeConversationItem {
     id: string;
-    role: IviConversationItemRole;
+    role: IviRuntimeConversationRole;
     lifecycle: IviRuntimeConversationLifecycle;
     status: IviRuntimeConversationStatus;
     item: IviConversationItem;
@@ -162,7 +171,7 @@ declare class TrtcSourceManager {
      * 按 sourceId 注册/更新 TRTC 配置。
      * 若配置发生变化，会先销毁旧会话再按新参数重建连接。
      */
-    upsertSource(sourceId: string, trtc: IviSourcePlaybackTrtc): void;
+    upsertSource(sourceId: string, trtc: IviRuntimeTrtcPlayback): void;
     /**
      * 删除指定 source 的 TRTC 会话并释放连接资源。
      * 该操作通常由 source.deleted 或会话重置触发。
@@ -402,7 +411,7 @@ declare const EMPTY_RUNTIME_STATE: IviRuntimeState;
 declare function useRuntimeState(runtime: IviRuntimeCoordinator | null): IviRuntimeState;
 
 interface IVITrtcPlayerProps {
-    trtc: IviSourcePlaybackTrtc;
+    trtc: IviRuntimeTrtcPlayback;
     sourceId?: string;
     runtime?: IviRuntimeCoordinator | null;
     className?: string;
@@ -451,11 +460,18 @@ interface IVISubtitleOverlayProps {
     /** 会话条目列表（由 runtime state 提供） */
     conversations: IviRuntimeConversationItem[];
     /** 要显示的发言人角色，默认 ["user"]。传单个字符串或数组均可。 */
-    roles?: IviConversationItemRole | IviConversationItemRole[];
+    roles?: IviRuntimeConversationRole | IviRuntimeConversationRole[];
     /** 同时可见的最大条目数，默认 2 */
     maxVisible?: number;
     /** lifecycle 变为 done 后自动消失的毫秒数，默认 5000 */
     dismissAfterMs?: number;
+    /**
+     * 按 source 生命周期展示字幕：
+     * - sourceKey 变化时建立一个新窗口；
+     * - 只展示窗口建立后新增到 conversations 的条目；
+     * - 不按 dismissAfterMs 自动消失，直到下一次 sourceKey 变化。
+     */
+    stickySourceKey?: string | null;
     /** 样式配置 */
     subtitleStyle?: IVISubtitleOverlayStyle;
     /** 自定义类名 */
@@ -505,6 +521,12 @@ interface IVITrackSlotProps {
     showSubtitle?: boolean;
     /** 字幕组件的自定义配置（字体、颜色、消失延时等） */
     subtitleProps?: Omit<IVISubtitleOverlayProps, "conversations">;
+    /**
+     * 对连续 generated_clip m3u8 启用按切片生命周期保留字幕。
+     * 启用后会展示 active source 切换后新增到 conversations 的全部条目，
+     * 并保留到下一次 source 切换（即当前切片播放完成）。
+     */
+    keepGeneratedClipSubtitlesUntilEnded?: boolean;
     /** 媒体空白区域（letterbox/pillarbox）的背景模式，默认 "black" */
     background?: IviTrackSlotBackground;
 }

package/dist/index.d.ts

@@ -1,12 +1,21 @@
-import { IviRealtimeSession, IviStage, IviTrack, IviSource, IviSourcePlayback, IviSessionSourceFailedPayload, IviStream, IviStreamStatus, IviConversationItemRole, IviConversationItem, IviConversationItemContent, ReceiveSessionEndedEvent, ParsedIviEvent, IviRealtimeResponseCreateParams, ReceiveConversationItemAddedEvent, ReceiveConversationItemDoneEvent, ReceiveResponseCreatedEvent, IviSourcePlaybackTrtc, IviClient, IviClientConfig } from '@vivix/ivi-sdk-ts';
+import { IviRealtimeSessionConfig, IviStageComposition, IviTrack, IviSourceAsset, IviReceiveSessionSourceReadyPayload, IviReceiveSessionSourceFailedPayload, IviStream, IviConversationItem, IviConversationItemContent, ReceiveSessionEndedEvent, ParsedIviEvent, IviRealtimeResponseCreateParams, ReceiveConversationItemAddedEvent, ReceiveConversationItemDoneEvent, ReceiveResponseCreatedEvent, IviClient, IviClientConfig } from '@vivix/ivi-sdk-ts';
 import { ReactNode, CSSProperties, ReactElement, VideoHTMLAttributes, ImgHTMLAttributes } from 'react';
 import { IviClientLogEntry } from '@vivix/ivi-sdk-ts/client';
 
 type IviRuntimeStatus = "idle" | "connecting" | "syncing" | "running" | "stopped";
+type IviRuntimeConversationRole = NonNullable<IviConversationItem["role"]>;
+type IviRuntimeSourcePlayback = IviReceiveSessionSourceReadyPayload["playback"];
+type IviRuntimeTrtcPlayback = NonNullable<NonNullable<IviRuntimeSourcePlayback>["trtc"]> & {
+    app_id: string;
+    user_id: string;
+    user_sig: string;
+    room_id: string;
+};
+type IviRuntimeStreamStatus = IviStream["status"];
 interface IviRuntimeState {
     status: IviRuntimeStatus;
-    session: IviRealtimeSession | null;
-    stage: IviStage | null;
+    session: IviRealtimeSessionConfig | null;
+    stage: IviStageComposition | null;
     tracks: Map<string, IviTrack>;
     sources: Map<string, IviRuntimeSource>;
     streams: Map<string, IviRuntimeStream>;
@@ -18,7 +27,7 @@ interface IviRuntimeState {
  */
 interface IviRuntimeStream {
     stream: IviStream;
-    status: IviStreamStatus;
+    status: IviRuntimeStreamStatus;
     /** stream.started 事件携带的关联 track ID。 */
     trackId?: string;
     error?: unknown;
@@ -32,14 +41,14 @@ interface IviRuntimeSourcePreloadState {
     autoclearAfterPlay: boolean;
 }
 interface IviRuntimeSource {
-    source: IviSource;
+    source: IviSourceAsset;
     status: "created" | "ready" | "failed";
-    playback?: IviSourcePlayback;
+    playback?: IviRuntimeSourcePlayback;
     width?: number;
     height?: number;
     durationMs?: number;
     hasAudio?: boolean;
-    error?: IviSessionSourceFailedPayload["error"];
+    error?: IviReceiveSessionSourceFailedPayload["error"];
     /**
      * 预加载状态：
      * - 存在：渲染层应对该 source 进行预加载；
@@ -60,7 +69,7 @@ type IviRuntimeConversationLifecycle = "added" | "done";
 type IviRuntimeConversationStatus = "in_progress" | "completed" | "incomplete";
 interface IviRuntimeConversationItem {
     id: string;
-    role: IviConversationItemRole;
+    role: IviRuntimeConversationRole;
     lifecycle: IviRuntimeConversationLifecycle;
     status: IviRuntimeConversationStatus;
     item: IviConversationItem;
@@ -162,7 +171,7 @@ declare class TrtcSourceManager {
      * 按 sourceId 注册/更新 TRTC 配置。
      * 若配置发生变化，会先销毁旧会话再按新参数重建连接。
      */
-    upsertSource(sourceId: string, trtc: IviSourcePlaybackTrtc): void;
+    upsertSource(sourceId: string, trtc: IviRuntimeTrtcPlayback): void;
     /**
      * 删除指定 source 的 TRTC 会话并释放连接资源。
      * 该操作通常由 source.deleted 或会话重置触发。
@@ -402,7 +411,7 @@ declare const EMPTY_RUNTIME_STATE: IviRuntimeState;
 declare function useRuntimeState(runtime: IviRuntimeCoordinator | null): IviRuntimeState;
 
 interface IVITrtcPlayerProps {
-    trtc: IviSourcePlaybackTrtc;
+    trtc: IviRuntimeTrtcPlayback;
     sourceId?: string;
     runtime?: IviRuntimeCoordinator | null;
     className?: string;
@@ -451,11 +460,18 @@ interface IVISubtitleOverlayProps {
     /** 会话条目列表（由 runtime state 提供） */
     conversations: IviRuntimeConversationItem[];
     /** 要显示的发言人角色，默认 ["user"]。传单个字符串或数组均可。 */
-    roles?: IviConversationItemRole | IviConversationItemRole[];
+    roles?: IviRuntimeConversationRole | IviRuntimeConversationRole[];
     /** 同时可见的最大条目数，默认 2 */
     maxVisible?: number;
     /** lifecycle 变为 done 后自动消失的毫秒数，默认 5000 */
     dismissAfterMs?: number;
+    /**
+     * 按 source 生命周期展示字幕：
+     * - sourceKey 变化时建立一个新窗口；
+     * - 只展示窗口建立后新增到 conversations 的条目；
+     * - 不按 dismissAfterMs 自动消失，直到下一次 sourceKey 变化。
+     */
+    stickySourceKey?: string | null;
     /** 样式配置 */
     subtitleStyle?: IVISubtitleOverlayStyle;
     /** 自定义类名 */
@@ -505,6 +521,12 @@ interface IVITrackSlotProps {
     showSubtitle?: boolean;
     /** 字幕组件的自定义配置（字体、颜色、消失延时等） */
     subtitleProps?: Omit<IVISubtitleOverlayProps, "conversations">;
+    /**
+     * 对连续 generated_clip m3u8 启用按切片生命周期保留字幕。
+     * 启用后会展示 active source 切换后新增到 conversations 的全部条目，
+     * 并保留到下一次 source 切换（即当前切片播放完成）。
+     */
+    keepGeneratedClipSubtitlesUntilEnded?: boolean;
     /** 媒体空白区域（letterbox/pillarbox）的背景模式，默认 "black" */
     background?: IviTrackSlotBackground;
 }

package/dist/index.js

@@ -1,4 +1,4 @@
-import { ReceiveConversationItemAddedEvent, ReceiveConversationItemDoneEvent, ReceiveResponseCreatedEvent, IviClient, SessionCreatedEvent, ReceiveSessionEndedEvent, ReceiveSessionStageGetResponseEvent, ReceiveSessionStageUpdatedEvent, ReceiveSessionTrackCreatedEvent, ReceiveSessionTrackDeletedEvent, ReceiveSessionTrackTookEvent, ReceiveSessionTrackCuedEvent, ReceiveSessionTrackNextSetEvent, ReceiveSessionTracksListResponseEvent, ReceiveSessionSourceCreatedEvent, ReceiveSessionSourceReadyEvent, ReceiveSessionSourceFailedEvent, ReceiveSessionSourceDeletedEvent, ReceiveSessionSourcePreloadEvent, ReceiveSessionSourceClearPreloadEvent, ReceiveSessionSourcesListResponseEvent, ReceiveSessionSourcePlaybackCompletedEvent, SessionStreamCreatedEvent, ReceiveSessionStreamStartedEvent, ReceiveSessionStreamEndedEvent, ReceiveSessionStreamFailedEvent, ReceiveSessionStreamDeletedEvent, ReceiveSessionStreamsListResponseEvent, ReceiveConversationListResponseEvent, ReceiveResponseOutputTextDeltaEvent, ReceiveResponseOutputTextDoneEvent, ReceiveResponseOutputAudioTranscriptDeltaEvent, ReceiveResponseOutputAudioTranscriptDoneEvent, ReceiveResponseDoneEvent } from '@vivix/ivi-sdk-ts';
+import { ReceiveConversationItemAddedEvent, ReceiveConversationItemDoneEvent, ReceiveResponseCreatedEvent, IviClient, ReceiveSessionCreatedEvent, ReceiveSessionEndedEvent, ReceiveSessionStageGetResponseEvent, ReceiveSessionStageUpdatedEvent, ReceiveSessionTrackCreatedEvent, ReceiveSessionTrackDeletedEvent, ReceiveSessionTrackTookEvent, ReceiveSessionTrackCuedEvent, ReceiveSessionTrackNextSetEvent, ReceiveSessionTracksListResponseEvent, ReceiveSessionSourceCreatedEvent, ReceiveSessionSourceReadyEvent, ReceiveSessionSourceFailedEvent, ReceiveSessionSourceDeletedEvent, ReceiveSessionSourcePreloadEvent, ReceiveSessionSourceClearPreloadEvent, ReceiveSessionSourcesListResponseEvent, ReceiveSessionSourcePlaybackCompletedEvent, ReceiveSessionStreamCreatedEvent, ReceiveSessionStreamStartedEvent, ReceiveSessionStreamEndedEvent, ReceiveSessionStreamFailedEvent, ReceiveSessionStreamDeletedEvent, ReceiveSessionStreamsListResponseEvent, ReceiveConversationListResponseEvent, ReceiveResponseOutputTextDeltaEvent, ReceiveResponseOutputTextDoneEvent, ReceiveResponseOutputAudioTranscriptDeltaEvent, ReceiveResponseOutputAudioTranscriptDoneEvent, ReceiveResponseDoneEvent } from '@vivix/ivi-sdk-ts';
 import { createContext, useState, useEffect, useMemo, useContext, useRef, useCallback } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 
@@ -108,7 +108,7 @@ var SessionEventHandler = class {
     this.callbacks = callbacks;
   }
   handle(event) {
-    if (event instanceof SessionCreatedEvent) {
+    if (event instanceof ReceiveSessionCreatedEvent) {
       const before = this.sessionManager.getSession();
       this.sessionManager.setSession(event.session);
       logIviStateChange("session", null, event.type, before, this.sessionManager.getSession());
@@ -257,7 +257,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));
       }
@@ -299,7 +299,7 @@ var StreamEventHandler = class {
     this.callbacks = callbacks;
   }
   handle(event) {
-    if (event instanceof SessionStreamCreatedEvent) {
+    if (event instanceof ReceiveSessionStreamCreatedEvent) {
       const streamId = event.stream.stream_id;
       const before = this.streamManager.getAll().get(streamId);
       this.streamManager.upsertCreated(event.stream);
@@ -372,32 +372,37 @@ var ConversationEventHandler = class {
       return { handled: true };
     }
     if (event instanceof 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 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 ReceiveResponseOutputTextDeltaEvent) {
+      if (!event.itemId) return { handled: true };
       const before = this.conversationManager.getAllMap().get(event.itemId);
       this.conversationManager.applyTextDelta(event.itemId, event.delta);
       logIviStateChange(
@@ -411,6 +416,7 @@ var ConversationEventHandler = class {
       return { handled: true };
     }
     if (event instanceof ReceiveResponseOutputTextDoneEvent) {
+      if (!event.itemId) return { handled: true };
       const before = this.conversationManager.getAllMap().get(event.itemId);
       this.conversationManager.applyTextDone(event.itemId, event.text);
       logIviStateChange(
@@ -424,6 +430,7 @@ var ConversationEventHandler = class {
       return { handled: true };
     }
     if (event instanceof ReceiveResponseOutputAudioTranscriptDeltaEvent) {
+      if (!event.itemId) return { handled: true };
       const before = this.conversationManager.getAllMap().get(event.itemId);
       this.conversationManager.applyTranscriptDelta(event.itemId, event.delta);
       logIviStateChange(
@@ -437,6 +444,7 @@ var ConversationEventHandler = class {
       return { handled: true };
     }
     if (event instanceof ReceiveResponseOutputAudioTranscriptDoneEvent) {
+      if (!event.itemId) return { handled: true };
       const before = this.conversationManager.getAllMap().get(event.itemId);
       this.conversationManager.applyTranscriptDone(event.itemId, event.transcript);
       logIviStateChange(
@@ -548,13 +556,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) {
@@ -851,6 +859,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);
@@ -1083,6 +1092,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]";
@@ -1527,7 +1539,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;
@@ -1958,7 +1971,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);
       }
@@ -1993,7 +2006,11 @@ var IviRuntimeCoordinator = class {
   }
   progressUserTextToResponseFlows(event) {
     if (event instanceof 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;
       }
@@ -2003,7 +2020,11 @@ var IviRuntimeCoordinator = class {
       return;
     }
     if (event instanceof 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;
       }
@@ -2144,14 +2165,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;
@@ -2441,6 +2462,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] = useState([]);
   const timersRef = useRef(/* @__PURE__ */ new Map());
@@ -2516,26 +2538,82 @@ function useSubtitleEntries(conversations, maxVisible, dismissAfterMs) {
     }).filter((entry) => entry !== null);
   }, [visibleIds, conversationMap]);
 }
+function useSourceWindowSubtitleEntries(conversations, sourceKey) {
+  const normalizedSourceKey = sourceKey ?? null;
+  const [windowState, setWindowState] = useState(() => ({
+    sourceKey: normalizedSourceKey,
+    baselineIds: new Set(conversations.map((item) => item.id)),
+    visibleIds: []
+  }));
+  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 = useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const item of conversations) {
+      map.set(item.id, item);
+    }
+    return map;
+  }, [conversations]);
+  return 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 = useMemo(
-    () => new Set(Array.isArray(roles) ? roles : [roles]),
-    [roles]
+    () => new Set(Array.isArray(resolvedRoles) ? resolvedRoles : [resolvedRoles]),
+    [resolvedRoles]
   );
   const filtered = 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;
@@ -3080,6 +3158,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";
@@ -3115,7 +3201,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__ */ jsx(
@@ -3180,6 +3266,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"
@@ -3276,6 +3365,7 @@ function IVITrackSlot(props) {
     volumeControlProps,
     showSubtitle,
     subtitleProps,
+    keepGeneratedClipSubtitlesUntilEnded = false,
     background = "black"
   } = props;
   const context = useIviStageView();
@@ -3286,6 +3376,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);
@@ -3348,7 +3439,8 @@ function IVITrackSlot(props) {
           IVISubtitleOverlay,
           {
             conversations: context.state.conversations,
-            ...subtitleProps
+            ...subtitleProps,
+            stickySourceKey: stickySubtitleSourceKey
           }
         ) }),
         showVolumeControl && mediaType !== null && /* @__PURE__ */ jsx("div", { style: VOLUME_OVERLAY_STYLE, children: /* @__PURE__ */ jsx(