realtime-avatar 0.24.1 → 0.26.0

package/dist/playout-delay-CtRZdtsj.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Turning the microphone on, and saying what went wrong when it does not.
+ *
+ * WHY THIS EXISTS. `room.localParticipant.setMicrophoneEnabled(true)` is one line, so every
+ * integration writes it inline and none of them handle its rejection — the reject path is
+ * invisible until a real user is on a real machine. When it fails there is nothing to see:
+ * the call is already connected, the page is mid-`await`, and the rejection becomes an
+ * unhandled promise nobody is looking at. The reported symptom is always the same sentence —
+ * "the mic won't start" — and it covers at least six unrelated causes with different fixes,
+ * one of which is not in the browser at all.
+ *
+ * So this returns a RESULT rather than throwing: the cause becomes a value the caller has to
+ * handle, and each one carries the sentence that names its actual fix. `message` is what the
+ * browser said; `hint` is what the person should do.
+ *
+ * It is deliberately structural — it never imports `livekit-client`, so it pins no version
+ * and adds no bytes. Anything with a `localParticipant.setMicrophoneEnabled` satisfies it.
+ */
+/** The sliver of livekit-client's `Room` this needs. Structural on purpose — see above. */
+interface MicrophoneCapableRoom {
+    localParticipant: {
+        setMicrophoneEnabled(enabled: boolean): Promise<unknown>;
+    };
+}
+/**
+ * Why the microphone did not start. Every variant has a DIFFERENT fix, which is the whole
+ * reason this is an enum and not a boolean.
+ */
+type MicrophoneFailureReason = 
+/** No `navigator.mediaDevices` — the page is not a secure context. */
+"insecure-origin"
+/** The permission prompt was never answered. getUserMedia may never settle; we time out. */
+ | "no-answer"
+/** The BROWSER denied it — the site's own permission, resettable from the address bar. */
+ | "denied-by-browser"
+/** The OS denied it — macOS System Settings, nothing the page or the site can change. */
+ | "denied-by-os"
+/** No input device is connected, or none matches the constraints. */
+ | "no-device"
+/** A device exists but something else holds it — another tab, app, or a stale call. */
+ | "device-in-use"
+/** Anything unrecognised. `message` still carries what the browser said. */
+ | "unknown";
+type MicrophoneResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: MicrophoneFailureReason;
+    /** What the browser reported, verbatim. Show it — it is often exact. */
+    message: string;
+    /** What the person should actually do about it. */
+    hint: string;
+};
+interface EnableMicrophoneOptions {
+    /**
+     * How long to wait before calling it a no-answer. Default 15s.
+     *
+     * This is not belt-and-braces. Per the getUserMedia specification a prompt the user never
+     * dismisses may leave the promise permanently pending — "neither resolve nor reject" — and
+     * a page that awaits it in its connect path hangs on a state that has no error and no end.
+     * A deadline turns that into a reportable outcome.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Why a microphone that was WORKING stopped: the device was unplugged, or access was revoked
+ * mid-call. LiveKit tries the default device first and mutes the track when that fails too.
+ * Only a live call can report this; `enableMicrophone` never does.
+ */
+type MicrophoneProblemReason = MicrophoneFailureReason | "device-lost";
+/** A microphone problem as a value: the cause, what the browser said, and what to do. */
+type MicrophoneProblem = {
+    reason: MicrophoneProblemReason;
+    message: string;
+    hint: string;
+};
+/**
+ * Describe a microphone failure, whoever caught it. The one classifier behind both
+ * {@link enableMicrophone} and the React call handle's `microphone` state, so the two can never
+ * give the same failure different advice.
+ */
+declare function describeMicrophoneFailure(error: unknown): MicrophoneProblem;
+/**
+ * Publish the caller's microphone, and report WHY if it does not start.
+ *
+ * ```ts
+ * const mic = await enableMicrophone(room);
+ * if (!mic.ok) {
+ *   status.textContent = `Microphone: ${mic.message}`;
+ *   help.textContent = mic.hint;          // the sentence that names the fix
+ * }
+ * ```
+ *
+ * Never throws. A call that cannot start the microphone is an ordinary outcome of asking a
+ * person for a device, not a programmer error, so it belongs in the return type.
+ *
+ * Note it does NOT hang up on failure — the call is still live and still billing, and only
+ * the caller knows whether a text-only session is useful to them. If it is not, disconnect
+ * in the `!ok` branch; leaving a room connected against a device the user never granted is
+ * how the retry ends up contending with the call that is still holding it.
+ */
+declare function enableMicrophone(room: MicrophoneCapableRoom, options?: EnableMicrophoneOptions): Promise<MicrophoneResult>;
+
+/**
+ * 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 `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).
+ *
+ * This lives in the vanilla browser package, not the React one, because the
+ * React surface applies it for you and a plain-DOM page has to be given it.
+ * Until this file existed the helper was only reachable through
+ * `realtime-avatar/react`, so every plain-DOM adopter — every one of this repo's
+ * own demos included — ran with the browser's default shallow buffer and froze on
+ * every lost packet. Nobody should have to know this knob exists: `prepareAvatarRoom`
+ * (and `attachRemoteAudio`, which calls it) applies it to every track the room
+ * subscribes, and `RealtimeAvatarLiveKitRoom` does the same for React. This file is
+ * the one place the number and its reasoning live.
+ * Structural like its siblings: no `livekit-client` import, no version pin.
+ */
+declare const DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS = 0.5;
+/**
+ * A track that can take a native playout-delay hint — livekit-client's subscribed
+ * `RemoteTrack`. Duck-typed on the method rather than `instanceof`, so a
+ * placeholder or local track is skipped and the helper is testable with a fake.
+ */
+interface PlayoutDelayTarget {
+    setPlayoutDelay(delayInSeconds: number): void;
+}
+/**
+ * Apply the receiver playout delay to ONE subscribed track.
+ *
+ * Call it for every track `RoomEvent.TrackSubscribed` hands you, audio and video
+ * alike, before or after `attach()` — WebRTC syncs the pair to the LARGER hint,
+ * so applying it to one stream and not the other lets the lips lag the voice.
+ * Returns `true` when the hint was applied and `false` when the object cannot take
+ * one (a local track, a placeholder, a not-yet-subscribed publication), so a
+ * caller can log the miss without a try/catch. The delay is floored at 0 so a
+ * negative input can never throw.
+ */
+declare function applyPlayoutDelay(track: unknown, delaySeconds?: number): boolean;
+/**
+ * Apply the SAME native playout delay to the avatar's audio + video tracks
+ * (kept equal so the a/v sync stays lip-locked). Pure and exported so the clamp
+ * and the both-tracks-equal invariant are unit-testable without a DOM; the React
+ * hook `useAvatarPlayoutDelay` is a thin effect wrapper around this.
+ */
+declare function applyAvatarPlayoutDelay(videoTrack: unknown, audioTrack: unknown, delaySeconds?: number): void;
+
+export { DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS as D, type EnableMicrophoneOptions as E, type MicrophoneCapableRoom as M, type PlayoutDelayTarget as P, type MicrophoneFailureReason as a, type MicrophoneProblem as b, type MicrophoneProblemReason as c, type MicrophoneResult as d, applyAvatarPlayoutDelay as e, applyPlayoutDelay as f, describeMicrophoneFailure as g, enableMicrophone as h };

package/dist/{proxy-client-DlFXaXtn.d.ts → proxy-client-C8M_G_Kk.d.ts}

@@ -2,6 +2,7 @@ import * as livekit_client from 'livekit-client';
 import { ConnectionQuality, Room, Participant, Track, DisconnectReason, SendTextOptions } from 'livekit-client';
 import { TrackReferenceOrPlaceholder, useTranscriptions, useConnectionState, LiveKitRoomProps } from '@livekit/components-react';
 import { CSSProperties, ReactNode, ReactElement } from 'react';
+import { b as MicrophoneProblem } from './playout-delay-CtRZdtsj.js';
 import { z } from 'zod';
 
 declare function useAvatarCamera({ allowed, active }: {
@@ -660,7 +661,7 @@ type AvatarVideoSurfaceProps = {
      *  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
+     * @deprecated No-op. The surface FILLS its container (100% x 100%); 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
@@ -700,11 +701,19 @@ type AvatarVideoSurfaceProps = {
      * are not stalls and do not wait on this.
      */
     frameStallMs?: number;
-    /** Extra className for the box (the layers fill it). */
+    /**
+     * Extra className for the box (the layers fill it). The surface's own layout is inline and
+     * needs no CSS build, so a class here ADDS styling; to change a property the surface sets
+     * (its 100% size, say), use `style`.
+     */
     className?: string;
-    /** Extra inline style for the box. */
+    /** Extra inline style for the box, spread over the surface's own. */
     style?: CSSProperties;
-    /** Overlay content rendered above both media layers (badges, chrome, scrims). */
+    /**
+     * Overlay content (controls, captions, scrims). Rendered in a layer that fills the box and
+     * stacks above both media layers and the live badge, so a positioned child places itself
+     * against the box and stays clickable while she is live.
+     */
     children?: ReactNode;
     /** Surface a small "live · WxH" badge when the live layer is shown. Default true. */
     showLiveBadge?: boolean;
@@ -730,7 +739,7 @@ type AvatarVideoSurfaceProps = {
      * desyncs by up to the whole adaptive range. Fires on change only, not per frame.
      */
     onPlayoutDelayChange?: (seconds: number) => void;
-    /** Test id for the box. */
+    /** Test id for the box. Default `avatar-video-surface`. */
     "data-testid"?: string;
 };
 /**
@@ -751,7 +760,7 @@ type AvatarVideoSurfaceProps = {
  * 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
+ * LAYOUT CONTRACT: the surface FILLS its container (100% x 100%) — 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
@@ -893,9 +902,9 @@ interface AvatarSessionClient<TLlmProvider extends LLMProvider = LLMProvider> {
      */
     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.
+     * The `pagehide` path: a send that outlives a closing page (a keepalive `fetch`, or
+     * `sendBeacon`), dispatched synchronously — hence a `boolean` return and no promise, so the
+     * caller can fall back to {@link releaseLiveKitSession} when nothing could be sent.
      */
     releaseLiveKitSessionBeacon(sessionId: string, reason?: LiveKitSessionReleaseReason): boolean;
     /**
@@ -1224,6 +1233,80 @@ type BehaviorSnapshot = {
     prevClipId: string | null;
 };
 
+/**
+ * The microphone, as a call's UI needs it.
+ *
+ * - `off`: this call does not listen (`listen={false}`), or it is not connected — before the
+ *   room joins and after it ends. Nothing is captured.
+ * - `pending`: the device has been asked for and has not answered. The permission prompt may be
+ *   open; per the getUserMedia spec it may never settle, so this can last.
+ * - `on`: published and live; she can hear the user.
+ * - `muted`: published and muted on purpose (`setMicrophoneEnabled(false)`).
+ * - `blocked`: refused by the browser, the operating system, or an insecure origin. The user has
+ *   to change a setting; `hint` names which one. Retry afterwards.
+ * - `unavailable`: no device, a device another app holds, one that stopped mid-call
+ *   (`device-lost`), or a failure nobody classified. `message` is what the browser said.
+ */
+type CallMicrophone = {
+    status: "off";
+} | {
+    status: "pending";
+} | {
+    status: "on";
+} | {
+    status: "muted";
+} | ({
+    status: "blocked";
+} & MicrophoneProblem) | ({
+    status: "unavailable";
+} & MicrophoneProblem);
+/** A microphone state that carries a problem: the argument of `onMicrophoneProblem`. */
+type CallMicrophoneProblem = Extract<CallMicrophone, {
+    status: "blocked" | "unavailable";
+}>;
+/**
+ * Whether her audio can play.
+ *
+ * - `unknown`: not connected yet, and no playback has been attempted.
+ * - `allowed`: no playback attempt has been refused (LiveKit's `room.canPlaybackAudio`).
+ * - `blocked`: the browser refused playback until a user gesture. Call `startAudio()` from one —
+ *   a click or tap handler — or she stays silent.
+ */
+type CallAudioPlayback = "unknown" | "allowed" | "blocked";
+/** What the in-room bridge reads off LiveKit. Raw facts; {@link callMicrophoneFrom} decides. */
+type CallMicrophoneFacts = Readonly<{
+    /** Whether this call publishes the microphone at all. */
+    wanted: boolean;
+    /** The room is connected (LiveKit acquires the microphone on its way there). */
+    connected: boolean;
+    /** An enable this SDK started is still in flight. */
+    enabling: boolean;
+    /** The local microphone publication, if one exists. */
+    publication: Readonly<{
+        muted: boolean;
+        ended: boolean;
+    }> | null;
+    /**
+     * `localParticipant.lastMicrophoneError`, scoped to THIS call: LiveKit keeps the last failure on
+     * the participant until a capture succeeds, and a redial reuses the same Room, so an error that
+     * was already there when this call's grant arrived describes an earlier call and reads as null.
+     */
+    deviceError: Error | null;
+}>;
+/** The two actions, registered by the bridge so the session above the room can call them. */
+type CallMediaControls = Readonly<{
+    /** `room.startAudio()`, resolving whether playback is allowed afterwards. Never rejects. */
+    startAudio: () => Promise<boolean>;
+    /** Mute, unmute, or retry after the user fixed a blocked or unavailable microphone. */
+    setMicrophoneEnabled: (enabled: boolean) => Promise<void>;
+}>;
+/** The sinks the bridge fills. All optional: a bare lifecycle simply does not observe media. */
+type CallMediaSinks = Partial<Readonly<{
+    setMicrophoneFacts: (facts: CallMicrophoneFacts) => void;
+    setAudioPlayback: (playback: CallAudioPlayback) => void;
+    registerMediaControls: (controls: CallMediaControls | null) => void;
+}>>;
+
 /**
  * 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
@@ -1274,8 +1357,11 @@ type ReconnectPolicy = {
  *   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).
+ * - `user`: the app ended it ({@link SessionLifecycleApi.end}) — from any phase, queued
+ *   included. The held session or queue ticket is released and nothing mints again until
+ *   {@link SessionLifecycleApi.reconnect}.
  */
-type SessionEndReason = "idle" | "disconnected" | "error";
+type SessionEndReason = "idle" | "disconnected" | "error" | "user";
 type SessionLifecyclePhase = {
     kind: "idle";
 } | {
@@ -1425,8 +1511,18 @@ type SessionLifecycleApi = {
      * resets the CLIENT idle clock (postpones the client-enforced end).
      */
     markActivity: () => void;
-    /** Manual reconnect (the Reconnect button): resets the attempt budget and re-mints. */
+    /**
+     * Manual reconnect (the Reconnect button): resets the attempt budget and re-mints. After
+     * {@link end} it is the one way to call again.
+     */
     reconnect: () => void;
+    /**
+     * End the session NOW, from any phase — queued, requesting, connecting, live or recovering.
+     * Stops the queue retry and the reconnect ladder, releases the held session or queue ticket
+     * (`manual`), leaves the room, and parks on `ended{reason:"user"}`. Terminal: nothing mints
+     * again until {@link reconnect}; {@link reset} does not undo it. Idempotent.
+     */
+    end: () => void;
     onConnected: () => void;
     onDisconnected: (reason?: DisconnectReason) => void;
     /**
@@ -1451,7 +1547,7 @@ type SessionLifecycleApi = {
      * never fires. Pass null to unregister.
      */
     registerLeaveRoom: (leave: (() => void) | null) => void;
-    /** Reset to idle (mode/avatar change). */
+    /** Reset to idle (mode/avatar change). Does not undo {@link end}: an ended call stays ended. */
     reset: () => void;
 };
 declare function useSessionLifecycle<T extends LLMProvider = LLMProvider>(input: UseSessionLifecycleInput<T>): SessionLifecycleApi;
@@ -1476,7 +1572,7 @@ type RealtimeSessionRoomSinks = Partial<{
         video: "live" | "stalled" | "connecting";
         audio: "flowing" | "silent";
     }) => void;
-}>;
+}> & CallMediaSinks;
 type PublisherConnectionDetails = Readonly<{
     publisherQuality: Participant["connectionQuality"];
     streamState: Track["streamState"] | null;
@@ -1500,6 +1596,12 @@ type SessionLifecycleRoomBridgeProps = {
      * Callback failures never affect the call; no stats polling or uploads are added.
      */
     onConnectionDetailsChange?: (details: AvatarConnectionDetails | null) => void;
+    /**
+     * Whether the room publishes the user's microphone — pass what you passed the room's `audio`.
+     * Default: the same rule {@link RealtimeAvatarLiveKitRoom} applies (server-transcribed calls).
+     * Decides whether a missing microphone track is a problem or simply not wanted.
+     */
+    microphone?: boolean;
     lifecycle: Pick<SessionLifecycleApi, "onConnectionStateChange" | "setAgentPresent" | "registerLeaveRoom" | "markActivity"> & Partial<Pick<SessionLifecycleApi, "grant">> & RealtimeSessionRoomSinks;
 };
 /**
@@ -1519,7 +1621,7 @@ type SessionLifecycleRoomBridgeProps = {
  *
  * Renders nothing. Mount it once inside RealtimeAvatarLiveKitRoom.
  */
-declare function SessionLifecycleRoomBridge({ lifecycle, onConnectionDetailsChange, onMediaModeChange, }: SessionLifecycleRoomBridgeProps): null;
+declare function SessionLifecycleRoomBridge({ lifecycle, onConnectionDetailsChange, onMediaModeChange, microphone, }: SessionLifecycleRoomBridgeProps): null;
 
 /**
  * The terminal, LABELED end reason surfaced to the app via `onEnded`. This is the
@@ -1729,6 +1831,28 @@ type RealtimeSessionApi = SessionLifecycleApi & {
     graceWindow: GraceWindowState;
     /** Honest media liveness from the bound agent's tracks. */
     media: RealtimeSessionMedia;
+    /** Can she hear the user? Derived from LiveKit's microphone facts; see {@link CallMicrophone}. */
+    microphone: CallMicrophone;
+    /** Can the user hear her? `blocked` until `startAudio()` runs inside a user gesture. `unknown` once ended. */
+    audioPlayback: CallAudioPlayback;
+    /**
+     * Unblock her audio (`room.startAudio()`). Call it from a click or tap handler. Never rejects:
+     * resolves whether playback is allowed afterwards (`false` outside a gesture, or with no room).
+     */
+    startAudio: () => Promise<boolean>;
+    /**
+     * Mute or unmute the user's microphone. `true` after a `blocked` or `unavailable` microphone is
+     * the retry, once the user has fixed what the hint names. Never rejects: a failure becomes the
+     * next `microphone` state. Before the room connects it only records the choice (nothing is
+     * captured); after the call ended it does nothing.
+     */
+    setMicrophoneEnabled: (enabled: boolean) => Promise<void>;
+    /**
+     * The user's mute choice, kept across the connect. If you render your own
+     * `RealtimeAvatarLiveKitRoom`, pass `audio={listens && !microphoneMuted}` so a mute made before
+     * the room connected is honoured when LiveKit captures at connect. `AvatarCall` does this.
+     */
+    microphoneMuted: boolean;
     /** 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. */
@@ -1748,7 +1872,12 @@ type RealtimeSessionApi = SessionLifecycleApi & {
     createTranscriptSender: (opts?: TranscriptSenderOptions) => TranscriptSender;
     /** Re-send the last turn with its resolved provenance, a new ID, and retry_of_turn_id. */
     retryTurn: () => void;
-    /** End gracefully now (the user tapped End). */
+    /**
+     * End now (the user tapped End), from any phase — queued and connecting included. Tells the
+     * worker (best-effort), then {@link SessionLifecycleApi.end}: releases the held session or
+     * queue ticket, leaves the room, and parks on `ended`. `onEnded` fires once, with `reason`
+     * (default `user_ended`). Nothing mints again until `reconnect()`.
+     */
     end: (reason?: EndReason) => void;
     /** The avatar's live nonverbal behavior, or null pre-choreo (see {@link BehaviorSnapshot}). */
     behavior: BehaviorSnapshot | null;
@@ -1766,6 +1895,12 @@ type RealtimeSessionApi = SessionLifecycleApi & {
     setTurnState: (state: string | null | undefined) => void;
     /** Honest media liveness from the bound agent's tracks. */
     setMedia: (media: RealtimeSessionMedia) => void;
+    /** The local microphone facts (the bridge reads them off LiveKit). */
+    setMicrophoneFacts: (facts: CallMicrophoneFacts) => void;
+    /** LiveKit's audio playback status. */
+    setAudioPlayback: (playback: CallAudioPlayback) => void;
+    /** The in-room media actions behind `startAudio` / `setMicrophoneEnabled`. */
+    registerMediaControls: (controls: CallMediaControls | null) => void;
 };
 declare function useRealtimeSession<T extends LLMProvider = LLMProvider>(input: UseRealtimeSessionInput<T>): RealtimeSessionApi;
 
@@ -1855,10 +1990,25 @@ interface ProxyClientOptions {
      * 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. */
+    /** Swap the transport — a test double, or a fetch that adds your own auth header. */
     fetch?: typeof globalThis.fetch;
     /**
-     * Per-request deadline, default 60s, `0` to disable.
+     * The `credentials` mode of EVERY request this client makes, the page-hide release included.
+     * Unset, the client sets none, so `fetch`'s own default (`"same-origin"`) applies, or whatever
+     * your `fetch` wrapper sets.
+     *
+     * Set `"include"` when your route is on another origin and authorizes on a cookie — an
+     * `app.example.com` page calling an `api.example.com` route. The route's CORS must then answer
+     * with `Access-Control-Allow-Credentials: true` and the page's exact origin, for the preflight
+     * of `connect` and of the release alike.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * Per-request deadline, default 60s, `0` to disable. Keep it above your route's `timeoutMs`
+     * (default 50s), so the route's answer arrives before the page stops listening. Running out throws a
+     * `RealtimeAvatarApiError` with `code: "upstream_timeout"` (status 504, `response: null`).
+     * Do not re-send a timed-out `connect` automatically: your route may still be minting it, and
+     * this client never retries a mint — the server client inside your route owns that retry.
      *
      * 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
@@ -1868,4 +2018,4 @@ interface ProxyClientOptions {
 }
 declare function createProxyClient(options: ProxyClientOptions): AvatarSessionClient;
 
-export { type ProxyClientOptions as $, type AvatarVideoFit 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 GovernorSignal as H, type GovernorState as I, type GraceWindowClosedEvent as J, type GraceWindowOpenEvent as K, type LiveKitSessionGrant as L, type GraceWindowState as M, type IdleWarningEvent as N, type InboundRtpCursor as O, type InboundRtpReading as P, type KnownBehaviorState as Q, type LLMProvider as R, type LLMSelection as S, type LiveKitAvatarGrantState as T, type LiveKitAvatarGrantStatus as U, type LiveKitCapacityState as V, type LiveKitConnectionStatus as W, type LiveKitSessionRequest as X, type LiveKitSessionStartResult as Y, MAX_RECONNECT_ATTEMPTS as Z, MAX_SESSION_INSTRUCTIONS_CHARS as _, AdaptivePlayoutController as a, shouldReplayPendingTurn as a$, type QualityCap as a0, RECONNECT_BACKOFF_MS as a1, type RealtimeAvatarRequestOptions as a2, type RealtimeSessionApi as a3, type RealtimeSessionMedia as a4, type RealtimeSessionRoomSinks as a5, type ReconnectPolicy as a6, type ReconnectingEvent as a7, type RecoveryState as a8, type RetryStep as a9, mapTurnState as aA, readInboundRtp as aB, sessionBehaviorSchema as aC, sessionClipSchema as aD, splitCallTranscript as aE, useAvatarAdaptivePlayoutDelay as aF, useAvatarCamera as aG, useAvatarPlayoutDelay as aH, useAvatarQualityGovernor as aI, useCallTranscript as aJ, useLiveKitAvatarGrant as aK, useLiveTrackProducing as aL, useMicLease as aM, useRealtimeSession as aN, useReleaseMicLeaseOnTrackEnded as aO, useSessionLifecycle as aP, AvatarVideoSurface as aQ, type AvatarVideoSurfaceProps as aR, type LivePlaybackKeeper as aS, MIC_LEASE_ENDED_TIMEOUT_MS as aT, type MicLease as aU, NETWORK_QUALITY_POLICY as aV, type NetworkQualityStatus as aW, type PlayableVideoElement as aX, RealtimeAvatarCapacityError as aY, RealtimeAvatarLiveKitRoom as aZ, type RealtimeAvatarLiveKitRoomProps as a_, type SendTurnOptions 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 TranscriptSender as al, type TranscriptSenderOptions as am, type TurnState as an, type TurnTimeoutEvent as ao, type UseAvatarQualityGovernorInput as ap, type UseLiveKitAvatarGrantInput as aq, type UseRealtimeSessionInput as ar, type UseSessionLifecycleInput as as, type VoiceSpec as at, type VoiceSpecInput as au, capacityErrorFromBusy as av, capacityStateFromGrant as aw, createProxyClient as ax, isNativeLiveTrackSubscribed as ay, knownBehaviorStates as az, type AdaptivePlayoutDecision as b, type AdaptivePlayoutOptions as c, type AdaptivePlayoutSample as d, type ApproachingEndEvent as e, type ApproachingEndReason as f, type AvatarConnectionDetails as g, type AvatarSessionClient as h, type CallTranscriptSegment as i, type CartesiaTtsModel as j, type ClipResult as k, type ClosingTurnResult as l, type CreditsLowEvent as m, DEFAULT_CREDITS_LOW_LEAD_SECONDS as n, DEFAULT_GOVERNOR_CONFIG as o, DEFAULT_GRACE_CEILING_SECONDS as p, DEFAULT_GRACE_WINDOW_LEAD_SECONDS as q, DEFAULT_IDLE_SECONDS as r, DEFAULT_IDLE_WARN_LEAD_SECONDS as s, DEFAULT_TURN_TIMEOUT_SECONDS as t, type DeclaredInputSource as u, type EndedEvent as v, type ExtendResult as w, type FreezeReadingFn as x, type GovernorAction as y, type GovernorConfig as z };
+export { type ProxyClientOptions as $, type AvatarVideoFit 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 GovernorSignal as H, type GovernorState as I, type GraceWindowClosedEvent as J, type GraceWindowOpenEvent as K, type LiveKitSessionGrant as L, type GraceWindowState as M, type IdleWarningEvent as N, type InboundRtpCursor as O, type InboundRtpReading as P, type KnownBehaviorState as Q, type LLMProvider as R, type LLMSelection as S, type LiveKitAvatarGrantState as T, type LiveKitAvatarGrantStatus as U, type LiveKitCapacityState as V, type LiveKitConnectionStatus as W, type LiveKitSessionRequest as X, type LiveKitSessionStartResult as Y, MAX_RECONNECT_ATTEMPTS as Z, MAX_SESSION_INSTRUCTIONS_CHARS as _, AdaptivePlayoutController as a, RealtimeAvatarCapacityError as a$, type QualityCap as a0, RECONNECT_BACKOFF_MS as a1, type RealtimeAvatarRequestOptions as a2, type RealtimeSessionApi as a3, type RealtimeSessionMedia as a4, type RealtimeSessionRoomSinks as a5, type ReconnectPolicy as a6, type ReconnectingEvent as a7, type RecoveryState as a8, type RetryStep as a9, mapTurnState as aA, readInboundRtp as aB, sessionBehaviorSchema as aC, sessionClipSchema as aD, splitCallTranscript as aE, useAvatarAdaptivePlayoutDelay as aF, useAvatarCamera as aG, useAvatarPlayoutDelay as aH, useAvatarQualityGovernor as aI, useCallTranscript as aJ, useLiveKitAvatarGrant as aK, useLiveTrackProducing as aL, useMicLease as aM, useRealtimeSession as aN, useReleaseMicLeaseOnTrackEnded as aO, useSessionLifecycle as aP, type CallMicrophone as aQ, type CallAudioPlayback as aR, type CallMicrophoneProblem as aS, AvatarVideoSurface as aT, type AvatarVideoSurfaceProps as aU, type LivePlaybackKeeper as aV, MIC_LEASE_ENDED_TIMEOUT_MS as aW, type MicLease as aX, NETWORK_QUALITY_POLICY as aY, type NetworkQualityStatus as aZ, type PlayableVideoElement as a_, type SendTurnOptions 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 TranscriptSender as al, type TranscriptSenderOptions as am, type TurnState as an, type TurnTimeoutEvent as ao, type UseAvatarQualityGovernorInput as ap, type UseLiveKitAvatarGrantInput as aq, type UseRealtimeSessionInput as ar, type UseSessionLifecycleInput as as, type VoiceSpec as at, type VoiceSpecInput as au, capacityErrorFromBusy as av, capacityStateFromGrant as aw, createProxyClient as ax, isNativeLiveTrackSubscribed as ay, knownBehaviorStates as az, type AdaptivePlayoutDecision as b, RealtimeAvatarLiveKitRoom as b0, type RealtimeAvatarLiveKitRoomProps as b1, shouldReplayPendingTurn as b2, type AdaptivePlayoutOptions as c, type AdaptivePlayoutSample as d, type ApproachingEndEvent as e, type ApproachingEndReason as f, type AvatarConnectionDetails as g, type AvatarSessionClient as h, type CallTranscriptSegment as i, type CartesiaTtsModel as j, type ClipResult as k, type ClosingTurnResult as l, type CreditsLowEvent as m, DEFAULT_CREDITS_LOW_LEAD_SECONDS as n, DEFAULT_GOVERNOR_CONFIG as o, DEFAULT_GRACE_CEILING_SECONDS as p, DEFAULT_GRACE_WINDOW_LEAD_SECONDS as q, DEFAULT_IDLE_SECONDS as r, DEFAULT_IDLE_WARN_LEAD_SECONDS as s, DEFAULT_TURN_TIMEOUT_SECONDS as t, type DeclaredInputSource as u, type EndedEvent as v, type ExtendResult as w, type FreezeReadingFn as x, type GovernorAction as y, type GovernorConfig as z };

package/dist/react-native.d.ts

@@ -1,11 +1,11 @@
 import { LiveKitRoomProps } from '@livekit/react-native';
 export { AudioSession, VideoTrack, VideoTrackProps, registerGlobals } from '@livekit/react-native';
-import { L as LiveKitSessionGrant, A as AvatarVideoFit } from './proxy-client-DlFXaXtn.js';
-export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarConnectionDetails, h as AvatarSessionClient, B as BehaviorSnapshot, C as CallTranscript, i as CallTranscriptSegment, j as CartesiaTtsModel, k as ClipResult, l as ClosingTurnResult, m as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, n as DEFAULT_CREDITS_LOW_LEAD_SECONDS, o as DEFAULT_GOVERNOR_CONFIG, p as DEFAULT_GRACE_CEILING_SECONDS, q as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, r as DEFAULT_IDLE_SECONDS, s as DEFAULT_IDLE_WARN_LEAD_SECONDS, t as DEFAULT_TURN_TIMEOUT_SECONDS, u as DeclaredInputSource, E as EndReason, v as EndedEvent, w as ExtendResult, F as FishTtsModel, x as FreezeReadingFn, G as Governor, y as GovernorAction, z as GovernorConfig, H as GovernorSignal, I as GovernorState, J as GraceWindowClosedEvent, K as GraceWindowOpenEvent, M as GraceWindowState, N as IdleWarningEvent, O as InboundRtpCursor, P as InboundRtpReading, Q as KnownBehaviorState, R as LLMProvider, S as LLMSelection, T as LiveKitAvatarGrantState, U as LiveKitAvatarGrantStatus, V as LiveKitCapacityState, W as LiveKitConnectionStatus, X as LiveKitSessionRequest, Y as LiveKitSessionStartResult, Z as MAX_RECONNECT_ATTEMPTS, _ as MAX_SESSION_INSTRUCTIONS_CHARS, $ as ProxyClientOptions, a0 as QualityCap, a1 as RECONNECT_BACKOFF_MS, a2 as RealtimeAvatarRequestOptions, a3 as RealtimeSessionApi, a4 as RealtimeSessionMedia, a5 as RealtimeSessionRoomSinks, a6 as ReconnectPolicy, a7 as ReconnectingEvent, a8 as RecoveryState, a9 as RetryStep, aa as SendTurnOptions, ab as SessionBehavior, ac as SessionClip, ad as SessionClocks, ae as SessionEndReason, af as SessionLifecycleApi, ag as SessionLifecyclePhase, ah as SessionLifecyclePhaseKind, ai as SessionLifecycleRoomBridge, aj as SessionLifecycleRoomBridgeProps, ak as SurfaceLayers, al as TranscriptSender, am as TranscriptSenderOptions, an as TurnState, ao as TurnTimeoutEvent, ap as UseAvatarQualityGovernorInput, aq as UseLiveKitAvatarGrantInput, ar as UseRealtimeSessionInput, as as UseSessionLifecycleInput, at as VoiceSpec, au as VoiceSpecInput, av as capacityErrorFromBusy, aw as capacityStateFromGrant, ax as createProxyClient, ay as isNativeLiveTrackSubscribed, az as knownBehaviorStates, aA as mapTurnState, aB as readInboundRtp, aC as sessionBehaviorSchema, aD as sessionClipSchema, aE as splitCallTranscript, aF as useAvatarAdaptivePlayoutDelay, aG as useAvatarCamera, aH as useAvatarPlayoutDelay, aI as useAvatarQualityGovernor, aJ as useCallTranscript, aK as useLiveKitAvatarGrant, aL as useLiveTrackProducing, aM as useMicLease, aN as useRealtimeSession, aO as useReleaseMicLeaseOnTrackEnded, aP as useSessionLifecycle } from './proxy-client-DlFXaXtn.js';
+import { L as LiveKitSessionGrant, A as AvatarVideoFit } from './proxy-client-C8M_G_Kk.js';
+export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarConnectionDetails, h as AvatarSessionClient, B as BehaviorSnapshot, C as CallTranscript, i as CallTranscriptSegment, j as CartesiaTtsModel, k as ClipResult, l as ClosingTurnResult, m as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, n as DEFAULT_CREDITS_LOW_LEAD_SECONDS, o as DEFAULT_GOVERNOR_CONFIG, p as DEFAULT_GRACE_CEILING_SECONDS, q as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, r as DEFAULT_IDLE_SECONDS, s as DEFAULT_IDLE_WARN_LEAD_SECONDS, t as DEFAULT_TURN_TIMEOUT_SECONDS, u as DeclaredInputSource, E as EndReason, v as EndedEvent, w as ExtendResult, F as FishTtsModel, x as FreezeReadingFn, G as Governor, y as GovernorAction, z as GovernorConfig, H as GovernorSignal, I as GovernorState, J as GraceWindowClosedEvent, K as GraceWindowOpenEvent, M as GraceWindowState, N as IdleWarningEvent, O as InboundRtpCursor, P as InboundRtpReading, Q as KnownBehaviorState, R as LLMProvider, S as LLMSelection, T as LiveKitAvatarGrantState, U as LiveKitAvatarGrantStatus, V as LiveKitCapacityState, W as LiveKitConnectionStatus, X as LiveKitSessionRequest, Y as LiveKitSessionStartResult, Z as MAX_RECONNECT_ATTEMPTS, _ as MAX_SESSION_INSTRUCTIONS_CHARS, $ as ProxyClientOptions, a0 as QualityCap, a1 as RECONNECT_BACKOFF_MS, a2 as RealtimeAvatarRequestOptions, a3 as RealtimeSessionApi, a4 as RealtimeSessionMedia, a5 as RealtimeSessionRoomSinks, a6 as ReconnectPolicy, a7 as ReconnectingEvent, a8 as RecoveryState, a9 as RetryStep, aa as SendTurnOptions, ab as SessionBehavior, ac as SessionClip, ad as SessionClocks, ae as SessionEndReason, af as SessionLifecycleApi, ag as SessionLifecyclePhase, ah as SessionLifecyclePhaseKind, ai as SessionLifecycleRoomBridge, aj as SessionLifecycleRoomBridgeProps, ak as SurfaceLayers, al as TranscriptSender, am as TranscriptSenderOptions, an as TurnState, ao as TurnTimeoutEvent, ap as UseAvatarQualityGovernorInput, aq as UseLiveKitAvatarGrantInput, ar as UseRealtimeSessionInput, as as UseSessionLifecycleInput, at as VoiceSpec, au as VoiceSpecInput, av as capacityErrorFromBusy, aw as capacityStateFromGrant, ax as createProxyClient, ay as isNativeLiveTrackSubscribed, az as knownBehaviorStates, aA as mapTurnState, aB as readInboundRtp, aC as sessionBehaviorSchema, aD as sessionClipSchema, aE as splitCallTranscript, aF as useAvatarAdaptivePlayoutDelay, aG as useAvatarCamera, aH as useAvatarPlayoutDelay, aI as useAvatarQualityGovernor, aJ as useCallTranscript, aK as useLiveKitAvatarGrant, aL as useLiveTrackProducing, aM as useMicLease, aN as useRealtimeSession, aO as useReleaseMicLeaseOnTrackEnded, aP as useSessionLifecycle } from './proxy-client-C8M_G_Kk.js';
 import { ReactNode, ReactElement } from 'react';
 import { StyleProp, ViewStyle } from 'react-native';
 export { useChat, useConnectionState, useLocalParticipant, useRoomContext, useTrackToggle, useTranscriptions, useVoiceAssistant } from '@livekit/components-react';
-export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS } from './playout-delay-DWOc8iCl.js';
+export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS } from './playout-delay-CtRZdtsj.js';
 export { DisconnectReason, RemoteAudioTrack, RemoteTrack, RemoteVideoTrack, Room, RoomEvent, SendTextOptions, Track } from 'livekit-client';
 import 'zod';