realtime-avatar 0.3.0

package/dist/react.js

@@ -0,0 +1,2610 @@
+"use client";
+import { useRef, useState, useEffect, useCallback, useMemo, createElement, Fragment } from 'react';
+import { useTranscriptions, useLocalParticipant, RoomAudioRenderer, LiveKitRoom, useMaybeRoomContext, useVoiceAssistant, useConnectionState, VideoTrack, useRoomContext, useChat } from '@livekit/components-react';
+import { ConnectionQuality, RoomEvent, ConnectionState, TrackEvent, Track, VideoQuality, ConnectionError, ConnectionErrorReason, DisconnectReason, Room } from 'livekit-client';
+import { z } from 'zod';
+
+// ../client/src/react/avatar-call.ts
+var holder = null;
+var queue = [];
+var pendingEnded = null;
+function acquireMicLease(token) {
+  if (holder === null || holder === token) {
+    holder = token;
+    if (pendingEnded === token) pendingEnded = null;
+    return Promise.resolve();
+  }
+  const existing = queue.find((w) => w.token === token);
+  if (existing) {
+    return new Promise((resolve) => {
+      const prior = existing.resolve;
+      existing.resolve = () => {
+        prior();
+        resolve();
+      };
+    });
+  }
+  return new Promise((resolve) => {
+    queue.push({ token, resolve });
+  });
+}
+function releaseMicLease(token) {
+  if (holder !== token) {
+    const i = queue.findIndex((w) => w.token === token);
+    if (i !== -1) queue.splice(i, 1);
+    return;
+  }
+  const next = queue.shift();
+  if (next) {
+    holder = next.token;
+    next.resolve();
+  } else {
+    holder = null;
+  }
+}
+function releaseMicLeaseWhenEnded(token, timeoutMs, setTimer) {
+  if (holder !== token) {
+    releaseMicLease(token);
+    return () => {
+    };
+  }
+  pendingEnded = token;
+  const cancelTimer = setTimer(() => {
+    if (pendingEnded === token) finishPendingRelease(token);
+  }, timeoutMs);
+  return cancelTimer;
+}
+function confirmMicTrackEnded(token) {
+  if (pendingEnded === token) finishPendingRelease(token);
+}
+function finishPendingRelease(token) {
+  pendingEnded = null;
+  releaseMicLease(token);
+}
+var MIC_LEASE_ENDED_TIMEOUT_MS = 1500;
+function useMicLease(want) {
+  const tokenRef = useRef(null);
+  if (tokenRef.current === null) tokenRef.current = /* @__PURE__ */ Symbol("mic-lease");
+  const token = tokenRef.current;
+  const [held, setHeld] = useState(false);
+  useEffect(() => {
+    if (!want) {
+      releaseMicLeaseWhenEnded(token, MIC_LEASE_ENDED_TIMEOUT_MS, timeoutSetter);
+      setHeld(false);
+      return;
+    }
+    let alive = true;
+    void acquireMicLease(token).then(() => {
+      if (alive) setHeld(true);
+    });
+    return () => {
+      alive = false;
+      releaseMicLeaseWhenEnded(token, MIC_LEASE_ENDED_TIMEOUT_MS, timeoutSetter);
+    };
+  }, [want, token]);
+  return { held, token };
+}
+function timeoutSetter(fn, ms) {
+  const id = setTimeout(fn, ms);
+  return () => clearTimeout(id);
+}
+
+// ../client/src/errors.ts
+var RealtimeAvatarCapacityError = class extends Error {
+  constructor(message, busy) {
+    super(message);
+    this.busy = busy;
+    this.name = "RealtimeAvatarCapacityError";
+  }
+  busy;
+  get queueSize() {
+    return this.busy.queue_size;
+  }
+  get queuePosition() {
+    return this.busy.queue_position;
+  }
+  get queueTicketId() {
+    return this.busy.queue_ticket_id;
+  }
+  get recommendedRetryMs() {
+    return this.busy.recommended_retry_ms;
+  }
+};
+function splitCallTranscript(all, localIdentity) {
+  if (!localIdentity) return { user: [], agent: all };
+  const user = [];
+  const agent = [];
+  for (const segment of all) {
+    if (segment.participantInfo.identity === localIdentity) user.push(segment);
+    else agent.push(segment);
+  }
+  return { user, agent };
+}
+function useCallTranscript() {
+  const all = useTranscriptions();
+  const { localParticipant } = useLocalParticipant();
+  return splitCallTranscript(all, localParticipant?.identity);
+}
+function useReleaseMicLeaseOnTrackEnded(token) {
+  const { localParticipant } = useLocalParticipant();
+  useEffect(() => {
+    if (!localParticipant) return;
+    const cleanups = [];
+    const watch = (raw) => {
+      if (!raw) return;
+      if (raw.readyState === "ended") {
+        confirmMicTrackEnded(token);
+        return;
+      }
+      const onEnded = () => confirmMicTrackEnded(token);
+      raw.addEventListener("ended", onEnded);
+      cleanups.push(() => raw.removeEventListener("ended", onEnded));
+    };
+    for (const pub of localParticipant.audioTrackPublications.values()) {
+      watch(pub.track?.mediaStreamTrack);
+    }
+    return () => {
+      for (const c of cleanups) c();
+    };
+  }, [localParticipant, token, localParticipant?.audioTrackPublications.size]);
+}
+var DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS = 0.5;
+function useAvatarPlayoutDelay(videoTrack, audioTrack, delaySeconds = DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS) {
+  const videoMediaTrack = videoTrack?.publication?.track;
+  const audioMediaTrack = audioTrack?.publication?.track;
+  useEffect(() => {
+    applyAvatarPlayoutDelay(videoMediaTrack, audioMediaTrack, delaySeconds);
+  }, [videoMediaTrack, audioMediaTrack, delaySeconds]);
+}
+function applyAvatarPlayoutDelay(videoTrack, audioTrack, delaySeconds = DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS) {
+  const delay = Math.max(0, delaySeconds);
+  playoutDelayTarget(videoTrack)?.setPlayoutDelay(delay);
+  playoutDelayTarget(audioTrack)?.setPlayoutDelay(delay);
+}
+function playoutDelayTarget(track) {
+  const candidate = track;
+  return typeof candidate?.setPlayoutDelay === "function" ? candidate : void 0;
+}
+function resolveReleaseTarget(heldSessionId, queueTicketId) {
+  if (heldSessionId) return { kind: "session", sessionId: heldSessionId };
+  if (queueTicketId) return { kind: "ticket", queueTicketId };
+  return { kind: "none" };
+}
+function capacityStateFromGrant(state) {
+  switch (state.status) {
+    case "busy":
+      if (state.busy) return { kind: "queued", busy: state.busy };
+      return { kind: "connecting" };
+    case "failed":
+      return { kind: "error", error: state.error ?? new Error("Realtime session request failed") };
+    case "ready":
+      return state.grant ? { kind: "active", grant: state.grant } : { kind: "connecting" };
+    case "requesting":
+      return { kind: "connecting" };
+    case "idle":
+    default:
+      return { kind: "idle" };
+  }
+}
+var cachedClientId = null;
+function randomClientId() {
+  return globalThis.crypto?.randomUUID?.() ?? `c_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+}
+function stableClientId() {
+  if (cachedClientId) return cachedClientId;
+  try {
+    const key = "rta.client_id";
+    const existing = globalThis.localStorage?.getItem(key) ?? null;
+    if (existing) return cachedClientId = existing;
+    const fresh = randomClientId();
+    globalThis.localStorage?.setItem(key, fresh);
+    return cachedClientId = fresh;
+  } catch {
+    return cachedClientId = randomClientId();
+  }
+}
+function createConnectionWarmer(prepare) {
+  const warmed = /* @__PURE__ */ new Set();
+  return (url) => {
+    const valid = validWarmUrl(url);
+    if (!valid || warmed.has(valid)) return;
+    warmed.add(valid);
+    prepare(valid);
+  };
+}
+function validWarmUrl(value) {
+  if (!value) return null;
+  try {
+    const { protocol } = new URL(value);
+    return protocol === "wss:" || protocol === "ws:" || protocol === "https:" || protocol === "http:" ? value : null;
+  } catch {
+    return null;
+  }
+}
+var warmRoom = null;
+var warmLiveKitHost = createConnectionWarmer((url) => {
+  try {
+    warmRoom ??= new Room();
+    void warmRoom.prepareConnection(url);
+  } catch {
+  }
+});
+var LIVEKIT_URL_HINT_KEY = "rta.livekit_url_hint";
+var cachedUrlHint = null;
+function readLiveKitUrlHint() {
+  try {
+    return validWarmUrl(globalThis.localStorage?.getItem(LIVEKIT_URL_HINT_KEY)) ?? cachedUrlHint;
+  } catch {
+    return cachedUrlHint;
+  }
+}
+function writeLiveKitUrlHint(url) {
+  if (!validWarmUrl(url)) return;
+  cachedUrlHint = url;
+  try {
+    globalThis.localStorage?.setItem(LIVEKIT_URL_HINT_KEY, url);
+  } catch {
+  }
+}
+function useLiveKitAvatarGrant(input) {
+  const { client, session, active = true, autoRetryBusy = false, requestOptions, serverUrlHint } = input;
+  const [version, setVersion] = useState(0);
+  const queueTicketRef = useRef(null);
+  const clientIdRef = useRef(stableClientId());
+  const heldSessionRef = useRef(null);
+  const releaseHeld = useCallback(
+    (reason, viaBeacon) => {
+      const target = resolveReleaseTarget(heldSessionRef.current, queueTicketRef.current);
+      if (target.kind === "none") return;
+      if (target.kind === "session") {
+        heldSessionRef.current = null;
+        if (viaBeacon && client.releaseLiveKitSessionBeacon(target.sessionId, reason)) return;
+        void client.releaseLiveKitSession(target.sessionId, reason);
+        return;
+      }
+      queueTicketRef.current = null;
+      if (viaBeacon && client.releaseLiveKitQueueTicketBeacon(target.queueTicketId, reason)) return;
+      void client.releaseLiveKitQueueTicket(target.queueTicketId, reason);
+    },
+    [client]
+  );
+  const sessionKey = useMemo(() => session ? stableStringify(session) : null, [session]);
+  const sessionRef = useRef(session);
+  sessionRef.current = session;
+  const serverUrlHintRef = useRef(serverUrlHint);
+  serverUrlHintRef.current = serverUrlHint;
+  const prevKeyRef = useRef(null);
+  const [state, setState] = useState({
+    status: "idle",
+    grant: null,
+    busy: null,
+    error: null
+  });
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const [tabVisible, setTabVisible] = useState(
+    () => typeof document === "undefined" || document.visibilityState === "visible"
+  );
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const onVisibility = () => setTabVisible(document.visibilityState === "visible");
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => document.removeEventListener("visibilitychange", onVisibility);
+  }, []);
+  useEffect(() => {
+    const current = sessionRef.current;
+    if (!active || !current || !sessionKey) {
+      releaseHeld("unmount", false);
+      queueTicketRef.current = null;
+      prevKeyRef.current = sessionKey;
+      setState({ status: "idle", grant: null, busy: null, error: null });
+      return;
+    }
+    if (prevKeyRef.current !== sessionKey) {
+      releaseHeld("superseded", false);
+      queueTicketRef.current = current.queueTicketId ?? null;
+      prevKeyRef.current = sessionKey;
+    }
+    const request = {
+      ...current,
+      queueTicketId: current.queueTicketId ?? queueTicketRef.current ?? clientIdRef.current
+    };
+    let cancelled = false;
+    const prior = stateRef.current;
+    const retryingQueued = prior.status === "busy" && prior.busy !== null;
+    if (!retryingQueued) {
+      warmLiveKitHost(serverUrlHintRef.current ?? readLiveKitUrlHint());
+      setState({ status: "requesting", grant: null, busy: null, error: null });
+    }
+    void client.createLiveKitSessionOrBusy(request, requestOptions).then((result) => {
+      if (cancelled) return;
+      if (result.status === "busy") {
+        queueTicketRef.current = result.busy.queue_ticket_id ?? queueTicketRef.current;
+        setState({ status: "busy", grant: null, busy: result.busy, error: null });
+        return;
+      }
+      queueTicketRef.current = null;
+      if (heldSessionRef.current && heldSessionRef.current !== result.grant.session_id) {
+        releaseHeld("superseded", false);
+      }
+      heldSessionRef.current = result.grant.session_id;
+      writeLiveKitUrlHint(result.grant.livekit_url);
+      setState({ status: "ready", grant: result.grant, busy: null, error: null });
+    }).catch((error) => {
+      if (cancelled) return;
+      setState({
+        status: "failed",
+        grant: null,
+        busy: null,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [active, client, sessionKey, requestOptions, version, releaseHeld]);
+  useEffect(() => {
+    const canListen = typeof window !== "undefined" && typeof window.addEventListener === "function";
+    const onPageHide = () => releaseHeld("page_hide", true);
+    if (canListen) window.addEventListener("pagehide", onPageHide);
+    return () => {
+      if (canListen) window.removeEventListener("pagehide", onPageHide);
+      releaseHeld("unmount", false);
+    };
+  }, [releaseHeld]);
+  const refresh = useCallback(() => setVersion((current) => current + 1), []);
+  const clear = useCallback(() => {
+    releaseHeld("manual", false);
+    queueTicketRef.current = null;
+    setState({ status: "idle", grant: null, busy: null, error: null });
+  }, [releaseHeld]);
+  const release = useCallback(
+    (reason = "disconnected") => releaseHeld(reason, false),
+    [releaseHeld]
+  );
+  useEffect(() => {
+    if (!autoRetryBusy || !active || !tabVisible || state.status !== "busy" || !state.busy) return;
+    const retryMs = Math.max(state.busy.recommended_retry_ms, 250);
+    const timer = window.setTimeout(refresh, retryMs);
+    return () => window.clearTimeout(timer);
+  }, [active, autoRetryBusy, tabVisible, refresh, state.busy, state.status]);
+  const capacityRef = useRef(null);
+  const capacity = useMemo(() => {
+    const next = capacityStateFromGrant(state);
+    const prev = capacityRef.current;
+    if (prev && sameCapacityState(prev, next)) return prev;
+    capacityRef.current = next;
+    return next;
+  }, [state]);
+  return useMemo(
+    () => ({ ...state, capacity, refresh, clear, release }),
+    [state, capacity, refresh, clear, release]
+  );
+}
+function sameCapacityState(a, b) {
+  if (a.kind !== b.kind) return false;
+  switch (a.kind) {
+    case "queued": {
+      const next = b.busy;
+      return a.busy.queue_position === next.queue_position && a.busy.queue_size === next.queue_size && a.busy.recommended_retry_ms === next.recommended_retry_ms;
+    }
+    case "active":
+      return a.grant === b.grant;
+    case "error":
+      return a.error === b.error;
+    default:
+      return true;
+  }
+}
+function RealtimeAvatarLiveKitRoom(props) {
+  const {
+    grant,
+    connect = true,
+    audio,
+    video = false,
+    options,
+    renderRoomAudio = true,
+    children,
+    ...roomProps
+  } = props;
+  const shouldConnect = Boolean(grant && connect);
+  const roomAudio = renderRoomAudio ? createElement(RoomAudioRenderer, { key: "room-audio" }) : null;
+  const roomOptions = { adaptiveStream: false, dynacast: true, ...options };
+  return createElement(
+    LiveKitRoom,
+    {
+      ...roomProps,
+      serverUrl: grant?.livekit_url,
+      token: grant?.participant_token,
+      connect: shouldConnect,
+      audio: audio ?? grant?.stt_mode === "server",
+      video,
+      options: roomOptions
+    },
+    createElement(Fragment, null, children, roomAudio)
+  );
+}
+var capacityErrorFromBusy = (busy) => {
+  return new RealtimeAvatarCapacityError(busy.message, busy);
+};
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const entries = Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(",")}}`;
+}
+
+// ../client/src/react/quality-governor.ts
+var DEFAULT_GOVERNOR_CONFIG = {
+  openingCap: "low",
+  downgradeFreezeMs: 150,
+  probationFreezeMs: 100,
+  openingDwellMs: 2e3,
+  dwellBaseMs: 8e3,
+  dwellMaxMs: 12e4,
+  cleanMs: 3e3,
+  probeMs: 1e4,
+  healthyResetMs: 12e4
+};
+var JITTER_BUFFER_RISE_THRESHOLD_MS = 25;
+function stepJitterBufferTrend(previous, current, riseThresholdMs = JITTER_BUFFER_RISE_THRESHOLD_MS) {
+  const baseline = { ...current, intervalAverageMs: null };
+  if (previous === null || !Number.isFinite(current.delaySeconds) || !Number.isFinite(current.emittedCount) || current.delaySeconds < previous.delaySeconds || current.emittedCount <= previous.emittedCount) {
+    return { state: baseline, rising: false };
+  }
+  const intervalAverageMs = (current.delaySeconds - previous.delaySeconds) * 1e3 / (current.emittedCount - previous.emittedCount);
+  const threshold = Number.isFinite(riseThresholdMs) ? Math.max(0, riseThresholdMs) : 0;
+  const rising = previous.intervalAverageMs !== null && intervalAverageMs > previous.intervalAverageMs + threshold;
+  return {
+    state: { ...current, intervalAverageMs },
+    rising
+  };
+}
+var initGovernor = (nowMs, openingCap = "low") => ({
+  state: openingCap === "high" ? "opening_high" : "opening",
+  cap: openingCap,
+  failures: 0,
+  enteredAtMs: nowMs,
+  healthySinceMs: null
+});
+var isDowngrade = (s, cfg) => s.paused || s.freezeMsInWindow >= cfg.downgradeFreezeMs || s.jitterRising && s.freezeMsInWindow > 0;
+var isProbationFail = (s, cfg) => s.paused || s.freezeMsInWindow >= cfg.probationFreezeMs;
+var isHealthy = (s) => !s.paused && s.freezeMsInWindow === 0 && !s.jitterRising && s.connectionQuality !== "poor" && s.connectionQuality !== "lost";
+var dwellMs = (failures, cfg) => Math.min(cfg.dwellBaseMs * 2 ** failures, cfg.dwellMaxMs);
+var enter = (g, state, cap, nowMs) => ({
+  ...g,
+  state,
+  cap,
+  enteredAtMs: nowMs,
+  healthySinceMs: null
+});
+var step = (g, s, nowMs, cfg = DEFAULT_GOVERNOR_CONFIG) => {
+  if (s.inhibited) {
+    return { governor: g };
+  }
+  const onProbation = g.state === "probing_up" || g.state === "opening_high";
+  const downgradeNow = onProbation ? isProbationFail(s, cfg) : isDowngrade(s, cfg);
+  if (g.cap === "high" && downgradeNow) {
+    const failed = onProbation;
+    return {
+      governor: {
+        ...enter(g, "cap_low_sticky", "low", nowMs),
+        failures: failed ? g.failures + 1 : g.failures
+      },
+      action: { setCap: "low" }
+    };
+  }
+  switch (g.state) {
+    case "opening_high": {
+      if (nowMs - g.enteredAtMs >= cfg.probeMs && isHealthy(s)) {
+        return { governor: enter(g, "cap_high_stable", "high", nowMs) };
+      }
+      return { governor: g };
+    }
+    case "opening": {
+      if (nowMs - g.enteredAtMs >= cfg.openingDwellMs && isHealthy(s)) {
+        return { governor: { ...enter(g, "cap_low_eligible", "low", nowMs), healthySinceMs: nowMs } };
+      }
+      return { governor: g };
+    }
+    case "cap_low_sticky": {
+      const healthy = isHealthy(s);
+      const healthySince = healthy ? g.healthySinceMs ?? nowMs : null;
+      const resetFailures = healthy && healthySince !== null && nowMs - healthySince >= cfg.healthyResetMs;
+      const dwellDone = nowMs - g.enteredAtMs >= dwellMs(g.failures, cfg);
+      if (dwellDone && healthy) {
+        return {
+          governor: {
+            ...enter(g, "cap_low_eligible", "low", nowMs),
+            failures: resetFailures ? 0 : g.failures,
+            healthySinceMs: nowMs
+          }
+        };
+      }
+      return {
+        governor: {
+          ...g,
+          healthySinceMs: healthySince,
+          failures: resetFailures ? 0 : g.failures
+        }
+      };
+    }
+    case "cap_low_eligible": {
+      if (!isHealthy(s)) {
+        return { governor: { ...g, healthySinceMs: null } };
+      }
+      const cleanSince = g.healthySinceMs ?? nowMs;
+      if (nowMs - cleanSince >= cfg.cleanMs) {
+        return {
+          governor: enter(g, "probing_up", "high", nowMs),
+          action: { setCap: "high" }
+        };
+      }
+      return { governor: { ...g, healthySinceMs: cleanSince } };
+    }
+    case "probing_up": {
+      if (nowMs - g.enteredAtMs >= cfg.probeMs) {
+        return { governor: { ...enter(g, "cap_high_stable", "high", nowMs), failures: 0 } };
+      }
+      return { governor: g };
+    }
+    case "cap_high_stable":
+      return { governor: g };
+    default:
+      return { governor: g };
+  }
+};
+var resolveLowCapQuality = (declaredLayerQualities) => {
+  const sorted = [...declaredLayerQualities].sort((a, b) => a - b);
+  return sorted.length >= 2 ? sorted[sorted.length - 2] : 1;
+};
+
+// ../client/src/react/use-quality-governor.ts
+var qualityToSignal = (q) => {
+  switch (q) {
+    case ConnectionQuality.Excellent:
+      return "excellent";
+    case ConnectionQuality.Good:
+      return "good";
+    case ConnectionQuality.Poor:
+      return "poor";
+    case ConnectionQuality.Lost:
+      return "lost";
+    default:
+      return "unknown";
+  }
+};
+function useAvatarQualityGovernor(input) {
+  const { enabled, freezeReading, config = DEFAULT_GOVERNOR_CONFIG, tickMs = 1e3 } = input;
+  const room = useMaybeRoomContext();
+  const { videoTrack } = useVoiceAssistant();
+  const pausedSinceTick = useRef(false);
+  const connQuality = useRef("unknown");
+  const lastFreezeStat = useRef(null);
+  const jitterTrend = useRef(null);
+  useEffect(() => {
+    if (!enabled || !room) return;
+    const targetPublication = videoTrack?.publication;
+    const targetParticipant = videoTrack?.participant;
+    pausedSinceTick.current = false;
+    lastFreezeStat.current = null;
+    jitterTrend.current = null;
+    connQuality.current = qualityToSignal(
+      targetParticipant?.connectionQuality ?? ConnectionQuality.Unknown
+    );
+    const onStreamState = (pub, streamState) => {
+      if (targetPublication && pub !== targetPublication) return;
+      if (streamState === Track.StreamState.Paused) pausedSinceTick.current = true;
+    };
+    const onQuality = (q, participant) => {
+      if (targetParticipant && participant.sid !== targetParticipant.sid) return;
+      connQuality.current = qualityToSignal(q);
+    };
+    try {
+      room.on(RoomEvent.TrackStreamStateChanged, onStreamState);
+      room.on(RoomEvent.ConnectionQualityChanged, onQuality);
+    } catch {
+      return;
+    }
+    let gov = initGovernor(Date.now());
+    const readGetStatsSignals = async () => {
+      try {
+        const track = targetPublication?.track;
+        const stats = await track?.getRTCStatsReport?.();
+        if (!stats) return { freezeMs: 0, jitterRising: false };
+        let frozenTotalMs = 0;
+        let jitterDelaySeconds = 0;
+        let jitterEmittedCount = 0;
+        stats.forEach((r) => {
+          if (r.type === "inbound-rtp" && typeof r.totalFreezesDuration === "number") {
+            frozenTotalMs = r.totalFreezesDuration * 1e3;
+          }
+          if (r.type === "inbound-rtp" && typeof r.jitterBufferDelay === "number" && typeof r.jitterBufferEmittedCount === "number") {
+            jitterDelaySeconds += r.jitterBufferDelay;
+            jitterEmittedCount += r.jitterBufferEmittedCount;
+          }
+        });
+        const now = Date.now();
+        const prev = lastFreezeStat.current;
+        lastFreezeStat.current = { frozen: frozenTotalMs, ts: now };
+        const trend = stepJitterBufferTrend(jitterTrend.current, {
+          delaySeconds: jitterDelaySeconds,
+          emittedCount: jitterEmittedCount
+        });
+        jitterTrend.current = trend.state;
+        return {
+          freezeMs: prev ? Math.max(0, frozenTotalMs - prev.frozen) : 0,
+          jitterRising: trend.rising
+        };
+      } catch {
+        return { freezeMs: 0, jitterRising: false };
+      }
+    };
+    const applyCap = (cap) => {
+      try {
+        const lowCap = resolveLowCapQuality(
+          (targetPublication?.trackInfo?.layers ?? []).map((l) => l.quality)
+        );
+        targetPublication?.setVideoQuality?.(cap === "low" ? lowCap : VideoQuality.HIGH);
+      } catch {
+      }
+    };
+    let disposed = false;
+    let tickRunning = false;
+    const tick = async () => {
+      if (disposed || tickRunning) return;
+      tickRunning = true;
+      try {
+        const rvfc = freezeReading?.() ?? { freezeMsInWindow: 0, inhibited: false };
+        const statsSignals = await readGetStatsSignals();
+        if (disposed) return;
+        const signal = {
+          paused: pausedSinceTick.current,
+          freezeMsInWindow: Math.max(rvfc.freezeMsInWindow, statsSignals.freezeMs),
+          jitterRising: statsSignals.jitterRising,
+          connectionQuality: connQuality.current,
+          inhibited: rvfc.inhibited
+        };
+        pausedSinceTick.current = false;
+        const { governor, action } = step(gov, signal, Date.now(), config);
+        gov = governor;
+        if (action) applyCap(action.setCap);
+      } catch {
+      } finally {
+        tickRunning = false;
+      }
+    };
+    applyCap(gov.cap);
+    const handle = setInterval(() => void tick(), tickMs);
+    return () => {
+      disposed = true;
+      clearInterval(handle);
+      try {
+        room.off(RoomEvent.TrackStreamStateChanged, onStreamState);
+        room.off(RoomEvent.ConnectionQualityChanged, onQuality);
+      } catch {
+      }
+    };
+  }, [enabled, room, videoTrack, freezeReading, config, tickMs]);
+}
+
+// ../client/src/react/avatar-video-surface.ts
+var DEFAULT_AVATAR_FRAME_STALL_MS = 800;
+var AVATAR_FRAME_GAP_FREEZE_FLOOR_MS = 100;
+function AvatarVideoSurface(props) {
+  const {
+    idleVideoUrl,
+    poster = null,
+    live = true,
+    adaptiveQuality = true,
+    openingCap,
+    fit = "contain",
+    aspectRatio,
+    idleReturnDelayMs = 700,
+    frameStallMs = DEFAULT_AVATAR_FRAME_STALL_MS,
+    className,
+    style,
+    children,
+    showLiveBadge = true
+  } = props;
+  const testId = props["data-testid"];
+  const { videoTrack, audioTrack } = useVoiceAssistant();
+  useAvatarPlayoutDelay(videoTrack, audioTrack);
+  const connectionState = useConnectionState();
+  const connected = connectionState === ConnectionState.Connected;
+  const trackProducing = useLiveTrackProducing(videoTrack);
+  const liveWrapRef = useRef(null);
+  const frameFlow = useLiveFrameFlow(
+    liveWrapRef,
+    trackProducing,
+    videoTrack?.publication?.track,
+    frameStallMs
+  );
+  const governorConfig = useMemo(
+    () => ({
+      ...DEFAULT_GOVERNOR_CONFIG,
+      openingCap: openingCap ?? DEFAULT_GOVERNOR_CONFIG.openingCap
+    }),
+    [openingCap]
+  );
+  useAvatarQualityGovernor({
+    // Keep the governor alive across presentation-intent changes; resetting it on
+    // every turn would re-apply LOW and a normal short turn could never earn HIGH.
+    enabled: adaptiveQuality,
+    freezeReading: frameFlow.freezeReading,
+    config: governorConfig
+  });
+  const liveWanted = live && connected && trackProducing && frameFlow.flowing;
+  const networkStalled = trackProducing && frameFlow.seenFrame && !frameFlow.flowing;
+  const showLive = useDebouncedHide(
+    liveWanted,
+    connected && !networkStalled ? idleReturnDelayMs : 0
+  );
+  const liveDims = videoTrack?.publication?.dimensions ?? null;
+  const idleVideoRef = useRef(null);
+  const boxAspect = aspectRatio ?? null;
+  useIdleWhileResting(idleVideoRef, idleVideoUrl, showLive);
+  useLiveResumeOnProducing(liveWrapRef, trackProducing);
+  const fitClass = fit === "cover" ? AVATAR_VIDEO_FIT_COVER : AVATAR_VIDEO_FIT_CONTAIN;
+  const liveLabel = showLive && liveDims && liveDims.width > 0 && liveDims.height > 0 ? `${liveDims.width}\xD7${liveDims.height}` : null;
+  const layers = resolveSurfaceLayers({ idleVideoUrl, poster });
+  const backFitClass = fitClass;
+  const posterLayer = layers.showPoster ? createElement("img", {
+    key: "poster",
+    src: poster,
+    alt: "",
+    "aria-hidden": true,
+    className: joinClass(AVATAR_VIDEO_LAYER, backFitClass),
+    "data-testid": "avatar-poster"
+  }) : null;
+  const idleLayer = layers.showIdleVideo ? createElement("video", {
+    key: "idle",
+    ref: idleVideoRef,
+    src: idleVideoUrl,
+    muted: true,
+    // NATIVE loop, not a scripted boomerang. These clips are generated i2v from
+    // the portrait with a matched head and tail, so the wrap closes on its own —
+    // measured on the shipped roster, every frame of a clip's last 0.1s differs
+    // from its frame 0 on 0.0% of the picture. Boomerang existed for clips that
+    // did NOT close, and it costs what the render platform retired it for:
+    // ambient motion played BACKWARDS (a breath un-inhaling) is an uncanny tell.
+    loop: true,
+    playsInline: true,
+    autoPlay: true,
+    preload: "auto",
+    className: joinClass(AVATAR_VIDEO_LAYER, backFitClass),
+    "data-testid": "avatar-idle-video"
+  }) : null;
+  const frontLayer = createElement(
+    "div",
+    {
+      key: "live",
+      ref: liveWrapRef,
+      className: joinClass(AVATAR_VIDEO_LIVE_WRAP, showLive ? void 0 : "pointer-events-none"),
+      style: {
+        opacity: showLive ? 1 : 0,
+        transitionDuration: "0ms"
+      },
+      "data-testid": "avatar-live-layer",
+      "aria-hidden": !showLive
+    },
+    videoTrack ? createElement(VideoTrack, {
+      trackRef: videoTrack,
+      className: joinClass(AVATAR_VIDEO_LAYER, fitClass),
+      playsInline: true,
+      autoPlay: true,
+      muted: true,
+      "aria-label": "Realtime avatar video"
+    }) : null
+  );
+  const badge = showLiveBadge && showLive ? createElement(
+    "span",
+    { key: "badge", className: AVATAR_VIDEO_BADGE },
+    createElement("span", { key: "dot", className: AVATAR_VIDEO_BADGE_DOT, "aria-hidden": true }),
+    liveLabel ? `live \xB7 ${liveLabel}` : "live"
+  ) : null;
+  return createElement(
+    "div",
+    {
+      className: joinClass(AVATAR_VIDEO_BOX, className),
+      style: boxAspect ? { aspectRatio: boxAspect, ...style } : style,
+      "data-testid": testId
+    },
+    // Deepest → shallowest: poster floor (the always-present face), the idle clip
+    // over it, then the live video. The poster guarantees the surface is never a
+    // black box before/between turns; the idle clip and live render layer over it.
+    posterLayer,
+    idleLayer,
+    frontLayer,
+    badge,
+    children
+  );
+}
+function resolveSurfaceLayers(input) {
+  return {
+    showPoster: Boolean(input.poster),
+    showIdleVideo: Boolean(input.idleVideoUrl)
+  };
+}
+function isLiveTrackProducing(videoTrack) {
+  const mst = videoTrack?.publication?.track?.mediaStreamTrack;
+  return mst != null && mst.readyState === "live" && mst.enabled && !mst.muted;
+}
+function useLiveTrackProducing(videoTrack, isProducing = isLiveTrackProducing) {
+  const publication = videoTrack?.publication;
+  const [producing, setProducing] = useState(() => isProducing(videoTrack));
+  useEffect(() => {
+    if (!publication) {
+      setProducing(false);
+      return;
+    }
+    const sync = () => setProducing(isProducing(videoTrack));
+    sync();
+    publication.on(TrackEvent.Muted, sync);
+    publication.on(TrackEvent.Unmuted, sync);
+    publication.on(TrackEvent.Ended, sync);
+    const mst = publication.track?.mediaStreamTrack;
+    mst?.addEventListener("ended", sync);
+    mst?.addEventListener("mute", sync);
+    mst?.addEventListener("unmute", sync);
+    return () => {
+      publication.off(TrackEvent.Muted, sync);
+      publication.off(TrackEvent.Unmuted, sync);
+      publication.off(TrackEvent.Ended, sync);
+      mst?.removeEventListener("ended", sync);
+      mst?.removeEventListener("mute", sync);
+      mst?.removeEventListener("unmute", sync);
+    };
+  }, [publication, videoTrack?.publication?.track, isProducing]);
+  return producing;
+}
+function normalizeFrameStallMs(value) {
+  if (!Number.isFinite(value)) return DEFAULT_AVATAR_FRAME_STALL_MS;
+  return Math.max(100, Math.min(1e4, value));
+}
+function isFrameFlowingAt(snapshot) {
+  const stallAfterMs = normalizeFrameStallMs(snapshot.stallAfterMs);
+  return snapshot.seenFrame && snapshot.lastFrameAtMs !== null && snapshot.nowMs - snapshot.lastFrameAtMs <= stallAfterMs;
+}
+function freezeMsFromFrameGap(gapMs) {
+  if (!Number.isFinite(gapMs) || gapMs <= AVATAR_FRAME_GAP_FREEZE_FLOOR_MS) return 0;
+  return gapMs;
+}
+function isFrameFreezeInhibited(snapshot) {
+  return snapshot.hidden || snapshot.resumePending || !snapshot.trackProducing || !snapshot.seenFrame || snapshot.lastFrameAtMs === null;
+}
+function useLiveFrameFlow(wrapRef, trackProducing, trackIdentity, stallAfterMs) {
+  const boundedStallMs = normalizeFrameStallMs(stallAfterMs);
+  const [flowing, setFlowing] = useState(false);
+  const [seenFrame, setSeenFrame] = useState(false);
+  const flowingRef = useRef(false);
+  const sampleRef = useRef({
+    seenFrame: false,
+    lastFrameAtMs: null,
+    maxGapMs: 0,
+    resumePending: false
+  });
+  useEffect(() => {
+    sampleRef.current = {
+      seenFrame: false,
+      lastFrameAtMs: null,
+      maxGapMs: 0,
+      resumePending: document.visibilityState !== "visible"
+    };
+    flowingRef.current = false;
+    setSeenFrame(false);
+    setFlowing(false);
+    if (!trackProducing) return;
+    const wrap = wrapRef.current;
+    if (!wrap) return;
+    let video = null;
+    let frameCallbackId = null;
+    let callbackGeneration = 0;
+    let lastCurrentTime = -1;
+    const markFrame = () => {
+      const previous = sampleRef.current;
+      const now = Date.now();
+      const firstFrame = !previous.seenFrame;
+      sampleRef.current = {
+        seenFrame: true,
+        lastFrameAtMs: now,
+        // A hidden tab/bfcache resume is a local scheduling gap, not network
+        // congestion. The first fresh frame becomes the new baseline.
+        maxGapMs: previous.resumePending ? 0 : Math.max(
+          previous.maxGapMs,
+          previous.lastFrameAtMs === null ? 0 : now - previous.lastFrameAtMs
+        ),
+        resumePending: false
+      };
+      if (firstFrame) setSeenFrame(true);
+      if (!flowingRef.current) {
+        flowingRef.current = true;
+        setFlowing(true);
+      }
+    };
+    const cancelFrameCallback = () => {
+      if (video && frameCallbackId !== null && video.cancelVideoFrameCallback) {
+        video.cancelVideoFrameCallback(frameCallbackId);
+      }
+      frameCallbackId = null;
+    };
+    const bind = (next) => {
+      cancelFrameCallback();
+      callbackGeneration += 1;
+      video = next;
+      lastCurrentTime = next?.currentTime ?? -1;
+      if (!next?.requestVideoFrameCallback) return;
+      const generation = callbackGeneration;
+      const onFrame = () => {
+        if (generation !== callbackGeneration || !video) return;
+        markFrame();
+        frameCallbackId = video.requestVideoFrameCallback(onFrame);
+      };
+      frameCallbackId = next.requestVideoFrameCallback(onFrame);
+    };
+    const stopObserving = observeVideoElement(wrap, bind);
+    const inhibitUntilFreshFrame = () => {
+      sampleRef.current.resumePending = true;
+      sampleRef.current.maxGapMs = 0;
+    };
+    const onVisibilityChange = () => {
+      if (document.visibilityState !== "visible") inhibitUntilFreshFrame();
+    };
+    const onPageShow = (event) => {
+      if (event.persisted) inhibitUntilFreshFrame();
+    };
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    window.addEventListener("pageshow", onPageShow);
+    const pollEveryMs = Math.max(100, Math.min(250, Math.floor(boundedStallMs / 2)));
+    const interval = window.setInterval(() => {
+      if (video && video.currentTime > lastCurrentTime + 1e-3) {
+        lastCurrentTime = video.currentTime;
+        markFrame();
+      }
+      const nextFlowing = isFrameFlowingAt({
+        seenFrame: sampleRef.current.seenFrame,
+        lastFrameAtMs: sampleRef.current.lastFrameAtMs,
+        nowMs: Date.now(),
+        stallAfterMs: boundedStallMs
+      });
+      if (flowingRef.current !== nextFlowing) {
+        flowingRef.current = nextFlowing;
+        setFlowing(nextFlowing);
+      }
+    }, pollEveryMs);
+    return () => {
+      window.clearInterval(interval);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+      window.removeEventListener("pageshow", onPageShow);
+      stopObserving();
+      cancelFrameCallback();
+    };
+  }, [wrapRef, trackProducing, trackIdentity, boundedStallMs]);
+  const freezeReading = useCallback(() => {
+    const sample = sampleRef.current;
+    const lastFrameAtMs = sample.lastFrameAtMs;
+    const hidden = typeof document !== "undefined" && document.visibilityState !== "visible";
+    const inhibited = isFrameFreezeInhibited({
+      hidden,
+      resumePending: sample.resumePending,
+      trackProducing,
+      seenFrame: sample.seenFrame,
+      lastFrameAtMs
+    });
+    if (inhibited || lastFrameAtMs === null) {
+      sample.maxGapMs = 0;
+      return { freezeMsInWindow: 0, inhibited: true };
+    }
+    const ongoingGapMs = Math.max(0, Date.now() - lastFrameAtMs);
+    const freezeMsInWindow = freezeMsFromFrameGap(Math.max(sample.maxGapMs, ongoingGapMs));
+    sample.maxGapMs = 0;
+    return { freezeMsInWindow, inhibited: false };
+  }, [trackProducing]);
+  return { flowing, seenFrame, freezeReading };
+}
+function useDebouncedHide(wanted, delayMs) {
+  const [shown, setShown] = useState(wanted);
+  useEffect(() => {
+    if (wanted) {
+      setShown(true);
+      return;
+    }
+    if (delayMs <= 0) {
+      setShown(false);
+      return;
+    }
+    const timer = window.setTimeout(() => setShown(false), delayMs);
+    return () => window.clearTimeout(timer);
+  }, [wanted, delayMs]);
+  return shown;
+}
+function useIdleWhileResting(videoRef, idleVideoUrl, showLive) {
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video || !idleVideoUrl) return;
+    applyIdleRest(video, showLive);
+  }, [videoRef, idleVideoUrl, showLive]);
+}
+function applyIdleRest(video, showLive) {
+  if (showLive) {
+    video.pause();
+    return;
+  }
+  if (video.currentTime !== 0) video.currentTime = 0;
+  if (video.paused) void Promise.resolve(video.play()).catch(() => {
+  });
+}
+function observeVideoElement(wrap, onBind) {
+  let current = wrap.querySelector("video");
+  onBind(current);
+  if (typeof MutationObserver !== "function") {
+    return () => onBind(null);
+  }
+  const observer = new MutationObserver(() => {
+    const next = wrap.querySelector("video");
+    if (next === current) return;
+    current = next;
+    onBind(next);
+  });
+  observer.observe(wrap, { childList: true, subtree: true });
+  return () => {
+    observer.disconnect();
+    onBind(null);
+  };
+}
+var LIVE_RESUME_EVENTS = ["canplay", "playing", "loadeddata"];
+function createLivePlaybackKeeper() {
+  let bound = null;
+  let disposed = false;
+  const resume = () => {
+    if (disposed) return;
+    const el = bound;
+    if (el && el.paused) {
+      void Promise.resolve(el.play()).catch(() => {
+      });
+    }
+  };
+  const unbindListeners = (el) => {
+    if (!el) return;
+    for (const type of LIVE_RESUME_EVENTS) el.removeEventListener(type, resume);
+  };
+  const bind = (video) => {
+    if (disposed || video === bound) return;
+    unbindListeners(bound);
+    bound = video;
+    if (!video) return;
+    for (const type of LIVE_RESUME_EVENTS) video.addEventListener(type, resume);
+    resume();
+  };
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    unbindListeners(bound);
+    bound = null;
+  };
+  return { bind, resume, dispose };
+}
+function useLiveResumeOnProducing(wrapRef, producing) {
+  useEffect(() => {
+    if (!producing) return;
+    const wrap = wrapRef.current;
+    if (!wrap) return;
+    const keeper = createLivePlaybackKeeper();
+    const stopObserving = observeVideoElement(wrap, (video) => keeper.bind(video));
+    const onVisible = () => {
+      if (document.visibilityState === "visible") keeper.resume();
+    };
+    const onPageShow = () => keeper.resume();
+    document.addEventListener("visibilitychange", onVisible);
+    window.addEventListener("pageshow", onPageShow);
+    return () => {
+      document.removeEventListener("visibilitychange", onVisible);
+      window.removeEventListener("pageshow", onPageShow);
+      stopObserving();
+      keeper.dispose();
+    };
+  }, [wrapRef, producing]);
+}
+function joinClass(...parts) {
+  return parts.filter(Boolean).join(" ");
+}
+var AVATAR_VIDEO_BOX = "relative size-full overflow-hidden";
+var AVATAR_VIDEO_LAYER = "absolute inset-0 size-full transform-gpu [image-rendering:auto] [object-position:center_22%]";
+var AVATAR_VIDEO_FIT_CONTAIN = "object-contain";
+var AVATAR_VIDEO_FIT_COVER = "object-cover";
+var AVATAR_VIDEO_LIVE_WRAP = "absolute inset-0 z-20 size-full transition-opacity ease-out";
+var AVATAR_VIDEO_BADGE = "absolute top-2 right-2 z-30 inline-flex items-center gap-1.5 rounded-md bg-black/55 px-1.5 py-0.5 font-mono text-[10px] text-white/85 backdrop-blur-sm";
+var AVATAR_VIDEO_BADGE_DOT = "size-1.5 rounded-full bg-emerald-400";
+var DEFAULT_AVATAR_ID = "maria";
+var DEFAULT_BACKGROUND_ID = "plain_white";
+var sessionModeSchema = z.enum(["avatar", "voice"]);
+var DEFAULT_SESSION_MODE = "avatar";
+var DEFAULT_MAX_SESSION_SECONDS = 1800;
+var avatarSourceKindSchema = z.enum(["portrait", "source_video"]);
+var liveKitSttModeSchema = z.enum(["server", "off"]);
+var renderBackendSchema = z.string();
+var sessionLiveEditSchema = z.object({
+  rules: z.string().min(1).max(2e3),
+  cooldown_seconds: z.number().int().min(5).max(600).optional(),
+  // Which machinery runs the re-edit. Absent ⇒ the server default ("editor"). A deploy
+  // that cannot provide the requested renderer serves the editor lane and logs it,
+  // rather than failing a call that would otherwise have connected fine.
+  renderer: z.enum(["editor", "generative"]).optional()
+}).strict();
+var sessionSupportEditsSchema = z.object({
+  instruction: z.string().min(1).max(1e3),
+  reference_url: z.string().url().optional(),
+  live_edit: sessionLiveEditSchema.optional()
+}).strict();
+var LLM_PROVIDERS = ["local", "gemini", "openai"];
+var llmProviderSchema = z.enum(LLM_PROVIDERS);
+var llmConfigSchema = z.object({
+  backend: llmProviderSchema.optional(),
+  model: z.string().max(200).nullable().optional()
+}).strict();
+var llmSelectionSchema = z.object({
+  provider: llmProviderSchema,
+  model: z.string().max(200).nullable().optional()
+}).strict();
+var liveKitInitialContextMessageSchema = z.object({
+  role: z.enum(["system", "user", "assistant"]),
+  content: z.string().min(1).max(4e3)
+}).strict();
+var CARTESIA_TTS_MODELS = [
+  "cartesia/sonic-2",
+  "cartesia/sonic-2-latest",
+  "cartesia/sonic-3",
+  "cartesia/sonic-3-latest",
+  "cartesia/sonic-turbo",
+  "cartesia/sonic-turbo-latest"
+];
+var cartesiaTtsModelSchema = z.enum(CARTESIA_TTS_MODELS);
+var cartesiaVoiceSpecSchema = z.object({
+  provider: z.literal("cartesia"),
+  model: cartesiaTtsModelSchema.default("cartesia/sonic-3"),
+  voice_id: z.string().min(1).max(120),
+  speed: z.number().min(0.5).max(2).nullable().optional(),
+  emotion: z.string().min(1).max(80).nullable().optional(),
+  language: z.string().min(2).max(16).nullable().optional()
+}).strict();
+var FISH_TTS_MODELS = ["speech-1.6", "s1", "s2-pro", "speech-1.5", "s1-mini"];
+var fishTtsModelSchema = z.enum(FISH_TTS_MODELS);
+var breezeVoiceSpecSchema = z.object({
+  provider: z.literal("breezeblue"),
+  model: z.string().min(1).max(80).default("bluebell-v1-en"),
+  voice_id: z.string().min(1).max(120),
+  guidance_scale: z.number().min(1).max(10).nullable().optional(),
+  instructions: z.string().min(1).max(1e3).nullable().optional(),
+  language: z.string().min(2).max(16).nullable().optional()
+}).strict();
+var fishVoiceSpecSchema = z.object({
+  provider: z.literal("fish"),
+  model: fishTtsModelSchema.default("speech-1.6"),
+  voice_id: z.string().min(1).max(120),
+  speed: z.number().min(0.5).max(2).nullable().optional(),
+  emotion: z.string().min(1).max(80).nullable().optional(),
+  language: z.string().min(2).max(16).nullable().optional()
+}).strict();
+var voiceSpecSchema = z.discriminatedUnion("provider", [
+  cartesiaVoiceSpecSchema,
+  breezeVoiceSpecSchema,
+  fishVoiceSpecSchema
+]);
+var nullableUrlSchema = z.string().url().nullable();
+var clipTriggerSchema = z.enum([
+  "idle",
+  "listen",
+  "think",
+  "directive"
+]);
+var sessionClipSchema = z.object({
+  clip_id: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "clip_id must be a slug").refine((id) => id !== "primary", "'primary' is reserved for the avatar's source video"),
+  source_video_url: z.string().url().optional(),
+  video_cache_id: z.string().min(8).max(160).optional(),
+  max_seconds: z.number().min(1).max(10).optional(),
+  trigger: clipTriggerSchema.optional(),
+  loop: z.boolean().optional(),
+  weight: z.number().min(0).max(100).optional(),
+  crossfade_ms: z.number().int().min(0).max(1e3).optional(),
+  trim_start_ms: z.number().int().min(0).max(2e3).optional(),
+  trim_end_ms: z.number().int().min(0).max(2e3).optional(),
+  // The cue the character reads to decide this clip. `when` is the public name and the
+  // one the docs use; `hint` is the name the wire first shipped under and still accepts.
+  // Both are listed because this object is `.strict()` — omitting `when` would make the
+  // public name a validation error. Send one, never both.
+  when: z.string().min(1).max(120).optional(),
+  hint: z.string().min(1).max(120).optional()
+}).strict().refine((clip) => clip.source_video_url || clip.video_cache_id, {
+  message: "a clip needs source_video_url or video_cache_id"
+}).refine((clip) => !(clip.when && clip.hint), {
+  message: "set `when` or `hint`, not both \u2014 they are the same field",
+  path: ["when"]
+});
+var sessionChoreographySchema = z.object({
+  idle_dwell_min_seconds: z.number().min(1).max(60).optional(),
+  idle_dwell_max_seconds: z.number().min(1).max(120).optional(),
+  special_weight: z.number().min(0).max(100).optional(),
+  start_grace_seconds: z.number().min(0).max(60).optional(),
+  crossfade_ms: z.number().int().min(0).max(1e3).optional(),
+  crossfade_easing: z.enum(["linear", "smooth", "ease_out"]).optional(),
+  wrap_crossfade_ms: z.number().int().min(0).max(1e3).optional()
+}).strict().refine(
+  (c) => c.idle_dwell_min_seconds === void 0 || c.idle_dwell_max_seconds === void 0 || c.idle_dwell_min_seconds <= c.idle_dwell_max_seconds,
+  { message: "idle_dwell_min_seconds must be <= idle_dwell_max_seconds" }
+);
+var sessionBehaviorSchema = z.object({
+  gestures_enabled: z.boolean().optional(),
+  gesture_freq: z.enum(["sparse", "balanced", "lively"]).optional()
+}).strict();
+var _SCENE_CLIP_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+var sceneIdSchema = z.string().regex(/^[a-z0-9_]{1,40}$/, "scene_id must be a lowercase slug");
+var sceneTransitionSchema = z.object({
+  clip_id: z.string().regex(_SCENE_CLIP_ID_RE, "clip_id must be a slug"),
+  source_video_url: z.string().url(),
+  from_scene: sceneIdSchema,
+  to_scene: sceneIdSchema,
+  max_seconds: z.number().min(1).max(10).optional()
+}).strict().superRefine((v, ctx) => {
+  if (v.from_scene === v.to_scene) {
+    ctx.addIssue({ code: "custom", message: "a transition's from_scene must differ from to_scene", path: ["to_scene"] });
+  }
+});
+var sceneClusterSchema = z.object({
+  scene_id: sceneIdSchema,
+  hub_clip_id: z.string().regex(_SCENE_CLIP_ID_RE, "hub_clip_id must be a slug"),
+  clips: z.array(sessionClipSchema).min(1).max(4)
+}).strict();
+var sceneGraphSchema = z.object({
+  scenes: z.array(sceneClusterSchema).min(1).max(4),
+  transitions: z.array(sceneTransitionSchema).min(2).max(12)
+}).strict();
+var transcriptWebhookSchema = z.object({
+  url: z.string().url().max(500),
+  secret: z.string().min(16).max(200)
+}).strict();
+var clientMetadataSchema = z.record(z.string().min(1).max(64), z.string().max(200)).refine((value) => Object.keys(value).length <= 16, {
+  message: "client_metadata carries at most 16 entries"
+});
+var MAX_SESSION_INSTRUCTIONS_CHARS = 4e3;
+z.object({
+  avatar_id: z.string().min(1).max(160).default(DEFAULT_AVATAR_ID),
+  background_id: z.string().min(1).max(160).default(DEFAULT_BACKGROUND_ID),
+  mode: sessionModeSchema.default(DEFAULT_SESSION_MODE),
+  create_room: z.boolean().default(true),
+  dispatch_agent: z.boolean().default(true),
+  instructions: z.string().min(1).max(MAX_SESSION_INSTRUCTIONS_CHARS).optional(),
+  initial_context: z.array(liveKitInitialContextMessageSchema).max(32).default([]),
+  initial_say: z.string().min(1).max(1e3).optional(),
+  llm: llmConfigSchema.nullable().optional(),
+  max_session_seconds: z.number().int().min(1).max(DEFAULT_MAX_SESSION_SECONDS).optional(),
+  participant_identity: z.string().min(1).max(160).optional(),
+  participant_name: z.string().max(160).optional(),
+  queue_ticket_id: z.string().min(1).max(160).optional(),
+  portrait_url: nullableUrlSchema.optional(),
+  room_name: z.string().min(1).max(160).optional(),
+  source_kind: avatarSourceKindSchema.default("portrait"),
+  source_video_url: nullableUrlSchema.optional(),
+  stt_mode: liveKitSttModeSchema.default("server"),
+  video_cache_id: z.string().min(1).max(240).nullable().optional(),
+  voice: voiceSpecSchema.nullable().optional(),
+  voice_id: z.string().min(1).max(240).nullable().optional(),
+  // Deliberately UNBOUNDED. This object is `.strict()`, so it rejects rather than trims:
+  // a count cap here does not mean "use fewer clips", it means "there is no call". How
+  // many a session actually warms is decided where the clips are loaded, and loading
+  // fewer is always safe — so the wire must not hold a number too.
+  clip_library: z.array(sessionClipSchema).optional(),
+  choreography: sessionChoreographySchema.optional(),
+  scene_graph: sceneGraphSchema.optional(),
+  behavior: sessionBehaviorSchema.optional(),
+  expression_profile: z.string().min(1).max(40).optional(),
+  render_backend: renderBackendSchema.optional(),
+  support_edits: sessionSupportEditsSchema.optional(),
+  transcript_webhook: transcriptWebhookSchema.optional(),
+  client_metadata: clientMetadataSchema.optional()
+}).strict().superRefine((value, ctx) => {
+  if (value.support_edits && value.render_backend === "generative") {
+    ctx.addIssue({
+      code: "custom",
+      message: "support_edits needs a source video to edit; it cannot be combined with render_backend='generative'",
+      path: ["support_edits"]
+    });
+  }
+  if (value.support_edits && value.mode === "voice") {
+    ctx.addIssue({
+      code: "custom",
+      message: "support_edits needs a video session; it cannot be combined with mode='voice'",
+      path: ["support_edits"]
+    });
+  }
+  if (value.source_kind === "portrait") {
+    if (value.source_video_url || value.video_cache_id) {
+      ctx.addIssue({
+        code: "custom",
+        message: "source_video_url/video_cache_id require source_kind='source_video'",
+        path: ["source_kind"]
+      });
+    }
+    return;
+  }
+  if (value.portrait_url) {
+    ctx.addIssue({
+      code: "custom",
+      message: "portrait_url cannot be combined with source_kind='source_video'",
+      path: ["portrait_url"]
+    });
+  }
+  if (!value.source_video_url && !value.video_cache_id) {
+    ctx.addIssue({
+      code: "custom",
+      message: "source_kind='source_video' requires source_video_url or video_cache_id",
+      path: ["source_video_url"]
+    });
+  }
+});
+z.object({
+  avatarId: z.string().min(1).max(160),
+  backgroundId: z.string().min(1).max(160).default(DEFAULT_BACKGROUND_ID),
+  mode: sessionModeSchema.default(DEFAULT_SESSION_MODE),
+  createRoom: z.boolean().default(true),
+  dispatchAgent: z.boolean().default(true),
+  instructions: z.string().min(1).max(MAX_SESSION_INSTRUCTIONS_CHARS).optional(),
+  initialContext: z.array(liveKitInitialContextMessageSchema).max(32).default([]),
+  initialSay: z.string().min(1).max(1e3).optional(),
+  llm: llmSelectionSchema.nullable().optional(),
+  maxSessionSeconds: z.number().int().min(1).max(DEFAULT_MAX_SESSION_SECONDS).optional(),
+  participantIdentity: z.string().min(1).max(160).optional(),
+  participantName: z.string().max(160).optional(),
+  queueTicketId: z.string().min(1).max(160).optional(),
+  roomName: z.string().min(1).max(160).optional(),
+  sttMode: liveKitSttModeSchema.default("server"),
+  voice: voiceSpecSchema.nullable().optional(),
+  voiceId: z.string().min(1).max(240).nullable().optional(),
+  // Unbounded, for the same reason as `clip_library` on the wire schema above.
+  clipLibrary: z.array(sessionClipSchema).optional(),
+  sceneGraph: sceneGraphSchema.optional(),
+  behavior: sessionBehaviorSchema.optional(),
+  renderBackend: renderBackendSchema.optional(),
+  supportEdits: sessionSupportEditsSchema.optional(),
+  transcriptWebhook: transcriptWebhookSchema.optional(),
+  clientMetadata: clientMetadataSchema.optional()
+}).strict();
+z.object({
+  status: z.literal("ready").default("ready"),
+  session_id: z.string().min(1),
+  room_name: z.string().min(1),
+  livekit_url: z.string().min(1),
+  participant_token: z.string().min(1),
+  participant_identity: z.string().min(1),
+  reservation_expires_at: z.string().datetime({ offset: true }),
+  stt_mode: liveKitSttModeSchema.default("server"),
+  room_created: z.boolean().default(false),
+  dispatch_created: z.boolean().default(false),
+  join_timeout_seconds: z.number().int().nonnegative().default(0),
+  idle_timeout_seconds: z.number().int().nonnegative().default(0),
+  max_session_seconds: z.number().int().nonnegative().default(0)
+}).passthrough();
+var RTA_LIFECYCLE_TOPIC = "rta.lifecycle";
+var RTA_TURN_INSTRUCTIONS_ATTR = "rta.turn_instructions";
+var RTA_CLOSING_TURN_ATTR = "rta.closing_turn";
+var RTA_TURN_ID_ATTR = "rta.turn_id";
+var sessionEndReasonSchema = z.enum([
+  "user_ended",
+  "session_cap",
+  "idle",
+  "disconnected",
+  "out_of_credits",
+  "agent_ended",
+  "failed"
+]);
+var approachingEndReasonSchema = z.enum(["session_cap", "idle"]);
+var sessionClockFrameSchema = z.object({
+  kind: z.literal("session_clock"),
+  started_at_unix_ms: z.number().int().nonnegative(),
+  max_session_seconds: z.number().int().nonnegative(),
+  idle_timeout_seconds: z.number().int().nonnegative()
+}).strict();
+var endingFrameSchema = z.object({ kind: z.literal("ending"), reason: approachingEndReasonSchema }).strict();
+var closingTurnDoneFrameSchema = z.object({ kind: z.literal("closing_turn_done"), turn_id: z.string().min(1) }).strict();
+var endedFrameSchema = z.object({ kind: z.literal("ended"), reason: sessionEndReasonSchema }).strict();
+var knownBehaviorStates = ["idle", "listening", "thinking", "speaking"];
+var behaviorStateFrameSchema = z.object({
+  kind: z.literal("behavior_state"),
+  state: z.string().min(1).max(32),
+  clip_id: z.string().min(1).max(64).optional(),
+  trigger: clipTriggerSchema.optional(),
+  loop: z.boolean().optional(),
+  prev_clip_id: z.string().min(1).max(64).optional(),
+  scene: z.string().min(1).max(40).optional(),
+  scene_transition: z.object({
+    clip_id: z.string().min(1).max(64),
+    from_scene: z.string().min(1).max(40),
+    to_scene: z.string().min(1).max(40)
+  }).optional()
+}).strip();
+var clipAckFrameSchema = z.object({
+  kind: z.literal("clip_ack"),
+  request_id: z.string().max(64),
+  accepted: z.boolean(),
+  reason: z.string().max(64)
+}).strip();
+var lifecycleServerFrameSchema = z.discriminatedUnion("kind", [
+  sessionClockFrameSchema,
+  endingFrameSchema,
+  closingTurnDoneFrameSchema,
+  endedFrameSchema,
+  behaviorStateFrameSchema,
+  clipAckFrameSchema
+]);
+var liveKitCapacitySnapshotSchema = z.object({
+  // Placement identity + per-worker session ceiling. These are always present on the
+  // wire (the platform serializes them and they come back on the grant, so a customer
+  // already sees them) but are typed OPTIONAL here on purpose: this SDK is the defensive
+  // READER of that wire, so a consumer must tolerate a response variant that omits them
+  // rather than hard-fail parse. `max_sessions_per_gpu` is how many sessions one waking
+  // worker serves — a queue-depth estimate input a consumer reads off the busy response.
+  capacity_pool: z.string().min(1).optional(),
+  agent_name: z.string().min(1).optional(),
+  max_sessions: z.number().int().nonnegative(),
+  max_sessions_per_gpu: z.number().int().positive().optional(),
+  worker_count: z.number().int().nonnegative(),
+  active_sessions: z.number().int().nonnegative(),
+  reserved_sessions: z.number().int().nonnegative(),
+  observed_worker_active_sessions: z.number().int().nonnegative(),
+  available_sessions: z.number().int().nonnegative(),
+  queue_size: z.number().int().nonnegative(),
+  admission_open: z.boolean(),
+  recommended_retry_ms: z.number().int().nonnegative(),
+  load: z.number().min(0).max(1)
+}).passthrough();
+z.object({
+  message: z.string().min(1),
+  capacity: liveKitCapacitySnapshotSchema,
+  queue_size: z.number().int().nonnegative(),
+  queue_ticket_id: z.string().min(1).optional(),
+  queue_position: z.number().int().positive().optional(),
+  recommended_retry_ms: z.number().int().nonnegative()
+}).strict();
+z.enum([
+  "page_hide",
+  "disconnected",
+  "superseded",
+  "unmount",
+  "manual",
+  "idle_timeout"
+]);
+
+// ../client/src/react/behavior-snapshot.ts
+function nextBehaviorSnapshot(prev, frame) {
+  const next = {
+    state: frame.state,
+    clipId: frame.clip_id ?? null,
+    trigger: frame.trigger ?? null,
+    loop: frame.loop ?? null,
+    prevClipId: frame.prev_clip_id ?? null
+  };
+  if (prev && prev.state === next.state && prev.clipId === next.clipId && prev.trigger === next.trigger && prev.loop === next.loop && prev.prevClipId === next.prevClipId)
+    return null;
+  return next;
+}
+
+// ../client/src/react/session-lifecycle.ts
+function phaseForReason(reason) {
+  switch (reason) {
+    case DisconnectReason.CLIENT_INITIATED:
+      return "ignore";
+    case DisconnectReason.ROOM_DELETED:
+    case DisconnectReason.SERVER_SHUTDOWN:
+    case DisconnectReason.DUPLICATE_IDENTITY:
+    case DisconnectReason.PARTICIPANT_REMOVED:
+      return "ended";
+    default:
+      return "reconnecting";
+  }
+}
+function disconnectAction(reason, _everConnected) {
+  const phase = phaseForReason(reason);
+  if (phase === "ignore") return "reset";
+  if (phase === "ended") return "end";
+  return "reconnect";
+}
+function isRecoverableConnectionError(error) {
+  if (!(error instanceof ConnectionError)) return false;
+  switch (error.reason) {
+    case ConnectionErrorReason.ServerUnreachable:
+    case ConnectionErrorReason.InternalError:
+    case ConnectionErrorReason.Timeout:
+    case ConnectionErrorReason.WebSocket:
+      return true;
+    default:
+      return false;
+  }
+}
+function shouldReplayPendingTurn(args) {
+  const { wasReconnecting, hasPendingTurn, sessionId, lastReplayedSessionId } = args;
+  if (!wasReconnecting || !hasPendingTurn || !sessionId) return false;
+  return lastReplayedSessionId !== sessionId;
+}
+var RECONNECT_BACKOFF_MS = [800, 2e3, 4e3];
+var MAX_RECONNECT_ATTEMPTS = 4;
+function resolveReconnectPolicy(override) {
+  const backoff = override?.backoffMs?.filter((ms) => Number.isFinite(ms) && ms > 0) ?? [];
+  const backoffMs = backoff.length > 0 ? backoff : RECONNECT_BACKOFF_MS;
+  const max = override?.maxAttempts;
+  const maxAttempts = typeof max === "number" && Number.isFinite(max) && max > 0 ? Math.floor(max) : MAX_RECONNECT_ATTEMPTS;
+  return { backoffMs, maxAttempts };
+}
+function retryStep(attempt, policy = resolveReconnectPolicy()) {
+  if (attempt >= policy.maxAttempts) return { kind: "give-up" };
+  const delayMs = policy.backoffMs[Math.min(attempt, policy.backoffMs.length - 1)];
+  return { kind: "retry", delayMs, attempt: attempt + 1 };
+}
+function idlePhaseFor(args) {
+  const { connected, agentPresent, msSinceActivity, idleTimeoutMs, warnAtMs } = args;
+  if (!connected || !agentPresent || idleTimeoutMs <= 0) return { kind: "inactive" };
+  const remainingMs = idleTimeoutMs - msSinceActivity;
+  if (remainingMs > warnAtMs) return { kind: "live" };
+  const secondsRemaining = Math.max(0, Math.ceil(remainingMs / 1e3));
+  return { kind: "idle-warning", secondsRemaining };
+}
+function idleExpired(args) {
+  const { msSinceActivity, idleTimeoutMs } = args;
+  if (idleTimeoutMs <= 0) return false;
+  return msSinceActivity >= idleTimeoutMs;
+}
+function needsFreshGrant(recovery) {
+  return recovery.kind === "reconnecting";
+}
+function lifecyclePhaseFrom(args) {
+  const { capacity, recovery, idle, connected, agentPresent } = args;
+  if (recovery.kind === "in-place-reconnecting") {
+    return { kind: "reconnectable", reconnecting: true, attempt: 0, strategy: "in-place" };
+  }
+  if (recovery.kind === "refreshing" || recovery.kind === "reconnecting") {
+    return {
+      kind: "reconnectable",
+      reconnecting: true,
+      attempt: recovery.attempt,
+      strategy: "fresh-grant"
+    };
+  }
+  if (recovery.kind === "failed") {
+    return {
+      kind: "reconnectable",
+      reconnecting: false,
+      attempt: MAX_RECONNECT_ATTEMPTS,
+      strategy: "fresh-grant"
+    };
+  }
+  if (recovery.kind === "ended") {
+    return recovery.reason ? { kind: "ended", reason: recovery.reason } : { kind: "ended" };
+  }
+  switch (capacity.kind) {
+    case "idle":
+      return { kind: "idle" };
+    case "connecting":
+      return { kind: "requesting" };
+    case "queued":
+      return { kind: "queued", busy: capacity.busy };
+    case "error":
+      return { kind: "ended", reason: "error" };
+    case "active": {
+      if (!connected || !agentPresent) {
+        return { kind: "connecting", grant: capacity.grant };
+      }
+      if (idle.kind === "idle-warning") {
+        return { kind: "idle-warning", secondsRemaining: idle.secondsRemaining, deadlineAt: idle.deadlineAt };
+      }
+      return { kind: "live" };
+    }
+    default:
+      return { kind: "idle" };
+  }
+}
+function isCallActivity(args) {
+  const { assistantState, transcriptionCount, prevTranscriptionCount } = args;
+  if (assistantState === "speaking" || assistantState === "thinking") return true;
+  return transcriptionCount > prevTranscriptionCount;
+}
+var DEFAULT_IDLE_SECONDS = 120;
+var DEFAULT_IDLE_WARN_LEAD_SECONDS = 20;
+var DEFAULT_TURN_TIMEOUT_SECONDS = 20;
+function resolveIdleTimeoutMs(args) {
+  const { idleSecondsOption, grantIdleSeconds } = args;
+  if (typeof idleSecondsOption === "number" && idleSecondsOption > 0) {
+    return Math.floor(idleSecondsOption) * 1e3;
+  }
+  if (grantIdleSeconds > 0) return grantIdleSeconds * 1e3;
+  return DEFAULT_IDLE_SECONDS * 1e3;
+}
+function resolveWarnBeforeMs(idleTimeoutMs, override, idleWarnLeadSeconds) {
+  if (idleTimeoutMs <= 0) return 0;
+  const maxLeadMs = Math.max(0, idleTimeoutMs - 1e3);
+  let leadMs;
+  if (typeof idleWarnLeadSeconds === "number" && idleWarnLeadSeconds > 0) {
+    leadMs = Math.floor(idleWarnLeadSeconds) * 1e3;
+  } else if (typeof override === "number" && override > 0) {
+    leadMs = override;
+  } else {
+    leadMs = DEFAULT_IDLE_WARN_LEAD_SECONDS * 1e3;
+  }
+  return Math.min(leadMs, maxLeadMs);
+}
+function useSessionLifecycle(input) {
+  const {
+    client,
+    session,
+    active = true,
+    idleSeconds,
+    idleWarnLeadSeconds,
+    warnBeforeMs,
+    reconnectBackoffMs,
+    maxReconnectAttempts,
+    autoRetryBusy = true,
+    requestOptions,
+    onBehaviorChange
+  } = input;
+  const reconnectPolicy = useMemo(
+    () => resolveReconnectPolicy({ backoffMs: reconnectBackoffMs, maxAttempts: maxReconnectAttempts }),
+    [reconnectBackoffMs, maxReconnectAttempts]
+  );
+  const reconnectPolicyRef = useRef(reconnectPolicy);
+  reconnectPolicyRef.current = reconnectPolicy;
+  const grantState = useLiveKitAvatarGrant({
+    client,
+    session,
+    active,
+    autoRetryBusy,
+    requestOptions
+  });
+  const capacity = grantState.capacity;
+  const [recovery, setRecovery] = useState({ kind: "connected" });
+  const recoveryRef = useRef(recovery);
+  recoveryRef.current = recovery;
+  const [attempt, setAttempt] = useState(0);
+  const connectedRef = useRef(false);
+  const attemptRef = useRef(0);
+  const timerRef = useRef(null);
+  const manualReconnectPendingRef = useRef(false);
+  const refreshRef = useRef(grantState.refresh);
+  refreshRef.current = grantState.refresh;
+  const releaseRef = useRef(grantState.release);
+  releaseRef.current = grantState.release;
+  const capacityRef = useRef(capacity);
+  capacityRef.current = capacity;
+  const refreshBaselineCapacityRef = useRef(null);
+  const idleTimeoutMs = resolveIdleTimeoutMs({
+    idleSecondsOption: idleSeconds,
+    grantIdleSeconds: grantState.grant?.idle_timeout_seconds ?? 0
+  });
+  const warnAtMs = resolveWarnBeforeMs(idleTimeoutMs, warnBeforeMs, idleWarnLeadSeconds);
+  const [agentPresent, setAgentPresentState] = useState(false);
+  const [connected, setConnected] = useState(false);
+  const lastActivityRef = useRef(Date.now());
+  const leaveRoomRef = useRef(null);
+  const [, setClockTick] = useState(0);
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      window.clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+  const reset = useCallback(() => {
+    clearTimer();
+    connectedRef.current = false;
+    manualReconnectPendingRef.current = false;
+    refreshBaselineCapacityRef.current = null;
+    attemptRef.current = 0;
+    setAttempt(0);
+    setRecovery({ kind: "connected" });
+    setConnected(false);
+    setAgentPresentState(false);
+    lastActivityRef.current = Date.now();
+  }, [clearTimer]);
+  useEffect(() => {
+    if (!active) reset();
+  }, [active, reset]);
+  const markActivity = useCallback(() => {
+    lastActivityRef.current = Date.now();
+    setClockTick((value) => value + 1);
+  }, []);
+  const stayConnected = useCallback(() => {
+    if (!connectedRef.current) return;
+    lastActivityRef.current = Date.now();
+    setClockTick((value) => value + 1);
+  }, []);
+  const setAgentPresent = useCallback((present) => {
+    setAgentPresentState((prev) => {
+      if (present && !prev) lastActivityRef.current = Date.now();
+      return present;
+    });
+  }, []);
+  const registerLeaveRoom = useCallback((leave) => {
+    leaveRoomRef.current = leave;
+  }, []);
+  const endIdle = useCallback(() => {
+    if (!connectedRef.current) return;
+    clearTimer();
+    connectedRef.current = false;
+    setConnected(false);
+    setAgentPresentState(false);
+    releaseRef.current("idle_timeout");
+    setRecovery({ kind: "ended", reason: "idle" });
+    leaveRoomRef.current?.();
+  }, [clearTimer]);
+  const onConnected = useCallback(() => {
+    clearTimer();
+    connectedRef.current = true;
+    manualReconnectPendingRef.current = false;
+    refreshBaselineCapacityRef.current = null;
+    setConnected(true);
+    attemptRef.current = 0;
+    setAttempt(0);
+    setRecovery({ kind: "connected" });
+    lastActivityRef.current = Date.now();
+  }, [clearTimer]);
+  const onDisconnected = useCallback(
+    (reason) => {
+      if (!active) return;
+      const action = disconnectAction(reason, connectedRef.current);
+      if (action === "noop") return;
+      if (action === "reset") {
+        if (recoveryRef.current.kind === "refreshing") return;
+        reset();
+        return;
+      }
+      connectedRef.current = false;
+      setConnected(false);
+      setAgentPresentState(false);
+      if (action === "end") {
+        manualReconnectPendingRef.current = false;
+        refreshBaselineCapacityRef.current = null;
+        releaseRef.current("disconnected");
+        setRecovery({ kind: "ended" });
+        return;
+      }
+      refreshBaselineCapacityRef.current = null;
+      setRecovery({ kind: "reconnecting", attempt: attemptRef.current });
+    },
+    [active, reset]
+  );
+  const onConnectionError = useCallback(
+    (error) => {
+      if (!active || !isRecoverableConnectionError(error)) return;
+      connectedRef.current = false;
+      setConnected(false);
+      setAgentPresentState(false);
+      setRecovery((prev) => {
+        if (prev.kind === "in-place-reconnecting") return prev;
+        if (prev.kind === "reconnecting" || prev.kind === "failed" || prev.kind === "ended") return prev;
+        refreshBaselineCapacityRef.current = null;
+        return { kind: "reconnecting", attempt: attemptRef.current };
+      });
+    },
+    [active]
+  );
+  useEffect(() => {
+    if (recovery.kind !== "refreshing" || capacity.kind !== "error") return;
+    const baseline = refreshBaselineCapacityRef.current;
+    if (baseline?.kind === "error" && baseline.error === capacity.error) return;
+    refreshBaselineCapacityRef.current = null;
+    setRecovery({ kind: "reconnecting", attempt: recovery.attempt });
+  }, [capacity, recovery]);
+  const onConnectionStateChange = useCallback(
+    (state) => {
+      if (!active) return;
+      if (state === "connected") {
+        onConnected();
+        return;
+      }
+      if (state === "reconnecting" || state === "signalReconnecting") {
+        if (connectedRef.current) {
+          setConnected(false);
+          setRecovery(
+            (prev) => prev.kind === "connected" ? { kind: "in-place-reconnecting" } : prev
+          );
+        }
+      }
+    },
+    [active, onConnected]
+  );
+  useEffect(() => {
+    if (!active || !needsFreshGrant(recovery)) return;
+    const step2 = retryStep(attemptRef.current, reconnectPolicyRef.current);
+    if (step2.kind === "give-up") {
+      manualReconnectPendingRef.current = false;
+      refreshBaselineCapacityRef.current = null;
+      releaseRef.current("disconnected");
+      setRecovery({ kind: "failed" });
+      return;
+    }
+    timerRef.current = window.setTimeout(() => {
+      timerRef.current = null;
+      attemptRef.current = step2.attempt;
+      setAttempt(step2.attempt);
+      refreshBaselineCapacityRef.current = capacityRef.current;
+      setRecovery({ kind: "refreshing", attempt: step2.attempt });
+      refreshRef.current();
+    }, step2.delayMs);
+    return clearTimer;
+  }, [recovery.kind, active, attempt, clearTimer]);
+  const reconnect = useCallback(() => {
+    if (!active || manualReconnectPendingRef.current || recovery.kind === "in-place-reconnecting") return;
+    manualReconnectPendingRef.current = true;
+    clearTimer();
+    attemptRef.current = 0;
+    setAttempt(0);
+    refreshBaselineCapacityRef.current = capacityRef.current;
+    setRecovery({ kind: "refreshing", attempt: 0 });
+    refreshRef.current();
+  }, [active, clearTimer, recovery.kind]);
+  const endIdleRef = useRef(endIdle);
+  endIdleRef.current = endIdle;
+  useEffect(() => {
+    if (!connected || !agentPresent || idleTimeoutMs <= 0 || recovery.kind !== "connected") return;
+    const timer = window.setInterval(() => {
+      if (idleExpired({ msSinceActivity: Date.now() - lastActivityRef.current, idleTimeoutMs })) {
+        endIdleRef.current();
+        return;
+      }
+      setClockTick((value) => value + 1);
+    }, 1e3);
+    return () => window.clearInterval(timer);
+  }, [connected, agentPresent, idleTimeoutMs, recovery.kind]);
+  const timeToDisconnectMs = connected && agentPresent && idleTimeoutMs > 0 && recovery.kind === "connected" ? Math.max(0, idleTimeoutMs - (Date.now() - lastActivityRef.current)) : null;
+  const idle = useMemo(() => {
+    const base = idlePhaseFor({
+      connected,
+      agentPresent,
+      msSinceActivity: Date.now() - lastActivityRef.current,
+      idleTimeoutMs,
+      warnAtMs
+    });
+    if (base.kind === "idle-warning") {
+      return { ...base, deadlineAt: lastActivityRef.current + idleTimeoutMs };
+    }
+    return base;
+  }, [connected, agentPresent, idleTimeoutMs, warnAtMs, timeToDisconnectMs]);
+  const phase = useMemo(
+    () => lifecyclePhaseFrom({ capacity, recovery, idle, connected, agentPresent }),
+    [capacity, recovery, idle, connected, agentPresent]
+  );
+  const onBehaviorChangeRef = useRef(onBehaviorChange);
+  onBehaviorChangeRef.current = onBehaviorChange;
+  const lastBehaviorRef = useRef(null);
+  const behaviorEnabled = Boolean(onBehaviorChange);
+  const onLifecycleData = useMemo(() => {
+    if (!behaviorEnabled) return void 0;
+    return (frame) => {
+      const parsed = lifecycleServerFrameSchema.safeParse(frame);
+      if (!parsed.success || parsed.data.kind !== "behavior_state") return;
+      const next = nextBehaviorSnapshot(lastBehaviorRef.current, parsed.data);
+      if (!next) return;
+      lastBehaviorRef.current = next;
+      onBehaviorChangeRef.current?.(next);
+    };
+  }, [behaviorEnabled]);
+  return useMemo(
+    () => ({
+      phase,
+      grant: grantState.grant,
+      capacity,
+      attempt,
+      timeToDisconnectMs,
+      stayConnected,
+      markActivity,
+      reconnect,
+      onConnected,
+      onDisconnected,
+      onConnectionError,
+      onConnectionStateChange,
+      setAgentPresent,
+      registerLeaveRoom,
+      reset,
+      onLifecycleData
+    }),
+    [
+      phase,
+      grantState.grant,
+      capacity,
+      attempt,
+      timeToDisconnectMs,
+      stayConnected,
+      markActivity,
+      reconnect,
+      onConnected,
+      onDisconnected,
+      onConnectionError,
+      onConnectionStateChange,
+      setAgentPresent,
+      registerLeaveRoom,
+      reset,
+      onLifecycleData
+    ]
+  );
+}
+function SessionLifecycleRoomBridge({ lifecycle }) {
+  const {
+    onConnectionStateChange,
+    setAgentPresent,
+    registerLeaveRoom,
+    markActivity,
+    onLifecycleData,
+    registerDataPublisher,
+    registerTurnSender,
+    setTurnState,
+    setMedia
+  } = lifecycle;
+  const connectionState = useConnectionState();
+  const assistant = useVoiceAssistant();
+  const transcriptions = useTranscriptions();
+  const room = useRoomContext();
+  const { send } = useChat();
+  const agentPresent = Boolean(assistant.agent);
+  const assistantState = assistant.state;
+  const videoLive = Boolean(assistant.videoTrack);
+  const audioLive = Boolean(assistant.audioTrack);
+  const transcriptionCount = transcriptions.length;
+  const prevTranscriptionCountRef = useRef(0);
+  useEffect(() => {
+    onConnectionStateChange(connectionState);
+  }, [connectionState, onConnectionStateChange]);
+  useEffect(() => {
+    setAgentPresent(agentPresent);
+  }, [agentPresent, setAgentPresent]);
+  useEffect(() => {
+    const active = isCallActivity({
+      assistantState,
+      transcriptionCount,
+      prevTranscriptionCount: prevTranscriptionCountRef.current
+    });
+    prevTranscriptionCountRef.current = transcriptionCount;
+    if (active) markActivity();
+  }, [assistantState, transcriptionCount, markActivity]);
+  useEffect(() => {
+    const leave = () => {
+      void Promise.resolve(room.disconnect()).catch(() => void 0);
+    };
+    registerLeaveRoom(leave);
+    return () => registerLeaveRoom(null);
+  }, [room, registerLeaveRoom]);
+  useEffect(() => {
+    if (!onLifecycleData) return;
+    const decoder = new TextDecoder();
+    const handler = (payload, _participant, _kind, topic) => {
+      if (topic !== RTA_LIFECYCLE_TOPIC) return;
+      try {
+        onLifecycleData(JSON.parse(decoder.decode(payload)));
+      } catch {
+      }
+    };
+    room.on(RoomEvent.DataReceived, handler);
+    return () => {
+      room.off(RoomEvent.DataReceived, handler);
+    };
+  }, [room, onLifecycleData]);
+  useEffect(() => {
+    if (!registerDataPublisher) return;
+    const encoder = new TextEncoder();
+    const publish = (frame) => {
+      try {
+        void room.localParticipant?.publishData(encoder.encode(JSON.stringify(frame)), { reliable: true, topic: RTA_LIFECYCLE_TOPIC }).catch(() => void 0);
+      } catch {
+      }
+    };
+    registerDataPublisher(publish);
+    return () => registerDataPublisher(null);
+  }, [room, registerDataPublisher]);
+  useEffect(() => {
+    if (!registerTurnSender) return;
+    const sender = (text, opts) => Promise.resolve(send(text, opts)).then(() => void 0);
+    registerTurnSender(sender);
+    return () => registerTurnSender(null);
+  }, [send, registerTurnSender]);
+  useEffect(() => {
+    setTurnState?.(assistantState);
+  }, [assistantState, setTurnState]);
+  useEffect(() => {
+    setMedia?.({ video: videoLive ? "live" : "connecting", audio: audioLive ? "flowing" : "silent" });
+  }, [videoLive, audioLive, setMedia]);
+  return null;
+}
+
+// ../client/src/react/grace-window.ts
+function mapTurnState(assistantState) {
+  switch (assistantState) {
+    case "listening":
+    case "thinking":
+    case "speaking":
+      return assistantState;
+    default:
+      return "quiet";
+  }
+}
+function endsAtFrom(args) {
+  const { serverStartedAtUnixMs, maxSessionSeconds } = args;
+  if (serverStartedAtUnixMs == null || !maxSessionSeconds) return null;
+  return serverStartedAtUnixMs + maxSessionSeconds * 1e3;
+}
+function sessionRemainingMsFrom(args) {
+  const endsAt = endsAtFrom(args);
+  if (endsAt == null) return null;
+  return Math.max(0, endsAt - args.nowUnixMs);
+}
+function approachingEndFrom(args) {
+  const { sessionRemainingMs, approachingEndLeadMs, alreadyFired } = args;
+  if (alreadyFired || sessionRemainingMs == null) return null;
+  if (sessionRemainingMs <= approachingEndLeadMs && sessionRemainingMs > 0) {
+    return { secondsLeft: Math.ceil(sessionRemainingMs / 1e3) };
+  }
+  return null;
+}
+function creditsLowFrom(args) {
+  const { creditRemainingMs, creditsLowLeadMs, alreadyFired } = args;
+  if (alreadyFired || creditRemainingMs == null) return null;
+  if (creditRemainingMs <= creditsLowLeadMs && creditRemainingMs > 0) {
+    return { secondsLeft: Math.ceil(creditRemainingMs / 1e3) };
+  }
+  return null;
+}
+function nextGraceWindow(args) {
+  const { prev, sessionRemainingMs, graceWindowLeadMs, endsAt, workerEnding, nowMs } = args;
+  switch (prev.kind) {
+    case "spent":
+      return prev;
+    // terminal
+    case "closed": {
+      const clockCrossed = sessionRemainingMs != null && sessionRemainingMs <= graceWindowLeadMs && sessionRemainingMs > 0;
+      if ((workerEnding || clockCrossed) && endsAt != null) {
+        return { kind: "open", reason: "session_cap", deadlineAt: endsAt, msLeft: Math.max(0, endsAt - nowMs) };
+      }
+      return prev;
+    }
+    case "open":
+      if (nowMs >= prev.deadlineAt) return { kind: "spent", delivered: false };
+      return { ...prev, msLeft: Math.max(0, prev.deadlineAt - nowMs) };
+    case "delivering":
+      if (nowMs >= prev.deadlineAt) return { kind: "spent", delivered: false };
+      return prev;
+  }
+}
+function resolveEndReason(workerLabel, innerReason) {
+  if (workerLabel) return workerLabel;
+  switch (innerReason) {
+    case "idle":
+      return "idle";
+    case "error":
+      return "failed";
+    default:
+      return "disconnected";
+  }
+}
+
+// ../client/src/react/use-realtime-session.ts
+var DEFAULT_APPROACHING_END_LEAD_SECONDS = 45;
+var DEFAULT_GRACE_WINDOW_LEAD_SECONDS = 12;
+var DEFAULT_GRACE_CEILING_SECONDS = 10;
+var DEFAULT_CREDITS_LOW_LEAD_SECONDS = 300;
+function positive(value, fallbackSeconds) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallbackSeconds;
+}
+function useRealtimeSession(input) {
+  const {
+    session,
+    maxSessionSeconds,
+    approachingEndLeadSeconds,
+    graceWindowLeadSeconds,
+    graceCeilingSeconds,
+    creditsLowLeadSeconds,
+    turnTimeoutSeconds,
+    creditRemainingMs = null,
+    autoStayConnectedDuringGrace = true,
+    onApproachingEnd,
+    onGraceWindowOpen,
+    onGraceWindowClosed,
+    onIdleWarning,
+    onCreditsLow,
+    onTurnTimeout,
+    onReconnecting,
+    onReconnected,
+    onEnded,
+    onBehaviorChange,
+    onClipResult,
+    // everything else (client/active/idleSeconds/idleWarnLeadSeconds/reconnect/requestOptions…)
+    // flows straight into the inner SSOT hook.
+    ...inner
+  } = input;
+  const effectiveSession = useMemo(
+    () => session && typeof maxSessionSeconds === "number" ? { ...session, maxSessionSeconds } : session,
+    [session, maxSessionSeconds]
+  );
+  const lifecycle = useSessionLifecycle({ ...inner, session: effectiveSession });
+  const [serverClock, setServerClock] = useState(null);
+  const [workerEnding, setWorkerEnding] = useState(false);
+  const [graceWindow, setGraceWindow] = useState({ kind: "closed" });
+  const [turn, setTurn] = useState("quiet");
+  const [media, setMediaState] = useState({ video: "connecting", audio: "silent" });
+  const [behavior, setBehavior] = useState(null);
+  const lastBehaviorRef = useRef(null);
+  const lastLabeledEndReasonRef = useRef(null);
+  const pendingClipsRef = useRef(/* @__PURE__ */ new Map());
+  const cbRef = useRef({ onApproachingEnd, onGraceWindowOpen, onGraceWindowClosed, onIdleWarning, onCreditsLow, onTurnTimeout, onReconnecting, onReconnected, onEnded, onBehaviorChange, onClipResult });
+  cbRef.current = { onApproachingEnd, onGraceWindowOpen, onGraceWindowClosed, onIdleWarning, onCreditsLow, onTurnTimeout, onReconnecting, onReconnected, onEnded, onBehaviorChange, onClipResult };
+  const approachingEndLeadMs = positive(approachingEndLeadSeconds, DEFAULT_APPROACHING_END_LEAD_SECONDS) * 1e3;
+  const graceWindowLeadMs = positive(graceWindowLeadSeconds, DEFAULT_GRACE_WINDOW_LEAD_SECONDS) * 1e3;
+  const graceCeilingMs = positive(graceCeilingSeconds, DEFAULT_GRACE_CEILING_SECONDS) * 1e3;
+  const creditsLowLeadMs = positive(creditsLowLeadSeconds, DEFAULT_CREDITS_LOW_LEAD_SECONDS) * 1e3;
+  const turnTimeoutMs = positive(turnTimeoutSeconds, DEFAULT_TURN_TIMEOUT_SECONDS) * 1e3;
+  const approachingFiredRef = useRef(false);
+  const creditsLowFiredRef = useRef(false);
+  const idleWarnFiredRef = useRef(false);
+  const endedFiredRef = useRef(false);
+  const prevPhaseKindRef = useRef("idle");
+  const graceWindowRef = useRef(graceWindow);
+  graceWindowRef.current = graceWindow;
+  const turnSenderRef = useRef(null);
+  const dataPublisherRef = useRef(null);
+  const lastTurnRef = useRef(null);
+  const [clockTick, setClockTick] = useState(0);
+  const endsAt = endsAtFrom({
+    serverStartedAtUnixMs: serverClock?.startedAtUnixMs ?? null,
+    maxSessionSeconds: serverClock?.maxSessionSeconds ?? null
+  });
+  const sessionRemainingMs = sessionRemainingMsFrom({
+    serverStartedAtUnixMs: serverClock?.startedAtUnixMs ?? null,
+    maxSessionSeconds: serverClock?.maxSessionSeconds ?? null,
+    nowUnixMs: Date.now()
+  });
+  const clocks = {
+    sessionRemainingMs,
+    idleRemainingMs: lifecycle.timeToDisconnectMs,
+    creditRemainingMs
+  };
+  const phaseKind = lifecycle.phase.kind;
+  const stayConnected = lifecycle.stayConnected;
+  const newTurnId = useCallback(() => {
+    try {
+      if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+    } catch {
+    }
+    return `t-${Date.now()}-${clockTick}`;
+  }, [clockTick]);
+  const onLifecycleData = useCallback((frame) => {
+    const parsed = lifecycleServerFrameSchema.safeParse(frame);
+    if (!parsed.success) return;
+    const f = parsed.data;
+    switch (f.kind) {
+      case "session_clock":
+        setServerClock({
+          startedAtUnixMs: f.started_at_unix_ms,
+          maxSessionSeconds: f.max_session_seconds,
+          idleTimeoutSeconds: f.idle_timeout_seconds
+        });
+        break;
+      case "ending":
+        setWorkerEnding(true);
+        break;
+      case "closing_turn_done":
+        setGraceWindow((prev) => {
+          if (prev.kind === "delivering" && prev.turnId === f.turn_id) {
+            cbRef.current.onGraceWindowClosed?.({ reason: "session_cap", delivered: true });
+            return { kind: "spent", delivered: true };
+          }
+          return prev;
+        });
+        break;
+      case "ended":
+        lastLabeledEndReasonRef.current = f.reason;
+        break;
+      case "behavior_state": {
+        const next = nextBehaviorSnapshot(lastBehaviorRef.current, f);
+        if (next) {
+          lastBehaviorRef.current = next;
+          setBehavior(next);
+          cbRef.current.onBehaviorChange?.(next);
+        }
+        break;
+      }
+      case "clip_ack": {
+        const result = { requestId: f.request_id, accepted: f.accepted, reason: f.reason };
+        const pending = pendingClipsRef.current.get(f.request_id);
+        if (pending) {
+          pendingClipsRef.current.delete(f.request_id);
+          clearTimeout(pending.timer);
+          pending.resolve(result);
+        }
+        cbRef.current.onClipResult?.(result);
+        break;
+      }
+    }
+  }, []);
+  const registerDataPublisher = useCallback((publish) => {
+    dataPublisherRef.current = publish;
+  }, []);
+  const registerTurnSender = useCallback((send) => {
+    turnSenderRef.current = send;
+  }, []);
+  const setTurnState = useCallback((state) => {
+    setTurn(mapTurnState(state));
+  }, []);
+  const setMedia = useCallback((next) => {
+    setMediaState((prev) => prev.video === next.video && prev.audio === next.audio ? prev : next);
+  }, []);
+  useEffect(() => {
+    if (phaseKind === "idle" || phaseKind === "ended") return;
+    const timer = window.setInterval(() => {
+      const now = Date.now();
+      const remaining = sessionRemainingMsFrom({
+        serverStartedAtUnixMs: serverClock?.startedAtUnixMs ?? null,
+        maxSessionSeconds: serverClock?.maxSessionSeconds ?? null,
+        nowUnixMs: now
+      });
+      const ends = endsAtFrom({
+        serverStartedAtUnixMs: serverClock?.startedAtUnixMs ?? null,
+        maxSessionSeconds: serverClock?.maxSessionSeconds ?? null
+      });
+      const approaching = approachingEndFrom({ sessionRemainingMs: remaining, approachingEndLeadMs, alreadyFired: approachingFiredRef.current });
+      if (approaching) {
+        approachingFiredRef.current = true;
+        cbRef.current.onApproachingEnd?.({ secondsLeft: approaching.secondsLeft, reason: "session_cap", threshold: approachingEndLeadMs / 1e3 });
+      }
+      const low = creditsLowFrom({ creditRemainingMs, creditsLowLeadMs, alreadyFired: creditsLowFiredRef.current });
+      if (low) {
+        creditsLowFiredRef.current = true;
+        cbRef.current.onCreditsLow?.({ secondsLeft: low.secondsLeft });
+      }
+      setGraceWindow((prev) => {
+        const next = nextGraceWindow({ prev, sessionRemainingMs: remaining, graceWindowLeadMs, endsAt: ends, workerEnding, nowMs: now });
+        if (prev.kind !== "open" && next.kind === "open") {
+          cbRef.current.onGraceWindowOpen?.({ reason: next.reason, deadlineAt: next.deadlineAt, msLeft: next.msLeft });
+        }
+        if (prev.kind !== "spent" && next.kind === "spent" && !next.delivered) {
+          cbRef.current.onGraceWindowClosed?.({ reason: "session_cap", delivered: false });
+        }
+        return next;
+      });
+      if (autoStayConnectedDuringGrace) {
+        const gw = graceWindowRef.current.kind;
+        if (gw === "open" || gw === "delivering") stayConnected();
+      }
+      const turnInfo = lastTurnRef.current;
+      if (turnInfo && now - turnInfo.sentAt >= turnTimeoutMs) {
+        lastTurnRef.current = null;
+        cbRef.current.onTurnTimeout?.({ turnId: turnInfo.id });
+      }
+      setClockTick((value) => value + 1);
+    }, 1e3);
+    return () => window.clearInterval(timer);
+  }, [phaseKind, serverClock, workerEnding, approachingEndLeadMs, graceWindowLeadMs, creditRemainingMs, creditsLowLeadMs, turnTimeoutMs, autoStayConnectedDuringGrace, stayConnected]);
+  useEffect(() => {
+    if (lifecycle.phase.kind === "idle-warning") {
+      if (!idleWarnFiredRef.current) {
+        idleWarnFiredRef.current = true;
+        cbRef.current.onIdleWarning?.({ secondsLeft: lifecycle.phase.secondsRemaining });
+      }
+    } else {
+      idleWarnFiredRef.current = false;
+    }
+  }, [lifecycle.phase]);
+  useEffect(() => {
+    const prev = prevPhaseKindRef.current;
+    if (phaseKind === "reconnectable" && prev !== "reconnectable") {
+      const attempt = lifecycle.phase.kind === "reconnectable" ? lifecycle.phase.attempt : lifecycle.attempt;
+      cbRef.current.onReconnecting?.({ attempt });
+    } else if (prev === "reconnectable" && (phaseKind === "live" || phaseKind === "connecting")) {
+      cbRef.current.onReconnected?.();
+    }
+    prevPhaseKindRef.current = phaseKind;
+  }, [phaseKind, lifecycle.phase, lifecycle.attempt]);
+  useEffect(() => {
+    if (phaseKind === "ended") {
+      if (!endedFiredRef.current) {
+        endedFiredRef.current = true;
+        const inner2 = lifecycle.phase.kind === "ended" ? lifecycle.phase.reason : void 0;
+        cbRef.current.onEnded?.({ reason: resolveEndReason(lastLabeledEndReasonRef.current, inner2) });
+      }
+    } else {
+      endedFiredRef.current = false;
+    }
+  }, [phaseKind, lifecycle.phase]);
+  const sendClosingTurn = useCallback((text, opts) => {
+    const trimmed = text.trim();
+    const gw = graceWindowRef.current;
+    if (gw.kind === "spent") return { ok: false, reason: "already_spent" };
+    if (gw.kind !== "open") return { ok: false, reason: "window_closed" };
+    const sender = turnSenderRef.current;
+    if (!sender || !trimmed) return { ok: false, reason: "not_connected" };
+    const turnId = newTurnId();
+    const attributes = { [RTA_CLOSING_TURN_ATTR]: "1", [RTA_TURN_ID_ATTR]: turnId };
+    if (opts?.instructions) attributes[RTA_TURN_INSTRUCTIONS_ATTR] = opts.instructions;
+    void sender(trimmed, { attributes }).catch(() => void 0);
+    const deadlineAt = (endsAt ?? Date.now()) + graceCeilingMs;
+    setGraceWindow({ kind: "delivering", turnId, deadlineAt });
+    return { ok: true, turnId };
+  }, [endsAt, graceCeilingMs, newTurnId]);
+  const requestGracefulClose = useCallback(() => {
+    dataPublisherRef.current?.({ kind: "request_graceful_close" });
+  }, []);
+  const extend = useCallback((req) => {
+    const publish = dataPublisherRef.current;
+    if (!publish || !(req.addSeconds > 0)) return { ok: false };
+    publish({ kind: "extend", add_seconds: Math.floor(req.addSeconds), ...req.proof ? { proof: req.proof } : {} });
+    approachingFiredRef.current = false;
+    setWorkerEnding(false);
+    setGraceWindow({ kind: "closed" });
+    return { ok: true };
+  }, []);
+  const sendTurn = useCallback(async (text, opts) => {
+    const trimmed = text.trim();
+    const sender = turnSenderRef.current;
+    if (!sender || !trimmed) return;
+    const turnId = newTurnId();
+    lastTurnRef.current = { text: trimmed, opts, id: turnId, sentAt: Date.now() };
+    lifecycle.markActivity();
+    const attributes = opts?.instructions ? { [RTA_TURN_INSTRUCTIONS_ATTR]: opts.instructions } : void 0;
+    await sender(trimmed, attributes ? { attributes } : void 0);
+  }, [lifecycle, newTurnId]);
+  const retryTurn = useCallback(() => {
+    const last = lastTurnRef.current;
+    if (!last) return;
+    void sendTurn(last.text, last.opts);
+  }, [sendTurn]);
+  const end = useCallback((reason) => {
+    if (reason) lastLabeledEndReasonRef.current = reason;
+    requestGracefulClose();
+    lifecycle.reset();
+  }, [lifecycle, requestGracefulClose]);
+  const performClip = useCallback(
+    (clipId, opts) => {
+      const requestId = newTurnId();
+      const publish = dataPublisherRef.current;
+      const trimmed = clipId.trim();
+      if (!publish || !trimmed) {
+        const result = { requestId, accepted: false, reason: "not_connected" };
+        cbRef.current.onClipResult?.(result);
+        return Promise.resolve(result);
+      }
+      return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          pendingClipsRef.current.delete(requestId);
+          const result = { requestId, accepted: false, reason: "timeout" };
+          cbRef.current.onClipResult?.(result);
+          resolve(result);
+        }, opts?.timeoutMs ?? 5e3);
+        pendingClipsRef.current.set(requestId, { resolve, timer });
+        publish({
+          kind: "clip_request",
+          request_id: requestId,
+          clip_id: trimmed,
+          ...typeof opts?.holdSeconds === "number" ? { hold_seconds: opts.holdSeconds } : {}
+        });
+      });
+    },
+    [newTurnId]
+  );
+  useEffect(
+    () => () => {
+      for (const [requestId, pending] of pendingClipsRef.current) {
+        clearTimeout(pending.timer);
+        pending.resolve({ requestId, accepted: false, reason: "unmounted" });
+      }
+      pendingClipsRef.current.clear();
+    },
+    []
+  );
+  const reset = useCallback(() => {
+    setServerClock(null);
+    setWorkerEnding(false);
+    setGraceWindow({ kind: "closed" });
+    lastLabeledEndReasonRef.current = null;
+    approachingFiredRef.current = false;
+    creditsLowFiredRef.current = false;
+    lastTurnRef.current = null;
+    lifecycle.reset();
+  }, [lifecycle]);
+  return useMemo(
+    () => ({
+      // Spread the inner SSOT verbatim (phase/grant/capacity/attempt/timeToDisconnectMs/
+      // stayConnected/reconnect/markActivity/the sinks) → a true drop-in superset, then
+      // add the realtime-session surface. `reset` + `lifecycle` come AFTER so ours win.
+      ...lifecycle,
+      turn,
+      clocks,
+      endsAt,
+      graceWindow,
+      media,
+      lifecycle,
+      sendClosingTurn,
+      requestGracefulClose,
+      extend,
+      sendTurn,
+      retryTurn,
+      end,
+      behavior,
+      performClip,
+      onLifecycleData,
+      registerDataPublisher,
+      registerTurnSender,
+      setTurnState,
+      setMedia,
+      reset
+    }),
+    [
+      lifecycle,
+      turn,
+      clocks,
+      endsAt,
+      graceWindow,
+      media,
+      sendClosingTurn,
+      requestGracefulClose,
+      extend,
+      sendTurn,
+      retryTurn,
+      end,
+      behavior,
+      performClip,
+      onLifecycleData,
+      registerDataPublisher,
+      registerTurnSender,
+      setTurnState,
+      setMedia,
+      reset
+    ]
+  );
+}
+
+// ../client/src/react/avatar-call.ts
+function statusFor(session) {
+  switch (session.phase.kind) {
+    case "queued":
+      return "waiting";
+    case "live":
+    case "idle-warning":
+      return "live";
+    case "reconnectable":
+      return "recovering";
+    case "ended":
+      return "ended";
+    default:
+      return "connecting";
+  }
+}
+function handleFor(session) {
+  const remainingMs = session.clocks.sessionRemainingMs;
+  return {
+    status: statusFor(session),
+    queuePosition: session.phase.kind === "queued" ? session.phase.busy.queue_position ?? null : null,
+    secondsRemaining: remainingMs === null ? null : Math.max(0, Math.round(remainingMs / 1e3)),
+    say: (text, options) => session.sendTurn(text, options?.steer ? { instructions: options.steer } : void 0),
+    sayAndEnd: (text) => {
+      session.sendClosingTurn(text);
+    },
+    keepAlive: session.stayConnected,
+    end: () => session.end("user_ended")
+  };
+}
+function useAvatarCall(props) {
+  const sessionRef = useRef(null);
+  const session = useRealtimeSession({
+    client: props.client,
+    session: { avatarId: props.avatarId, mode: props.mode ?? "avatar", sttMode: props.listen === false ? "off" : "server" },
+    creditRemainingMs: props.balanceMs,
+    onApproachingEnd: props.onEnding ? ({ secondsLeft }) => {
+      const live = sessionRef.current;
+      if (live) props.onEnding?.({ secondsLeft, call: handleFor(live) });
+    } : void 0,
+    onIdleWarning: props.onQuiet ? ({ secondsLeft }) => props.onQuiet?.({ secondsLeft }) : void 0,
+    onCreditsLow: props.onLowBalance ? ({ secondsLeft }) => props.onLowBalance?.({ secondsLeft }) : void 0,
+    onEnded: props.onEnded ? ({ reason }) => props.onEnded?.({ reason }) : void 0
+  });
+  sessionRef.current = session;
+  const call = handleFor(session);
+  const lastStatusRef = useRef(null);
+  const onStatusChange = props.onStatusChange;
+  useEffect(() => {
+    if (lastStatusRef.current === call.status) return;
+    lastStatusRef.current = call.status;
+    onStatusChange?.(call.status);
+  }, [call.status, onStatusChange]);
+  const view = createElement(
+    RealtimeAvatarLiveKitRoom,
+    {
+      grant: session.grant,
+      audio: props.listen !== false,
+      onConnected: session.onConnected,
+      onDisconnected: session.onDisconnected,
+      onError: session.onConnectionError
+    },
+    createElement(SessionLifecycleRoomBridge, { key: "bridge", lifecycle: session }),
+    createElement(
+      AvatarVideoSurface,
+      {
+        key: "surface",
+        idleVideoUrl: props.idleVideoUrl ?? null,
+        poster: props.poster ?? null,
+        fit: props.fit ?? "cover",
+        className: props.className
+      },
+      props.children ? props.children(call) : null
+    )
+  );
+  return { call, view };
+}
+function AvatarCall(props) {
+  const { call, view } = useAvatarCall(props);
+  return view;
+}
+
+// ../client/src/proxy-client.ts
+var DEFAULT_TIMEOUT_MS = 6e4;
+var normalize = (url) => url.replace(/\/+$/, "");
+function createProxyClient(options) {
+  const base = normalize(options.proxyUrl);
+  const doFetch = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const deadline = (caller) => {
+    if (!timeoutMs) return caller;
+    const timer = AbortSignal.timeout(timeoutMs);
+    return caller ? AbortSignal.any([caller, timer]) : timer;
+  };
+  const post = async (path, body, request) => {
+    if (!doFetch) throw new Error("realtime-avatar: no fetch available \u2014 pass one via `fetch`.");
+    return doFetch(`${base}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...request?.headers ?? {} },
+      body: JSON.stringify(body),
+      signal: deadline(request?.signal)
+    });
+  };
+  const beacon = (path, body) => {
+    const send = globalThis.navigator?.sendBeacon?.bind(globalThis.navigator);
+    if (!send) return false;
+    return send(`${base}${path}`, new Blob([JSON.stringify(body)], { type: "application/json" }));
+  };
+  return {
+    async createLiveKitSessionOrBusy(input, requestOptions) {
+      const response = await post(
+        "/connect",
+        { avatarId: input.avatarId, mode: input.mode },
+        requestOptions
+      );
+      if (response.status === 429) {
+        const busy = await response.json().catch(() => ({}));
+        return { status: "busy", busy };
+      }
+      if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new Error(`realtime-avatar: proxy refused the call (${response.status}) ${detail}`.trim());
+      }
+      return { status: "ready", grant: await response.json() };
+    },
+    async releaseLiveKitSession(sessionId, reason, requestOptions) {
+      if (!sessionId) return false;
+      try {
+        const response = await post("/end", { session_id: sessionId, reason }, requestOptions);
+        return response.ok;
+      } catch {
+        return false;
+      }
+    },
+    releaseLiveKitSessionBeacon(sessionId, reason) {
+      if (!sessionId) return false;
+      return beacon("/end", { session_id: sessionId, reason: reason ?? "page_hide" });
+    },
+    async releaseLiveKitQueueTicket(queueTicketId, reason, requestOptions) {
+      if (!queueTicketId) return false;
+      try {
+        const response = await post("/end", { queue_ticket_id: queueTicketId, reason }, requestOptions);
+        return response.ok;
+      } catch {
+        return false;
+      }
+    },
+    releaseLiveKitQueueTicketBeacon(queueTicketId, reason) {
+      if (!queueTicketId) return false;
+      return beacon("/end", { queue_ticket_id: queueTicketId, reason: reason ?? "page_hide" });
+    }
+  };
+}
+
+export { 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, sessionBehaviorSchema, sessionClipSchema, shouldReplayPendingTurn, splitCallTranscript, useAvatarCall, useAvatarPlayoutDelay, useAvatarQualityGovernor, useCallTranscript, useLiveKitAvatarGrant, useMicLease, useRealtimeSession, useReleaseMicLeaseOnTrackEnded, useSessionLifecycle };