@vivix-ai/ivi-frontend-sdk 0.3.6 → 0.3.8

package/dist/index.d.cts

@@ -628,6 +628,12 @@ interface IVIVolumeControlProps {
 
 type IviSubtitleRole = IviRuntimeConversationItem["role"];
 type IviSubtitleSource = "conversation" | "response_audio_transcript";
+type IviSubtitleCompletedReason = "conversation_done" | "response_done";
+type IviCompletedSubtitleDecision = "keep" | "remove" | {
+    removeAfterMs: number;
+};
+type IviCompletedSubtitleDecisionResult = IviCompletedSubtitleDecision | void | Promise<IviCompletedSubtitleDecision | void>;
+declare const DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS = 3000;
 interface IviSubtitleItem {
     id: string;
     role: IviSubtitleRole;
@@ -649,6 +655,15 @@ interface IviSubtitleItem {
     /** 最近一次字幕内容或状态更新的时间戳。 */
     updatedAt: number;
 }
+interface IviSubtitleCompletedContext {
+    /** 当前字幕队列快照。 */
+    entries: readonly IviSubtitleItem[];
+    /** 本次完成态来自 conversation 完成还是 response 完成。 */
+    reason: IviSubtitleCompletedReason;
+    /** 当字幕被移除、会话结束、配置变化或组件卸载时触发。 */
+    signal: AbortSignal;
+}
+type IviSubtitleCompletedHandler = (item: IviSubtitleItem, context: IviSubtitleCompletedContext) => IviCompletedSubtitleDecisionResult;
 interface IviUseSubtitlesOptions {
     /** 要收集的发言人角色，默认 ["user"]。传单个字符串或数组均可。 */
     roles?: IviSubtitleRole | IviSubtitleRole[];
@@ -660,6 +675,16 @@ interface IviUseSubtitlesOptions {
      * 只有 response.done 才会把这一轮 model 字幕标记为 done。
      */
     useModelStreamingTranscript?: boolean;
+    /**
+     * 字幕进入完成态后多久自动移除，默认 3000ms；传 false 可恢复为一直保留直到被 maxItems 裁剪。
+     * 自定义 onSubtitleCompleted 时，此配置仅作为未提供自定义策略时的默认策略。
+     */
+    hideCompletedAfterMs?: number | false;
+    /**
+     * 字幕进入完成态时调用一次。返回 "remove" 立即删除，返回 { removeAfterMs } 延迟删除，
+     * 返回 "keep" 或 undefined 则保留。异步策略可通过 context.signal 响应取消。
+     */
+    onSubtitleCompleted?: IviSubtitleCompletedHandler;
 }
 /**
  * 监听 runtime 中的 conversation/response 事件，并维护当前应展示的字幕队列。
@@ -689,6 +714,10 @@ interface IVISubtitleOverlayProps {
      * 当 roles 包含 "model" 时，是否使用 response.output_audio_transcript.* 事件作为 model 字幕来源。
      */
     useModelStreamingTranscript?: boolean;
+    /** 字幕进入完成态后多久自动移除，默认 3000ms；传 false 可关闭自动移除。 */
+    hideCompletedAfterMs?: IviUseSubtitlesOptions["hideCompletedAfterMs"];
+    /** 字幕进入完成态时的自定义保留/删除策略，优先于 hideCompletedAfterMs。 */
+    onSubtitleCompleted?: IviUseSubtitlesOptions["onSubtitleCompleted"];
     /** 样式配置 */
     subtitleStyle?: IVISubtitleOverlayStyle;
     /** 自定义类名 */
@@ -773,4 +802,4 @@ declare function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRunti
 
 declare function useIviStageView(): IviStageViewContextValue;
 
-export { EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
+export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };

package/dist/index.d.ts

@@ -628,6 +628,12 @@ interface IVIVolumeControlProps {
 
 type IviSubtitleRole = IviRuntimeConversationItem["role"];
 type IviSubtitleSource = "conversation" | "response_audio_transcript";
+type IviSubtitleCompletedReason = "conversation_done" | "response_done";
+type IviCompletedSubtitleDecision = "keep" | "remove" | {
+    removeAfterMs: number;
+};
+type IviCompletedSubtitleDecisionResult = IviCompletedSubtitleDecision | void | Promise<IviCompletedSubtitleDecision | void>;
+declare const DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS = 3000;
 interface IviSubtitleItem {
     id: string;
     role: IviSubtitleRole;
@@ -649,6 +655,15 @@ interface IviSubtitleItem {
     /** 最近一次字幕内容或状态更新的时间戳。 */
     updatedAt: number;
 }
+interface IviSubtitleCompletedContext {
+    /** 当前字幕队列快照。 */
+    entries: readonly IviSubtitleItem[];
+    /** 本次完成态来自 conversation 完成还是 response 完成。 */
+    reason: IviSubtitleCompletedReason;
+    /** 当字幕被移除、会话结束、配置变化或组件卸载时触发。 */
+    signal: AbortSignal;
+}
+type IviSubtitleCompletedHandler = (item: IviSubtitleItem, context: IviSubtitleCompletedContext) => IviCompletedSubtitleDecisionResult;
 interface IviUseSubtitlesOptions {
     /** 要收集的发言人角色，默认 ["user"]。传单个字符串或数组均可。 */
     roles?: IviSubtitleRole | IviSubtitleRole[];
@@ -660,6 +675,16 @@ interface IviUseSubtitlesOptions {
      * 只有 response.done 才会把这一轮 model 字幕标记为 done。
      */
     useModelStreamingTranscript?: boolean;
+    /**
+     * 字幕进入完成态后多久自动移除，默认 3000ms；传 false 可恢复为一直保留直到被 maxItems 裁剪。
+     * 自定义 onSubtitleCompleted 时，此配置仅作为未提供自定义策略时的默认策略。
+     */
+    hideCompletedAfterMs?: number | false;
+    /**
+     * 字幕进入完成态时调用一次。返回 "remove" 立即删除，返回 { removeAfterMs } 延迟删除，
+     * 返回 "keep" 或 undefined 则保留。异步策略可通过 context.signal 响应取消。
+     */
+    onSubtitleCompleted?: IviSubtitleCompletedHandler;
 }
 /**
  * 监听 runtime 中的 conversation/response 事件，并维护当前应展示的字幕队列。
@@ -689,6 +714,10 @@ interface IVISubtitleOverlayProps {
      * 当 roles 包含 "model" 时，是否使用 response.output_audio_transcript.* 事件作为 model 字幕来源。
      */
     useModelStreamingTranscript?: boolean;
+    /** 字幕进入完成态后多久自动移除，默认 3000ms；传 false 可关闭自动移除。 */
+    hideCompletedAfterMs?: IviUseSubtitlesOptions["hideCompletedAfterMs"];
+    /** 字幕进入完成态时的自定义保留/删除策略，优先于 hideCompletedAfterMs。 */
+    onSubtitleCompleted?: IviUseSubtitlesOptions["onSubtitleCompleted"];
     /** 样式配置 */
     subtitleStyle?: IVISubtitleOverlayStyle;
     /** 自定义类名 */
@@ -773,4 +802,4 @@ declare function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRunti
 
 declare function useIviStageView(): IviStageViewContextValue;
 
-export { EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
+export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };

package/dist/index.js

@@ -1105,6 +1105,8 @@ var ConversationManager = class {
 
 // src/runtime/managers/trtc-source-manager.ts
 var TAG = "[IVI-TRTC]";
+var TRTC_VIEW_ATTR = "data-ivi-trtc-view";
+var TRTC_MEDIA_STYLE_ID = "ivi-trtc-media-style";
 var DEFAULT_DENOISER_OPTIONS = {
   enabled: true,
   mode: "normal"
@@ -1266,6 +1268,8 @@ var TrtcSourceManager = class {
     if (!session) {
       throw new Error(`TRTC source session not found: ${sourceId}`);
     }
+    ensureTrtcMediaStyleSheet();
+    container.setAttribute(TRTC_VIEW_ATTR, "");
     session.views.set(viewId, {
       sourceId,
       container,
@@ -1288,6 +1292,7 @@ var TrtcSourceManager = class {
     }
     const binding = session.views.get(viewId);
     if (binding?.sourceId === sourceId) {
+      binding.container.removeAttribute(TRTC_VIEW_ATTR);
       session.views.delete(viewId);
     }
     void this.applyAudioPolicy(session);
@@ -1309,6 +1314,7 @@ var TrtcSourceManager = class {
     this.sourceSessionKeys.delete(sourceId);
     session.views.forEach((binding, viewId) => {
       if (binding.sourceId === sourceId) {
+        binding.container.removeAttribute(TRTC_VIEW_ATTR);
         session.views.delete(viewId);
       }
     });
@@ -1628,6 +1634,38 @@ var TrtcSourceManager = class {
     this.onTrtcEvent?.(event);
   }
 };
+function ensureTrtcMediaStyleSheet() {
+  if (typeof document === "undefined") {
+    return;
+  }
+  if (document.getElementById(TRTC_MEDIA_STYLE_ID)) {
+    return;
+  }
+  const style = document.createElement("style");
+  style.id = TRTC_MEDIA_STYLE_ID;
+  style.textContent = `
+[${TRTC_VIEW_ATTR}] [id^="player_"],
+[${TRTC_VIEW_ATTR}] [id^="video_"],
+[${TRTC_VIEW_ATTR}] [id^="audio_"],
+[${TRTC_VIEW_ATTR}] video,
+[${TRTC_VIEW_ATTR}] canvas {
+  width: 100% !important;
+  height: 100% !important;
+  max-width: 100% !important;
+  max-height: 100% !important;
+  background: transparent !important;
+  background-color: transparent !important;
+  background-image: none !important;
+}
+
+[${TRTC_VIEW_ATTR}] video,
+[${TRTC_VIEW_ATTR}] canvas {
+  object-fit: contain !important;
+  display: block !important;
+}
+`;
+  document.head.appendChild(style);
+}
 function isRuntimeTrtcSource(source) {
   return source.status === "ready" && source.playback?.type === "trtc" && typeof source.playback.trtc === "object" && source.playback.trtc !== null;
 }
@@ -1719,6 +1757,9 @@ function enforceContainMedia(container) {
     element.style.setProperty("max-height", "100%", "important");
     element.style.setProperty("object-fit", "contain", "important");
     element.style.setProperty("display", "block", "important");
+    element.style.setProperty("background", "transparent", "important");
+    element.style.setProperty("background-color", "transparent", "important");
+    element.style.setProperty("background-image", "none", "important");
   });
 }
 
@@ -3078,9 +3119,12 @@ function useApplyVolumeToSlot(containerRef, volume, enabled, activeSourceId) {
     return () => observer.disconnect();
   }, [containerRef, volume, enabled, activeSourceId]);
 }
+var DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS = 3e3;
 function useIviSubtitles(runtime, options = {}) {
   const roles = options.roles ?? "user";
   const maxItems = normalizeMaxItems(options.maxItems);
+  const hideCompletedAfterMs = normalizeHideCompletedAfterMs(options.hideCompletedAfterMs);
+  const onSubtitleCompleted = options.onSubtitleCompleted;
   const roleKey = Array.isArray(roles) ? roles.join("\0") : roles;
   const roleSet = useMemo(
     () => new Set(roleKey.split("\0")),
@@ -3090,9 +3134,14 @@ function useIviSubtitles(runtime, options = {}) {
   const [subtitles, setSubtitles] = useState([]);
   const seenIdsRef = useRef(/* @__PURE__ */ new Set());
   const initializedRef = useRef(false);
+  const completedSubtitleIdsRef = useRef(/* @__PURE__ */ new Set());
+  const completionControllersRef = useRef(/* @__PURE__ */ new Map());
+  const completionPolicyRef = useRef(null);
   useEffect(() => {
     seenIdsRef.current = /* @__PURE__ */ new Set();
     initializedRef.current = false;
+    completedSubtitleIdsRef.current = /* @__PURE__ */ new Set();
+    abortCompletedSubtitleTasks(completionControllersRef.current);
     setSubtitles([]);
     if (!runtime) {
       return;
@@ -3148,6 +3197,8 @@ function useIviSubtitles(runtime, options = {}) {
       if (event.type === "session.ended") {
         seenIdsRef.current = /* @__PURE__ */ new Set();
         initializedRef.current = false;
+        completedSubtitleIdsRef.current = /* @__PURE__ */ new Set();
+        abortCompletedSubtitleTasks(completionControllersRef.current);
         setSubtitles([]);
         return;
       }
@@ -3165,6 +3216,78 @@ function useIviSubtitles(runtime, options = {}) {
       syncConversations(state.conversations);
     });
   }, [runtime, roleSet, maxItems, useModelStreamingTranscript]);
+  useEffect(() => {
+    return () => {
+      completedSubtitleIdsRef.current = /* @__PURE__ */ new Set();
+      abortCompletedSubtitleTasks(completionControllersRef.current);
+    };
+  }, []);
+  useEffect(() => {
+    const previousPolicy = completionPolicyRef.current;
+    const policyChanged = Boolean(
+      previousPolicy && (previousPolicy.hideCompletedAfterMs !== hideCompletedAfterMs || previousPolicy.onSubtitleCompleted !== onSubtitleCompleted)
+    );
+    completionPolicyRef.current = { hideCompletedAfterMs, onSubtitleCompleted };
+    if (policyChanged) {
+      completedSubtitleIdsRef.current = /* @__PURE__ */ new Set();
+      abortCompletedSubtitleTasks(completionControllersRef.current);
+    }
+    const subtitleById = new Map(subtitles.map((item) => [item.id, item]));
+    const completedIds = completedSubtitleIdsRef.current;
+    const controllers = completionControllersRef.current;
+    for (const [id, controller] of Array.from(controllers)) {
+      const item = subtitleById.get(id);
+      if (!item || !isCompletedSubtitle(item)) {
+        controller.abort();
+        controllers.delete(id);
+        completedIds.delete(id);
+      }
+    }
+    for (const id of Array.from(completedIds)) {
+      const item = subtitleById.get(id);
+      if (!item || !isCompletedSubtitle(item)) {
+        completedIds.delete(id);
+      }
+    }
+    for (const item of subtitles) {
+      if (!isCompletedSubtitle(item) || completedIds.has(item.id)) {
+        continue;
+      }
+      completedIds.add(item.id);
+      const controller = new AbortController();
+      controllers.set(item.id, controller);
+      const context = {
+        entries: subtitles,
+        reason: getSubtitleCompletedReason(item),
+        signal: controller.signal
+      };
+      let decisionResult;
+      try {
+        decisionResult = onSubtitleCompleted ? onSubtitleCompleted(item, context) : getDefaultCompletedSubtitleDecision(hideCompletedAfterMs);
+      } catch {
+        decisionResult = "keep";
+      }
+      void Promise.resolve(decisionResult).then((decision) => {
+        applyCompletedSubtitleDecision(
+          item.id,
+          decision,
+          controller,
+          controllers,
+          completedIds,
+          (id) => setSubtitles((previous) => removeSubtitleById(previous, id))
+        );
+      }).catch(() => {
+        applyCompletedSubtitleDecision(
+          item.id,
+          "keep",
+          controller,
+          controllers,
+          completedIds,
+          (id) => setSubtitles((previous) => removeSubtitleById(previous, id))
+        );
+      });
+    }
+  }, [subtitles, hideCompletedAfterMs, onSubtitleCompleted]);
   return subtitles;
 }
 function normalizeMaxItems(maxItems) {
@@ -3176,6 +3299,35 @@ function normalizeMaxItems(maxItems) {
   }
   return Math.max(0, Math.floor(maxItems));
 }
+function normalizeHideCompletedAfterMs(hideCompletedAfterMs) {
+  if (hideCompletedAfterMs === false) {
+    return false;
+  }
+  if (hideCompletedAfterMs === void 0 || !Number.isFinite(hideCompletedAfterMs)) {
+    return DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS;
+  }
+  return Math.max(0, Math.floor(hideCompletedAfterMs));
+}
+function getDefaultCompletedSubtitleDecision(hideCompletedAfterMs) {
+  if (hideCompletedAfterMs === false) {
+    return "keep";
+  }
+  return hideCompletedAfterMs === 0 ? "remove" : { removeAfterMs: hideCompletedAfterMs };
+}
+function normalizeCompletedSubtitleDecision(decision) {
+  if (decision === "keep" || decision === "remove") {
+    return decision;
+  }
+  if (decision && typeof decision === "object" && "removeAfterMs" in decision) {
+    const removeAfterMs = Number(decision.removeAfterMs);
+    if (!Number.isFinite(removeAfterMs)) {
+      return "keep";
+    }
+    const normalized = Math.max(0, Math.floor(removeAfterMs));
+    return normalized === 0 ? "remove" : { removeAfterMs: normalized };
+  }
+  return "keep";
+}
 function shouldUseConversationRole(role, roleSet, useModelStreamingTranscript) {
   if (!roleSet.has(role)) {
     return false;
@@ -3189,6 +3341,54 @@ function trimSubtitleItems(items, maxItems) {
   const sorted = [...items].sort((a, b) => a.timestamp - b.timestamp);
   return sorted.length > maxItems ? sorted.slice(sorted.length - maxItems) : sorted;
 }
+function isCompletedSubtitle(item) {
+  return item.lifecycle === "done" || item.status === "completed" || item.status === "incomplete";
+}
+function getSubtitleCompletedReason(item) {
+  return item.source === "response_audio_transcript" || item.role === "model" ? "response_done" : "conversation_done";
+}
+function abortCompletedSubtitleTasks(controllers) {
+  for (const controller of controllers.values()) {
+    controller.abort();
+  }
+  controllers.clear();
+}
+function applyCompletedSubtitleDecision(itemId, decision, controller, controllers, completedIds, removeSubtitle) {
+  if (controller.signal.aborted) {
+    return;
+  }
+  const normalizedDecision = normalizeCompletedSubtitleDecision(decision);
+  if (normalizedDecision === "keep") {
+    controllers.delete(itemId);
+    return;
+  }
+  const remove = () => {
+    if (controller.signal.aborted) {
+      return;
+    }
+    controllers.delete(itemId);
+    completedIds.delete(itemId);
+    removeSubtitle(itemId);
+  };
+  if (normalizedDecision === "remove") {
+    remove();
+    return;
+  }
+  const timeout = setTimeout(remove, normalizedDecision.removeAfterMs);
+  controller.signal.addEventListener(
+    "abort",
+    () => {
+      clearTimeout(timeout);
+    },
+    { once: true }
+  );
+}
+function removeSubtitleById(items, itemId) {
+  if (!items.some((item) => item.id === itemId)) {
+    return items;
+  }
+  return items.filter((item) => item.id !== itemId);
+}
 function getDisplayText(item) {
   return item.text || item.transcript;
 }
@@ -3314,6 +3514,8 @@ function IVISubtitleOverlay(props) {
     maxItems,
     maxVisible,
     useModelStreamingTranscript,
+    hideCompletedAfterMs,
+    onSubtitleCompleted,
     subtitleStyle,
     className,
     style
@@ -3321,7 +3523,9 @@ function IVISubtitleOverlay(props) {
   const entries = useIviSubtitles(runtime, {
     roles,
     maxItems: maxItems ?? maxVisible,
-    useModelStreamingTranscript
+    useModelStreamingTranscript,
+    hideCompletedAfterMs,
+    onSubtitleCompleted
   });
   if (entries.length === 0) return null;
   const fontFamily = subtitleStyle?.fontFamily ?? "system-ui, -apple-system, sans-serif";
@@ -3453,7 +3657,6 @@ function IVITrtcPlayer(props) {
         height: "100%",
         minWidth: 0,
         minHeight: 0,
-        backgroundColor: "#000",
         position: "relative",
         ...style
       },
@@ -4412,6 +4615,6 @@ function getClientLogTag(category) {
   return "[IVI-CLIENT]";
 }
 
-export { EMPTY_RUNTIME_STATE, IVILivekitPlayer, IVIStageView, IVISubtitleOverlay, IVITrackSlot, IVITrtcPlayer, IviFrontendSdk, IviRuntimeCoordinator, IviRuntimeDispatcher, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
+export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, IVIStageView, IVISubtitleOverlay, IVITrackSlot, IVITrtcPlayer, IviFrontendSdk, IviRuntimeCoordinator, IviRuntimeDispatcher, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map