realtime-avatar 0.11.0 → 0.11.2

package/dist/{chunk-RVBBZCVM.js → chunk-MJJ6GSAU.js}

@@ -1,4 +1,4 @@
-import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-MBQ2VKLC.js';
+import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-SKXUGNEK.js';
 
 // ../proxy/src/config.ts
 var json = (body, status = 200) => new Response(JSON.stringify(body), {

package/dist/{chunk-MBQ2VKLC.js → chunk-SKXUGNEK.js}

@@ -218,7 +218,7 @@ function isTransient(cause) {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.11.0";
+var SDK_VERSION = "0.11.2";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;

package/dist/express.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-DrgyCwLC.js';
-import './types-FoJMJimV.js';
+import { P as ProxyConfig } from './types-9a0bRdXl.js';
+import './types-nxdohaiH.js';
 
 type Expressish = {
     method: string;

package/dist/express.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-RVBBZCVM.js';
-import './chunk-MBQ2VKLC.js';
+import { createProxyHandler } from './chunk-MJJ6GSAU.js';
+import './chunk-SKXUGNEK.js';
 
 // ../proxy/src/express.ts
 function realtimeAvatarExpress(config) {

package/dist/hono.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-DrgyCwLC.js';
-import './types-FoJMJimV.js';
+import { P as ProxyConfig } from './types-9a0bRdXl.js';
+import './types-nxdohaiH.js';
 
 /**
  * Hono (and anything else built on Fetch handlers — Workers, Bun, Deno).

package/dist/hono.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-RVBBZCVM.js';
-import './chunk-MBQ2VKLC.js';
+import { createProxyHandler } from './chunk-MJJ6GSAU.js';
+import './chunk-SKXUGNEK.js';
 
 // ../proxy/src/hono.ts
 function realtimeAvatarHono(config) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipLibraryDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as AssetKind, h as Asset, i as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as CreditBalance, T as TranscriptPayload } from './types-FoJMJimV.js';
-export { l as AvatarClip, m as CallConnection, n as CallQueued, o as ClipDeclaration, p as ClipLibraryPlan, q as ClipSource, r as ContextMessage, s as EndCallReason, V as VideoPolicy, t as isQueued } from './types-FoJMJimV.js';
+import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipLibraryDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as AssetKind, h as Asset, i as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as CreditBalance, T as TranscriptPayload } from './types-nxdohaiH.js';
+export { l as AvatarClip, m as CallConnection, n as CallQueued, o as ClipDeclaration, p as ClipLibraryPlan, q as ClipSource, r as ContextMessage, s as EndCallReason, V as VideoPolicy, t as isQueued } from './types-nxdohaiH.js';
 import { z } from 'zod';
 
 interface RealtimeAvatarOptions {

package/dist/index.js

@@ -1 +1 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, verifyTranscript } from './chunk-MBQ2VKLC.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, verifyTranscript } from './chunk-SKXUGNEK.js';

package/dist/nextjs.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-DrgyCwLC.js';
-import './types-FoJMJimV.js';
+import { P as ProxyConfig } from './types-9a0bRdXl.js';
+import './types-nxdohaiH.js';
 
 /**
  * App Router. Mount at `app/api/realtime-avatar/[...path]/route.ts`:

package/dist/nextjs.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-RVBBZCVM.js';
-import './chunk-MBQ2VKLC.js';
+import { createProxyHandler } from './chunk-MJJ6GSAU.js';
+import './chunk-SKXUGNEK.js';
 
 // ../proxy/src/nextjs.ts
 function createRealtimeAvatarRoute(config) {

package/dist/{proxy-client-CWvT16wz.d.ts → proxy-client-D1Zm7reb.d.ts}

@@ -468,7 +468,14 @@ type AvatarVideoSurfaceProps = {
     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.
+     * treated as stalled and replaced by the idle/poster floor — i.e. how long the LAST
+     * live frame is held through a network gap. Default
+     * {@link DEFAULT_AVATAR_FRAME_STALL_MS} (2 s). Once two stalls land inside 15 s the
+     * link is treated as unstable and the hold steps up to
+     * {@link DEFAULT_AVATAR_UNSTABLE_STALL_MS} (4 s) until the window clears, so a
+     * flapping link settles on a briefly frozen face rather than a body swap per gap.
+     * A disconnect, a turn end (track muted) and a track that never presented a frame
+     * are not stalls and do not wait on this.
      */
     frameStallMs?: number;
     /** Extra className for the box (the layers fill it). */

package/dist/react-native.d.ts

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

package/dist/react-native.js

@@ -837,9 +837,10 @@ var step = (g, s, nowMs, cfg = DEFAULT_GOVERNOR_CONFIG) => {
       return { governor: g };
   }
 };
-var resolveLowCapQuality = (declaredLayerQualities) => {
+var resolveLowCapQuality = (declaredLayerQualities, failures = 0) => {
   const sorted = [...declaredLayerQualities].sort((a, b) => a - b);
-  return sorted.length >= 2 ? sorted[sorted.length - 2] : 1;
+  if (sorted.length < 2) return 1;
+  return failures >= 1 ? sorted[0] : sorted[sorted.length - 2];
 };
 
 // ../client/src/react/use-quality-governor.ts
@@ -959,10 +960,11 @@ function useAvatarQualityGovernor(input) {
         return { freezeMs: 0, jitterRising: false };
       }
     };
-    const applyCap = (cap) => {
+    const applyCap = (cap, failures = 0) => {
       try {
         const lowCap = resolveLowCapQuality(
-          (targetPublication?.trackInfo?.layers ?? []).map((l) => l.quality)
+          (targetPublication?.trackInfo?.layers ?? []).map((l) => l.quality),
+          failures
         );
         targetPublication?.setVideoQuality?.(cap === "low" ? lowCap : VideoQuality.HIGH);
       } catch {
@@ -987,13 +989,13 @@ function useAvatarQualityGovernor(input) {
         pausedSinceTick = false;
         const { governor, action } = step(gov, signal, Date.now(), config);
         gov = governor;
-        if (action) applyCap(action.setCap);
+        if (action) applyCap(action.setCap, gov.failures);
       } catch {
       } finally {
         tickRunning = false;
       }
     };
-    applyCap(gov.cap);
+    applyCap(gov.cap, gov.failures);
     const handle = setInterval(() => void tick(), tickMs);
     return () => {
       disposed = true;

package/dist/react.d.ts

@@ -1,12 +1,21 @@
 import { RegisteredTool, ToolRegistration } from './tools.js';
 import { ReactNode } from 'react';
-import { g as AvatarSessionClient, A as AvatarVideoFit } from './proxy-client-CWvT16wz.js';
-export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, aK as AvatarVideoSurface, aL as AvatarVideoSurfaceProps, B as BehaviorSnapshot, C as CallTranscript, h as CallTranscriptSegment, i as CartesiaTtsModel, j as ClipResult, k as ClosingTurnResult, l as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, m as DEFAULT_CREDITS_LOW_LEAD_SECONDS, n as DEFAULT_GOVERNOR_CONFIG, o as DEFAULT_GRACE_CEILING_SECONDS, p as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, q as DEFAULT_IDLE_SECONDS, r as DEFAULT_IDLE_WARN_LEAD_SECONDS, s as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, t as EndedEvent, u as ExtendResult, F as FishTtsModel, v as FreezeReadingFn, G as Governor, w as GovernorAction, x as GovernorConfig, y as GovernorSignal, z as GovernorState, H as GraceWindowClosedEvent, I as GraceWindowOpenEvent, J as GraceWindowState, K as IdleWarningEvent, M as InboundRtpCursor, N as InboundRtpReading, O as KnownBehaviorState, P as LLMProvider, Q as LLMSelection, R as LiveKitAvatarGrantState, S as LiveKitAvatarGrantStatus, T as LiveKitCapacityState, U as LiveKitConnectionStatus, V as LiveKitSessionRequest, W as LiveKitSessionStartResult, aM as LivePlaybackKeeper, X as MAX_RECONNECT_ATTEMPTS, Y as MAX_SESSION_INSTRUCTIONS_CHARS, aN as MIC_LEASE_ENDED_TIMEOUT_MS, aO as MicLease, aP as PlayableVideoElement, Z as ProxyClientOptions, _ as QualityCap, $ as RECONNECT_BACKOFF_MS, aQ as RealtimeAvatarCapacityError, aR as RealtimeAvatarLiveKitRoom, aS as RealtimeAvatarLiveKitRoomProps, a0 as RealtimeAvatarRequestOptions, a1 as RealtimeSessionApi, a2 as RealtimeSessionMedia, a3 as RealtimeSessionRoomSinks, a4 as ReconnectPolicy, a5 as ReconnectingEvent, a6 as RecoveryState, a7 as RetryStep, a8 as SessionBehavior, a9 as SessionClip, aa as SessionClocks, ab as SessionEndReason, ac as SessionLifecycleApi, ad as SessionLifecyclePhase, ae as SessionLifecyclePhaseKind, af as SessionLifecycleRoomBridge, ag as SessionLifecycleRoomBridgeProps, ah as SurfaceLayers, ai as TurnState, aj as TurnTimeoutEvent, ak as UseAvatarQualityGovernorInput, al as UseLiveKitAvatarGrantInput, am as UseRealtimeSessionInput, an as UseSessionLifecycleInput, ao as VoiceSpec, ap as VoiceSpecInput, aq as capacityErrorFromBusy, ar as capacityStateFromGrant, as as createProxyClient, au as knownBehaviorStates, av as mapTurnState, aw as readInboundRtp, ax as sessionBehaviorSchema, ay as sessionClipSchema, aT as shouldReplayPendingTurn, az as splitCallTranscript, aA as useAvatarAdaptivePlayoutDelay, aB as useAvatarPlayoutDelay, aC as useAvatarQualityGovernor, aD as useCallTranscript, aE as useLiveKitAvatarGrant, aG as useMicLease, aH as useRealtimeSession, aI as useReleaseMicLeaseOnTrackEnded, aJ as useSessionLifecycle } from './proxy-client-CWvT16wz.js';
+import { g as AvatarSessionClient, A as AvatarVideoFit } from './proxy-client-D1Zm7reb.js';
+export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, aK as AvatarVideoSurface, aL as AvatarVideoSurfaceProps, B as BehaviorSnapshot, C as CallTranscript, h as CallTranscriptSegment, i as CartesiaTtsModel, j as ClipResult, k as ClosingTurnResult, l as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, m as DEFAULT_CREDITS_LOW_LEAD_SECONDS, n as DEFAULT_GOVERNOR_CONFIG, o as DEFAULT_GRACE_CEILING_SECONDS, p as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, q as DEFAULT_IDLE_SECONDS, r as DEFAULT_IDLE_WARN_LEAD_SECONDS, s as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, t as EndedEvent, u as ExtendResult, F as FishTtsModel, v as FreezeReadingFn, G as Governor, w as GovernorAction, x as GovernorConfig, y as GovernorSignal, z as GovernorState, H as GraceWindowClosedEvent, I as GraceWindowOpenEvent, J as GraceWindowState, K as IdleWarningEvent, M as InboundRtpCursor, N as InboundRtpReading, O as KnownBehaviorState, P as LLMProvider, Q as LLMSelection, R as LiveKitAvatarGrantState, S as LiveKitAvatarGrantStatus, T as LiveKitCapacityState, U as LiveKitConnectionStatus, V as LiveKitSessionRequest, W as LiveKitSessionStartResult, aM as LivePlaybackKeeper, X as MAX_RECONNECT_ATTEMPTS, Y as MAX_SESSION_INSTRUCTIONS_CHARS, aN as MIC_LEASE_ENDED_TIMEOUT_MS, aO as MicLease, aP as PlayableVideoElement, Z as ProxyClientOptions, _ as QualityCap, $ as RECONNECT_BACKOFF_MS, aQ as RealtimeAvatarCapacityError, aR as RealtimeAvatarLiveKitRoom, aS as RealtimeAvatarLiveKitRoomProps, a0 as RealtimeAvatarRequestOptions, a1 as RealtimeSessionApi, a2 as RealtimeSessionMedia, a3 as RealtimeSessionRoomSinks, a4 as ReconnectPolicy, a5 as ReconnectingEvent, a6 as RecoveryState, a7 as RetryStep, a8 as SessionBehavior, a9 as SessionClip, aa as SessionClocks, ab as SessionEndReason, ac as SessionLifecycleApi, ad as SessionLifecyclePhase, ae as SessionLifecyclePhaseKind, af as SessionLifecycleRoomBridge, ag as SessionLifecycleRoomBridgeProps, ah as SurfaceLayers, ai as TurnState, aj as TurnTimeoutEvent, ak as UseAvatarQualityGovernorInput, al as UseLiveKitAvatarGrantInput, am as UseRealtimeSessionInput, an as UseSessionLifecycleInput, ao as VoiceSpec, ap as VoiceSpecInput, aq as capacityErrorFromBusy, ar as capacityStateFromGrant, as as createProxyClient, au as knownBehaviorStates, av as mapTurnState, aw as readInboundRtp, ax as sessionBehaviorSchema, ay as sessionClipSchema, aT as shouldReplayPendingTurn, az as splitCallTranscript, aA as useAvatarAdaptivePlayoutDelay, aB as useAvatarPlayoutDelay, aC as useAvatarQualityGovernor, aD as useCallTranscript, aE as useLiveKitAvatarGrant, aG as useMicLease, aH as useRealtimeSession, aI as useReleaseMicLeaseOnTrackEnded, aJ as useSessionLifecycle } from './proxy-client-D1Zm7reb.js';
 export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS } from './playout-delay-DWOc8iCl.js';
 import 'zod';
 import '@livekit/components-react';
 import 'livekit-client';
 
+/**
+ * Once a link has proven unstable, hold the frozen live frame this long before
+ * falling back to the idle floor. Measured on a prod rtx6000 call through a
+ * 900 kbit / 150 ms / 10 % loss link (2026-09-09): after the opening, presented-frame
+ * gaps cluster at 650–1150 ms with two multi-second outages around simulcast layer
+ * switches. Nothing shorter than a few seconds is worth a body swap on such a link.
+ */
+declare const DEFAULT_AVATAR_UNSTABLE_STALL_MS = 4000;
+
 declare function useCharacterTools(tools: Record<string, RegisteredTool>, options?: {
     onResult?: (event: {
         name: string;
@@ -120,4 +129,4 @@ declare function useAvatarCall(props: AvatarCallProps): {
 /** One component: a live character on screen. */
 declare function AvatarCall(props: AvatarCallProps): ReactNode;
 
-export { AvatarCall, type AvatarCallEndReason, type AvatarCallHandle, type AvatarCallProps, type AvatarCallStatus, AvatarSessionClient, AvatarVideoFit, useAvatarCall, useCharacterTools };
+export { AvatarCall, type AvatarCallEndReason, type AvatarCallHandle, type AvatarCallProps, type AvatarCallStatus, AvatarSessionClient, AvatarVideoFit, DEFAULT_AVATAR_UNSTABLE_STALL_MS, useAvatarCall, useCharacterTools };

package/dist/react.js

@@ -1038,9 +1038,10 @@ var step = (g, s, nowMs, cfg = DEFAULT_GOVERNOR_CONFIG) => {
       return { governor: g };
   }
 };
-var resolveLowCapQuality = (declaredLayerQualities) => {
+var resolveLowCapQuality = (declaredLayerQualities, failures = 0) => {
   const sorted = [...declaredLayerQualities].sort((a, b) => a - b);
-  return sorted.length >= 2 ? sorted[sorted.length - 2] : 1;
+  if (sorted.length < 2) return 1;
+  return failures >= 1 ? sorted[0] : sorted[sorted.length - 2];
 };
 
 // ../client/src/react/use-quality-governor.ts
@@ -1160,10 +1161,11 @@ function useAvatarQualityGovernor(input) {
         return { freezeMs: 0, jitterRising: false };
       }
     };
-    const applyCap = (cap) => {
+    const applyCap = (cap, failures = 0) => {
       try {
         const lowCap = resolveLowCapQuality(
-          (targetPublication?.trackInfo?.layers ?? []).map((l) => l.quality)
+          (targetPublication?.trackInfo?.layers ?? []).map((l) => l.quality),
+          failures
         );
         targetPublication?.setVideoQuality?.(cap === "low" ? lowCap : VideoQuality.HIGH);
       } catch {
@@ -1188,13 +1190,13 @@ function useAvatarQualityGovernor(input) {
         pausedSinceTick = false;
         const { governor, action } = step(gov, signal, Date.now(), config);
         gov = governor;
-        if (action) applyCap(action.setCap);
+        if (action) applyCap(action.setCap, gov.failures);
       } catch {
       } finally {
         tickRunning = false;
       }
     };
-    applyCap(gov.cap);
+    applyCap(gov.cap, gov.failures);
     const handle = setInterval(() => void tick(), tickMs);
     return () => {
       disposed = true;
@@ -1234,9 +1236,48 @@ var FrameRecovery = class {
     return this.ready;
   }
 };
+var AVATAR_FIRST_FRAME_GRACE_MS = 1e3;
+function firstFrameWaitFreezeMs(waitedMs) {
+  if (!Number.isFinite(waitedMs) || waitedMs <= AVATAR_FIRST_FRAME_GRACE_MS) return 0;
+  return waitedMs - AVATAR_FIRST_FRAME_GRACE_MS;
+}
+var DEFAULT_AVATAR_UNSTABLE_STALL_MS = 4e3;
+var AVATAR_UNSTABLE_LINK_STALLS = 2;
+var AVATAR_UNSTABLE_LINK_WINDOW_MS = 15e3;
+var StallEscalation = class {
+  constructor(baseMs, unstableMs = DEFAULT_AVATAR_UNSTABLE_STALL_MS, windowMs = AVATAR_UNSTABLE_LINK_WINDOW_MS, stallsToEscalate = AVATAR_UNSTABLE_LINK_STALLS) {
+    this.baseMs = baseMs;
+    this.windowMs = windowMs;
+    this.stallsToEscalate = stallsToEscalate;
+    this.unstableMs = Math.max(baseMs, unstableMs);
+  }
+  baseMs;
+  windowMs;
+  stallsToEscalate;
+  stallsAtMs = [];
+  unstableMs;
+  /** Record one stall EPISODE (the moment the live layer is hidden), not one poll tick. */
+  recordStall(nowMs) {
+    this.prune(nowMs);
+    this.stallsAtMs.push(nowMs);
+  }
+  /** The threshold in force right now. */
+  thresholdMs(nowMs) {
+    this.prune(nowMs);
+    return this.stallsAtMs.length >= this.stallsToEscalate ? this.unstableMs : this.baseMs;
+  }
+  /** Is the link currently considered unstable (escalated)? */
+  unstable(nowMs) {
+    return this.thresholdMs(nowMs) !== this.baseMs;
+  }
+  prune(nowMs) {
+    const cutoff = nowMs - this.windowMs;
+    while (this.stallsAtMs.length > 0 && this.stallsAtMs[0] < cutoff) this.stallsAtMs.shift();
+  }
+};
 
 // ../client/src/react/avatar-video-surface.ts
-var DEFAULT_AVATAR_FRAME_STALL_MS = 800;
+var DEFAULT_AVATAR_FRAME_STALL_MS = 2e3;
 var AVATAR_FRAME_GAP_FREEZE_FLOOR_MS = 100;
 function AvatarVideoSurface(props) {
   const {
@@ -1437,7 +1478,7 @@ function isFrameFlowingAt(snapshot) {
 }
 function freezeMsFromFrameGap(gapMs) {
   if (!Number.isFinite(gapMs) || gapMs <= AVATAR_FRAME_GAP_FREEZE_FLOOR_MS) return 0;
-  return gapMs;
+  return gapMs - AVATAR_FRAME_GAP_FREEZE_FLOOR_MS;
 }
 function isFrameFreezeInhibited(snapshot) {
   return snapshot.hidden || snapshot.resumePending || !snapshot.trackProducing || !snapshot.seenFrame || snapshot.lastFrameAtMs === null;
@@ -1445,6 +1486,7 @@ function isFrameFreezeInhibited(snapshot) {
 function useLiveFrameFlow(wrapRef, trackProducing, trackIdentity, stallAfterMs) {
   const boundedStallMs = normalizeFrameStallMs(stallAfterMs);
   const recovery = useMemo(() => new FrameRecovery(boundedStallMs), [trackIdentity, boundedStallMs]);
+  const escalation = useMemo(() => new StallEscalation(boundedStallMs), [trackIdentity, boundedStallMs]);
   const [flowing, setFlowing] = useState(false);
   const [seenFrame, setSeenFrame] = useState(false);
   const flowingRef = useRef(false);
@@ -1452,14 +1494,16 @@ function useLiveFrameFlow(wrapRef, trackProducing, trackIdentity, stallAfterMs)
     seenFrame: false,
     lastFrameAtMs: null,
     maxGapMs: 0,
-    resumePending: false
+    resumePending: false,
+    producingSinceMs: null
   });
   useEffect(() => {
     sampleRef.current = {
       seenFrame: false,
       lastFrameAtMs: null,
       maxGapMs: 0,
-      resumePending: document.visibilityState !== "visible"
+      resumePending: document.visibilityState !== "visible",
+      producingSinceMs: trackProducing ? Date.now() : null
     };
     flowingRef.current = false;
     setSeenFrame(false);
@@ -1477,6 +1521,7 @@ function useLiveFrameFlow(wrapRef, trackProducing, trackIdentity, stallAfterMs)
       lastCurrentTime = video?.currentTime ?? lastCurrentTime;
       const firstFrame = !previous.seenFrame;
       sampleRef.current = {
+        producingSinceMs: previous.producingSinceMs,
         seenFrame: true,
         lastFrameAtMs: now,
         // A hidden tab/bfcache resume is a local scheduling gap, not network
@@ -1488,6 +1533,7 @@ function useLiveFrameFlow(wrapRef, trackProducing, trackIdentity, stallAfterMs)
         resumePending: false
       };
       if (firstFrame) setSeenFrame(true);
+      recovery.stallAfterMs = escalation.thresholdMs(now);
       const nextFlowing = recovery.frame(now);
       if (flowingRef.current !== nextFlowing) {
         flowingRef.current = nextFlowing;
@@ -1533,13 +1579,19 @@ function useLiveFrameFlow(wrapRef, trackProducing, trackIdentity, stallAfterMs)
         lastCurrentTime = video.currentTime;
         markFrame();
       }
+      const nowMs = Date.now();
+      const stallAfterMs2 = escalation.thresholdMs(nowMs);
+      recovery.stallAfterMs = stallAfterMs2;
       const frameFresh = isFrameFlowingAt({
         seenFrame: sampleRef.current.seenFrame,
         lastFrameAtMs: sampleRef.current.lastFrameAtMs,
-        nowMs: Date.now(),
-        stallAfterMs: boundedStallMs
+        nowMs,
+        stallAfterMs: stallAfterMs2
       });
-      if (!frameFresh && sampleRef.current.seenFrame) recovery.stall();
+      if (!frameFresh && sampleRef.current.seenFrame) {
+        if (flowingRef.current) escalation.recordStall(nowMs);
+        recovery.stall();
+      }
       const nextFlowing = frameFresh && recovery.ready;
       if (flowingRef.current !== nextFlowing) {
         flowingRef.current = nextFlowing;
@@ -1553,11 +1605,14 @@ function useLiveFrameFlow(wrapRef, trackProducing, trackIdentity, stallAfterMs)
       stopObserving();
       cancelFrameCallback();
     };
-  }, [wrapRef, trackProducing, trackIdentity, boundedStallMs, recovery]);
+  }, [wrapRef, trackProducing, trackIdentity, boundedStallMs, recovery, escalation]);
   const freezeReading = useCallback(() => {
     const sample = sampleRef.current;
     const lastFrameAtMs = sample.lastFrameAtMs;
     const hidden = typeof document !== "undefined" && document.visibilityState !== "visible";
+    if (!hidden && !sample.resumePending && trackProducing && !sample.seenFrame && sample.producingSinceMs !== null) {
+      return { freezeMsInWindow: firstFrameWaitFreezeMs(Date.now() - sample.producingSinceMs), inhibited: false };
+    }
     const inhibited = isFrameFreezeInhibited({
       hidden,
       resumePending: sample.resumePending,
@@ -3164,4 +3219,4 @@ function createProxyClient(options) {
   };
 }
 
-export { AdaptivePlayoutController, AvatarCall, AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, DEFAULT_CREDITS_LOW_LEAD_SECONDS, DEFAULT_GOVERNOR_CONFIG, DEFAULT_GRACE_CEILING_SECONDS, DEFAULT_GRACE_WINDOW_LEAD_SECONDS, DEFAULT_IDLE_SECONDS, DEFAULT_IDLE_WARN_LEAD_SECONDS, DEFAULT_TURN_TIMEOUT_SECONDS, MAX_RECONNECT_ATTEMPTS, MAX_SESSION_INSTRUCTIONS_CHARS, MIC_LEASE_ENDED_TIMEOUT_MS, RECONNECT_BACKOFF_MS, RealtimeAvatarCapacityError, RealtimeAvatarLiveKitRoom, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, shouldReplayPendingTurn, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarCall, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useCharacterTools, useLiveKitAvatarGrant, useMicLease, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };
+export { AdaptivePlayoutController, AvatarCall, AvatarVideoSurface, DEFAULT_APPROACHING_END_LEAD_SECONDS, DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, DEFAULT_AVATAR_UNSTABLE_STALL_MS, DEFAULT_CREDITS_LOW_LEAD_SECONDS, DEFAULT_GOVERNOR_CONFIG, DEFAULT_GRACE_CEILING_SECONDS, DEFAULT_GRACE_WINDOW_LEAD_SECONDS, DEFAULT_IDLE_SECONDS, DEFAULT_IDLE_WARN_LEAD_SECONDS, DEFAULT_TURN_TIMEOUT_SECONDS, MAX_RECONNECT_ATTEMPTS, MAX_SESSION_INSTRUCTIONS_CHARS, MIC_LEASE_ENDED_TIMEOUT_MS, RECONNECT_BACKOFF_MS, RealtimeAvatarCapacityError, RealtimeAvatarLiveKitRoom, SessionLifecycleRoomBridge, capacityErrorFromBusy, capacityStateFromGrant, createProxyClient, knownBehaviorStates, mapTurnState, readInboundRtp, sessionBehaviorSchema, sessionClipSchema, shouldReplayPendingTurn, splitCallTranscript, useAvatarAdaptivePlayoutDelay, useAvatarCall, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useCharacterTools, useLiveKitAvatarGrant, useMicLease, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };

package/dist/server.d.ts

@@ -1,3 +1,3 @@
 export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, RealtimeAvatarOptions, StartCallOptions, clipLibraryDeclarationSchema, verifyTranscript } from './index.js';
-export { h as Asset, g as AssetKind, A as Avatar, l as AvatarClip, c as AvatarSourceSwap, b as AvatarUpdate, m as CallConnection, C as CallMode, a as CallPolicy, n as CallQueued, o as ClipDeclaration, f as ClipLibrary, d as ClipLibraryDeclaration, p as ClipLibraryPlan, e as ClipLibraryUpdate, q as ClipSource, r as ContextMessage, k as CreditBalance, E as EndCallOptions, s as EndCallReason, i as ListSessionsOptions, L as LoopRedirect, S as StartCallResult, T as TranscriptPayload, j as UsageSession, U as UsageSessionPage, V as VideoPolicy, t as isQueued } from './types-FoJMJimV.js';
+export { h as Asset, g as AssetKind, A as Avatar, l as AvatarClip, c as AvatarSourceSwap, b as AvatarUpdate, m as CallConnection, C as CallMode, a as CallPolicy, n as CallQueued, o as ClipDeclaration, f as ClipLibrary, d as ClipLibraryDeclaration, p as ClipLibraryPlan, e as ClipLibraryUpdate, q as ClipSource, r as ContextMessage, k as CreditBalance, E as EndCallOptions, s as EndCallReason, i as ListSessionsOptions, L as LoopRedirect, S as StartCallResult, T as TranscriptPayload, j as UsageSession, U as UsageSessionPage, V as VideoPolicy, t as isQueued } from './types-nxdohaiH.js';
 import 'zod';

package/dist/server.js

@@ -1 +1 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, verifyTranscript } from './chunk-MBQ2VKLC.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, verifyTranscript } from './chunk-SKXUGNEK.js';

package/dist/tanstack-start.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-DrgyCwLC.js';
-import './types-FoJMJimV.js';
+import { P as ProxyConfig } from './types-9a0bRdXl.js';
+import './types-nxdohaiH.js';
 
 /**
  * TanStack Start. Mount at `routes/api/realtime-avatar/$.ts` — the trailing `$` is Start's

package/dist/tanstack-start.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-RVBBZCVM.js';
-import './chunk-MBQ2VKLC.js';
+import { createProxyHandler } from './chunk-MJJ6GSAU.js';
+import './chunk-SKXUGNEK.js';
 
 // src/tanstack-start.ts
 function realtimeAvatarServerRoute(config) {

package/dist/{types-DrgyCwLC.d.ts → types-9a0bRdXl.d.ts}

@@ -1,4 +1,4 @@
-import { C as CallMode, a as CallPolicy } from './types-FoJMJimV.js';
+import { C as CallMode, a as CallPolicy } from './types-nxdohaiH.js';
 
 /** The three things a caller can ask the proxy to do. Gate on these, not on URLs. */
 type ProxyOperation = "connect" | "end" | "avatars" | "credits";

package/dist/{types-FoJMJimV.d.ts → types-nxdohaiH.d.ts}

@@ -645,6 +645,11 @@ interface components {
             documentation: string;
             /** @description Set when the failure is worth retrying as-is. */
             retryable?: boolean;
+            /**
+             * Format: uuid
+             * @description Server-generated correlation ID, also returned in X-Request-ID on correlated failures. Quote this when contacting support. Detailed diagnostics require separate operational access.
+             */
+            requestId?: string;
             /**
              * @description Present on `403 insufficient_scope` — the one scope this operation needed and the key did not carry. Repeated in the `WWW-Authenticate` challenge as `scope=`.
              * @enum {string}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-avatar",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Realtime Avatar SDK. `realtime-avatar` and the route adapters hold your API key and are server-only; `realtime-avatar/react`, `/browser` and `/tools` never can — importing a server entry into a browser build throws at bundle time.",
   "license": "MIT",
   "author": "The Influence Company",