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

package/dist/index.d.cts

@@ -1,5 +1,7 @@
 import { ReceiveSessionSourceReadyPayload, IviStream, IviConversationItem, IviRealtimeSessionConfig, IviStageComposition, IviTrack, IviSourceAsset, ReceiveSessionSourceFailedPayload, IviConversationItemContent, ReceiveSessionEndedEvent, ParsedIviEvent, IviRealtimeResponseCreateParams, ReceiveConversationItemAddedEvent, ReceiveConversationItemDoneEvent, ReceiveResponseCreatedEvent, IviClient, IviClientConfig } from '@vivix-ai/ivi-sdk-ts';
+import { Tracer, Context, Attributes, Span } from '@opentelemetry/api';
 import { LiveKitBrowserTransportConfig } from '@vivix-ai/ivi-sdk-ts/transports/livekit-browser';
+import { WebSocketTransportConfig } from '@vivix-ai/ivi-sdk-ts/transports/websocket';
 import { ReactNode, CSSProperties, ReactElement, VideoHTMLAttributes, ImgHTMLAttributes } from 'react';
 import { IviClientLogEntry } from '@vivix-ai/ivi-sdk-ts/client';
 
@@ -8,6 +10,27 @@ type IviSourcePlayback = NonNullable<ReceiveSessionSourceReadyPayload["playback"
 type IviSourcePlaybackTrtc = NonNullable<IviSourcePlayback["trtc"]>;
 type IviStreamStatus = IviStream["status"];
 
+interface IviFrontendTelemetryOptions {
+    /**
+     * OpenTelemetry tracer。未传入时使用全局 `trace.getTracer("@vivix-ai/ivi-frontend-sdk")`。
+     *
+     * SDK 只依赖 `@opentelemetry/api`，不会内置 exporter/provider；未配置 provider 时这些 span 会是 no-op。
+     */
+    tracer?: Tracer;
+    /**
+     * 外部调用链的父 context。通常由业务点击、建会话或上层 SDK span 内传入 `context.active()`。
+     */
+    context?: Context;
+    /**
+     * 追加到每个 frontend SDK span 上的低基数字段。不要放 token、密钥、完整 payload 或用户文本。
+     */
+    attributes?: Attributes;
+}
+interface IviTelemetrySpanHandle {
+    span: Span;
+    context: Context;
+}
+
 type IviRuntimeStatus = "idle" | "connecting" | "syncing" | "running" | "stopped";
 interface IviRuntimeState {
     status: IviRuntimeStatus;
@@ -18,6 +41,7 @@ interface IviRuntimeState {
     streams: Map<string, IviRuntimeStream>;
     conversationItems: Map<string, IviRuntimeConversationItem>;
     conversations: IviRuntimeConversationItem[];
+    bootstrap?: IviRuntimeBootstrapViewState | null;
 }
 /**
  * Runtime 层归一化后的 stream 视图。
@@ -37,6 +61,7 @@ interface IviRuntimeSourcePreloadState {
      */
     autoclearAfterPlay: boolean;
 }
+type IviRuntimeSourceOrigin = "prebuilt-session-response";
 interface IviRuntimeSource {
     source: IviSourceAsset;
     status: "created" | "ready" | "failed";
@@ -52,6 +77,27 @@ interface IviRuntimeSource {
      * - 不存在：不进行预加载（active source 由上层独立决定是否渲染）。
      */
     preload?: IviRuntimeSourcePreloadState;
+    origin?: IviRuntimeSourceOrigin;
+    provisional?: boolean;
+}
+interface IviRuntimeBootstrapSource {
+    sourceId: string;
+    streamId?: string;
+    slot: string;
+    trackId: string;
+    playback: IviSourcePlayback;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    hasAudio?: boolean;
+    source?: Partial<IviSourceAsset>;
+}
+interface IviRuntimeBootstrapViewState {
+    active: boolean;
+    slot: string;
+    trackId: string;
+    sourceId: string;
+    streamId?: string;
 }
 type IviRuntimeLogLevel = "info" | "warn" | "error";
 interface IviRuntimeLogEntry {
@@ -122,6 +168,10 @@ interface IviRuntimeCoordinatorConfig {
      * TRTC SDK AIDenoiser 降噪配置。默认开启；传 false 可关闭。
      */
     trtcAIDenoiser?: boolean | IviRuntimeTrtcAIDenoiserOptions;
+    /**
+     * OpenTelemetry 埋点配置；SDK 只创建 span，不负责配置 provider/exporter。
+     */
+    telemetry?: IviFrontendTelemetryOptions;
 }
 /**
  * 用户输入触发回复链路配置。
@@ -197,10 +247,11 @@ declare class TrtcSourceManager {
     private readonly onLog?;
     private readonly onTrtcEvent?;
     private readonly aiDenoiser?;
+    private readonly telemetry?;
     private readonly sessions;
     private readonly sourceSessionKeys;
     private readonly listeners;
-    constructor(onLog?: IviRuntimeLogCallback | undefined, onTrtcEvent?: IviRuntimeTrtcEventListener | undefined, aiDenoiser?: (boolean | IviRuntimeTrtcAIDenoiserOptions) | undefined);
+    constructor(onLog?: IviRuntimeLogCallback | undefined, onTrtcEvent?: IviRuntimeTrtcEventListener | undefined, aiDenoiser?: (boolean | IviRuntimeTrtcAIDenoiserOptions) | undefined, telemetry?: IviFrontendTelemetryOptions | undefined);
     /**
      * 将 runtime 当前 sources 与 TRTC 会话池对齐：
      * - 对 ready + trtc 的 source 进行 upsert（必要时建立连接）
@@ -239,6 +290,7 @@ declare class TrtcSourceManager {
     attachView(sourceId: string, viewId: string, container: HTMLElement, muted: boolean): Promise<void>;
     detachView(sourceId: string, viewId: string): void;
     updateViewMuted(sourceId: string, viewId: string, muted: boolean): void;
+    reassignView(fromSourceId: string, toSourceId: string, viewId: string): boolean;
     private unlinkSourceFromSession;
     private getSession;
     private snapshotFromSession;
@@ -315,9 +367,11 @@ type LivekitSourceListener = (snapshot: LivekitSourceSnapshot) => void;
  */
 declare class LivekitSourceManager {
     private readonly onLog?;
+    private readonly onRemoteVideoAvailable?;
+    private readonly telemetry?;
     private readonly sessions;
     private readonly listeners;
-    constructor(onLog?: IviRuntimeLogCallback | undefined);
+    constructor(onLog?: IviRuntimeLogCallback | undefined, onRemoteVideoAvailable?: ((sourceId: string) => void) | undefined, telemetry?: IviFrontendTelemetryOptions | undefined);
     /**
      * 与 runtime 当前 sources 对齐：
      * - 对 ready + livekit 的 source 进行 upsert（必要时建立连接）；
@@ -428,6 +482,7 @@ declare class IviRuntimeCoordinator {
     private userTextFlowCounter;
     private waitingTracksListValidation;
     private waitingSourcesListValidation;
+    private bootstrapSource;
     private state;
     /**
      * @param client 底层实时客户端，负责实际事件收发。
@@ -444,10 +499,12 @@ declare class IviRuntimeCoordinator {
      */
     stop(): void;
     getState(): IviRuntimeState;
+    getTelemetryOptions(): IviRuntimeCoordinatorConfig["telemetry"];
     onStateChange(listener: (state: IviRuntimeState) => void): () => void;
     onEvent(listener: IviRuntimeEventListener): () => void;
     onTrtcEvent(listener: IviRuntimeTrtcEventListener): () => void;
     emitLog(entry: IviRuntimeLogEntry): void;
+    setBootstrapSource(source: IviRuntimeBootstrapSource | null): void;
     /**
      * 编排一次"用户文本输入 -> 触发模型回复"链路。
      *
@@ -484,8 +541,15 @@ declare class IviRuntimeCoordinator {
     private onStreamsChanged;
     private onConversationsChanged;
     private setState;
+    private composeBootstrapState;
+    private shouldExposeBootstrap;
+    private isReadyForBootstrapHandoff;
+    private recomposeBootstrapState;
+    private ensureBootstrapSourceRegistered;
+    private syncPlaybackManagers;
     private emitEvent;
     private emitTrtcEvent;
+    private onTrtcManagerEvent;
     private resetStoppedState;
     private ensureSourcesSyncedForTracks;
     private validateSourcesListRefreshed;
@@ -523,10 +587,110 @@ declare class IviRuntimeDispatcher {
     private dispatchEvent;
 }
 
+type IviCreateSessionStreamType = "TRTC" | "LIVEKIT" | string;
+interface IviCreateIVISessionPrebuiltCharacter {
+    characterId: string;
+    characterPayload: unknown;
+}
+interface IviCreateIVISessionPrebuiltStream {
+    streamId?: string;
+    sourceId?: string;
+    mode: "character" | string;
+    streamConfig: unknown;
+}
+interface IviCreateIVISessionRequest {
+    idempotencyKey?: string;
+    streamType?: IviCreateSessionStreamType;
+    iviVersion?: string;
+    sessionParameters?: Record<string, string>;
+    enableDecoderPublish?: boolean;
+    sessionRecording?: {
+        enabled: boolean;
+        aspectRatio?: string;
+    };
+    prebuiltCharacters?: IviCreateIVISessionPrebuiltCharacter[];
+    prebuiltStream?: IviCreateIVISessionPrebuiltStream;
+    [key: string]: unknown;
+}
+interface IviCreateIVISessionHttpOptions {
+    baseUrl?: string;
+    path?: string;
+    url?: string;
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    fetch?: typeof fetch;
+    credentials?: RequestCredentials;
+    signal?: AbortSignal;
+    telemetry?: IviFrontendTelemetryOptions;
+}
+interface IviPrebuiltPlayback {
+    sourceId: string;
+    streamId?: string;
+    kind: "trtc" | "livekit";
+    playback: IviSourcePlayback;
+    provisional: true;
+}
+interface IviCreateIVISessionResult {
+    iviSessionId: string;
+    endpoint: string;
+    tokenInfo?: unknown;
+    trtcInfo?: IviSourcePlaybackTrtc;
+    livekitInfo?: IviSourcePlaybackLivekit;
+    prebuildTrtcInfo?: {
+        trtcInfo?: IviSourcePlaybackTrtc;
+        livekitInfo?: IviSourcePlaybackLivekit;
+    };
+    prebuiltPlayback?: IviPrebuiltPlayback;
+    raw: unknown;
+    requestBody: Record<string, unknown>;
+}
+interface IviRuntimeWebSocketOptions {
+    url?: string;
+    protocols?: WebSocketTransportConfig["protocols"];
+    query?: Record<string, string | undefined | null>;
+    socketFactory?: WebSocketTransportConfig["socketFactory"];
+}
+interface IviRuntimeFromSessionOptions {
+    fastStart?: boolean;
+    bootstrapSlot?: string;
+    bootstrapTrackId?: string;
+    clientConfig?: Omit<IviClientConfig, "transport">;
+    runtimeConfig?: IviRuntimeCoordinatorConfig;
+    websocket?: IviRuntimeWebSocketOptions;
+    telemetry?: IviFrontendTelemetryOptions;
+}
+interface IviSessionRuntime {
+    session: IviCreateIVISessionResult;
+    client: IviClient;
+    runtime: IviRuntimeCoordinator;
+}
+interface IviCreateIVISessionRuntimeOptions extends IviRuntimeFromSessionOptions {
+    http: IviCreateIVISessionHttpOptions;
+}
+declare class IviCreateIVISessionError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: unknown;
+    constructor(response: Response, body: unknown);
+}
+declare function createIVISession(request: IviCreateIVISessionRequest, options: IviCreateIVISessionHttpOptions): Promise<IviCreateIVISessionResult>;
+declare function createRuntimeFromSession(session: IviCreateIVISessionResult, options?: IviRuntimeFromSessionOptions): IviSessionRuntime;
+declare function createIVISessionRuntime(request: IviCreateIVISessionRequest, options: IviCreateIVISessionRuntimeOptions): Promise<IviSessionRuntime>;
+declare function toCpCreateIVISessionRequestBody(request: IviCreateIVISessionRequest): Record<string, unknown>;
+declare function normalizeCreateIVISessionResponse(responseBody: unknown, request?: IviCreateIVISessionRequest, requestBody?: Record<string, unknown>): IviCreateIVISessionResult;
+
 type IviFrontendClientConfig = IviClientConfig;
+interface IviFrontendSdkConfig {
+    http?: IviCreateIVISessionHttpOptions;
+    telemetry?: IviFrontendTelemetryOptions;
+}
 declare class IviFrontendSdk {
+    private readonly config;
+    constructor(config?: IviFrontendSdkConfig);
     createClient(config: IviFrontendClientConfig): IviClient;
     createRuntimeCoordinator(clientConfig: IviFrontendClientConfig, runtimeConfig?: IviRuntimeCoordinatorConfig): IviRuntimeCoordinator;
+    createIVISession(request: IviCreateIVISessionRequest, options?: IviCreateIVISessionHttpOptions): Promise<IviCreateIVISessionResult>;
+    createRuntimeFromSession(session: IviCreateIVISessionResult, options?: IviRuntimeFromSessionOptions): IviSessionRuntime;
+    createIVISessionRuntime(request: IviCreateIVISessionRequest, options?: Partial<IviCreateIVISessionRuntimeOptions>): Promise<IviSessionRuntime>;
 }
 
 interface IviStageSlotBinding {
@@ -800,6 +964,24 @@ interface IviManagedRuntimeConfig {
 }
 declare function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRuntimeCoordinator | null;
 
+type IviSessionRuntimeHookStatus = "idle" | "creating" | "connecting" | "running" | "error" | "stopped";
+interface UseIviSessionRuntimeConfig extends IviCreateIVISessionRuntimeOptions {
+    request: IviCreateIVISessionRequest | null | undefined;
+    enabled?: boolean;
+    autoStart?: boolean;
+    onCreated?: (session: IviCreateIVISessionResult) => void;
+    onRuntimeReady?: (runtime: IviRuntimeCoordinator, client: IviClient) => void;
+    onError?: (error: unknown) => void;
+}
+interface UseIviSessionRuntimeResult {
+    status: IviSessionRuntimeHookStatus;
+    session: IviCreateIVISessionResult | null;
+    runtime: IviRuntimeCoordinator | null;
+    client: IviClient | null;
+    error: Error | null;
+}
+declare function useIviSessionRuntime(config: UseIviSessionRuntimeConfig): UseIviSessionRuntimeResult;
+
 declare function useIviStageView(): IviStageViewContextValue;
 
-export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
+export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, IviCreateIVISessionError, type IviCreateIVISessionHttpOptions, type IviCreateIVISessionPrebuiltCharacter, type IviCreateIVISessionPrebuiltStream, type IviCreateIVISessionRequest, type IviCreateIVISessionResult, type IviCreateIVISessionRuntimeOptions, type IviCreateSessionStreamType, type IviFrontendClientConfig, IviFrontendSdk, type IviFrontendSdkConfig, type IviFrontendTelemetryOptions, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviPrebuiltPlayback, type IviRuntimeBootstrapSource, type IviRuntimeBootstrapViewState, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeFromSessionOptions, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourceOrigin, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviRuntimeWebSocketOptions, type IviSessionRuntime, type IviSessionRuntimeHookStatus, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviTelemetrySpanHandle, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, type UseIviSessionRuntimeConfig, type UseIviSessionRuntimeResult, createIVISession, createIVISessionRuntime, createRuntimeFromSession, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, normalizeCreateIVISessionResponse, toCpCreateIVISessionRequestBody, useIviSessionRuntime, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { ReceiveSessionSourceReadyPayload, IviStream, IviConversationItem, IviRealtimeSessionConfig, IviStageComposition, IviTrack, IviSourceAsset, ReceiveSessionSourceFailedPayload, IviConversationItemContent, ReceiveSessionEndedEvent, ParsedIviEvent, IviRealtimeResponseCreateParams, ReceiveConversationItemAddedEvent, ReceiveConversationItemDoneEvent, ReceiveResponseCreatedEvent, IviClient, IviClientConfig } from '@vivix-ai/ivi-sdk-ts';
+import { Tracer, Context, Attributes, Span } from '@opentelemetry/api';
 import { LiveKitBrowserTransportConfig } from '@vivix-ai/ivi-sdk-ts/transports/livekit-browser';
+import { WebSocketTransportConfig } from '@vivix-ai/ivi-sdk-ts/transports/websocket';
 import { ReactNode, CSSProperties, ReactElement, VideoHTMLAttributes, ImgHTMLAttributes } from 'react';
 import { IviClientLogEntry } from '@vivix-ai/ivi-sdk-ts/client';
 
@@ -8,6 +10,27 @@ type IviSourcePlayback = NonNullable<ReceiveSessionSourceReadyPayload["playback"
 type IviSourcePlaybackTrtc = NonNullable<IviSourcePlayback["trtc"]>;
 type IviStreamStatus = IviStream["status"];
 
+interface IviFrontendTelemetryOptions {
+    /**
+     * OpenTelemetry tracer。未传入时使用全局 `trace.getTracer("@vivix-ai/ivi-frontend-sdk")`。
+     *
+     * SDK 只依赖 `@opentelemetry/api`，不会内置 exporter/provider；未配置 provider 时这些 span 会是 no-op。
+     */
+    tracer?: Tracer;
+    /**
+     * 外部调用链的父 context。通常由业务点击、建会话或上层 SDK span 内传入 `context.active()`。
+     */
+    context?: Context;
+    /**
+     * 追加到每个 frontend SDK span 上的低基数字段。不要放 token、密钥、完整 payload 或用户文本。
+     */
+    attributes?: Attributes;
+}
+interface IviTelemetrySpanHandle {
+    span: Span;
+    context: Context;
+}
+
 type IviRuntimeStatus = "idle" | "connecting" | "syncing" | "running" | "stopped";
 interface IviRuntimeState {
     status: IviRuntimeStatus;
@@ -18,6 +41,7 @@ interface IviRuntimeState {
     streams: Map<string, IviRuntimeStream>;
     conversationItems: Map<string, IviRuntimeConversationItem>;
     conversations: IviRuntimeConversationItem[];
+    bootstrap?: IviRuntimeBootstrapViewState | null;
 }
 /**
  * Runtime 层归一化后的 stream 视图。
@@ -37,6 +61,7 @@ interface IviRuntimeSourcePreloadState {
      */
     autoclearAfterPlay: boolean;
 }
+type IviRuntimeSourceOrigin = "prebuilt-session-response";
 interface IviRuntimeSource {
     source: IviSourceAsset;
     status: "created" | "ready" | "failed";
@@ -52,6 +77,27 @@ interface IviRuntimeSource {
      * - 不存在：不进行预加载（active source 由上层独立决定是否渲染）。
      */
     preload?: IviRuntimeSourcePreloadState;
+    origin?: IviRuntimeSourceOrigin;
+    provisional?: boolean;
+}
+interface IviRuntimeBootstrapSource {
+    sourceId: string;
+    streamId?: string;
+    slot: string;
+    trackId: string;
+    playback: IviSourcePlayback;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    hasAudio?: boolean;
+    source?: Partial<IviSourceAsset>;
+}
+interface IviRuntimeBootstrapViewState {
+    active: boolean;
+    slot: string;
+    trackId: string;
+    sourceId: string;
+    streamId?: string;
 }
 type IviRuntimeLogLevel = "info" | "warn" | "error";
 interface IviRuntimeLogEntry {
@@ -122,6 +168,10 @@ interface IviRuntimeCoordinatorConfig {
      * TRTC SDK AIDenoiser 降噪配置。默认开启；传 false 可关闭。
      */
     trtcAIDenoiser?: boolean | IviRuntimeTrtcAIDenoiserOptions;
+    /**
+     * OpenTelemetry 埋点配置；SDK 只创建 span，不负责配置 provider/exporter。
+     */
+    telemetry?: IviFrontendTelemetryOptions;
 }
 /**
  * 用户输入触发回复链路配置。
@@ -197,10 +247,11 @@ declare class TrtcSourceManager {
     private readonly onLog?;
     private readonly onTrtcEvent?;
     private readonly aiDenoiser?;
+    private readonly telemetry?;
     private readonly sessions;
     private readonly sourceSessionKeys;
     private readonly listeners;
-    constructor(onLog?: IviRuntimeLogCallback | undefined, onTrtcEvent?: IviRuntimeTrtcEventListener | undefined, aiDenoiser?: (boolean | IviRuntimeTrtcAIDenoiserOptions) | undefined);
+    constructor(onLog?: IviRuntimeLogCallback | undefined, onTrtcEvent?: IviRuntimeTrtcEventListener | undefined, aiDenoiser?: (boolean | IviRuntimeTrtcAIDenoiserOptions) | undefined, telemetry?: IviFrontendTelemetryOptions | undefined);
     /**
      * 将 runtime 当前 sources 与 TRTC 会话池对齐：
      * - 对 ready + trtc 的 source 进行 upsert（必要时建立连接）
@@ -239,6 +290,7 @@ declare class TrtcSourceManager {
     attachView(sourceId: string, viewId: string, container: HTMLElement, muted: boolean): Promise<void>;
     detachView(sourceId: string, viewId: string): void;
     updateViewMuted(sourceId: string, viewId: string, muted: boolean): void;
+    reassignView(fromSourceId: string, toSourceId: string, viewId: string): boolean;
     private unlinkSourceFromSession;
     private getSession;
     private snapshotFromSession;
@@ -315,9 +367,11 @@ type LivekitSourceListener = (snapshot: LivekitSourceSnapshot) => void;
  */
 declare class LivekitSourceManager {
     private readonly onLog?;
+    private readonly onRemoteVideoAvailable?;
+    private readonly telemetry?;
     private readonly sessions;
     private readonly listeners;
-    constructor(onLog?: IviRuntimeLogCallback | undefined);
+    constructor(onLog?: IviRuntimeLogCallback | undefined, onRemoteVideoAvailable?: ((sourceId: string) => void) | undefined, telemetry?: IviFrontendTelemetryOptions | undefined);
     /**
      * 与 runtime 当前 sources 对齐：
      * - 对 ready + livekit 的 source 进行 upsert（必要时建立连接）；
@@ -428,6 +482,7 @@ declare class IviRuntimeCoordinator {
     private userTextFlowCounter;
     private waitingTracksListValidation;
     private waitingSourcesListValidation;
+    private bootstrapSource;
     private state;
     /**
      * @param client 底层实时客户端，负责实际事件收发。
@@ -444,10 +499,12 @@ declare class IviRuntimeCoordinator {
      */
     stop(): void;
     getState(): IviRuntimeState;
+    getTelemetryOptions(): IviRuntimeCoordinatorConfig["telemetry"];
     onStateChange(listener: (state: IviRuntimeState) => void): () => void;
     onEvent(listener: IviRuntimeEventListener): () => void;
     onTrtcEvent(listener: IviRuntimeTrtcEventListener): () => void;
     emitLog(entry: IviRuntimeLogEntry): void;
+    setBootstrapSource(source: IviRuntimeBootstrapSource | null): void;
     /**
      * 编排一次"用户文本输入 -> 触发模型回复"链路。
      *
@@ -484,8 +541,15 @@ declare class IviRuntimeCoordinator {
     private onStreamsChanged;
     private onConversationsChanged;
     private setState;
+    private composeBootstrapState;
+    private shouldExposeBootstrap;
+    private isReadyForBootstrapHandoff;
+    private recomposeBootstrapState;
+    private ensureBootstrapSourceRegistered;
+    private syncPlaybackManagers;
     private emitEvent;
     private emitTrtcEvent;
+    private onTrtcManagerEvent;
     private resetStoppedState;
     private ensureSourcesSyncedForTracks;
     private validateSourcesListRefreshed;
@@ -523,10 +587,110 @@ declare class IviRuntimeDispatcher {
     private dispatchEvent;
 }
 
+type IviCreateSessionStreamType = "TRTC" | "LIVEKIT" | string;
+interface IviCreateIVISessionPrebuiltCharacter {
+    characterId: string;
+    characterPayload: unknown;
+}
+interface IviCreateIVISessionPrebuiltStream {
+    streamId?: string;
+    sourceId?: string;
+    mode: "character" | string;
+    streamConfig: unknown;
+}
+interface IviCreateIVISessionRequest {
+    idempotencyKey?: string;
+    streamType?: IviCreateSessionStreamType;
+    iviVersion?: string;
+    sessionParameters?: Record<string, string>;
+    enableDecoderPublish?: boolean;
+    sessionRecording?: {
+        enabled: boolean;
+        aspectRatio?: string;
+    };
+    prebuiltCharacters?: IviCreateIVISessionPrebuiltCharacter[];
+    prebuiltStream?: IviCreateIVISessionPrebuiltStream;
+    [key: string]: unknown;
+}
+interface IviCreateIVISessionHttpOptions {
+    baseUrl?: string;
+    path?: string;
+    url?: string;
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    fetch?: typeof fetch;
+    credentials?: RequestCredentials;
+    signal?: AbortSignal;
+    telemetry?: IviFrontendTelemetryOptions;
+}
+interface IviPrebuiltPlayback {
+    sourceId: string;
+    streamId?: string;
+    kind: "trtc" | "livekit";
+    playback: IviSourcePlayback;
+    provisional: true;
+}
+interface IviCreateIVISessionResult {
+    iviSessionId: string;
+    endpoint: string;
+    tokenInfo?: unknown;
+    trtcInfo?: IviSourcePlaybackTrtc;
+    livekitInfo?: IviSourcePlaybackLivekit;
+    prebuildTrtcInfo?: {
+        trtcInfo?: IviSourcePlaybackTrtc;
+        livekitInfo?: IviSourcePlaybackLivekit;
+    };
+    prebuiltPlayback?: IviPrebuiltPlayback;
+    raw: unknown;
+    requestBody: Record<string, unknown>;
+}
+interface IviRuntimeWebSocketOptions {
+    url?: string;
+    protocols?: WebSocketTransportConfig["protocols"];
+    query?: Record<string, string | undefined | null>;
+    socketFactory?: WebSocketTransportConfig["socketFactory"];
+}
+interface IviRuntimeFromSessionOptions {
+    fastStart?: boolean;
+    bootstrapSlot?: string;
+    bootstrapTrackId?: string;
+    clientConfig?: Omit<IviClientConfig, "transport">;
+    runtimeConfig?: IviRuntimeCoordinatorConfig;
+    websocket?: IviRuntimeWebSocketOptions;
+    telemetry?: IviFrontendTelemetryOptions;
+}
+interface IviSessionRuntime {
+    session: IviCreateIVISessionResult;
+    client: IviClient;
+    runtime: IviRuntimeCoordinator;
+}
+interface IviCreateIVISessionRuntimeOptions extends IviRuntimeFromSessionOptions {
+    http: IviCreateIVISessionHttpOptions;
+}
+declare class IviCreateIVISessionError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: unknown;
+    constructor(response: Response, body: unknown);
+}
+declare function createIVISession(request: IviCreateIVISessionRequest, options: IviCreateIVISessionHttpOptions): Promise<IviCreateIVISessionResult>;
+declare function createRuntimeFromSession(session: IviCreateIVISessionResult, options?: IviRuntimeFromSessionOptions): IviSessionRuntime;
+declare function createIVISessionRuntime(request: IviCreateIVISessionRequest, options: IviCreateIVISessionRuntimeOptions): Promise<IviSessionRuntime>;
+declare function toCpCreateIVISessionRequestBody(request: IviCreateIVISessionRequest): Record<string, unknown>;
+declare function normalizeCreateIVISessionResponse(responseBody: unknown, request?: IviCreateIVISessionRequest, requestBody?: Record<string, unknown>): IviCreateIVISessionResult;
+
 type IviFrontendClientConfig = IviClientConfig;
+interface IviFrontendSdkConfig {
+    http?: IviCreateIVISessionHttpOptions;
+    telemetry?: IviFrontendTelemetryOptions;
+}
 declare class IviFrontendSdk {
+    private readonly config;
+    constructor(config?: IviFrontendSdkConfig);
     createClient(config: IviFrontendClientConfig): IviClient;
     createRuntimeCoordinator(clientConfig: IviFrontendClientConfig, runtimeConfig?: IviRuntimeCoordinatorConfig): IviRuntimeCoordinator;
+    createIVISession(request: IviCreateIVISessionRequest, options?: IviCreateIVISessionHttpOptions): Promise<IviCreateIVISessionResult>;
+    createRuntimeFromSession(session: IviCreateIVISessionResult, options?: IviRuntimeFromSessionOptions): IviSessionRuntime;
+    createIVISessionRuntime(request: IviCreateIVISessionRequest, options?: Partial<IviCreateIVISessionRuntimeOptions>): Promise<IviSessionRuntime>;
 }
 
 interface IviStageSlotBinding {
@@ -800,6 +964,24 @@ interface IviManagedRuntimeConfig {
 }
 declare function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRuntimeCoordinator | null;
 
+type IviSessionRuntimeHookStatus = "idle" | "creating" | "connecting" | "running" | "error" | "stopped";
+interface UseIviSessionRuntimeConfig extends IviCreateIVISessionRuntimeOptions {
+    request: IviCreateIVISessionRequest | null | undefined;
+    enabled?: boolean;
+    autoStart?: boolean;
+    onCreated?: (session: IviCreateIVISessionResult) => void;
+    onRuntimeReady?: (runtime: IviRuntimeCoordinator, client: IviClient) => void;
+    onError?: (error: unknown) => void;
+}
+interface UseIviSessionRuntimeResult {
+    status: IviSessionRuntimeHookStatus;
+    session: IviCreateIVISessionResult | null;
+    runtime: IviRuntimeCoordinator | null;
+    client: IviClient | null;
+    error: Error | null;
+}
+declare function useIviSessionRuntime(config: UseIviSessionRuntimeConfig): UseIviSessionRuntimeResult;
+
 declare function useIviStageView(): IviStageViewContextValue;
 
-export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
+export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, IviCreateIVISessionError, type IviCreateIVISessionHttpOptions, type IviCreateIVISessionPrebuiltCharacter, type IviCreateIVISessionPrebuiltStream, type IviCreateIVISessionRequest, type IviCreateIVISessionResult, type IviCreateIVISessionRuntimeOptions, type IviCreateSessionStreamType, type IviFrontendClientConfig, IviFrontendSdk, type IviFrontendSdkConfig, type IviFrontendTelemetryOptions, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviPrebuiltPlayback, type IviRuntimeBootstrapSource, type IviRuntimeBootstrapViewState, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeFromSessionOptions, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourceOrigin, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviRuntimeWebSocketOptions, type IviSessionRuntime, type IviSessionRuntimeHookStatus, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviTelemetrySpanHandle, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, type UseIviSessionRuntimeConfig, type UseIviSessionRuntimeResult, createIVISession, createIVISessionRuntime, createRuntimeFromSession, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, normalizeCreateIVISessionResponse, toCpCreateIVISessionRequestBody, useIviSessionRuntime, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };