@vivix-ai/ivi-frontend-sdk 0.3.7 → 0.3.9

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var iviSdkTs = require('@vivix-ai/ivi-sdk-ts');
+var websocket = require('@vivix-ai/ivi-sdk-ts/transports/websocket');
 var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 
@@ -622,7 +623,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;
   }
@@ -637,7 +640,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;
   }
@@ -671,11 +705,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;
@@ -1107,6 +1144,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"
@@ -1268,6 +1307,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,
@@ -1275,6 +1316,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) {
@@ -1290,6 +1332,8 @@ 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);
     }
     void this.applyAudioPolicy(session);
@@ -1306,11 +1350,30 @@ 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);
     session.views.forEach((binding, viewId) => {
       if (binding.sourceId === sourceId) {
+        binding.container.removeAttribute(TRTC_VIEW_ATTR);
         session.views.delete(viewId);
       }
     });
@@ -1479,6 +1542,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,
@@ -1494,12 +1558,14 @@ var TrtcSourceManager = class {
     }
     binding.startingVideoKeys.add(remoteVideoKey);
     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" }
       });
+      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) {
@@ -1630,11 +1696,43 @@ 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;
 }
 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);
@@ -1642,7 +1740,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,
@@ -1721,6 +1818,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");
   });
 }
 
@@ -1748,8 +1848,9 @@ function describeLivekitRoom(livekit) {
 // src/runtime/managers/livekit-source-manager.ts
 var TAG2 = "[IVI-LIVEKIT]";
 var LivekitSourceManager = class {
-  constructor(onLog) {
+  constructor(onLog, onRemoteVideoAvailable) {
     this.onLog = onLog;
+    this.onRemoteVideoAvailable = onRemoteVideoAvailable;
     this.sessions = /* @__PURE__ */ new Map();
     this.listeners = /* @__PURE__ */ new Map();
   }
@@ -1976,6 +2077,7 @@ var LivekitSourceManager = class {
             waiter(true);
           }
           session.remoteVideoWaiters.length = 0;
+          this.onRemoteVideoAvailable?.(session.sourceId);
         }
         session.views.forEach((binding) => {
           this.attachTrackToView(track, kind, trackKey, binding);
@@ -2171,6 +2273,7 @@ var IviRuntimeCoordinator = class {
     this.userTextFlowCounter = 0;
     this.waitingTracksListValidation = false;
     this.waitingSourcesListValidation = false;
+    this.bootstrapSource = null;
     this.state = {
       status: "idle",
       session: null,
@@ -2179,7 +2282,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 = {
@@ -2188,10 +2292,12 @@ var IviRuntimeCoordinator = class {
     };
     this.trtcSourceManager = new TrtcSourceManager(
       this.config.onLog,
-      (event) => this.emitTrtcEvent(event),
+      (event) => this.onTrtcManagerEvent(event),
       this.config.trtcAIDenoiser
     );
-    this.livekitSourceManager = new LivekitSourceManager(this.config.onLog);
+    this.livekitSourceManager = new LivekitSourceManager(this.config.onLog, () => {
+      this.recomposeBootstrapState();
+    });
     this.sessionHandler = new SessionEventHandler(this.sessionManager, {
       onSessionCreated: (event) => this.onSessionCreated(event),
       onSessionEnded: (event) => this.onSessionEnded(event)
@@ -2272,6 +2378,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()
+    });
+  }
   /**
    * 编排一次"用户文本输入 -> 触发模型回复"链路。
    *
@@ -2392,10 +2514,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,
@@ -2433,8 +2555,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(),
@@ -2448,8 +2570,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(),
@@ -2489,8 +2611,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()
@@ -2513,12 +2635,101 @@ 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;
+    this.state = composedNextState;
     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));
@@ -2527,6 +2738,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.")
@@ -2691,7 +2908,331 @@ 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 requestBody = toCpCreateIVISessionRequestBody(request);
+  const response = await fetchImpl(resolveCreateIVISessionUrl(options), {
+    method: "POST",
+    headers: await buildHeaders(options.headers),
+    body: JSON.stringify(requestBody),
+    credentials: options.credentials,
+    signal: options.signal
+  });
+  const responseBody = await readJsonResponse(response);
+  if (!response.ok) {
+    throw new IviCreateIVISessionError(response, responseBody);
+  }
+  return normalizeCreateIVISessionResponse(responseBody, request, requestBody);
+}
+function createRuntimeFromSession(session, options = {}) {
+  const websocketUrl = buildWebSocketUrl(session.endpoint, options.websocket);
+  const client = new iviSdkTs.IviClient({
+    ...options.clientConfig ?? {},
+    transport: new websocket.WebSocketTransport({
+      url: websocketUrl,
+      sessionId: session.iviSessionId,
+      protocols: options.websocket?.protocols,
+      socketFactory: options.websocket?.socketFactory
+    })
+  });
+  const runtime = new IviRuntimeCoordinator(client, options.runtimeConfig);
+  if (options.fastStart !== false && session.prebuiltPlayback) {
+    runtime.setBootstrapSource(toBootstrapSource(session.prebuiltPlayback, options));
+  }
+  return {
+    session,
+    client,
+    runtime
+  };
+}
+async function createIVISessionRuntime(request, options) {
+  const session = await createIVISession(request, options.http);
+  return createRuntimeFromSession(session, options);
+}
+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();
+}
+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;
+}
+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 iviSdkTs.IviClient(config);
   }
@@ -2699,6 +3240,25 @@ var IviFrontendSdk = class {
     const client = this.createClient(clientConfig);
     return new IviRuntimeCoordinator(client, runtimeConfig);
   }
+  createIVISession(request, options) {
+    return createIVISession(request, {
+      ...this.config.http ?? {},
+      ...options ?? {}
+    });
+  }
+  createRuntimeFromSession(session, options) {
+    return createRuntimeFromSession(session, options);
+  }
+  createIVISessionRuntime(request, options) {
+    const http = {
+      ...this.config.http ?? {},
+      ...options?.http ?? {}
+    };
+    return createIVISessionRuntime(request, {
+      ...options ?? {},
+      http
+    });
+  }
 };
 var IviStageViewContext = react.createContext(null);
 var EMPTY_RUNTIME_STATE = {
@@ -2709,7 +3269,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] = react.useState(() => runtime?.getState() ?? EMPTY_RUNTIME_STATE);
@@ -2737,10 +3298,10 @@ function IVIStageView(props) {
   const state = useRuntimeState(runtime);
   const slotTrackMap = react.useMemo(() => {
     return buildSlotTrackMapFromState(state);
-  }, [state.stage]);
+  }, [state.stage, state.bootstrap]);
   const slotBindings = react.useMemo(() => {
     return buildSlotBindingsFromState(state);
-  }, [state.stage, state.tracks, state.sources]);
+  }, [state.stage, state.tracks, state.sources, state.bootstrap]);
   react.useEffect(() => {
     onBindingsChange?.(slotBindings);
   }, [slotBindings, onBindingsChange]);
@@ -2780,15 +3341,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,
@@ -2796,7 +3360,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;
@@ -3564,23 +4139,25 @@ function IVITrtcPlayer(props) {
   const [loading, setLoading] = react.useState(true);
   const [error, setError] = react.useState(null);
   const mutedRef = react.useRef(muted);
+  const attachedSourceIdRef = react.useRef(null);
   mutedRef.current = muted;
+  react.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]);
   react.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;
@@ -3590,15 +4167,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,
@@ -3606,6 +4183,15 @@ function IVITrtcPlayer(props) {
     trtc.user_sig,
     trtcAIDenoiser
   ]);
+  react.useEffect(() => {
+    const previousSourceId = attachedSourceIdRef.current;
+    if (!previousSourceId || previousSourceId === resolvedSourceId) {
+      return;
+    }
+    if (manager.reassignView(previousSourceId, resolvedSourceId, viewIdRef.current)) {
+      attachedSourceIdRef.current = resolvedSourceId;
+    }
+  }, [manager, resolvedSourceId]);
   react.useEffect(() => {
     manager.updateViewMuted(resolvedSourceId, viewIdRef.current, muted);
   }, [manager, muted, resolvedSourceId]);
@@ -3618,7 +4204,6 @@ function IVITrtcPlayer(props) {
         height: "100%",
         minWidth: 0,
         minHeight: 0,
-        backgroundColor: "#000",
         position: "relative",
         ...style
       },
@@ -4114,13 +4699,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 {
@@ -4576,6 +5155,82 @@ function getClientLogTag(category) {
   if (category === "reconnect") return "[IVI-RECONNECT]";
   return "[IVI-CLIENT]";
 }
+function useIviSessionRuntime(config) {
+  const [status, setStatus] = react.useState("idle");
+  const [session, setSession] = react.useState(null);
+  const [runtime, setRuntime] = react.useState(null);
+  const [client, setClient] = react.useState(null);
+  const [error, setError] = react.useState(null);
+  react.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
+  };
+}
 
 exports.DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS = DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS;
 exports.EMPTY_RUNTIME_STATE = EMPTY_RUNTIME_STATE;
@@ -4584,14 +5239,21 @@ exports.IVIStageView = IVIStageView;
 exports.IVISubtitleOverlay = IVISubtitleOverlay;
 exports.IVITrackSlot = IVITrackSlot;
 exports.IVITrtcPlayer = IVITrtcPlayer;
+exports.IviCreateIVISessionError = IviCreateIVISessionError;
 exports.IviFrontendSdk = IviFrontendSdk;
 exports.IviRuntimeCoordinator = IviRuntimeCoordinator;
 exports.IviRuntimeDispatcher = IviRuntimeDispatcher;
 exports.LivekitSourceManager = LivekitSourceManager;
 exports.TrtcSourceManager = TrtcSourceManager;
+exports.createIVISession = createIVISession;
+exports.createIVISessionRuntime = createIVISessionRuntime;
+exports.createRuntimeFromSession = createRuntimeFromSession;
 exports.isLivekitSourcePlayback = isLivekitSourcePlayback;
 exports.isReadyLivekitRuntimeSource = isReadyLivekitRuntimeSource;
 exports.isSameLivekitConfig = isSameLivekitConfig;
+exports.normalizeCreateIVISessionResponse = normalizeCreateIVISessionResponse;
+exports.toCpCreateIVISessionRequestBody = toCpCreateIVISessionRequestBody;
+exports.useIviSessionRuntime = useIviSessionRuntime;
 exports.useIviStageView = useIviStageView;
 exports.useIviSubtitles = useIviSubtitles;
 exports.useManagedIviRuntime = useManagedIviRuntime;