realtime-avatar 0.3.0

package/dist/proxy-client-cZyX50-O.d.ts

@@ -0,0 +1,1508 @@
+import { TrackReferenceOrPlaceholder, useTranscriptions, useConnectionState, LiveKitRoomProps } from '@livekit/components-react';
+import { CSSProperties, ReactNode, ReactElement } from 'react';
+import { DisconnectReason, SendTextOptions } from 'livekit-client';
+import { z } from 'zod';
+
+/**
+ * Wire schemas for the public Realtime Avatar API.
+ *
+ * Code only, by policy: this file carries schemas and no narrative. Prose is where
+ * boundaries are hardest to hold, because a sentence explaining WHY a field exists tends
+ * to describe the thing on the other side of it.
+ *
+ * What may appear here is bounded by `public-surface.txt` and enforced by
+ * `npm run surface`: every export must be named on that allowlist, so a new one is
+ * refused until someone decides it is public. Documentation lives at
+ * https://realtimeavatar.ai/docs.
+ */
+
+declare const llmProviderSchema: z.ZodEnum<{
+    local: "local";
+    gemini: "gemini";
+    openai: "openai";
+}>;
+declare const llmSelectionSchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        local: "local";
+        gemini: "gemini";
+        openai: "openai";
+    }>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+declare const cartesiaTtsModelSchema: z.ZodEnum<{
+    "cartesia/sonic-2": "cartesia/sonic-2";
+    "cartesia/sonic-2-latest": "cartesia/sonic-2-latest";
+    "cartesia/sonic-3": "cartesia/sonic-3";
+    "cartesia/sonic-3-latest": "cartesia/sonic-3-latest";
+    "cartesia/sonic-turbo": "cartesia/sonic-turbo";
+    "cartesia/sonic-turbo-latest": "cartesia/sonic-turbo-latest";
+}>;
+declare const fishTtsModelSchema: z.ZodEnum<{
+    "speech-1.6": "speech-1.6";
+    s1: "s1";
+    "s2-pro": "s2-pro";
+    "speech-1.5": "speech-1.5";
+    "s1-mini": "s1-mini";
+}>;
+declare const voiceSpecSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    provider: z.ZodLiteral<"cartesia">;
+    model: z.ZodDefault<z.ZodEnum<{
+        "cartesia/sonic-2": "cartesia/sonic-2";
+        "cartesia/sonic-2-latest": "cartesia/sonic-2-latest";
+        "cartesia/sonic-3": "cartesia/sonic-3";
+        "cartesia/sonic-3-latest": "cartesia/sonic-3-latest";
+        "cartesia/sonic-turbo": "cartesia/sonic-turbo";
+        "cartesia/sonic-turbo-latest": "cartesia/sonic-turbo-latest";
+    }>>;
+    voice_id: z.ZodString;
+    speed: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    emotion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    provider: z.ZodLiteral<"breezeblue">;
+    model: z.ZodDefault<z.ZodString>;
+    voice_id: z.ZodString;
+    guidance_scale: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    instructions: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    provider: z.ZodLiteral<"fish">;
+    model: z.ZodDefault<z.ZodEnum<{
+        "speech-1.6": "speech-1.6";
+        s1: "s1";
+        "s2-pro": "s2-pro";
+        "speech-1.5": "speech-1.5";
+        "s1-mini": "s1-mini";
+    }>>;
+    voice_id: z.ZodString;
+    speed: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    emotion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>], "provider">;
+declare const sessionClipSchema: z.ZodObject<{
+    clip_id: z.ZodString;
+    source_video_url: z.ZodOptional<z.ZodString>;
+    video_cache_id: z.ZodOptional<z.ZodString>;
+    max_seconds: z.ZodOptional<z.ZodNumber>;
+    trigger: z.ZodOptional<z.ZodEnum<{
+        idle: "idle";
+        listen: "listen";
+        think: "think";
+        directive: "directive";
+    }>>;
+    loop: z.ZodOptional<z.ZodBoolean>;
+    weight: z.ZodOptional<z.ZodNumber>;
+    crossfade_ms: z.ZodOptional<z.ZodNumber>;
+    trim_start_ms: z.ZodOptional<z.ZodNumber>;
+    trim_end_ms: z.ZodOptional<z.ZodNumber>;
+    when: z.ZodOptional<z.ZodString>;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type SessionClip = z.infer<typeof sessionClipSchema>;
+declare const sessionBehaviorSchema: z.ZodObject<{
+    gestures_enabled: z.ZodOptional<z.ZodBoolean>;
+    gesture_freq: z.ZodOptional<z.ZodEnum<{
+        sparse: "sparse";
+        balanced: "balanced";
+        lively: "lively";
+    }>>;
+}, z.core.$strict>;
+type SessionBehavior = z.infer<typeof sessionBehaviorSchema>;
+/**
+ * The cap the mint enforces on `instructions`. Exported so an app can budget its prompt
+ * assembly against the real number instead of probing for it with a binary search.
+ */
+declare const MAX_SESSION_INSTRUCTIONS_CHARS = 4000;
+declare const liveKitSessionRequestSchema: z.ZodObject<{
+    avatarId: z.ZodString;
+    backgroundId: z.ZodDefault<z.ZodString>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        avatar: "avatar";
+        voice: "voice";
+    }>>;
+    createRoom: z.ZodDefault<z.ZodBoolean>;
+    dispatchAgent: z.ZodDefault<z.ZodBoolean>;
+    instructions: z.ZodOptional<z.ZodString>;
+    initialContext: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+        }>;
+        content: z.ZodString;
+    }, z.core.$strict>>>;
+    initialSay: z.ZodOptional<z.ZodString>;
+    llm: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        provider: z.ZodEnum<{
+            local: "local";
+            gemini: "gemini";
+            openai: "openai";
+        }>;
+        model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+    maxSessionSeconds: z.ZodOptional<z.ZodNumber>;
+    participantIdentity: z.ZodOptional<z.ZodString>;
+    participantName: z.ZodOptional<z.ZodString>;
+    queueTicketId: z.ZodOptional<z.ZodString>;
+    roomName: z.ZodOptional<z.ZodString>;
+    sttMode: z.ZodDefault<z.ZodEnum<{
+        server: "server";
+        off: "off";
+    }>>;
+    voice: z.ZodOptional<z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        provider: z.ZodLiteral<"cartesia">;
+        model: z.ZodDefault<z.ZodEnum<{
+            "cartesia/sonic-2": "cartesia/sonic-2";
+            "cartesia/sonic-2-latest": "cartesia/sonic-2-latest";
+            "cartesia/sonic-3": "cartesia/sonic-3";
+            "cartesia/sonic-3-latest": "cartesia/sonic-3-latest";
+            "cartesia/sonic-turbo": "cartesia/sonic-turbo";
+            "cartesia/sonic-turbo-latest": "cartesia/sonic-turbo-latest";
+        }>>;
+        voice_id: z.ZodString;
+        speed: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        emotion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        provider: z.ZodLiteral<"breezeblue">;
+        model: z.ZodDefault<z.ZodString>;
+        voice_id: z.ZodString;
+        guidance_scale: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        instructions: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        provider: z.ZodLiteral<"fish">;
+        model: z.ZodDefault<z.ZodEnum<{
+            "speech-1.6": "speech-1.6";
+            s1: "s1";
+            "s2-pro": "s2-pro";
+            "speech-1.5": "speech-1.5";
+            "s1-mini": "s1-mini";
+        }>>;
+        voice_id: z.ZodString;
+        speed: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        emotion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>], "provider">>>;
+    voiceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    clipLibrary: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        clip_id: z.ZodString;
+        source_video_url: z.ZodOptional<z.ZodString>;
+        video_cache_id: z.ZodOptional<z.ZodString>;
+        max_seconds: z.ZodOptional<z.ZodNumber>;
+        trigger: z.ZodOptional<z.ZodEnum<{
+            idle: "idle";
+            listen: "listen";
+            think: "think";
+            directive: "directive";
+        }>>;
+        loop: z.ZodOptional<z.ZodBoolean>;
+        weight: z.ZodOptional<z.ZodNumber>;
+        crossfade_ms: z.ZodOptional<z.ZodNumber>;
+        trim_start_ms: z.ZodOptional<z.ZodNumber>;
+        trim_end_ms: z.ZodOptional<z.ZodNumber>;
+        when: z.ZodOptional<z.ZodString>;
+        hint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    sceneGraph: z.ZodOptional<z.ZodObject<{
+        scenes: z.ZodArray<z.ZodObject<{
+            scene_id: z.ZodString;
+            hub_clip_id: z.ZodString;
+            clips: z.ZodArray<z.ZodObject<{
+                clip_id: z.ZodString;
+                source_video_url: z.ZodOptional<z.ZodString>;
+                video_cache_id: z.ZodOptional<z.ZodString>;
+                max_seconds: z.ZodOptional<z.ZodNumber>;
+                trigger: z.ZodOptional<z.ZodEnum<{
+                    idle: "idle";
+                    listen: "listen";
+                    think: "think";
+                    directive: "directive";
+                }>>;
+                loop: z.ZodOptional<z.ZodBoolean>;
+                weight: z.ZodOptional<z.ZodNumber>;
+                crossfade_ms: z.ZodOptional<z.ZodNumber>;
+                trim_start_ms: z.ZodOptional<z.ZodNumber>;
+                trim_end_ms: z.ZodOptional<z.ZodNumber>;
+                when: z.ZodOptional<z.ZodString>;
+                hint: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        transitions: z.ZodArray<z.ZodObject<{
+            clip_id: z.ZodString;
+            source_video_url: z.ZodString;
+            from_scene: z.ZodString;
+            to_scene: z.ZodString;
+            max_seconds: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    behavior: z.ZodOptional<z.ZodObject<{
+        gestures_enabled: z.ZodOptional<z.ZodBoolean>;
+        gesture_freq: z.ZodOptional<z.ZodEnum<{
+            sparse: "sparse";
+            balanced: "balanced";
+            lively: "lively";
+        }>>;
+    }, z.core.$strict>>;
+    renderBackend: z.ZodOptional<z.ZodString>;
+    supportEdits: z.ZodOptional<z.ZodObject<{
+        instruction: z.ZodString;
+        reference_url: z.ZodOptional<z.ZodString>;
+        live_edit: z.ZodOptional<z.ZodObject<{
+            rules: z.ZodString;
+            cooldown_seconds: z.ZodOptional<z.ZodNumber>;
+            renderer: z.ZodOptional<z.ZodEnum<{
+                generative: "generative";
+                editor: "editor";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    transcriptWebhook: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        secret: z.ZodString;
+    }, z.core.$strict>>;
+    clientMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+declare const liveKitSessionGrantSchema: z.ZodObject<{
+    status: z.ZodDefault<z.ZodLiteral<"ready">>;
+    session_id: z.ZodString;
+    room_name: z.ZodString;
+    livekit_url: z.ZodString;
+    participant_token: z.ZodString;
+    participant_identity: z.ZodString;
+    reservation_expires_at: z.ZodString;
+    stt_mode: z.ZodDefault<z.ZodEnum<{
+        server: "server";
+        off: "off";
+    }>>;
+    room_created: z.ZodDefault<z.ZodBoolean>;
+    dispatch_created: z.ZodDefault<z.ZodBoolean>;
+    join_timeout_seconds: z.ZodDefault<z.ZodNumber>;
+    idle_timeout_seconds: z.ZodDefault<z.ZodNumber>;
+    max_session_seconds: z.ZodDefault<z.ZodNumber>;
+}, z.core.$loose>;
+declare const sessionEndReasonSchema: z.ZodEnum<{
+    idle: "idle";
+    disconnected: "disconnected";
+    failed: "failed";
+    user_ended: "user_ended";
+    session_cap: "session_cap";
+    out_of_credits: "out_of_credits";
+    agent_ended: "agent_ended";
+}>;
+type SessionEndReasonLabel = z.infer<typeof sessionEndReasonSchema>;
+declare const approachingEndReasonSchema: z.ZodEnum<{
+    idle: "idle";
+    session_cap: "session_cap";
+}>;
+type ApproachingEndReason = z.infer<typeof approachingEndReasonSchema>;
+declare const knownBehaviorStates: readonly ["idle", "listening", "thinking", "speaking"];
+type KnownBehaviorState = (typeof knownBehaviorStates)[number];
+declare const capacityBusyResponseSchema: z.ZodObject<{
+    message: z.ZodString;
+    capacity: z.ZodObject<{
+        capacity_pool: z.ZodOptional<z.ZodString>;
+        agent_name: z.ZodOptional<z.ZodString>;
+        max_sessions: z.ZodNumber;
+        max_sessions_per_gpu: z.ZodOptional<z.ZodNumber>;
+        worker_count: z.ZodNumber;
+        active_sessions: z.ZodNumber;
+        reserved_sessions: z.ZodNumber;
+        observed_worker_active_sessions: z.ZodNumber;
+        available_sessions: z.ZodNumber;
+        queue_size: z.ZodNumber;
+        admission_open: z.ZodBoolean;
+        recommended_retry_ms: z.ZodNumber;
+        load: z.ZodNumber;
+    }, z.core.$loose>;
+    queue_size: z.ZodNumber;
+    queue_ticket_id: z.ZodOptional<z.ZodString>;
+    queue_position: z.ZodOptional<z.ZodNumber>;
+    recommended_retry_ms: z.ZodNumber;
+}, z.core.$strict>;
+declare const liveKitSessionReleaseReasonSchema: z.ZodEnum<{
+    page_hide: "page_hide";
+    disconnected: "disconnected";
+    superseded: "superseded";
+    unmount: "unmount";
+    manual: "manual";
+    idle_timeout: "idle_timeout";
+}>;
+type LLMProvider = z.infer<typeof llmProviderSchema>;
+type LLMSelection = z.infer<typeof llmSelectionSchema>;
+type LLMSelectionForProvider<TProvider extends LLMProvider = LLMProvider> = TProvider extends LLMProvider ? Omit<LLMSelection, "provider"> & {
+    provider: TProvider;
+} : never;
+type CartesiaTtsModel = z.infer<typeof cartesiaTtsModelSchema>;
+type FishTtsModel = z.infer<typeof fishTtsModelSchema>;
+type VoiceSpec = z.infer<typeof voiceSpecSchema>;
+type VoiceSpecInput = z.input<typeof voiceSpecSchema>;
+type LiveKitSessionRequestInput = z.input<typeof liveKitSessionRequestSchema>;
+type LiveKitSessionGrant = z.infer<typeof liveKitSessionGrantSchema>;
+type CapacityBusyResponse = z.infer<typeof capacityBusyResponseSchema>;
+type LiveKitSessionReleaseReason = z.infer<typeof liveKitSessionReleaseReasonSchema>;
+
+type LiveKitSessionRequest<TLlmProvider extends LLMProvider = LLMProvider> = Omit<LiveKitSessionRequestInput, "llm" | "voice"> & {
+    llm?: LLMSelectionForProvider<TLlmProvider> | null;
+    voice?: VoiceSpecInput | null;
+};
+
+/** The subscriber-cap levels we drive (map to LiveKit VideoQuality LOW/HIGH). */
+type QualityCap = "low" | "high";
+/** The governor's finite states (the video-quality design doc). */
+type GovernorState = "opening" | "opening_high" | "cap_low_sticky" | "cap_low_eligible" | "probing_up" | "cap_high_stable";
+/**
+ * One normalized input the hook feeds each tick. The hook translates ALL of
+ * {TrackStreamStateChanged, ConnectionQualityChanged, getStats, rVFC freeze} into
+ * this shape, so the core never sees a vendor type.
+ */
+interface GovernorSignal {
+    /** SFU congestion controller paused the track since the last tick — Tier-0, the
+     *  single most trustworthy downgrade trigger (server already confirmed congestion). */
+    paused: boolean;
+    /** Frozen milliseconds observed in the trailing freeze window W (max of inbound-rtp
+     *  delta and the rVFC-derived gap — Safari coverage). */
+    freezeMsInWindow: number;
+    /** jitterBufferDelay is trending up — the earliest LEADING pre-freeze sign. */
+    jitterRising: boolean;
+    /** LiveKit ConnectionQuality — a LAGGING corroborator only (jitter/RTT are disabled
+     *  in its score + known false-Poor bugs). Blocks up-probes; never a sole trigger. */
+    connectionQuality: "excellent" | "good" | "poor" | "lost" | "unknown";
+    /** The tab is hidden / track muted / freezes correlate with local CPU not network —
+     *  the false-positive fence (our own Dia-freeze lesson). When true the machine is
+     *  frozen: no signal is trusted, no transition fires. */
+    inhibited: boolean;
+}
+/** The side effect the hook must apply after a step (absent = leave the cap alone). */
+interface GovernorAction {
+    setCap: QualityCap;
+}
+interface GovernorConfig {
+    /** Where the cap OPENS. "low" (default): the shipped posture — first impression is
+     *  never a freeze, at the cost of a visible soft start (openingDwellMs + cleanMs
+     *  before the first up-probe, plus the LOW→HIGH rung switch's decoder-reconfigure
+     *  keyframe pop). "high": first impression is never a RAMP — the session opens at
+     *  the top rung already under the STRICT probation bar (probationFreezeMs, paused
+     *  = instant), so a link that cannot afford it is demoted within one tick of
+     *  evidence and then follows the normal ladder with a failure on record. Pick
+     *  "high" for surfaces where the opening softness reads as a defect (the canary
+     *  demo comparison, 2026-08-13) and the link population skews capable. */
+    openingCap: QualityCap;
+    /** Frozen-ms in window W that forces an immediate downgrade from a stable cap. */
+    downgradeFreezeMs: number;
+    /** Stricter frozen-ms bar DURING probation — kill a bad upgrade fast. */
+    probationFreezeMs: number;
+    /** Hold at low at SESSION START before an up-probe is considered. Separate from
+     *  dwellBaseMs because the opening carries no failure evidence — the 8s recovery
+     *  dwell was being served to every fresh call, and prod measurement
+     *  (call_connect_profile, 2026-08-05) showed the cost: median 14s at the small
+     *  rung before first upgrade, 56% of 30s windows never upgrading at all. Opening
+     *  low is kept (first impression is never a freeze); paying the POST-FAILURE
+     *  penalty before any failure is not. */
+    openingDwellMs: number;
+    /** Base minimum hold at low before an up-probe is considered (grows on failure). */
+    dwellBaseMs: number;
+    /** Cap on the exponential dwell backoff — never pin low permanently. */
+    dwellMaxMs: number;
+    /** Continuously-healthy window required before raising the cap. 3s: still well above
+     *  the sub-second downgrade reaction (the asymmetry that prevents flap), but short
+     *  enough that a clean link reaches the probe at ~5s from session start
+     *  (openingDwellMs + cleanMs) instead of 13s under the old 8s+5s posture. */
+    cleanMs: number;
+    /** Probation length after raising the cap before committing to high. */
+    probeMs: number;
+    /** Sustained-healthy-at-low duration that resets the failure count (link improved). */
+    healthyResetMs: number;
+}
+/** The grounded defaults (Meet <10s recovery + GCC +5%/−15% step asymmetry). */
+declare const DEFAULT_GOVERNOR_CONFIG: GovernorConfig;
+/** The full reducer state (immutable; `step` returns a new object on change). */
+interface Governor {
+    state: GovernorState;
+    cap: QualityCap;
+    /** Consecutive failed up-probes — drives the exponential dwell backoff. */
+    failures: number;
+    /** Wall-clock ms the current state was entered (for dwell/clean/probe timing). */
+    enteredAtMs: number;
+    /** Wall-clock ms of the last healthy tick in the current low period (clean-window
+     *  accumulation); null until the first healthy tick after entering low. */
+    healthySinceMs: number | null;
+}
+
+/** How the media is fit into the surface box. Mirrors CSS `object-fit`. */
+type AvatarVideoFit = "contain" | "cover";
+type AvatarVideoSurfaceProps = {
+    /**
+     * The avatar's idle/ambient clip, natively looped, layered OVER the
+     * {@link poster} floor. When a realtime turn is not producing media — including
+     * after a session disconnect — the surface rests on this clip. Pass `null` for
+     * avatars with no idle clip; the poster floor then shows at rest.
+     */
+    idleVideoUrl: string | null;
+    /**
+     * The avatar's PORTRAIT (its face) — the DEEPEST floor, rendered behind the idle
+     * clip and the live video whenever provided. It paints IMMEDIATELY on connect
+     * (an `<img>` decodes before a `<video>` reaches its first frame) and is the
+     * guaranteed no-frames backdrop, so the surface is NEVER a black box while
+     * connecting / listening / idle / between turns. With an idle clip it sits behind
+     * it; with none it is the resting floor. Pass `null` to fall through to the
+     * caller's own branded floor. Rendered with the same fit/box as the video layers
+     * so swaps are in place.
+     */
+    poster?: string | null;
+    /**
+     * The caller's INTENT to show the live stream — typically "the avatar is
+     * actively producing media this turn". The surface still gates this on the
+     * LiveKit connection state and a subscribed, PRODUCING video track, so a stale
+     * `true` after a drop can never reveal a frozen/black live layer: it falls back
+     * to the idle clip in the SAME box. Defaults to `true` (show live whenever a
+     * connected, producing track exists).
+     */
+    live?: boolean;
+    /**
+     * Enable the subscriber-side fast-down/sticky-up quality governor. It starts on
+     * the lower simulcast rung, reacts immediately to an SFU pause or decoded-frame
+     * freeze, and only probes the full layer after a clean dwell. Default true.
+     */
+    adaptiveQuality?: boolean;
+    /**
+     * Opening bet for the governor when `adaptiveQuality` is on. `"high"` opens on the
+     * FULL simulcast layer under probation — sharp from frame 1, no LOW→HIGH layer-walk —
+     * and instant-demotes a cold link within one tick; `"low"` is the reactive soft-open.
+     * Unset ⇒ the fleet default (`DEFAULT_GOVERNOR_CONFIG.openingCap`, currently `"low"`).
+     * `<AvatarCall>` sets this to `"high"` only for rtx6000-pool sessions (see
+     * opening-cap-policy.ts); everything else keeps the soft-open.
+     */
+    openingCap?: QualityCap;
+    /** `object-fit` for BOTH layers. Both layers always use the SAME fit + box so
+     *  the front (live) fully covers the back (idle) — no peek-through. */
+    fit?: AvatarVideoFit;
+    /**
+     * @deprecated No-op. The surface FILLS its container (`size-full`); the CONSUMER
+     * owns the aspect box. Self-pinning a native ratio INSIDE the surface could not
+     * survive an indefinite-height ancestor (it collapsed to zero height — the
+     * black-screen bug), so aspect ownership moved out to the caller: wrap the
+     * surface in a box with a definite size (e.g. `aspect-[9/16]` + a height seed).
+     * Accepted for source compatibility; ignored.
+     */
+    pinNativeAspect?: boolean;
+    /** CSS `aspect-ratio` placeholder for the box (a size-jump guard on first paint).
+     *  Applied to the fill box when set; the caller's own aspect box still wins. */
+    aspectRatio?: string;
+    /**
+     * @deprecated Retained for source compatibility; the idle↔live handover is a SWAP,
+     * not a blend. Both layers show the same body from independent clocks, so any
+     * overlap is a double exposure rather than a softening (measured: 31.8% of the
+     * picture differs at the median cursor pair). The layers are made to agree at the
+     * ANCHOR instead, where a swap is invisible — which is also the falsifiable test:
+     * 0 and 500 must look identical. Accepted; ignored.
+     */
+    crossfadeMs?: number;
+    /**
+     * Debounce (ms) before dropping BACK to the idle clip once the live layer stops
+     * being shown (turn end), so back-to-back turns don't flash the idle clip for a
+     * frame between them. Default 700. A disconnect bypasses this and reverts to idle
+     * immediately (a dead room is never held). Showing the live layer is always
+     * immediate — only the hide is debounced.
+     */
+    idleReturnDelayMs?: number;
+    /**
+     * Maximum time without a newly presented decoded frame before the live layer is
+     * treated as stalled and immediately replaced by the idle/poster floor. Default 800ms.
+     */
+    frameStallMs?: number;
+    /** Extra className for the box (the layers fill it). */
+    className?: string;
+    /** Extra inline style for the box. */
+    style?: CSSProperties;
+    /** Overlay content rendered above both media layers (badges, chrome, scrims). */
+    children?: ReactNode;
+    /** Surface a small "live · WxH" badge when the live layer is shown. Default true. */
+    showLiveBadge?: boolean;
+    /** Test id for the box. */
+    "data-testid"?: string;
+};
+/**
+ * The avatar video surface: a single box that FILLS its container and renders the
+ * looping idle clip and the realtime LiveKit video as two PIXEL-ALIGNED layers,
+ * with an anchor-aligned SWAP between them and an automatic fall-back to the idle
+ * clip whenever the realtime session is not connected or producing (max-duration
+ * end, network drop, agent gone, turn-end mute).
+ *
+ * ONE BODY, ONE POSE. Only one media layer ever runs: the idle clip is paused while
+ * the live layer covers it, and re-enters at its anchor (frame 0) when it takes over.
+ * That is what lets the handover be a swap with no blending — see the front-layer and
+ * `useIdleWhileResting` notes for the measurements behind it.
+ *
+ * This is the SSOT for "is the avatar live right now": it reads the LiveKit
+ * connection state ({@link useConnectionState}) and the bound avatar track
+ * ({@link useVoiceAssistant}) directly, so a caller's stale `live` intent can
+ * never leave a frozen/black frame on screen — the surface always reverts to the
+ * idle loop in the SAME box. Must be rendered inside a LiveKit `RoomContext`
+ * (e.g. under `RealtimeAvatarLiveKitRoom`).
+ *
+ * LAYOUT CONTRACT: the surface FILLS its container (`size-full`) — it does NOT pin
+ * its own aspect. The CONSUMER owns the aspect box: wrap the surface in an element
+ * with a DEFINITE size (e.g. `aspect-[9/16]` plus a height seed). Self-pinning a
+ * native ratio inside the surface (`h-full w-auto`) collapsed to zero height
+ * against an indefinite-height (flex) ancestor — the black-screen bug — so that
+ * ownership moved out. Both media layers are `absolute inset-0` over the filled box
+ * and share the SAME `object-fit`, so the front layer fully covers the back with no
+ * sliver.
+ */
+declare function AvatarVideoSurface(props: AvatarVideoSurfaceProps): ReactElement;
+/** Which back (non-live) layers the surface renders, deepest first. */
+type SurfaceLayers = {
+    /** Render the poster `<img>` — the deepest floor, the always-present face. */
+    showPoster: boolean;
+    /** Render the idle clip `<video>`, layered OVER the poster. */
+    showIdleVideo: boolean;
+};
+/**
+ * The COARSE producing gate the React Native (Android) surface twin passes to
+ * {@link useLiveTrackProducing} in place of {@link isLiveTrackProducing}.
+ *
+ * On Android #446 mounts the live `<VideoTrack>` (a below-window SurfaceView) ONLY
+ * while it's producing, so this predicate is the upstream switch that decides
+ * whether the video shows at all — and the strict {@link isLiveTrackProducing}
+ * reads it false there. react-native-webrtc's REMOTE `MediaStreamTrack` does not
+ * drive the browser-shaped micro-signals that predicate depends on: `enabled` is a
+ * LOCAL playback toggle (not frame flow), and a remote track's `muted` can read
+ * `true` for an entire producing turn (or never emit `unmute`). So on a real
+ * Android device the strict test returned false while frames flowed and the avatar
+ * froze on its poster ("voice only / static image").
+ *
+ * We therefore gate on the one fact react-native-webrtc reports reliably: a
+ * subscribed remote track whose underlying `MediaStreamTrack` has not ENDED. The
+ * trade-off is that a turn-end no longer crossfades back to the idle clip on
+ * Android (the live layer stays up between turns) — an acceptable price for the
+ * video actually appearing. The room's connection state still unmounts the layer on
+ * disconnect, and the track's `ended` event (wired in {@link useLiveTrackProducing})
+ * still tears it down. iOS keeps {@link isLiveTrackProducing}: its in-tree UIView
+ * and DOM-shaped track behave like the web, where the strict signal works today.
+ *
+ * Pure + DOM-free (reads only `mediaStreamTrack.readyState`), so it lives here with
+ * its web twin and is unit-tested in the shared suite rather than the RN module.
+ */
+declare function isNativeLiveTrackSubscribed(videoTrack: TrackReferenceOrPlaceholder | undefined): boolean;
+/**
+ * Reactive {@link isLiveTrackProducing}: returns whether the avatar's live video
+ * is producing frames, and re-renders the surface when that changes.
+ *
+ * `useVoiceAssistant` re-renders when the track APPEARS/DISAPPEARS, but NOT when a
+ * present track merely mutes — so a plain read in render would be stale and leave
+ * the frozen last frame up after a turn ends. We subscribe to the publication's
+ * own lifecycle events — the SDK's `TrackEvent.Muted`/`Unmuted` (turn end/start)
+ * and `Ended` (track torn down) — PLUS the underlying MediaStreamTrack's
+ * mute/unmute/ended (which fire even when the publication's mute flag is stale),
+ * and recompute on each, so a turn-end crossfades back to the idle loop
+ * immediately. Unconditional (safe with no track) and re-subscribes whenever the
+ * underlying publication/track changes.
+ *
+ * Exported (not just the pure {@link isLiveTrackProducing}) because it is
+ * DOM-free — publication events + MediaStreamTrack events exist on React Native's
+ * WebRTC shim too — so the react-native surface twin reuses THIS hook (the event
+ * wiring never drifts between platforms) but may pass its OWN `isProducing`
+ * predicate: react-native-webrtc's remote track does not drive the browser-shaped
+ * `enabled`/`muted` flags {@link isLiveTrackProducing} reads, so Android supplies a
+ * coarser subscribed-and-not-ended test (see the RN surface twin). Defaults to
+ * {@link isLiveTrackProducing} so every web caller is unchanged.
+ */
+declare function useLiveTrackProducing(videoTrack: TrackReferenceOrPlaceholder | undefined, isProducing?: (videoTrack: TrackReferenceOrPlaceholder | undefined) => boolean): boolean;
+/** A `<video>` narrowed to the members the live-playback keeper touches. */
+type PlayableVideoElement = {
+    paused: boolean;
+    play: () => Promise<void> | void;
+    addEventListener: (type: string, listener: () => void) => void;
+    removeEventListener: (type: string, listener: () => void) => void;
+};
+/** Controls a live `<video>`'s continuous playback across turns (the freeze fix). */
+type LivePlaybackKeeper = {
+    /** Bind (or rebind) the element to keep playing; pass `null` on detach. */
+    bind: (video: PlayableVideoElement | null) => void;
+    /** Re-check playback after a tab/page resume. */
+    resume: () => void;
+    /** Stop keeping the element alive and drop its listeners. */
+    dispose: () => void;
+};
+
+declare class RealtimeAvatarCapacityError extends Error {
+    readonly busy: CapacityBusyResponse;
+    constructor(message: string, busy: CapacityBusyResponse);
+    get queueSize(): number;
+    get queuePosition(): number | undefined;
+    get queueTicketId(): string | undefined;
+    get recommendedRetryMs(): number;
+}
+
+/**
+ * What the React bindings actually need from a client: mint a call, and give the slot back.
+ *
+ * They used to demand `RealtimeAvatarClient` itself, and that is why `AvatarCall` could not be
+ * used at all. The component is exported at runtime from `realtime-avatar/react` and required
+ * `client: RealtimeAvatarClient` — but that package exports no client constructor, because the
+ * class carries an API-key path and keeping it out of the browser is what took `apiKey`/`Bearer`
+ * to zero occurrences in the shipped bundles. So the prop named a type no consumer could produce.
+ *
+ * The fix is nominal, not structural: the bindings depend on this INTERFACE instead of on that
+ * class. Anything with these five methods satisfies it — a fake in a test, or a thin fetch wrapper
+ * over an app's own proxy routes, which is what an integrator writes anyway.
+ *
+ * The carried class itself is GONE as of 2026-08-26. Once nothing named it, a module-graph walk
+ * (`npm run reachable`) showed it and six files with it were reachable from nothing at all: 1,230
+ * lines of a second HTTP client, a second error path and a second key parser, shipping nowhere.
+ * So this interface is now the only client contract in the repo, which is the point.
+ *
+ * The LLM-provider generic is KEPT. It pairs the client with `session: LiveKitSessionRequest<T>`,
+ * so a client built for one provider set still cannot be handed a session requesting another —
+ * that check was never what made the prop unusable, and giving it up would have bought nothing.
+ */
+
+/** Per-request escape hatches. Lives here, not on the client, so the React half never imports it from there. */
+type RealtimeAvatarRequestOptions = {
+    signal?: AbortSignal;
+    headers?: HeadersInit;
+};
+/**
+ * Capacity exhaustion is a VALUE here, not a throw — `queued` is not an error, and modelling it
+ * as one is the most common bad first impression an integration makes.
+ */
+type LiveKitSessionStartResult = {
+    status: "ready";
+    grant: LiveKitSessionGrant;
+} | {
+    status: "busy";
+    busy: CapacityBusyResponse;
+};
+interface AvatarSessionClient<TLlmProvider extends LLMProvider = LLMProvider> {
+    /** Mint a call, or report that every slot is busy. Never throws for capacity. */
+    createLiveKitSessionOrBusy(input: LiveKitSessionRequest<TLlmProvider>, options?: RealtimeAvatarRequestOptions): Promise<LiveKitSessionStartResult>;
+    /**
+     * Free a started call's slot. Returns `false` rather than throwing — a release that is lost
+     * is a slower release, never a broken page, because the join timeout is the backstop.
+     */
+    releaseLiveKitSession(sessionId: string, reason?: LiveKitSessionReleaseReason, options?: RealtimeAvatarRequestOptions): Promise<boolean>;
+    /**
+     * The `pagehide` path. `sendBeacon` is the one send that outlives a closing page, and it is
+     * synchronous-or-nothing — hence a `boolean` return and no promise, so the caller can fall
+     * back to {@link releaseLiveKitSession} when the browser has no beacon.
+     */
+    releaseLiveKitSessionBeacon(sessionId: string, reason?: LiveKitSessionReleaseReason): boolean;
+    /**
+     * A queued call holds no session id yet, so {@link releaseLiveKitSession} cannot free it.
+     * This is the queue's own release.
+     */
+    releaseLiveKitQueueTicket(queueTicketId: string, reason?: LiveKitSessionReleaseReason, options?: RealtimeAvatarRequestOptions): Promise<boolean>;
+    releaseLiveKitQueueTicketBeacon(queueTicketId: string, reason?: LiveKitSessionReleaseReason): boolean;
+}
+
+/**
+ * One room transcription entry as surfaced by {@link useTranscriptions} — a LiveKit `TextStreamData`
+ * carrying the spoken `text` plus `participantInfo.identity` (WHO spoke) and `streamInfo`.
+ */
+type CallTranscriptSegment = ReturnType<typeof useTranscriptions>[number];
+/**
+ * A live call's transcript, split by who spoke — so BOTH sides are first-class, not just the agent's.
+ * See {@link useCallTranscript}.
+ */
+type CallTranscript = {
+    /**
+     * The USER's spoken lines (their server-STT). Already on the wire — the worker's room input path
+     * publishes user input transcriptions to the room, attributed to the user participant — but
+     * previously only reachable by hand-filtering {@link useTranscriptions}. Empty until the user speaks.
+     */
+    user: CallTranscriptSegment[];
+    /** The AGENT/character's spoken lines (every room transcription that isn't the local user's). */
+    agent: CallTranscriptSegment[];
+};
+/**
+ * Split room transcription entries into the user's vs the agent's, by participant identity.
+ *
+ * In an avatar call the browser user is the LOCAL participant and the character is a remote (agent)
+ * participant, so a segment authored by the local identity is the user's and everything else is the
+ * agent's. Splitting on the identity carried by each `TextStreamData` is exact (no id-scheme or
+ * ordering heuristic). When the local identity isn't known yet (pre-connect) nothing is attributed to
+ * the user — safer than a false positive. Pure + exported so it's unit-testable without a live room.
+ */
+declare function splitCallTranscript(all: CallTranscriptSegment[], localIdentity: string | null | undefined): CallTranscript;
+/**
+ * The live call transcript, split into the user's and the agent's spoken lines.
+ *
+ * The user's side was always published to the room by the worker, but only the agent's was
+ * conveniently exposed (via {@link useVoiceAssistant}); this surfaces BOTH so adopters can build a
+ * two-sided call recap / caption history. Both arrays are empty before anyone speaks. Must be called
+ * inside a LiveKit room context (e.g. under {@link RealtimeAvatarLiveKitRoom}).
+ */
+declare function useCallTranscript(): CallTranscript;
+/**
+ * In-room companion to {@link useMicLease}: fires the lease's PRECISE release the
+ * moment this call's local microphone MediaStreamTrack actually reaches `ended`
+ * (the true hardware-release signal) — not merely on React unmount. Pass the
+ * `token` returned by `useMicLease`.
+ *
+ * Why it exists: `Room.disconnect()` stops the local track on a NON-awaited path
+ * (livekit-client 2.19.2), so after a call's React teardown the browser keeps the
+ * capture device for a beat. Handing the tab-global mic lease to the next call at
+ * unmount can therefore let a rapid redial's getUserMedia collide with the still-
+ * closing device. This hook holds the lease across that gap and releases it on the
+ * track's own `ended` event; `useMicLease` carries a timeout backstop so a track
+ * that never emits `ended` can't wedge the lease. MUST be rendered inside the room
+ * (needs `useLocalParticipant`), e.g. under {@link RealtimeAvatarLiveKitRoom}.
+ */
+declare function useReleaseMicLeaseOnTrackEnded(token: symbol): void;
+/**
+ * Receiver-side playout delay (SECONDS) for the avatar media tracks.
+ *
+ * The avatar is published from a GPU datacenter and reaches viewers over the
+ * public internet, where a few percent of packet loss is normal. A shallow
+ * receiver buffer stalls (freezes) on every loss while it waits for a
+ * retransmit; a deeper buffer recovers the lost packets BEFORE playout, so the
+ * viewer sees smooth 25fps instead of freezing. Measured at ~5% loss this took
+ * the stream from ~11fps with multi-second freezes to a steady 25fps with zero
+ * freezes.
+ *
+ * 0.5s is applied via the native {@link RemoteTrack.setPlayoutDelay}, which sets
+ * the receiver's `playoutDelayHint` — the same Chromium jitter-buffer knob the
+ * old hand-rolled `jitterBufferTarget` reached into (the spec renamed
+ * playoutDelayHint→jitterBufferTarget; both influence the same buffer depth),
+ * but typed and SDK-owned so there is no cast or feature-probe. The hint is NOT
+ * free at the open: the receiver holds the FIRST video frame toward the target
+ * (~250-450ms of measured TTFF), a deliberate cost paid once for the freeze-free
+ * steady state above. The open-small-then-ramp variant that tried to dodge that
+ * cost was shipped, failed twice (the rVFC ramp trigger is throttled on the
+ * opacity:0-mounted element, stranding the shallow buffer), and was deliberately
+ * removed in 2262e4c7b — do not re-propose it. No-op on browsers that don't
+ * support the hint (the SDK warns and moves on).
+ */
+declare const DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS = 0.5;
+/**
+ * Sets the avatar AUDIO and VIDEO tracks' native playout delay so the stream has
+ * a real de-jitter / loss-recovery cushion for smooth, freeze-free playback.
+ *
+ * Both tracks are kept at the SAME delay so the two streams stay lip-synced
+ * (WebRTC syncs the pair to the LARGER of the two receivers' hints; an unequal
+ * video-only buffer would make the lips lag the audio). Pass the `videoTrack`
+ * and `audioTrack` from {@link useVoiceAssistant}. A `RemoteTrack` is required —
+ * placeholders/local tracks lack `setPlayoutDelay` and are skipped.
+ */
+declare function useAvatarPlayoutDelay(videoTrack: TrackReferenceOrPlaceholder | undefined, audioTrack: TrackReferenceOrPlaceholder | undefined, delaySeconds?: number): void;
+type LiveKitAvatarGrantStatus = "idle" | "requesting" | "ready" | "busy" | "failed";
+type LiveKitConnectionStatus = ReturnType<typeof useConnectionState>;
+/**
+ * A clean, adopter-facing discriminated capacity signal derived from the raw
+ * grant {@link LiveKitAvatarGrantStatus}. The point is that a transient capacity
+ * wait ("all GPU slots busy, queued behind N others, auto-retrying") is NOT an
+ * error — it is a normal, self-healing waiting state. Only a genuinely failed
+ * grant maps to `error`. Adopters should render `queued`/`connecting` calmly
+ * (spinner + queue position) and reserve error UI for the `error` variant.
+ *
+ * - `idle`      — no active session requested.
+ * - `connecting`— a grant fetch is in flight (no prior queue placement).
+ * - `queued`    — all slots are busy; the client holds a queue ticket and is
+ *                 auto-retrying. Carries the raw {@link CapacityBusyResponse}
+ *                 (queue position/size, recommended retry delay). NOT an error.
+ * - `active`    — a grant is held; the room can connect.
+ * - `error`     — the grant request genuinely failed (not capacity-related).
+ */
+type LiveKitCapacityState = {
+    kind: "idle";
+} | {
+    kind: "connecting";
+} | {
+    kind: "queued";
+    busy: CapacityBusyResponse;
+} | {
+    kind: "active";
+    grant: LiveKitSessionGrant;
+} | {
+    kind: "error";
+    error: Error;
+};
+type LiveKitAvatarGrantState = {
+    status: LiveKitAvatarGrantStatus;
+    grant: LiveKitSessionGrant | null;
+    busy: CapacityBusyResponse | null;
+    error: Error | null;
+    /**
+     * Discriminated capacity signal — prefer this over `status` in UI: it
+     * separates a normal capacity wait (`queued`) from a real failure (`error`).
+     */
+    capacity: LiveKitCapacityState;
+    refresh: () => void;
+    clear: () => void;
+    /**
+     * Eagerly release the CURRENTLY-HELD session's capacity lease (best-effort,
+     * fire-and-forget). Wire this to the LiveKit room's terminal `Disconnected`
+     * event so a session that ends for good frees its GPU slot immediately instead
+     * of lingering until the worker reconcile. A no-op when no grant is held.
+     * Releasing on a supersede (reconnect) and on unmount/tab-close is automatic.
+     */
+    release: (reason?: LiveKitSessionReleaseReason) => void;
+};
+/** Maps the raw grant status into the adopter-facing discriminated capacity signal. */
+declare function capacityStateFromGrant(state: Pick<LiveKitAvatarGrantState, "status" | "grant" | "busy" | "error">): LiveKitCapacityState;
+type UseLiveKitAvatarGrantInput<TLlmProvider extends LLMProvider = LLMProvider> = {
+    client: AvatarSessionClient<TLlmProvider>;
+    session: LiveKitSessionRequest<TLlmProvider> | null | undefined;
+    active?: boolean;
+    autoRetryBusy?: boolean;
+    requestOptions?: RealtimeAvatarRequestOptions;
+    /**
+     * Optional LiveKit host URL (`wss://…`) to pre-warm (DNS + TCP + TLS) while
+     * the grant POST is in flight — the only way to cover a browser's FIRST-ever
+     * call, before any landed grant has persisted a host hint. ADVISORY ONLY:
+     * the room always connects to the freshly-granted `livekit_url`, never this
+     * value, so a wrong hint costs one wasted HEAD request and nothing else.
+     */
+    serverUrlHint?: string;
+};
+/**
+ * Requests a Realtime Avatar LiveKit grant, then lets LiveKit's own React
+ * components own the room connection, tracks, agent state, and media controls.
+ */
+declare function useLiveKitAvatarGrant<TLlmProvider extends LLMProvider = LLMProvider>(input: UseLiveKitAvatarGrantInput<TLlmProvider>): LiveKitAvatarGrantState;
+type RealtimeAvatarLiveKitRoomProps = Omit<LiveKitRoomProps, "serverUrl" | "token" | "connect" | "audio" | "video" | "options"> & {
+    grant: LiveKitSessionGrant | null | undefined;
+    connect?: boolean;
+    /** Native LiveKit audio publish option. Defaults to server-STT sessions only. */
+    audio?: LiveKitRoomProps["audio"];
+    /** Native LiveKit video publish option. Defaults to false for avatar calls. */
+    video?: LiveKitRoomProps["video"];
+    /** Passed directly to LiveKitRoom. */
+    options?: LiveKitRoomProps["options"];
+    renderRoomAudio?: boolean;
+    children?: ReactNode;
+};
+/** Thin typed bridge from a Realtime Avatar grant into LiveKitRoom. */
+declare function RealtimeAvatarLiveKitRoom(props: RealtimeAvatarLiveKitRoomProps): ReactElement;
+declare const capacityErrorFromBusy: (busy: CapacityBusyResponse) => RealtimeAvatarCapacityError;
+
+/**
+ * Avatar nonverbal-behavior snapshot + its SSOT derivation.
+ *
+ * This is the ONE place that turns a decoded `behavior_state` frame into the app-facing
+ * snapshot. Both {@link useSessionLifecycle} (opt-in `onBehaviorChange`) and
+ * {@link useRealtimeSession} (`behavior` state + `onBehaviorChange`) route through
+ * {@link nextBehaviorSnapshot}, so the extract + change-diff live exactly once.
+ *
+ * A LEAF module (no hook imports) so both hooks depend on it without an import cycle.
+ */
+/**
+ * The avatar's live nonverbal behavior (multi-clip choreography). `state` is an OPEN
+ * string so newer workers can ship new states without breaking old apps — narrow with
+ * `knownBehaviorStates` and treat unknown values like `"idle"`. `clipId` is the internal
+ * render clip currently playing (a debug/admin detail), or `null` before the first frame.
+ */
+type BehaviorSnapshot = {
+    state: string;
+    clipId: string | null;
+    /** WIRE clip model of the current clip — the same trigger vocabulary the session
+     *  minted with ("idle" | "listen" | "directive"; "think" is retired and never emitted). `null` on pre-Tier-1
+     *  workers (the fields simply aren't on the frame yet). */
+    trigger: string | null;
+    /** Whether the current clip is a looping resting state (vs a one-shot). */
+    loop: boolean | null;
+    /** The clip the last seam faded FROM (`null` before the first seam). */
+    prevClipId: string | null;
+};
+
+/**
+ * Wired up by CONSUMERS, not by this package. Nothing inside the carry calls it — checked
+ * 2026-08-26 by searching for `pendingTurn` and `replay`, which appear nowhere else here. The
+ * upstream studio imports it to gate its own turn replay on reconnect, which is why it is on the
+ * public `/react` surface (exported 2026-08-27): the hooks own the reconnect, but the pending
+ * turn lives in the app, so the app is the one that has to ask.
+ *
+ * Whether a re-queued turn should replay onto a freshly-(re)connected room. Pure
+ * so the "replay exactly once, keyed on the NEW session_id" guard is testable.
+ *
+ * Replays only when ALL hold:
+ * - the connect was a RECOVERY (we were reconnecting), not a first connect;
+ * - there is a pending turn to replay;
+ * - the fresh grant has a session_id;
+ * - that session_id hasn't already replayed (a flapping reconnect that re-fires
+ *   onConnected for the SAME session must not double-send).
+ */
+declare function shouldReplayPendingTurn(args: {
+    wasReconnecting: boolean;
+    hasPendingTurn: boolean;
+    sessionId: string | null | undefined;
+    lastReplayedSessionId: string | null | undefined;
+}): boolean;
+declare const RECONNECT_BACKOFF_MS: number[];
+declare const MAX_RECONNECT_ATTEMPTS = 4;
+type RetryStep = {
+    kind: "retry";
+    delayMs: number;
+    attempt: number;
+} | {
+    kind: "give-up";
+};
+/**
+ * The reconnect policy: the backoff schedule + the give-up bound. Both are CLIENT-
+ * UX-tier knobs (not infra), so they are configurable on the hook with the audited
+ * defaults above. A non-positive / empty override falls back to the default.
+ */
+type ReconnectPolicy = {
+    backoffMs: number[];
+    maxAttempts: number;
+};
+/**
+ * Why a session reached the terminal {@link SessionLifecyclePhase} `ended` arm.
+ * OPTIONAL on the phase (back-compat: a bare `{ kind: "ended" }` still type-checks
+ * and renders), so adopters can disambiguate the end without forking the union:
+ * - `idle`: the CLIENT-AUTHORITATIVE idle clock expired and the SDK ended the
+ *   session itself (released the lease + left the room → the worker's disconnect release
+ *   frees the GPU). This is the reason the idle-warning countdown is now TRUE.
+ * - `disconnected`: a deliberate server/peer end or an exhausted auto-reconnect.
+ * - `error`: a grant failure surfaced as a terminal phase (no lease, no retry).
+ */
+type SessionEndReason = "idle" | "disconnected" | "error";
+type SessionLifecyclePhase = {
+    kind: "idle";
+} | {
+    kind: "requesting";
+} | {
+    kind: "queued";
+    busy: CapacityBusyResponse;
+} | {
+    kind: "connecting";
+    grant: LiveKitSessionGrant;
+} | {
+    kind: "live";
+} | {
+    kind: "idle-warning";
+    secondsRemaining: number;
+    deadlineAt: number;
+} | {
+    kind: "reconnectable";
+    reconnecting: boolean;
+    attempt: number;
+    /** Native LiveKit recovery keeps the same grant; fresh-grant recovery re-mints. */
+    strategy: "in-place" | "fresh-grant";
+} | {
+    kind: "ended";
+    reason?: SessionEndReason;
+};
+type SessionLifecyclePhaseKind = SessionLifecyclePhase["kind"];
+/**
+ * The recovery sub-state, the bridge between the pure recovery classifiers above
+ * and the unified phase. Kept as a small explicit union so the reducer below can
+ * compose it without re-deriving the recover-vs-end table.
+ */
+type RecoveryState = {
+    kind: "connected";
+} | {
+    kind: "in-place-reconnecting";
+} | {
+    kind: "refreshing";
+    attempt: number;
+} | {
+    kind: "reconnecting";
+    attempt: number;
+} | {
+    kind: "failed";
+} | {
+    kind: "ended";
+    reason?: SessionEndReason;
+};
+/**
+ * The CLIENT-OWNED idle budget (seconds): how long "quiet" before the client-
+ * enforced idle end. This is the AUTHORITY for the reap decision (the worker reap
+ * is off). Falls back to the grant's `idle_timeout_seconds` if the app omits it,
+ * then to this default. Matches docs/SDK_SESSION_API.md (`idleSeconds = 120`).
+ */
+declare const DEFAULT_IDLE_SECONDS = 120;
+/**
+ * How early the `idle-warning` phase fires before the idle end (seconds). Replaces
+ * the legacy `min(30s, idle/3)` magic; clamped so the lead is always < the idle
+ * budget. Matches docs/SDK_SESSION_API.md (`idleWarnLeadSeconds = 20`).
+ */
+declare const DEFAULT_IDLE_WARN_LEAD_SECONDS = 20;
+/**
+ * The per-turn "no response" watchdog (seconds). The SDK owns this as the SINGLE
+ * source for the turn timeout so adopters (the studio controller) thread ONE knob
+ * instead of hardcoding a second literal. Matches docs/SDK_SESSION_API.md
+ * (`turnTimeoutSeconds = 20`).
+ */
+declare const DEFAULT_TURN_TIMEOUT_SECONDS = 20;
+type UseSessionLifecycleInput<T extends LLMProvider = LLMProvider> = {
+    client: AvatarSessionClient<T>;
+    session: LiveKitSessionRequest<T> | null | undefined;
+    active?: boolean;
+    /**
+     * The CLIENT-OWNED idle budget (seconds) — the authority for the client-enforced
+     * idle end. Falls back to the grant's `idle_timeout_seconds`, then
+     * {@link DEFAULT_IDLE_SECONDS}. Validated positive (a non-positive value falls
+     * back).
+     */
+    idleSeconds?: number;
+    /**
+     * How early the `idle-warning` phase fires before the idle end (seconds). Default
+     * {@link DEFAULT_IDLE_WARN_LEAD_SECONDS}; clamped so the lead is always strictly
+     * less than the idle budget.
+     */
+    idleWarnLeadSeconds?: number;
+    /**
+     * @deprecated Use {@link idleWarnLeadSeconds}. The legacy ms warn-window override;
+     * still honored (clamped to the idle budget) for back-compat. `idleWarnLeadSeconds`
+     * wins when both are set.
+     */
+    warnBeforeMs?: number;
+    /** Auto-reconnect backoff schedule (ms). Default {@link RECONNECT_BACKOFF_MS}. */
+    reconnectBackoffMs?: number[];
+    /** Auto-reconnect give-up bound. Default {@link MAX_RECONNECT_ATTEMPTS}. */
+    maxReconnectAttempts?: number;
+    /** Forwarded to {@link useLiveKitAvatarGrant}. Defaults true (queue auto-retry). */
+    autoRetryBusy?: boolean;
+    requestOptions?: UseLiveKitAvatarGrantInput<T>["requestOptions"];
+    /**
+     * Opt-in tap for the avatar's live nonverbal behavior (multi-clip choreography). Fires
+     * ONLY on a real change of {@link BehaviorSnapshot}, via the SAME `nextBehaviorSnapshot`
+     * derivation {@link useRealtimeSession} uses for its `behavior` state — one source of truth.
+     *
+     * Omit it and the SDK never subscribes to behavior frames (zero overhead). Treat the
+     * snapshot as DEBUG/admin signal: `clipId` is an internal render-clip id, not a
+     * product-facing value — gate any UI that shows it (e.g. behind an admin flag).
+     */
+    onBehaviorChange?: (snapshot: BehaviorSnapshot) => void;
+};
+type SessionLifecycleApi = {
+    phase: SessionLifecyclePhase;
+    /** The held grant for RealtimeAvatarLiveKitRoom (null until connecting+). */
+    grant: LiveKitSessionGrant | null;
+    /** The underlying capacity signal (queue position/size, error) — unchanged. */
+    capacity: LiveKitCapacityState;
+    /** The DOM recovery contract: auto-reconnect attempts since the last connect. */
+    attempt: number;
+    /**
+     * ms until the CLIENT-ENFORCED idle end, or null when not connected/live. Drives
+     * the countdown — and it is TRUE: at zero the SDK ends the session (`ended{idle}`).
+     * This is the consumer's leverageable window (read it to act in-character before
+     * the line closes; `stayConnected()` to extend; or let it run out).
+     */
+    timeToDisconnectMs: number | null;
+    /**
+     * EXTEND the session: reset the CLIENT idle clock (the load-bearing effect that
+     * postpones the client-enforced end). idle-warning → live. Idempotent,
+     * fire-and-forget, no-op if not connected.
+     */
+    stayConnected: () => void;
+    /**
+     * Mark organic activity (text-turn start, mic unmute, inbound transcription) —
+     * resets the CLIENT idle clock (postpones the client-enforced end).
+     */
+    markActivity: () => void;
+    /** Manual reconnect (the Reconnect button): resets the attempt budget and re-mints. */
+    reconnect: () => void;
+    onConnected: () => void;
+    onDisconnected: (reason?: DisconnectReason) => void;
+    /**
+     * Wire to the room's onError callback. Only retryable LiveKit transport errors
+     * enter recovery; media-device/autoplay/client-cancel errors remain UI errors.
+     */
+    onConnectionError: (error: Error) => void;
+    /**
+     * Wire to onConnectionStateChange so LiveKit's IN-PLACE reconnect
+     * (signalReconnecting → reconnecting → connected) flips the phase too — fixes
+     * the "invisible mid-flight reconnect" gap on the text path.
+     */
+    onConnectionStateChange: (state: LiveKitConnectionStatus) => void;
+    /** Feed the bound-agent signal (useVoiceAssistant().agent presence) from in-room. */
+    setAgentPresent: (present: boolean) => void;
+    /**
+     * Register the in-room room-leave handle (room.disconnect). The in-room bridge
+     * supplies it because the Room lives below this hook. This is what makes idle
+     * CLIENT-AUTHORITATIVE: when the idle clock expires the hook calls this to LEAVE
+     * the room, which (with the worker's disconnect release) ends the worker
+     * session and frees the GPU — no leaked session, no waiting on a server reap that
+     * never fires. Pass null to unregister.
+     */
+    registerLeaveRoom: (leave: (() => void) | null) => void;
+    /** Reset to idle (mode/avatar change). */
+    reset: () => void;
+};
+declare function useSessionLifecycle<T extends LLMProvider = LLMProvider>(input: UseSessionLifecycleInput<T>): SessionLifecycleApi;
+/**
+ * The optional realtime-session sinks the bridge ALSO fills when given the richer
+ * {@link RealtimeSessionApi} (vs a bare {@link SessionLifecycleApi}). All optional, so
+ * mounting the bridge with either surface type-checks — the extra wiring is inert when
+ * the sink is absent. This keeps ONE bridge for both `useSessionLifecycle` and
+ * `useRealtimeSession`.
+ */
+type RealtimeSessionRoomSinks = Partial<{
+    /** Inbound `rta.lifecycle` data frames (DataReceived on the lifecycle topic). */
+    onLifecycleData: (frame: unknown) => void;
+    /** Publisher for client→worker frames (request_graceful_close / extend). */
+    registerDataPublisher: (publish: ((frame: unknown) => void) | null) => void;
+    /** The turn sender (`useChat().send`) used for closing + normal turns. */
+    registerTurnSender: (send: ((text: string, opts?: SendTextOptions) => Promise<void>) | null) => void;
+    /** Live assistant state → the `turn` micro-state. */
+    setTurnState: (state: string | null | undefined) => void;
+    /** Honest media liveness from the bound agent's tracks. */
+    setMedia: (media: {
+        video: "live" | "stalled" | "connecting";
+        audio: "flowing" | "silent";
+    }) => void;
+}>;
+type SessionLifecycleRoomBridgeProps = {
+    lifecycle: Pick<SessionLifecycleApi, "onConnectionStateChange" | "setAgentPresent" | "registerLeaveRoom" | "markActivity"> & RealtimeSessionRoomSinks;
+};
+/**
+ * Wire the in-room LiveKit facts into a {@link useSessionLifecycle} instance:
+ * - `useConnectionState()` → `onConnectionStateChange` (in-place reconnect).
+ * - `useVoiceAssistant().agent` presence → `setAgentPresent` (idle clock gate).
+ * - `useVoiceAssistant().state` + `useTranscriptions()` → `markActivity` (the
+ *   IDLE×CALL fix: a voice call has no per-turn text send to reset the client idle
+ *   clock, so without this an ACTIVE call is falsely reaped at the 120s client idle
+ *   end. We reset on REAL activity only — the agent actively producing
+ *   (`speaking`/`thinking`) or a fresh user transcript (the user spoke) — NOT on the
+ *   resting `listening` state, so a genuinely SILENT call still reaps as intended.
+ *   On the text path the per-turn send already marks activity; this is harmless +
+ *   redundant there, and load-bearing on the call path — one DRY signal for both).
+ * - `room.disconnect()` → `registerLeaveRoom` (so the CLIENT-AUTHORITATIVE idle end
+ *   actually LEAVES the room → `the worker's disconnect release` frees the GPU).
+ *
+ * Renders nothing. Mount it once inside RealtimeAvatarLiveKitRoom.
+ */
+declare function SessionLifecycleRoomBridge({ lifecycle }: SessionLifecycleRoomBridgeProps): null;
+
+/**
+ * The terminal, LABELED end reason surfaced to the app via `onEnded`. This is the
+ * contracts {@link SessionEndReasonLabel} (a superset of the client-internal
+ * {@link SessionEndReason}) — the worker stamps the precise label on its `ended`
+ * frame; {@link resolveEndReason} falls back to mapping the internal reason when no
+ * frame arrived (an old worker), so the app always gets a usable reason.
+ */
+type EndReason = SessionEndReasonLabel;
+/**
+ * The three DISTINCT session clocks — never conflated, each with its own authority:
+ * - `sessionRemainingMs`: to the hard cap. SERVER-MIRRORED off the worker
+ *   `session_clock` frame (a client-only timer drifts across the cold-start gap and
+ *   would cut the goodbye mid-syllable). `null` until the frame lands ("unknown").
+ * - `idleRemainingMs`: to the CLIENT-AUTHORITATIVE idle end (alias of the lifecycle
+ *   `timeToDisconnectMs`; the SDK enforces this one).
+ * - `creditRemainingMs`: an app-supplied passthrough — the SDK never fetches or
+ *   decides billing, it only surfaces the balance + fires `onCreditsLow`.
+ */
+type SessionClocks = {
+    sessionRemainingMs: number | null;
+    idleRemainingMs: number | null;
+    creditRemainingMs: number | null;
+};
+/**
+ * The grace-window state machine. Drives the guaranteed closing line:
+ * - `closed`: no end imminent.
+ * - `open`: the SOFT end is reached — send the ONE closing turn NOW. `deadlineAt`
+ *   is the hard cap (`endsAt`); past it an unused window is `spent{false}`.
+ * - `delivering`: the closing turn is in flight / being spoken. `deadlineAt` is the
+ *   worker's hard ceiling (`endsAt + graceCeilingMs`); past it → `spent{false}`.
+ * - `spent`: terminal — `delivered:true` on the worker `closing_turn_done` frame,
+ *   `delivered:false` if a deadline passed first (the line was cut / never sent).
+ */
+type GraceWindowState = {
+    kind: "closed";
+} | {
+    kind: "open";
+    reason: ApproachingEndReason;
+    deadlineAt: number;
+    msLeft: number;
+} | {
+    kind: "delivering";
+    turnId: string;
+    deadlineAt: number;
+} | {
+    kind: "spent";
+    delivered: boolean;
+};
+/** The live turn micro-state, mapped from `useVoiceAssistant().state`. */
+type TurnState = "listening" | "thinking" | "speaking" | "quiet";
+/**
+ * Map the LiveKit voice-assistant state onto the 4-value turn micro-state. Only the
+ * three "doing something" states pass through; everything else
+ * (`initializing`/`connecting`/`disconnected`/`idle`/unknown) reads as `quiet`.
+ */
+declare function mapTurnState(assistantState: string | null | undefined): TurnState;
+
+/** How early `onApproachingEnd` fires before the hard cap (room to compose the goodbye). */
+declare const DEFAULT_APPROACHING_END_LEAD_SECONDS = 45;
+/** How early the grace window opens before the cap (fits LLM excuse + send RTT + TTS + playout). */
+declare const DEFAULT_GRACE_WINDOW_LEAD_SECONDS = 12;
+/** Client mirror of the worker's hard grace ceiling — how long a closing line may run past the cap. */
+declare const DEFAULT_GRACE_CEILING_SECONDS = 10;
+/** Surface "low on minutes" at ~5 min of the app-supplied credit balance. */
+declare const DEFAULT_CREDITS_LOW_LEAD_SECONDS = 300;
+type ClosingTurnResult = {
+    ok: true;
+    turnId: string;
+} | {
+    ok: false;
+    reason: "window_closed" | "not_connected" | "already_spent";
+};
+type ExtendResult = {
+    ok: boolean;
+};
+type ApproachingEndEvent = {
+    secondsLeft: number;
+    reason: ApproachingEndReason;
+    threshold: number;
+};
+type GraceWindowOpenEvent = {
+    reason: ApproachingEndReason;
+    deadlineAt: number;
+    msLeft: number;
+};
+type GraceWindowClosedEvent = {
+    reason: ApproachingEndReason;
+    delivered: boolean;
+};
+type IdleWarningEvent = {
+    secondsLeft: number;
+};
+type CreditsLowEvent = {
+    secondsLeft: number;
+};
+type TurnTimeoutEvent = {
+    turnId: string | null;
+};
+type ReconnectingEvent = {
+    attempt: number;
+};
+type EndedEvent = {
+    reason: EndReason;
+};
+type RealtimeSessionMedia = {
+    video: "live" | "stalled" | "connecting";
+    audio: "flowing" | "silent";
+};
+
+/** The worker's verdict on a gesture request (every request is answered or times out). */
+type ClipResult = {
+    requestId: string;
+    accepted: boolean;
+    reason: string;
+};
+/**
+ * The `useRealtimeSession` input. ADDITIVE over {@link UseSessionLifecycleInput}
+ * (whose `client`/`session`/`active`/`idleSeconds`/`idleWarnLeadSeconds`/reconnect
+ * knobs are reused VERBATIM — see the "Timeouts & budgets" group). The new fields
+ * are the credit passthrough, the 5 moment callbacks, and the lead-second knobs.
+ *
+ * DESIGN PRINCIPLE — maximum developer control: every timeout/budget is a knob with a
+ * safe default. Client-owned clocks (idle + every lead) are set freely; the hard cap
+ * is a REQUEST (`maxSessionSeconds`, bounded by the platform max + server-enforced for
+ * billing/GPU safety). The app wires only the NARRATIVE callbacks + copy.
+ */
+type UseRealtimeSessionInput<T extends LLMProvider = LLMProvider> = UseSessionLifecycleInput<T> & {
+    /** Echoed by the app on its own events; the SDK never inspects it. */
+    clientMetadata?: Record<string, unknown>;
+    /**
+     * Requested hard cap (seconds). Injected into the session request → the platform
+     * grant → the worker enforces it. Bounded by the platform max (billing/GPU safety);
+     * falls back to the grant's `max_session_seconds`. `idleSeconds`/`idleWarnLeadSeconds`
+     * are inherited from {@link UseSessionLifecycleInput} (client-authoritative).
+     */
+    maxSessionSeconds?: number;
+    /** Lead before the cap for `onApproachingEnd`. Default {@link DEFAULT_APPROACHING_END_LEAD_SECONDS}. */
+    approachingEndLeadSeconds?: number;
+    /** Lead before the cap for the grace window to open. Default {@link DEFAULT_GRACE_WINDOW_LEAD_SECONDS}. */
+    graceWindowLeadSeconds?: number;
+    /** Client mirror of the worker grace ceiling. Default {@link DEFAULT_GRACE_CEILING_SECONDS}. */
+    graceCeilingSeconds?: number;
+    /** Lead before the credit balance runs out for `onCreditsLow`. Default {@link DEFAULT_CREDITS_LOW_LEAD_SECONDS}. */
+    creditsLowLeadSeconds?: number;
+    /** Per-turn "no response" watchdog (seconds). Default {@link DEFAULT_TURN_TIMEOUT_SECONDS}. */
+    turnTimeoutSeconds?: number;
+    /** App-supplied credit balance (ms) — surfaced on `clocks.creditRemainingMs` + drives `onCreditsLow`. */
+    creditRemainingMs?: number | null;
+    /**
+     * Auto-hold the idle clock (`stayConnected`) while the grace window is open/delivering
+     * so the idle reaper can't preempt the guaranteed closing line. Default true.
+     */
+    autoStayConnectedDuringGrace?: boolean;
+    onApproachingEnd?: (e: ApproachingEndEvent) => void;
+    onGraceWindowOpen?: (e: GraceWindowOpenEvent) => void;
+    onGraceWindowClosed?: (e: GraceWindowClosedEvent) => void;
+    onIdleWarning?: (e: IdleWarningEvent) => void;
+    onCreditsLow?: (e: CreditsLowEvent) => void;
+    onTurnTimeout?: (e: TurnTimeoutEvent) => void;
+    onReconnecting?: (e: ReconnectingEvent) => void;
+    onReconnected?: () => void;
+    onEnded?: (e: EndedEvent) => void;
+    /** The avatar's behavior changed (listening/thinking/idle/special clips). */
+    onBehaviorChange?: (b: BehaviorSnapshot) => void;
+    /** A clip request was answered (also resolved on the performClip promise). */
+    onClipResult?: (r: ClipResult) => void;
+};
+/**
+ * The composed realtime-session surface. `phase` is the {@link SessionLifecyclePhase}
+ * SSOT VERBATIM (no union fork). Adds the three clocks, the grace window, the live turn
+ * micro-state, honest media, and the leverage actions. The in-room sinks
+ * (`onLifecycleData`/`registerDataPublisher`/`registerTurnSender`/`setTurnState`/`setMedia`)
+ * are filled by {@link SessionLifecycleRoomBridge} — the app just mounts the bridge.
+ */
+/**
+ * The composed realtime-session surface. A strict SUPERSET of {@link SessionLifecycleApi}
+ * (so it is a DROP-IN replacement everywhere the inner hook was used — `phase`/`grant`/
+ * `capacity`/`stayConnected`/`reconnect`/`timeToDisconnectMs`/the sinks all pass through
+ * verbatim), plus the three clocks, the grace window, the live turn micro-state, honest
+ * media, and the new leverage actions. The realtime-session sinks
+ * (`onLifecycleData`/`registerDataPublisher`/`registerTurnSender`/`setTurnState`/`setMedia`)
+ * are filled by {@link SessionLifecycleRoomBridge} — the app just mounts the bridge.
+ */
+type RealtimeSessionApi = SessionLifecycleApi & {
+    /** Live turn micro-state, mapped from `useVoiceAssistant().state`. */
+    turn: TurnState;
+    /** The three DISTINCT clocks (session/idle/credit), never conflated. */
+    clocks: SessionClocks;
+    /** Wall-clock hard-cap deadline (server-mirrored), or null until the clock frame lands. */
+    endsAt: number | null;
+    /** The grace-window state machine driving the guaranteed closing line. */
+    graceWindow: GraceWindowState;
+    /** Honest media liveness from the bound agent's tracks. */
+    media: RealtimeSessionMedia;
+    /** The inner SSOT surface, for explicit access (it is also spread at top level). */
+    lifecycle: SessionLifecycleApi;
+    /** Speak ONE final in-character line VERBATIM, then end. Guaranteed delivered before the cut. */
+    sendClosingTurn: (text: string, opts?: {
+        instructions?: string;
+    }) => ClosingTurnResult;
+    /** Ask the worker to wind down + close gracefully now (publishes request_graceful_close). */
+    requestGracefulClose: () => void;
+    /** Request a billable, guarded cap extension (the app owns who-pays; the worker validates). */
+    extend: (req: {
+        addSeconds: number;
+        proof?: string;
+    }) => ExtendResult;
+    /** Send a normal turn THROUGH the SDK (arms the turn-timeout watchdog + enables retryTurn). */
+    sendTurn: (text: string, opts?: {
+        instructions?: string;
+    }) => Promise<void>;
+    /** Re-send the last turn sent through the SDK (the "no response" recovery). */
+    retryTurn: () => void;
+    /** End gracefully now (the user tapped End). */
+    end: (reason?: EndReason) => void;
+    /** The avatar's live nonverbal behavior, or null pre-choreo (see {@link BehaviorSnapshot}). */
+    behavior: BehaviorSnapshot | null;
+    /**
+     * Ask the character to PERFORM a clip by id — a gesture arc plays once (e.g. the
+     * gift moment); a `special`-role clip pins for `holdSeconds` (3-20, default 8).
+     * Scheduled at the next seamless swap point, never a hard cut. Resolves with the
+     * worker's verdict (`accepted:false` + reason on refusal / not connected /
+     * timeout) — never rejects, so the app can always fall back to text-only behavior.
+     */
+    performClip: (clipId: string, opts?: {
+        holdSeconds?: number;
+        timeoutMs?: number;
+    }) => Promise<ClipResult>;
+    /** Inbound `rta.lifecycle` frames (the bridge decodes RoomEvent.DataReceived). */
+    onLifecycleData: (frame: unknown) => void;
+    /** Publisher for client→worker frames (request_graceful_close / extend). */
+    registerDataPublisher: (publish: ((frame: unknown) => void) | null) => void;
+    /** The turn sender (the bridge's `useChat().send`) for closing + normal turns. */
+    registerTurnSender: (send: ((text: string, opts?: SendTextOptions) => Promise<void>) | null) => void;
+    /** Live assistant state → `turn`. */
+    setTurnState: (state: string | null | undefined) => void;
+    /** Honest media liveness from the bound agent's tracks. */
+    setMedia: (media: RealtimeSessionMedia) => void;
+};
+declare function useRealtimeSession<T extends LLMProvider = LLMProvider>(input: UseRealtimeSessionInput<T>): RealtimeSessionApi;
+
+/** The player's freeze verdict for the trailing window, in milliseconds. The app
+ *  computes this from its rVFC telemetry (call-telemetry `analyzeCallVideo`) and hands
+ *  a GETTER so the hook samples on its own tick — the app owns no timing. */
+type FreezeReadingFn = () => {
+    /** Frozen ms observed in the trailing window (rVFC-derived; 0 = smooth). */
+    freezeMsInWindow: number;
+    /** The tab is hidden OR the freeze correlates with local CPU, not the network — the
+     *  false-positive fence. When true the governor is frozen (a downgrade can't fix a
+     *  decode/paint stall — our Dia-freeze lesson). */
+    inhibited: boolean;
+};
+interface UseAvatarQualityGovernorInput {
+    /** Master switch (product policy — the player's feature flag). Off ⇒ inert, no tick,
+     *  no subscriptions, the cap is never touched (byte-identical to today). */
+    enabled: boolean;
+    /** The player's rVFC freeze reading getter (see FreezeReadingFn). Optional: without
+     *  it the governor still reacts to Paused + getStats freezes, just without the
+     *  cross-browser rVFC signal. */
+    freezeReading?: FreezeReadingFn;
+    /** Governor timing overrides (tests / tuning). Defaults are the grounded constants. */
+    config?: GovernorConfig;
+    /** Poll cadence (ms). Default 1000 — the governor tick. */
+    tickMs?: number;
+}
+/**
+ * Drive the adaptive quality governor for the avatar's subscribed video track.
+ *
+ * Returns nothing the app must act on — it is a pure side-effect hook (like
+ * useCallTelemetry). Mount it once inside the call body; it self-tears-down.
+ */
+declare function useAvatarQualityGovernor(input: UseAvatarQualityGovernorInput): void;
+
+/** How long the deferred (`ended`-gated) release waits for the track's `ended`
+ *  event before handing the lease on anyway. A backstop against a track that
+ *  never fires `ended`; comfortably longer than a normal stop (~tens of ms). */
+declare const MIC_LEASE_ENDED_TIMEOUT_MS = 1500;
+type MicLease = {
+    /** True once THIS room owns the lease — fold into the mic-intent signal. */
+    held: boolean;
+    /** Stable per-mount lease token. Pass to {@link useReleaseMicLeaseOnTrackEnded}
+     *  (rendered INSIDE the room) to release on the real hardware `ended` signal. */
+    token: symbol;
+};
+/**
+ * React binding for the tab-global mic lease. Pass `want=true` when this room
+ * intends to hold the live microphone (a voice-first / speak-mode call); pass
+ * `false` for a text-mode room that must not touch the mic. Returns `{ held,
+ * token }` — the caller folds `held` into its single mic-intent signal
+ * (`micLive = want && held`), so a rapid redial keeps its mic OFF until the
+ * previous call's room has released, and no two rooms contend for getUserMedia.
+ *
+ * RELEASE is DEFERRED to the local mic track's real `ended` event when an in-room
+ * {@link useReleaseMicLeaseOnTrackEnded} is mounted with this `token`: on unmount
+ * / `want=false` the lease is not handed on until the browser has actually let go
+ * of the capture device (or a safety timeout). Without that companion hook it
+ * falls back to releasing on unmount (still correct for the dominant overlap
+ * case, just coarser). Uncontended, acquisition resolves in a microtask.
+ */
+declare function useMicLease(want: boolean): MicLease;
+
+/**
+ * The client `AvatarCall` and the hooks ask for, talking to YOUR proxy route.
+ *
+ * Everything in this package is keyless by construction, and this is no exception: it holds a
+ * URL, not a credential. Your route holds the key and decides the call; this only relays who to
+ * call and, later, that the call is over.
+ *
+ * It exists because the prop was unsatisfiable without it. `AvatarCall` requires
+ * `client: AvatarSessionClient`, and until now nothing in the published package could produce
+ * one — the only implementation lived in a key-bearing class that is deliberately not exported
+ * to browsers. So the flagship component typechecked, shipped, and could not be used.
+ *
+ * Pair it with `realtime-avatar/nextjs` (or `/hono`, `/express`, `/tanstack-start`) mounted at
+ * the same prefix. Those adapters serve `POST …/connect` and `POST …/end`, which is exactly
+ * what the five methods below call.
+ */
+interface ProxyClientOptions {
+    /**
+     * Where your route is mounted, e.g. `/api/realtime-avatar`.
+     *
+     * Same-origin and relative is the normal case. React Native has no page origin, so pass an
+     * ABSOLUTE url there or every request resolves against nothing.
+     */
+    proxyUrl: string;
+    /** Swap the transport — a test double, or a fetch that carries your session cookie. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Per-request deadline, default 60s, `0` to disable.
+     *
+     * Not optional in spirit: a proxy that accepts the connection and then never answers leaves
+     * a promise that never settles, which presents as a page stuck on "connecting" with no error
+     * and a call slot held until the join timeout reclaims it.
+     */
+    timeoutMs?: number;
+}
+declare function createProxyClient(options: ProxyClientOptions): AvatarSessionClient;
+
+export { RECONNECT_BACKOFF_MS as $, type AvatarSessionClient as A, type BehaviorSnapshot as B, type CallTranscript as C, DEFAULT_APPROACHING_END_LEAD_SECONDS as D, type EndReason as E, type FishTtsModel as F, type Governor as G, type GraceWindowOpenEvent as H, type GraceWindowState as I, type IdleWarningEvent as J, type KnownBehaviorState as K, type LLMProvider as L, type LLMSelection as M, type LiveKitAvatarGrantState as N, type LiveKitAvatarGrantStatus as O, type LiveKitCapacityState as P, type LiveKitConnectionStatus as Q, type LiveKitSessionRequest as R, type LiveKitSessionStartResult as S, type LivePlaybackKeeper as T, MAX_RECONNECT_ATTEMPTS as U, MAX_SESSION_INSTRUCTIONS_CHARS as V, MIC_LEASE_ENDED_TIMEOUT_MS as W, type MicLease as X, type PlayableVideoElement as Y, type ProxyClientOptions as Z, type QualityCap as _, type AvatarVideoFit as a, RealtimeAvatarCapacityError as a0, RealtimeAvatarLiveKitRoom as a1, type RealtimeAvatarLiveKitRoomProps as a2, type RealtimeAvatarRequestOptions as a3, type RealtimeSessionApi as a4, type RealtimeSessionMedia as a5, type RealtimeSessionRoomSinks as a6, type ReconnectPolicy as a7, type ReconnectingEvent as a8, type RecoveryState as a9, shouldReplayPendingTurn as aA, splitCallTranscript as aB, useAvatarPlayoutDelay as aC, useAvatarQualityGovernor as aD, useCallTranscript as aE, useLiveKitAvatarGrant as aF, useMicLease as aG, useRealtimeSession as aH, useReleaseMicLeaseOnTrackEnded as aI, useSessionLifecycle as aJ, type LiveKitSessionGrant as aK, isNativeLiveTrackSubscribed as aL, useLiveTrackProducing as aM, type RetryStep as aa, type SessionBehavior as ab, type SessionClip as ac, type SessionClocks as ad, type SessionEndReason as ae, type SessionLifecycleApi as af, type SessionLifecyclePhase as ag, type SessionLifecyclePhaseKind as ah, SessionLifecycleRoomBridge as ai, type SessionLifecycleRoomBridgeProps as aj, type SurfaceLayers as ak, type TurnState as al, type TurnTimeoutEvent as am, type UseAvatarQualityGovernorInput as an, type UseLiveKitAvatarGrantInput as ao, type UseRealtimeSessionInput as ap, type UseSessionLifecycleInput as aq, type VoiceSpec as ar, type VoiceSpecInput as as, capacityErrorFromBusy as at, capacityStateFromGrant as au, createProxyClient as av, knownBehaviorStates as aw, mapTurnState as ax, sessionBehaviorSchema as ay, sessionClipSchema as az, type ApproachingEndEvent as b, type ApproachingEndReason as c, AvatarVideoSurface as d, type AvatarVideoSurfaceProps as e, type CallTranscriptSegment as f, type CartesiaTtsModel as g, type ClipResult as h, type ClosingTurnResult as i, type CreditsLowEvent as j, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS as k, DEFAULT_CREDITS_LOW_LEAD_SECONDS as l, DEFAULT_GOVERNOR_CONFIG as m, DEFAULT_GRACE_CEILING_SECONDS as n, DEFAULT_GRACE_WINDOW_LEAD_SECONDS as o, DEFAULT_IDLE_SECONDS as p, DEFAULT_IDLE_WARN_LEAD_SECONDS as q, DEFAULT_TURN_TIMEOUT_SECONDS as r, type EndedEvent as s, type ExtendResult as t, type FreezeReadingFn as u, type GovernorAction as v, type GovernorConfig as w, type GovernorSignal as x, type GovernorState as y, type GraceWindowClosedEvent as z };