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

package/dist/index.js

@@ -1,4 +1,6 @@
 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-ai/ivi-sdk-ts';
+import { propagation, SpanKind, trace, SpanStatusCode, context } from '@opentelemetry/api';
+import { WebSocketTransport } from '@vivix-ai/ivi-sdk-ts/transports/websocket';
 import { createContext, useState, useEffect, useMemo, useRef, useContext, useCallback, useId } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 
@@ -620,7 +622,9 @@ var SourceManager = class {
       durationMs: previous?.durationMs,
       hasAudio: previous?.hasAudio,
       error: previous?.status === "failed" ? previous.error : void 0,
-      preload: previous?.preload
+      preload: previous?.preload,
+      origin: previous?.origin,
+      provisional: previous?.provisional ? false : previous?.provisional
     });
     this.sources = next;
   }
@@ -635,7 +639,38 @@ var SourceManager = class {
       height: payload.height,
       durationMs: payload.durationMs,
       hasAudio: payload.hasAudio,
-      preload: previous?.preload
+      preload: previous?.preload,
+      origin: previous?.origin,
+      provisional: previous?.provisional ? false : previous?.provisional
+    });
+    this.sources = next;
+  }
+  upsertBootstrapReady(payload) {
+    const previous = this.sources.get(payload.sourceId);
+    const next = new Map(this.sources);
+    const source = {
+      source_id: payload.sourceId,
+      kind: payload.source?.kind ?? (payload.streamId ? "generation_stream" : "stream"),
+      stream_id: payload.source?.stream_id ?? payload.streamId,
+      asset_type: payload.source?.asset_type ?? "video",
+      url: payload.source?.url,
+      generation: payload.source?.generation,
+      metadata: {
+        ...payload.source?.metadata ?? {},
+        label: payload.source?.metadata?.label ?? "prebuilt"
+      }
+    };
+    next.set(payload.sourceId, {
+      source,
+      status: "ready",
+      playback: previous?.playback ?? payload.playback,
+      width: previous?.width ?? payload.width,
+      height: previous?.height ?? payload.height,
+      durationMs: previous?.durationMs ?? payload.durationMs,
+      hasAudio: previous?.hasAudio ?? payload.hasAudio,
+      preload: previous?.preload ?? { autoclearAfterPlay: true },
+      origin: previous?.origin ?? "prebuilt-session-response",
+      provisional: previous?.provisional ?? true
     });
     this.sources = next;
   }
@@ -669,11 +704,14 @@ var SourceManager = class {
     const next = /* @__PURE__ */ new Map();
     sources.forEach((source) => {
       const previous = this.sources.get(source.source_id);
+      const playback = source.playback ?? previous?.playback;
       next.set(source.source_id, {
         source,
-        status: source.playback ? "ready" : "created",
-        playback: source.playback,
-        preload: previous?.preload
+        status: playback ? "ready" : "created",
+        playback,
+        preload: previous?.preload,
+        origin: previous?.origin,
+        provisional: source.playback && previous?.provisional ? false : previous?.provisional
       });
     });
     this.sources = next;
@@ -1102,6 +1140,94 @@ var ConversationManager = class {
     ];
   }
 };
+var DEFAULT_TRACER_NAME = "@vivix-ai/ivi-frontend-sdk";
+function getIviTelemetryTracer(options) {
+  return options?.tracer ?? trace.getTracer(DEFAULT_TRACER_NAME);
+}
+function getIviTelemetryContext(options) {
+  return options?.context ?? context.active();
+}
+function startIviTelemetrySpan(name, options, attributes) {
+  const tracer = getIviTelemetryTracer(options);
+  const parentContext = getIviTelemetryContext(options);
+  const span = tracer.startSpan(
+    name,
+    {
+      kind: SpanKind.INTERNAL,
+      attributes: mergeIviTelemetryAttributes(options?.attributes, attributes)
+    },
+    parentContext
+  );
+  return {
+    span,
+    context: trace.setSpan(parentContext, span)
+  };
+}
+function endIviTelemetrySpan(span, attributes) {
+  const cleaned = cleanIviTelemetryAttributes(attributes);
+  if (cleaned) {
+    span.setAttributes(cleaned);
+  }
+  span.setStatus({ code: SpanStatusCode.OK });
+  span.end();
+}
+function failIviTelemetrySpan(span, error, attributes) {
+  const cleaned = cleanIviTelemetryAttributes(attributes);
+  if (cleaned) {
+    span.setAttributes(cleaned);
+  }
+  recordIviTelemetryError(span, error);
+  span.end();
+}
+function recordIviTelemetrySpan(name, options, attributes, error) {
+  const { span } = startIviTelemetrySpan(name, options, attributes);
+  if (error === void 0) {
+    span.setStatus({ code: SpanStatusCode.OK });
+  } else {
+    recordIviTelemetryError(span, error);
+  }
+  span.end();
+}
+function withIviTelemetryContext(options, context, attributes) {
+  return {
+    ...options,
+    context,
+    attributes: mergeIviTelemetryAttributes(options?.attributes, attributes)
+  };
+}
+function mergeIviTelemetryAttributes(base, next) {
+  return cleanIviTelemetryAttributes({
+    ...base ?? {},
+    ...next ?? {}
+  });
+}
+function cleanIviTelemetryAttributes(attributes) {
+  const cleaned = {};
+  Object.entries(attributes ?? {}).forEach(([key, value]) => {
+    if (isIviTelemetryAttributeValue(value)) {
+      cleaned[key] = value;
+    }
+  });
+  return Object.keys(cleaned).length > 0 ? cleaned : void 0;
+}
+function recordIviTelemetryError(span, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  span.recordException(error instanceof Error ? error : message);
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message
+  });
+}
+function isIviTelemetryAttributeValue(value) {
+  if (typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (!Array.isArray(value)) return false;
+  const nonNullValues = value.filter((item) => item !== null && item !== void 0);
+  if (nonNullValues.length === 0) return true;
+  const firstType = typeof nonNullValues[0];
+  if (firstType !== "string" && firstType !== "number" && firstType !== "boolean") return false;
+  return nonNullValues.every((item) => typeof item === firstType && (typeof item !== "number" || Number.isFinite(item)));
+}
 
 // src/runtime/managers/trtc-source-manager.ts
 var TAG = "[IVI-TRTC]";
@@ -1112,10 +1238,11 @@ var DEFAULT_DENOISER_OPTIONS = {
   mode: "normal"
 };
 var TrtcSourceManager = class {
-  constructor(onLog, onTrtcEvent, aiDenoiser) {
+  constructor(onLog, onTrtcEvent, aiDenoiser, telemetry) {
     this.onLog = onLog;
     this.onTrtcEvent = onTrtcEvent;
     this.aiDenoiser = aiDenoiser;
+    this.telemetry = telemetry;
     this.sessions = /* @__PURE__ */ new Map();
     this.sourceSessionKeys = /* @__PURE__ */ new Map();
     this.listeners = /* @__PURE__ */ new Map();
@@ -1277,6 +1404,7 @@ var TrtcSourceManager = class {
       startedVideoKeys: /* @__PURE__ */ new Set(),
       startingVideoKeys: /* @__PURE__ */ new Set()
     });
+    this.log("info", `\u7ED1\u5B9A\u89C6\u56FE source=${sourceId} view=${viewId} views=${session.views.size}`);
     await this.ensureConnected(session);
     const binding = session.views.get(viewId);
     if (!binding) {
@@ -1292,6 +1420,7 @@ var TrtcSourceManager = class {
     }
     const binding = session.views.get(viewId);
     if (binding?.sourceId === sourceId) {
+      this.log("info", `\u89E3\u7ED1\u89C6\u56FE source=${sourceId} view=${viewId}`);
       binding.container.removeAttribute(TRTC_VIEW_ATTR);
       session.views.delete(viewId);
     }
@@ -1309,6 +1438,24 @@ var TrtcSourceManager = class {
     binding.muted = muted;
     void this.applyAudioPolicy(session);
   }
+  reassignView(fromSourceId, toSourceId, viewId) {
+    if (fromSourceId === toSourceId) {
+      return true;
+    }
+    const fromSession = this.getSession(fromSourceId);
+    const toSession = this.getSession(toSourceId);
+    if (!fromSession || !toSession || fromSession !== toSession) {
+      return false;
+    }
+    const binding = fromSession.views.get(viewId);
+    if (!binding || binding.sourceId !== fromSourceId) {
+      return false;
+    }
+    this.log("info", `\u8FC1\u79FB\u89C6\u56FE source=${fromSourceId}->${toSourceId} view=${viewId}`);
+    binding.sourceId = toSourceId;
+    void this.applyAudioPolicy(fromSession);
+    return true;
+  }
   unlinkSourceFromSession(sourceId, session) {
     session.sourceIds.delete(sourceId);
     this.sourceSessionKeys.delete(sourceId);
@@ -1391,6 +1538,11 @@ var TrtcSourceManager = class {
       const client = TRTC.create();
       const onRemoteVideoAvailable = (event) => {
         this.log("info", `\u8FDC\u7AEF\u89C6\u9891\u53EF\u7528 source=${session.sourceId} userId=${event.userId} streamType=${event.streamType}`);
+        recordIviTelemetrySpan(
+          "ivi.media.trtc.remote_video_available",
+          this.telemetry,
+          buildTrtcMediaTelemetryAttributes(session.sourceId, event.userId, event.streamType)
+        );
         const remoteVideoKey = buildRemoteVideoKey(event.userId, String(event.streamType));
         session.remoteVideoStreams.add(remoteVideoKey);
         if (!session.hasEverReceivedRemoteVideo) {
@@ -1483,6 +1635,7 @@ var TrtcSourceManager = class {
       if (!parsed) {
         continue;
       }
+      this.log("info", `\u56DE\u653E\u5DF2\u77E5\u8FDC\u7AEF\u89C6\u9891 source=${binding.sourceId} userId=${parsed.userId} streamType=${parsed.streamType}`);
       await this.startRemoteVideoForBinding(
         client,
         parsed.userId,
@@ -1497,20 +1650,42 @@ var TrtcSourceManager = class {
       return;
     }
     binding.startingVideoKeys.add(remoteVideoKey);
+    const telemetryAttributes = buildTrtcMediaTelemetryAttributes(
+      binding.sourceId,
+      userId,
+      streamType
+    );
+    const telemetrySpan = startIviTelemetrySpan(
+      "ivi.media.trtc.start_remote_video",
+      this.telemetry,
+      telemetryAttributes
+    );
     try {
+      this.log("info", `\u5F00\u59CB\u6E32\u67D3\u8FDC\u7AEF\u89C6\u9891 source=${binding.sourceId} view=${remoteVideoKey} userId=${userId} streamType=${streamType}`);
       await client.startRemoteVideo({
         userId,
         streamType,
         view: binding.container,
         option: { fillMode: "contain" }
       });
+      endIviTelemetrySpan(telemetrySpan.span);
+      recordIviTelemetrySpan(
+        "ivi.media.trtc.remote_video_rendered",
+        this.telemetry,
+        telemetryAttributes
+      );
+      this.log("info", `\u8FDC\u7AEF\u89C6\u9891\u6E32\u67D3\u5B8C\u6210 source=${binding.sourceId} userId=${userId} streamType=${streamType}`);
       binding.startedVideoKeys.add(remoteVideoKey);
       enforceContainMedia(binding.container);
     } catch (error) {
       if (error instanceof Error && /already started|OPERATION_ABORT/i.test(error.message)) {
         binding.startedVideoKeys.add(remoteVideoKey);
+        endIviTelemetrySpan(telemetrySpan.span, {
+          "ivi.media.trtc.start_remote_video.result": "already_started"
+        });
         return;
       }
+      failIviTelemetrySpan(telemetrySpan.span, error);
       this.log("warn", `\u8FDC\u7AEF\u89C6\u9891\u6E32\u67D3\u5931\u8D25 userId=${userId} streamType=${streamType}`, error);
     } finally {
       binding.startingVideoKeys.delete(remoteVideoKey);
@@ -1670,7 +1845,7 @@ function isRuntimeTrtcSource(source) {
   return source.status === "ready" && source.playback?.type === "trtc" && typeof source.playback.trtc === "object" && source.playback.trtc !== null;
 }
 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;
+  return a.app_id === b.app_id && a.user_id === b.user_id && a.room_id === b.room_id;
 }
 function buildTrtcSessionKey(trtc, aiDenoiser) {
   const denoiser = resolveAIDenoiserOptions(aiDenoiser);
@@ -1678,7 +1853,6 @@ function buildTrtcSessionKey(trtc, aiDenoiser) {
     appId: trtc.app_id,
     roomId: trtc.room_id,
     userId: trtc.user_id,
-    userSig: trtc.user_sig,
     aiDenoiser: {
       enabled: denoiser.enabled,
       mode: denoiser.mode,
@@ -1725,6 +1899,13 @@ function getAIDenoiserModeValue(mode) {
 function buildRemoteVideoKey(userId, streamType) {
   return `${userId}::${streamType}`;
 }
+function buildTrtcMediaTelemetryAttributes(sourceId, userId, streamType) {
+  return {
+    "ivi.source.id": sourceId,
+    "ivi.trtc.user_id": userId,
+    "ivi.trtc.stream_type": String(streamType)
+  };
+}
 function parseRemoteVideoKey(key) {
   const separatorIndex = key.indexOf("::");
   if (separatorIndex < 0) {
@@ -1787,8 +1968,10 @@ function describeLivekitRoom(livekit) {
 // src/runtime/managers/livekit-source-manager.ts
 var TAG2 = "[IVI-LIVEKIT]";
 var LivekitSourceManager = class {
-  constructor(onLog) {
+  constructor(onLog, onRemoteVideoAvailable, telemetry) {
     this.onLog = onLog;
+    this.onRemoteVideoAvailable = onRemoteVideoAvailable;
+    this.telemetry = telemetry;
     this.sessions = /* @__PURE__ */ new Map();
     this.listeners = /* @__PURE__ */ new Map();
   }
@@ -2010,11 +2193,21 @@ var LivekitSourceManager = class {
           kind
         });
         if (kind === "video" && !session.hasEverReceivedRemoteVideo) {
+          recordIviTelemetrySpan(
+            "ivi.media.livekit.remote_video_available",
+            this.telemetry,
+            {
+              "ivi.source.id": session.sourceId,
+              "ivi.livekit.participant_identity": participant.identity,
+              "ivi.livekit.track_sid": track.sid
+            }
+          );
           session.hasEverReceivedRemoteVideo = true;
           for (const waiter of session.remoteVideoWaiters) {
             waiter(true);
           }
           session.remoteVideoWaiters.length = 0;
+          this.onRemoteVideoAvailable?.(session.sourceId);
         }
         session.views.forEach((binding) => {
           this.attachTrackToView(track, kind, trackKey, binding);
@@ -2210,6 +2403,7 @@ var IviRuntimeCoordinator = class {
     this.userTextFlowCounter = 0;
     this.waitingTracksListValidation = false;
     this.waitingSourcesListValidation = false;
+    this.bootstrapSource = null;
     this.state = {
       status: "idle",
       session: null,
@@ -2218,7 +2412,8 @@ var IviRuntimeCoordinator = class {
       sources: /* @__PURE__ */ new Map(),
       streams: /* @__PURE__ */ new Map(),
       conversationItems: /* @__PURE__ */ new Map(),
-      conversations: []
+      conversations: [],
+      bootstrap: null
     };
     this.client = client;
     this.config = {
@@ -2227,10 +2422,17 @@ var IviRuntimeCoordinator = class {
     };
     this.trtcSourceManager = new TrtcSourceManager(
       this.config.onLog,
-      (event) => this.emitTrtcEvent(event),
-      this.config.trtcAIDenoiser
+      (event) => this.onTrtcManagerEvent(event),
+      this.config.trtcAIDenoiser,
+      this.config.telemetry
+    );
+    this.livekitSourceManager = new LivekitSourceManager(
+      this.config.onLog,
+      () => {
+        this.recomposeBootstrapState();
+      },
+      this.config.telemetry
     );
-    this.livekitSourceManager = new LivekitSourceManager(this.config.onLog);
     this.sessionHandler = new SessionEventHandler(this.sessionManager, {
       onSessionCreated: (event) => this.onSessionCreated(event),
       onSessionEnded: (event) => this.onSessionEnded(event)
@@ -2267,15 +2469,27 @@ var IviRuntimeCoordinator = class {
    * 启动后状态会从 idle/stopped 进入 connecting，连接成功后由事件驱动进入后续状态。
    */
   async start() {
-    this.setState({
-      ...this.state,
-      status: "connecting"
+    const telemetrySpan = startIviTelemetrySpan("ivi.runtime.start", this.config.telemetry, {
+      "ivi.runtime.status": this.state.status,
+      "ivi.session.id": this.state.session?.id
     });
-    this.dispatcher.start();
     try {
+      this.setState({
+        ...this.state,
+        status: "connecting"
+      });
+      this.dispatcher.start();
       await this.client.connect();
+      endIviTelemetrySpan(telemetrySpan.span, {
+        "ivi.runtime.status": this.state.status,
+        "ivi.session.id": this.state.session?.id
+      });
     } catch (error) {
       this.stop();
+      failIviTelemetrySpan(telemetrySpan.span, error, {
+        "ivi.runtime.status": this.state.status,
+        "ivi.session.id": this.state.session?.id
+      });
       throw error;
     }
   }
@@ -2283,13 +2497,31 @@ var IviRuntimeCoordinator = class {
    * 停止协调器并断开实时连接，同时重置运行态数据为 stopped。
    */
   stop() {
-    this.dispatcher.stop();
-    this.client.disconnect();
-    this.resetStoppedState();
+    const telemetrySpan = startIviTelemetrySpan("ivi.runtime.stop", this.config.telemetry, {
+      "ivi.runtime.status": this.state.status,
+      "ivi.session.id": this.state.session?.id
+    });
+    try {
+      this.dispatcher.stop();
+      this.client.disconnect();
+      this.resetStoppedState();
+      endIviTelemetrySpan(telemetrySpan.span, {
+        "ivi.runtime.status": this.state.status
+      });
+    } catch (error) {
+      failIviTelemetrySpan(telemetrySpan.span, error, {
+        "ivi.runtime.status": this.state.status,
+        "ivi.session.id": this.state.session?.id
+      });
+      throw error;
+    }
   }
   getState() {
     return this.state;
   }
+  getTelemetryOptions() {
+    return this.config.telemetry;
+  }
   onStateChange(listener) {
     this.stateListeners.add(listener);
     return () => {
@@ -2311,6 +2543,22 @@ var IviRuntimeCoordinator = class {
   emitLog(entry) {
     this.config.onLog?.(entry);
   }
+  setBootstrapSource(source) {
+    const previous = this.bootstrapSource;
+    if (previous && (!source || previous.sourceId !== source.sourceId)) {
+      const existing = this.sourceManager.get(previous.sourceId);
+      if (existing?.origin === "prebuilt-session-response" && existing.provisional) {
+        this.sourceManager.remove(previous.sourceId);
+      }
+    }
+    this.bootstrapSource = source;
+    this.ensureBootstrapSourceRegistered();
+    this.syncPlaybackManagers();
+    this.setState({
+      ...this.state,
+      sources: this.sourceManager.getAll()
+    });
+  }
   /**
    * 编排一次"用户文本输入 -> 触发模型回复"链路。
    *
@@ -2431,10 +2679,10 @@ var IviRuntimeCoordinator = class {
     this.trackManager.reset();
     this.sourceManager.reset();
     this.streamManager.reset();
-    this.trtcSourceManager.reset();
-    this.livekitSourceManager.reset();
     this.conversationManager.reset();
     this.reset();
+    this.ensureBootstrapSourceRegistered();
+    this.syncPlaybackManagers();
     const nextStatus = this.config.syncStageOnSessionCreated !== false ? "syncing" : "running";
     this.setState({
       status: nextStatus,
@@ -2472,8 +2720,8 @@ var IviRuntimeCoordinator = class {
   onTracksChanged(listRefreshed) {
     const nextStage = this.stageManager.getStage();
     this.sourceManager.syncWithTracks(this.trackManager.getAll());
-    this.trtcSourceManager.syncRuntimeSources(this.sourceManager.getAll());
-    this.livekitSourceManager.syncRuntimeSources(this.sourceManager.getAll());
+    this.ensureBootstrapSourceRegistered();
+    this.syncPlaybackManagers();
     this.setState({
       ...this.state,
       tracks: this.trackManager.getAll(),
@@ -2487,8 +2735,8 @@ var IviRuntimeCoordinator = class {
   applyLocalTrackTake(trackId) {
     this.trackManager.applyTrackTook(trackId);
     this.sourceManager.syncWithTracks(this.trackManager.getAll());
-    this.trtcSourceManager.syncRuntimeSources(this.sourceManager.getAll());
-    this.livekitSourceManager.syncRuntimeSources(this.sourceManager.getAll());
+    this.ensureBootstrapSourceRegistered();
+    this.syncPlaybackManagers();
     this.setState({
       ...this.state,
       tracks: this.trackManager.getAll(),
@@ -2528,8 +2776,8 @@ var IviRuntimeCoordinator = class {
   }
   onSourcesChanged(listRefreshed) {
     this.sourceManager.syncWithTracks(this.trackManager.getAll());
-    this.trtcSourceManager.syncRuntimeSources(this.sourceManager.getAll());
-    this.livekitSourceManager.syncRuntimeSources(this.sourceManager.getAll());
+    this.ensureBootstrapSourceRegistered();
+    this.syncPlaybackManagers();
     this.setState({
       ...this.state,
       sources: this.sourceManager.getAll()
@@ -2552,12 +2800,110 @@ var IviRuntimeCoordinator = class {
     });
   }
   setState(nextState) {
-    if (this.state.status === nextState.status && this.state.session === nextState.session && this.state.stage === nextState.stage && this.state.tracks === nextState.tracks && this.state.sources === nextState.sources && this.state.streams === nextState.streams && this.state.conversationItems === nextState.conversationItems && this.state.conversations === nextState.conversations) {
+    let resolvedNextState = nextState;
+    if (this.bootstrapSource && nextState.status !== "stopped" && !nextState.sources.has(this.bootstrapSource.sourceId)) {
+      this.ensureBootstrapSourceRegistered();
+      resolvedNextState = {
+        ...nextState,
+        sources: this.sourceManager.getAll()
+      };
+    }
+    const composedNextState = this.composeBootstrapState(resolvedNextState);
+    if (this.state.status === composedNextState.status && this.state.session === composedNextState.session && this.state.stage === composedNextState.stage && this.state.tracks === composedNextState.tracks && this.state.sources === composedNextState.sources && this.state.streams === composedNextState.streams && this.state.conversationItems === composedNextState.conversationItems && this.state.conversations === composedNextState.conversations && isSameBootstrapState(this.state.bootstrap, composedNextState.bootstrap)) {
       return;
     }
-    this.state = nextState;
+    const previousState = this.state;
+    this.state = composedNextState;
+    if (previousState.status !== composedNextState.status) {
+      recordIviTelemetrySpan("ivi.runtime.state_change", this.config.telemetry, {
+        "ivi.runtime.status.previous": previousState.status,
+        "ivi.runtime.status.next": composedNextState.status,
+        "ivi.runtime.state_change.reason": "state_update",
+        "ivi.session.id": composedNextState.session?.id ?? previousState.session?.id
+      });
+    }
     this.stateListeners.forEach((listener) => listener(this.state));
   }
+  composeBootstrapState(nextState) {
+    const bootstrap = this.bootstrapSource;
+    if (!bootstrap) {
+      return nextState.bootstrap === null || nextState.bootstrap === void 0 ? nextState : { ...nextState, bootstrap: null };
+    }
+    const shouldExpose = this.shouldExposeBootstrap(nextState, bootstrap);
+    const bootstrapState = {
+      active: shouldExpose,
+      slot: bootstrap.slot,
+      trackId: bootstrap.trackId,
+      sourceId: bootstrap.sourceId,
+      streamId: bootstrap.streamId
+    };
+    if (!shouldExpose) {
+      return {
+        ...nextState,
+        bootstrap: bootstrapState
+      };
+    }
+    const tracks = new Map(nextState.tracks);
+    tracks.set(bootstrap.trackId, {
+      track_id: bootstrap.trackId,
+      active_source_id: bootstrap.sourceId
+    });
+    return {
+      ...nextState,
+      tracks,
+      bootstrap: bootstrapState
+    };
+  }
+  shouldExposeBootstrap(state, bootstrap) {
+    if (state.status === "stopped") {
+      return false;
+    }
+    const bootstrapRuntimeSource = state.sources.get(bootstrap.sourceId);
+    if (!isReadyRenderableSource(bootstrapRuntimeSource)) {
+      return false;
+    }
+    const layer = (state.stage?.composition ?? []).find((item) => item.slot === bootstrap.slot);
+    if (!layer) {
+      return true;
+    }
+    const track = state.tracks.get(layer.track_id);
+    const activeSourceId = track?.active_source_id;
+    if (!activeSourceId || activeSourceId === bootstrap.sourceId) {
+      return true;
+    }
+    return !this.isReadyForBootstrapHandoff(activeSourceId, state.sources.get(activeSourceId));
+  }
+  isReadyForBootstrapHandoff(sourceId, source) {
+    if (!isReadyRenderableSource(source)) {
+      return false;
+    }
+    if (isTrtcPlaybackSource(source)) {
+      return this.trtcSourceManager.hasRemoteVideoAvailable(sourceId);
+    }
+    if (isLivekitPlaybackSource(source)) {
+      return this.livekitSourceManager.hasRemoteVideoAvailable(sourceId);
+    }
+    return true;
+  }
+  recomposeBootstrapState() {
+    if (!this.bootstrapSource) {
+      return;
+    }
+    this.setState({ ...this.state });
+  }
+  ensureBootstrapSourceRegistered() {
+    if (!this.bootstrapSource) {
+      return;
+    }
+    if (this.sourceManager.has(this.bootstrapSource.sourceId)) {
+      return;
+    }
+    this.sourceManager.upsertBootstrapReady(this.bootstrapSource);
+  }
+  syncPlaybackManagers() {
+    this.trtcSourceManager.syncRuntimeSources(this.sourceManager.getAll());
+    this.livekitSourceManager.syncRuntimeSources(this.sourceManager.getAll());
+  }
   emitEvent(event) {
     this.progressUserTextToResponseFlows(event);
     this.eventListeners.forEach((listener) => listener(event, this.state));
@@ -2566,6 +2912,12 @@ var IviRuntimeCoordinator = class {
     this.config.onTrtcEvent?.(event);
     this.trtcEventListeners.forEach((listener) => listener(event));
   }
+  onTrtcManagerEvent(event) {
+    this.emitTrtcEvent(event);
+    if (event.type === "remote_video_available") {
+      this.recomposeBootstrapState();
+    }
+  }
   resetStoppedState() {
     this.rejectPendingUserTextToResponseFlows(
       new Error("Runtime stopped before user text to response flow completed.")
@@ -2730,15 +3082,481 @@ function isLivekitPlaybackSource(source) {
   if (!source || !source.playback) return false;
   return isLivekitSourcePlayback(source.playback);
 }
+function isReadyRenderableSource(source) {
+  return Boolean(source && source.status === "ready" && source.playback);
+}
+function isSameBootstrapState(a, b) {
+  if (!a && !b) return true;
+  if (!a || !b) return false;
+  return a.active === b.active && a.slot === b.slot && a.trackId === b.trackId && a.sourceId === b.sourceId && a.streamId === b.streamId;
+}
+var IviCreateIVISessionError = class extends Error {
+  constructor(response, body) {
+    super(`CreateIVISession failed with ${response.status} ${response.statusText}`);
+    this.name = "IviCreateIVISessionError";
+    this.status = response.status;
+    this.statusText = response.statusText;
+    this.body = body;
+  }
+};
+async function createIVISession(request, options) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new Error("fetch is not available. Pass options.fetch to createIVISession.");
+  }
+  const telemetrySpan = startIviTelemetrySpan(
+    "ivi.session.create",
+    options.telemetry,
+    buildCreateSessionTelemetryAttributes(request)
+  );
+  try {
+    const requestBody = toCpCreateIVISessionRequestBody(request);
+    const headers = await buildHeaders(options.headers);
+    injectIviTelemetryHeaders(headers, telemetrySpan.context);
+    const response = await fetchImpl(resolveCreateIVISessionUrl(options), {
+      method: "POST",
+      headers,
+      body: JSON.stringify(requestBody),
+      credentials: options.credentials,
+      signal: options.signal
+    });
+    const responseBody = await readJsonResponse(response);
+    if (!response.ok) {
+      const error = new IviCreateIVISessionError(response, responseBody);
+      failIviTelemetrySpan(telemetrySpan.span, error, {
+        "http.response.status_code": response.status,
+        "http.response.status_text": response.statusText
+      });
+      throw error;
+    }
+    const result = normalizeCreateIVISessionResponse(responseBody, request, requestBody);
+    endIviTelemetrySpan(telemetrySpan.span, {
+      "http.response.status_code": response.status,
+      "ivi.session.id": result.iviSessionId,
+      "ivi.prebuild.playback.kind": result.prebuiltPlayback?.kind
+    });
+    return result;
+  } catch (error) {
+    if (!(error instanceof IviCreateIVISessionError)) {
+      failIviTelemetrySpan(telemetrySpan.span, error);
+    }
+    throw error;
+  }
+}
+function createRuntimeFromSession(session, options = {}) {
+  const telemetrySpan = startIviTelemetrySpan("ivi.runtime.create", options.telemetry, {
+    "ivi.session.id": session.iviSessionId,
+    "ivi.prebuild.playback.kind": session.prebuiltPlayback?.kind
+  });
+  try {
+    const websocketUrl = buildWebSocketUrl(session.endpoint, options.websocket);
+    const childTelemetry = withIviTelemetryContext(options.telemetry, telemetrySpan.context, {
+      "ivi.session.id": session.iviSessionId
+    });
+    const clientTelemetry = mergeIviTelemetryOptions(
+      options.clientConfig?.telemetry,
+      childTelemetry
+    );
+    const runtimeTelemetry = mergeIviTelemetryOptions(
+      options.runtimeConfig?.telemetry,
+      childTelemetry
+    );
+    const client = new IviClient({
+      ...options.clientConfig ?? {},
+      telemetry: clientTelemetry,
+      transport: new WebSocketTransport({
+        url: websocketUrl,
+        sessionId: session.iviSessionId,
+        protocols: options.websocket?.protocols,
+        socketFactory: options.websocket?.socketFactory
+      })
+    });
+    const runtime = new IviRuntimeCoordinator(client, {
+      ...options.runtimeConfig ?? {},
+      telemetry: runtimeTelemetry
+    });
+    if (options.fastStart !== false && session.prebuiltPlayback) {
+      runtime.setBootstrapSource(toBootstrapSource(session.prebuiltPlayback, options));
+    }
+    endIviTelemetrySpan(telemetrySpan.span);
+    return {
+      session,
+      client,
+      runtime
+    };
+  } catch (error) {
+    failIviTelemetrySpan(telemetrySpan.span, error);
+    throw error;
+  }
+}
+async function createIVISessionRuntime(request, options) {
+  const telemetry = mergeIviTelemetryOptions(options.telemetry, options.http.telemetry);
+  const session = await createIVISession(request, {
+    ...options.http,
+    telemetry
+  });
+  return createRuntimeFromSession(session, {
+    ...options,
+    telemetry
+  });
+}
+function toCpCreateIVISessionRequestBody(request) {
+  const body = { ...request };
+  delete body.idempotencyKey;
+  delete body.streamType;
+  delete body.iviVersion;
+  delete body.sessionParameters;
+  delete body.enableDecoderPublish;
+  delete body.sessionRecording;
+  delete body.prebuiltCharacters;
+  delete body.prebuiltStream;
+  if (request.idempotencyKey !== void 0) body.idempotency_key = request.idempotencyKey;
+  if (request.streamType !== void 0) body.stream_type = request.streamType;
+  if (request.iviVersion !== void 0) body.ivi_version = request.iviVersion;
+  if (request.sessionParameters !== void 0) body.session_parameters = request.sessionParameters;
+  if (request.enableDecoderPublish !== void 0) body.enable_decoder_publish = request.enableDecoderPublish;
+  if (request.sessionRecording !== void 0) {
+    body.session_recording = {
+      enabled: request.sessionRecording.enabled,
+      aspect_ratio: request.sessionRecording.aspectRatio
+    };
+  }
+  if (request.prebuiltCharacters !== void 0) {
+    body.prebuilt_characters = request.prebuiltCharacters.map((character) => ({
+      character_id: character.characterId,
+      character_payload: serializePrebuiltPayload(character.characterPayload)
+    }));
+  }
+  if (request.prebuiltStream !== void 0) {
+    body.prebuilt_stream = {
+      stream_id: request.prebuiltStream.streamId,
+      mode: request.prebuiltStream.mode,
+      stream_config: serializePrebuiltPayload(request.prebuiltStream.streamConfig)
+    };
+  }
+  return body;
+}
+function normalizeCreateIVISessionResponse(responseBody, request = {}, requestBody = toCpCreateIVISessionRequestBody(request)) {
+  const payload = unwrapResponsePayload(responseBody);
+  const iviSessionId = getString(payload, "ivi_session_id") ?? getString(payload, "iviSessionId");
+  const endpoint = getString(payload, "endpoint");
+  if (!iviSessionId) {
+    throw new Error("CreateIVISession response missing ivi_session_id.");
+  }
+  if (!endpoint) {
+    throw new Error("CreateIVISession response missing endpoint.");
+  }
+  const trtcInfo = normalizeTrtcInfo(getObjectValue(payload, "trtc_info") ?? getObjectValue(payload, "trtcInfo"));
+  const livekitInfo = normalizeLivekitInfo(getObjectValue(payload, "livekit_info") ?? getObjectValue(payload, "livekitInfo"));
+  const prebuildInfo = getObjectValue(payload, "prebuild_trtc_info") ?? getObjectValue(payload, "prebuildTrtcInfo");
+  const prebuildTrtcInfo = normalizeTrtcInfo(
+    getObjectValue(prebuildInfo, "trtc_info") ?? getObjectValue(prebuildInfo, "trtcInfo")
+  );
+  const prebuildLivekitInfo = normalizeLivekitInfo(
+    getObjectValue(prebuildInfo, "livekit_info") ?? getObjectValue(prebuildInfo, "livekitInfo")
+  );
+  const prebuiltPlayback = buildPrebuiltPlayback(
+    request,
+    requestBody,
+    prebuildTrtcInfo,
+    prebuildLivekitInfo
+  );
+  return {
+    iviSessionId,
+    endpoint,
+    tokenInfo: getObjectValue(payload, "token_info") ?? getObjectValue(payload, "tokenInfo"),
+    trtcInfo,
+    livekitInfo,
+    prebuildTrtcInfo: prebuildTrtcInfo || prebuildLivekitInfo ? {
+      trtcInfo: prebuildTrtcInfo,
+      livekitInfo: prebuildLivekitInfo
+    } : void 0,
+    prebuiltPlayback,
+    raw: responseBody,
+    requestBody
+  };
+}
+function resolveCreateIVISessionUrl(options) {
+  if (options.url) return options.url;
+  if (!options.baseUrl) {
+    throw new Error("CreateIVISession requires options.baseUrl or options.url.");
+  }
+  const path = options.path ?? "/v1/ivi/sessions";
+  return new URL(path, ensureTrailingSlash(options.baseUrl)).toString();
+}
+function buildCreateSessionTelemetryAttributes(request) {
+  return {
+    "ivi.version": request.iviVersion,
+    "ivi.stream.type": request.streamType,
+    "ivi.prebuild.enabled": Boolean(
+      request.prebuiltStream || request.prebuiltCharacters && request.prebuiltCharacters.length > 0
+    )
+  };
+}
+function mergeIviTelemetryOptions(explicit, inherited) {
+  if (!explicit && !inherited) {
+    return void 0;
+  }
+  return {
+    tracer: explicit?.tracer ?? inherited?.tracer,
+    context: explicit?.context ?? inherited?.context,
+    attributes: mergeIviTelemetryAttributes(inherited?.attributes, explicit?.attributes)
+  };
+}
+async function buildHeaders(headers) {
+  const resolvedHeaders = typeof headers === "function" ? await headers() : headers;
+  const next = new Headers(resolvedHeaders);
+  if (!next.has("content-type")) {
+    next.set("content-type", "application/json");
+  }
+  return next;
+}
+var headersTextMapSetter = {
+  set(carrier, key, value) {
+    carrier.set(key, value);
+  }
+};
+function injectIviTelemetryHeaders(headers, context) {
+  propagation.inject(context, headers, headersTextMapSetter);
+}
+async function readJsonResponse(response) {
+  const text = await response.text();
+  if (!text) {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function buildWebSocketUrl(endpoint, options) {
+  const rawUrl = options?.url ?? endpoint;
+  if (!options?.query) {
+    return rawUrl;
+  }
+  const url = new URL(rawUrl);
+  Object.entries(options.query).forEach(([key, value]) => {
+    if (value === void 0 || value === null) return;
+    url.searchParams.set(key, value);
+  });
+  return url.toString();
+}
+function toBootstrapSource(prebuiltPlayback, options) {
+  return {
+    sourceId: prebuiltPlayback.sourceId,
+    streamId: prebuiltPlayback.streamId,
+    slot: options.bootstrapSlot ?? "main",
+    trackId: options.bootstrapTrackId ?? "__ivi_bootstrap_track",
+    playback: prebuiltPlayback.playback,
+    source: {
+      source_id: prebuiltPlayback.sourceId,
+      kind: prebuiltPlayback.streamId ? "generation_stream" : "stream",
+      stream_id: prebuiltPlayback.streamId,
+      asset_type: "video",
+      metadata: {
+        label: "prebuilt"
+      }
+    }
+  };
+}
+function buildPrebuiltPlayback(request, requestBody, trtcInfo, livekitInfo) {
+  if (!trtcInfo && !livekitInfo) {
+    return void 0;
+  }
+  const streamId = resolvePrebuiltStreamId(request, requestBody, trtcInfo, livekitInfo);
+  const sourceId = request.prebuiltStream?.sourceId ?? streamId;
+  if (!sourceId) {
+    return void 0;
+  }
+  if (trtcInfo) {
+    return {
+      sourceId,
+      streamId,
+      kind: "trtc",
+      playback: {
+        type: "trtc",
+        trtc: trtcInfo
+      },
+      provisional: true
+    };
+  }
+  if (livekitInfo) {
+    return {
+      sourceId,
+      streamId,
+      kind: "livekit",
+      playback: {
+        type: "livekit",
+        livekit: livekitInfo
+      },
+      provisional: true
+    };
+  }
+  return void 0;
+}
+function resolvePrebuiltStreamId(request, requestBody, trtcInfo, livekitInfo) {
+  const prebuiltStream = getObjectValue(requestBody, "prebuilt_stream");
+  return request.prebuiltStream?.streamId ?? getString(prebuiltStream, "stream_id") ?? getString(prebuiltStream, "streamId") ?? trtcInfo?.room_id ?? livekitInfo?.room;
+}
+function normalizeTrtcInfo(value) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const appId = getString(value, "app_id") ?? getString(value, "appId");
+  const roomId = getString(value, "room_id") ?? getString(value, "roomId");
+  const userId = getString(value, "user_id") ?? getString(value, "userId");
+  const userSig = getString(value, "user_sig") ?? getString(value, "userSig");
+  if (!appId || !roomId || !userId || !userSig) {
+    return void 0;
+  }
+  const normalized = {
+    ...value,
+    app_id: appId,
+    room_id: roomId,
+    user_id: userId,
+    user_sig: userSig
+  };
+  delete normalized.secret_key;
+  delete normalized.secretKey;
+  return normalized;
+}
+function normalizeLivekitInfo(value) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const wsUrl = getString(value, "ws_url") ?? getString(value, "url") ?? getString(value, "wsUrl");
+  const token = getString(value, "token") ?? getString(value, "access_token") ?? getString(value, "accessToken");
+  if (!wsUrl || !token) {
+    return void 0;
+  }
+  return {
+    ws_url: wsUrl,
+    token,
+    room: getString(value, "room") ?? getString(value, "room_name") ?? getString(value, "roomName"),
+    identity: getString(value, "identity")
+  };
+}
+function serializePrebuiltPayload(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  return encodeJsonBase64(value);
+}
+function encodeJsonBase64(value) {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  let binary = "";
+  bytes.forEach((byte) => {
+    binary += String.fromCharCode(byte);
+  });
+  if (typeof btoa === "function") {
+    return btoa(binary);
+  }
+  const maybeBuffer = globalThis.Buffer;
+  if (maybeBuffer) {
+    return maybeBuffer.from(bytes).toString("base64");
+  }
+  throw new Error("Base64 encoder is not available in this runtime.");
+}
+function unwrapResponsePayload(value) {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const data = getObjectValue(value, "data");
+  return data ?? value;
+}
+function getObjectValue(value, key) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const nested = value[key];
+  return isRecord(nested) ? nested : void 0;
+}
+function getString(value, key) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const nested = value[key];
+  return typeof nested === "string" && nested.trim().length > 0 ? nested.trim() : void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function ensureTrailingSlash(value) {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+// src/sdk.ts
 var IviFrontendSdk = class {
+  constructor(config = {}) {
+    this.config = config;
+  }
   createClient(config) {
-    return new IviClient(config);
+    return new IviClient({
+      ...config,
+      telemetry: mergeSdkTelemetryOptions(config.telemetry, this.config.telemetry)
+    });
   }
   createRuntimeCoordinator(clientConfig, runtimeConfig) {
     const client = this.createClient(clientConfig);
-    return new IviRuntimeCoordinator(client, runtimeConfig);
+    return new IviRuntimeCoordinator(client, {
+      ...runtimeConfig ?? {},
+      telemetry: mergeSdkTelemetryOptions(runtimeConfig?.telemetry, this.config.telemetry)
+    });
+  }
+  createIVISession(request, options) {
+    const telemetry = mergeSdkTelemetryChain(
+      this.config.telemetry,
+      this.config.http?.telemetry,
+      options?.telemetry
+    );
+    return createIVISession(request, {
+      ...this.config.http ?? {},
+      ...options ?? {},
+      telemetry
+    });
+  }
+  createRuntimeFromSession(session, options) {
+    return createRuntimeFromSession(session, {
+      ...options ?? {},
+      telemetry: mergeSdkTelemetryChain(this.config.telemetry, options?.telemetry)
+    });
+  }
+  createIVISessionRuntime(request, options) {
+    const telemetry = mergeSdkTelemetryChain(
+      this.config.telemetry,
+      this.config.http?.telemetry,
+      options?.http?.telemetry,
+      options?.telemetry
+    );
+    const http = {
+      ...this.config.http ?? {},
+      ...options?.http ?? {},
+      telemetry
+    };
+    return createIVISessionRuntime(request, {
+      ...options ?? {},
+      telemetry,
+      http
+    });
   }
 };
+function mergeSdkTelemetryChain(...items) {
+  return items.reduce(
+    (merged, item) => mergeSdkTelemetryOptions(item, merged),
+    void 0
+  );
+}
+function mergeSdkTelemetryOptions(explicit, inherited) {
+  if (!explicit && !inherited) {
+    return void 0;
+  }
+  return {
+    tracer: explicit?.tracer ?? inherited?.tracer,
+    context: explicit?.context ?? inherited?.context,
+    attributes: mergeIviTelemetryAttributes(inherited?.attributes, explicit?.attributes)
+  };
+}
 var IviStageViewContext = createContext(null);
 var EMPTY_RUNTIME_STATE = {
   status: "idle",
@@ -2748,7 +3566,8 @@ var EMPTY_RUNTIME_STATE = {
   sources: /* @__PURE__ */ new Map(),
   streams: /* @__PURE__ */ new Map(),
   conversationItems: /* @__PURE__ */ new Map(),
-  conversations: []
+  conversations: [],
+  bootstrap: null
 };
 function useRuntimeState(runtime) {
   const [state, setState] = useState(() => runtime?.getState() ?? EMPTY_RUNTIME_STATE);
@@ -2776,10 +3595,10 @@ function IVIStageView(props) {
   const state = useRuntimeState(runtime);
   const slotTrackMap = useMemo(() => {
     return buildSlotTrackMapFromState(state);
-  }, [state.stage]);
+  }, [state.stage, state.bootstrap]);
   const slotBindings = useMemo(() => {
     return buildSlotBindingsFromState(state);
-  }, [state.stage, state.tracks, state.sources]);
+  }, [state.stage, state.tracks, state.sources, state.bootstrap]);
   useEffect(() => {
     onBindingsChange?.(slotBindings);
   }, [slotBindings, onBindingsChange]);
@@ -2819,15 +3638,18 @@ function buildSlotTrackMapFromState(state) {
   (state.stage?.composition ?? []).forEach((item) => {
     map.set(item.slot, item.track_id);
   });
+  if (state.bootstrap?.active) {
+    map.set(state.bootstrap.slot, state.bootstrap.trackId);
+  }
   return map;
 }
 function buildSlotBindingsFromState(state) {
-  const bindings = [];
+  const bindingsBySlot = /* @__PURE__ */ new Map();
   (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;
-    bindings.push({
+    bindingsBySlot.set(item.slot, {
       slot: item.slot,
       trackId: item.track_id,
       track,
@@ -2835,7 +3657,18 @@ function buildSlotBindingsFromState(state) {
       source
     });
   });
-  return bindings;
+  if (state.bootstrap?.active) {
+    const track = state.tracks.get(state.bootstrap.trackId);
+    const source = state.sources.get(state.bootstrap.sourceId);
+    bindingsBySlot.set(state.bootstrap.slot, {
+      slot: state.bootstrap.slot,
+      trackId: state.bootstrap.trackId,
+      track,
+      sourceId: state.bootstrap.sourceId,
+      source
+    });
+  }
+  return Array.from(bindingsBySlot.values());
 }
 var VOLUME_STORAGE_KEY = "ivi-volume-preferences";
 var DEFAULT_VOLUME = 80;
@@ -3603,23 +4436,25 @@ function IVITrtcPlayer(props) {
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState(null);
   const mutedRef = useRef(muted);
+  const attachedSourceIdRef = useRef(null);
   mutedRef.current = muted;
+  useEffect(() => {
+    const unsubscribe = manager.subscribe(resolvedSourceId, (snapshot) => {
+      setLoading(snapshot.status === "idle" || snapshot.status === "connecting");
+      setError(snapshot.status === "error" ? snapshot.error ?? "TRTC \u62C9\u6D41\u5931\u8D25" : null);
+    });
+    return unsubscribe;
+  }, [manager, resolvedSourceId]);
   useEffect(() => {
     const container = containerRef.current;
     if (!container) {
       return;
     }
     let disposed = false;
+    attachedSourceIdRef.current = resolvedSourceId;
     if (shouldManageSourceLifecycle) {
       manager.upsertSource(resolvedSourceId, trtc, trtcAIDenoiser);
     }
-    const unsubscribe = manager.subscribe(resolvedSourceId, (snapshot) => {
-      if (disposed) {
-        return;
-      }
-      setLoading(snapshot.status === "idle" || snapshot.status === "connecting");
-      setError(snapshot.status === "error" ? snapshot.error ?? "TRTC \u62C9\u6D41\u5931\u8D25" : null);
-    });
     void manager.attachView(resolvedSourceId, viewIdRef.current, container, mutedRef.current).catch((caughtError) => {
       if (disposed) {
         return;
@@ -3629,15 +4464,15 @@ function IVITrtcPlayer(props) {
     });
     return () => {
       disposed = true;
-      unsubscribe();
-      manager.detachView(resolvedSourceId, viewIdRef.current);
+      const attachedSourceId = attachedSourceIdRef.current ?? resolvedSourceId;
+      manager.detachView(attachedSourceId, viewIdRef.current);
       if (shouldManageSourceLifecycle) {
-        manager.removeSource(resolvedSourceId);
+        manager.removeSource(attachedSourceId);
       }
+      attachedSourceIdRef.current = null;
     };
   }, [
     manager,
-    resolvedSourceId,
     shouldManageSourceLifecycle,
     trtc.app_id,
     trtc.room_id,
@@ -3645,6 +4480,15 @@ function IVITrtcPlayer(props) {
     trtc.user_sig,
     trtcAIDenoiser
   ]);
+  useEffect(() => {
+    const previousSourceId = attachedSourceIdRef.current;
+    if (!previousSourceId || previousSourceId === resolvedSourceId) {
+      return;
+    }
+    if (manager.reassignView(previousSourceId, resolvedSourceId, viewIdRef.current)) {
+      attachedSourceIdRef.current = resolvedSourceId;
+    }
+  }, [manager, resolvedSourceId]);
   useEffect(() => {
     manager.updateViewMuted(resolvedSourceId, viewIdRef.current, muted);
   }, [manager, muted, resolvedSourceId]);
@@ -3913,7 +4757,16 @@ function makeLoadPolicy(label, onLog) {
   };
 }
 function IVIHlsVideo(props) {
-  const { url, videoProps, style, aggressivePreload = false, paused = false, onLog } = props;
+  const {
+    url,
+    sourceId,
+    videoProps,
+    style,
+    aggressivePreload = false,
+    paused = false,
+    onLog,
+    telemetry
+  } = props;
   const videoRef = useRef(null);
   const pausedRef = useRef(paused);
   useEffect(() => {
@@ -3950,6 +4803,7 @@ function IVIHlsVideo(props) {
     const onVideoError = () => {
       const el = videoRef.current;
       const mediaErr = el?.error;
+      recordVideoTelemetry("ivi.media.video.error", telemetry, sourceId, "hls", mediaErr);
       emitHlsLog(onLog, "warn", "<video> \u5143\u7D20\u62A5\u9519", {
         code: mediaErr?.code,
         message: mediaErr?.message,
@@ -3959,6 +4813,13 @@ function IVIHlsVideo(props) {
       });
     };
     const onVideoStalled = () => {
+      recordVideoTelemetry(
+        "ivi.media.video.stalled",
+        telemetry,
+        sourceId,
+        "hls",
+        new Error("<video> stalled")
+      );
       emitHlsLog(onLog, "warn", "<video> stalled\uFF08\u7F13\u51B2\u505C\u6EDE\uFF09", {
         currentTime: videoRef.current?.currentTime,
         readyState: videoRef.current?.readyState
@@ -4101,7 +4962,7 @@ function IVIHlsVideo(props) {
       hlsInstance?.destroy();
       hlsInstance = null;
     };
-  }, [url, aggressivePreload, onLog]);
+  }, [url, sourceId, aggressivePreload, onLog, telemetry]);
   return /* @__PURE__ */ jsx(
     "video",
     {
@@ -4114,6 +4975,17 @@ function IVIHlsVideo(props) {
     }
   );
 }
+function recordVideoTelemetry(name, telemetry, sourceId, kind, error) {
+  recordIviTelemetrySpan(
+    name,
+    telemetry,
+    {
+      "ivi.source.id": sourceId,
+      "ivi.media.kind": kind
+    },
+    error
+  );
+}
 function isM3u8Url(url) {
   return /\.m3u8(?:$|[?#])/i.test(url);
 }
@@ -4152,13 +5024,7 @@ function getSourceRenderKey(sourceId, source) {
   if (!trtc) {
     return sourceId;
   }
-  return [
-    "trtc",
-    trtc.app_id ?? "",
-    trtc.room_id ?? "",
-    trtc.user_id ?? "",
-    trtc.user_sig ?? ""
-  ].join(":");
+  return ["trtc", trtc.app_id ?? "", trtc.room_id ?? ""].join(":");
 }
 function TrackSlotMediaContent(props) {
   const {
@@ -4185,6 +5051,7 @@ function TrackSlotMediaContent(props) {
     source,
     isPreloading: !isActive
   };
+  const telemetry = runtime?.getTelemetryOptions();
   const mediaStyle = buildAdaptiveMediaStyle(adaptToSourceSize, fitStrategy);
   const shouldMute = !isActive;
   if (renderMedia) return renderMedia(renderContext);
@@ -4256,9 +5123,11 @@ function TrackSlotMediaContent(props) {
       IVIHlsVideo,
       {
         url: playbackUrl,
+        sourceId: slotSourceId,
         videoProps: mergedVideoProps,
         style: videoStyle,
-        paused: shouldPause
+        paused: shouldPause,
+        telemetry
       }
     );
   }
@@ -4280,6 +5149,7 @@ function TrackSlotMediaContent(props) {
     SlotVideo,
     {
       src: playbackUrl,
+      sourceId: slotSourceId,
       paused: shouldPause,
       videoProps: {
         ...mergedVideoProps,
@@ -4287,7 +5157,8 @@ function TrackSlotMediaContent(props) {
         playsInline: videoProps?.playsInline ?? true,
         controls: isActive ? videoProps?.controls ?? true : false
       },
-      style: videoStyle
+      style: videoStyle,
+      telemetry
     }
   );
 }
@@ -4337,17 +5208,48 @@ function SlotVideo(props) {
       video.play().catch(() => void 0);
     }
   }, [props.paused]);
+  const onError = (event) => {
+    recordPlainVideoTelemetry(
+      "ivi.media.video.error",
+      props.telemetry,
+      props.sourceId,
+      event.currentTarget.error
+    );
+    props.videoProps.onError?.(event);
+  };
+  const onStalled = (event) => {
+    recordPlainVideoTelemetry(
+      "ivi.media.video.stalled",
+      props.telemetry,
+      props.sourceId,
+      new Error("<video> stalled")
+    );
+    props.videoProps.onStalled?.(event);
+  };
   return /* @__PURE__ */ jsx(
     "video",
     {
       ref: videoRef,
       src: props.src,
       ...props.videoProps,
+      onError,
+      onStalled,
       autoPlay: props.paused ? false : props.videoProps.autoPlay ?? true,
       style: props.style
     }
   );
 }
+function recordPlainVideoTelemetry(name, telemetry, sourceId, error) {
+  recordIviTelemetrySpan(
+    name,
+    telemetry,
+    {
+      "ivi.source.id": sourceId,
+      "ivi.media.kind": "video"
+    },
+    error
+  );
+}
 
 // src/react/internal/use-multi-preload-sources.ts
 function useMultiPreloadSources(sources, activeSourceId) {
@@ -4614,7 +5516,83 @@ function getClientLogTag(category) {
   if (category === "reconnect") return "[IVI-RECONNECT]";
   return "[IVI-CLIENT]";
 }
+function useIviSessionRuntime(config) {
+  const [status, setStatus] = useState("idle");
+  const [session, setSession] = useState(null);
+  const [runtime, setRuntime] = useState(null);
+  const [client, setClient] = useState(null);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    const {
+      request,
+      enabled = true,
+      autoStart = true,
+      onCreated,
+      onRuntimeReady,
+      onError,
+      ...options
+    } = config;
+    if (!enabled || !request) {
+      setStatus("idle");
+      setSession(null);
+      setRuntime(null);
+      setClient(null);
+      setError(null);
+      return;
+    }
+    let disposed = false;
+    let activeRuntime = null;
+    setStatus("creating");
+    setSession(null);
+    setRuntime(null);
+    setClient(null);
+    setError(null);
+    void createIVISessionRuntime(request, options).then(async (created) => {
+      if (disposed) {
+        created.runtime.stop();
+        return;
+      }
+      activeRuntime = created.runtime;
+      setSession(created.session);
+      setRuntime(created.runtime);
+      setClient(created.client);
+      onCreated?.(created.session);
+      onRuntimeReady?.(created.runtime, created.client);
+      if (!autoStart) {
+        setStatus("idle");
+        return;
+      }
+      setStatus("connecting");
+      await created.runtime.start();
+      if (disposed) {
+        created.runtime.stop();
+        return;
+      }
+      setStatus("running");
+    }).catch((caughtError) => {
+      if (disposed) {
+        return;
+      }
+      const normalizedError = caughtError instanceof Error ? caughtError : new Error(String(caughtError));
+      setError(normalizedError);
+      setStatus("error");
+      onError?.(caughtError);
+    });
+    return () => {
+      disposed = true;
+      activeRuntime?.stop();
+      setStatus("stopped");
+    };
+  }, [config]);
+  return {
+    status,
+    session,
+    runtime,
+    client,
+    error
+  };
+}
 
-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 };
+export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, IVIStageView, IVISubtitleOverlay, IVITrackSlot, IVITrtcPlayer, IviCreateIVISessionError, IviFrontendSdk, IviRuntimeCoordinator, IviRuntimeDispatcher, LivekitSourceManager, TrtcSourceManager, createIVISession, createIVISessionRuntime, createRuntimeFromSession, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, normalizeCreateIVISessionResponse, toCpCreateIVISessionRequestBody, useIviSessionRuntime, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map