realtime-avatar 0.25.0 → 0.26.1

package/dist/react.js

@@ -1,7 +1,7 @@
 "use client";
-import { useRef, useState, useEffect, useCallback, useMemo, createElement, Fragment } from 'react';
-import { useRoomContext, useConnectionState, useLocalParticipant, useTranscriptions, RoomAudioRenderer, LiveKitRoom, useMaybeRoomContext, useVoiceAssistant, VideoTrack, useChat } from '@livekit/components-react';
-import { ConnectionState, isRemoteTrack, VideoQuality, ConnectionQuality, RoomEvent, TrackEvent, Track, ConnectionError, ConnectionErrorReason, DisconnectReason, createLocalVideoTrack, Room } from 'livekit-client';
+import { useRef, useMemo, useState, useEffect, useCallback, createElement, Fragment } from 'react';
+import { useRoomContext, useConnectionState, useLocalParticipant, useTranscriptions, RoomAudioRenderer, LiveKitRoom, useMaybeRoomContext, useVoiceAssistant, VideoTrack, useChat, useAudioPlayback } from '@livekit/components-react';
+import { ConnectionState, isRemoteTrack, VideoQuality, ConnectionQuality, RoomEvent, TrackEvent, Track, ConnectionError, ConnectionErrorReason, ParticipantEvent, DisconnectReason, createLocalVideoTrack, Room } from 'livekit-client';
 import { z } from 'zod';
 import { jsxs, jsx } from 'react/jsx-runtime';
 
@@ -27,14 +27,26 @@ function candidateIdentities(room) {
   const agents = all.filter((id) => /^agent[-_]/i.test(id));
   return [...agents, ...all.filter((id) => !agents.includes(id))];
 }
+function rpcCode(error) {
+  return typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+}
 function methodMissing(error) {
-  const code = error?.code;
-  if (code === "UNSUPPORTED_METHOD" || code === "RECIPIENT_NOT_FOUND" || code === 1401 || code === 1402) {
+  const code = rpcCode(error);
+  if (code === "UNSUPPORTED_METHOD" || code === "RECIPIENT_NOT_FOUND" || code === 1400 || code === 1401) {
     return true;
   }
   const message = error instanceof Error ? error.message : String(error ?? "");
   return /not supported|unsupported_method|recipient_not_found|recipient not found/i.test(message);
 }
+var TRANSIENT_RPC_CODES = /* @__PURE__ */ new Set([1501, 1502, 1503, 1505]);
+var ToolRegistrationError = class extends Error {
+  name = "ToolRegistrationError";
+  retryable;
+  constructor(message, options) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.retryable = options.retryable;
+  }
+};
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function buildManifest(tools) {
   const descriptors = [];
@@ -64,8 +76,9 @@ async function attachAvatarTools(room, tools, options = {}) {
   const { descriptors, rejected } = buildManifest(tools);
   const payload = JSON.stringify({ tools: descriptors });
   if (payload.length > MAX_MANIFEST_BYTES) {
-    throw new Error(
-      `tool manifest is ${payload.length} bytes, over the ${MAX_MANIFEST_BYTES} limit \u2014 shorten descriptions or register fewer tools`
+    throw new ToolRegistrationError(
+      `tool manifest is ${payload.length} bytes, over the ${MAX_MANIFEST_BYTES} limit \u2014 shorten descriptions or register fewer tools`,
+      { retryable: false }
     );
   }
   options.signal?.throwIfAborted();
@@ -148,14 +161,21 @@ async function attachAvatarTools(room, tools, options = {}) {
         } catch (error) {
           activeCaller = void 0;
           lastError = error;
-          if (!methodMissing(error)) throw error;
+          if (!methodMissing(error)) {
+            if (options.signal?.aborted) throw error;
+            throw new ToolRegistrationError(
+              `tool registration failed: ${error instanceof Error ? error.message : String(error)}`,
+              { retryable: TRANSIENT_RPC_CODES.has(rpcCode(error)), cause: error }
+            );
+          }
         }
       }
       if (Date.now() >= deadline) break;
       await sleep(200);
     }
-    throw new Error(
-      sawCandidate ? `no participant accepted the tool manifest \u2014 either this session was not minted with the \`client_tools\` capability (a server-side grant), or the agent never armed registration within ${options.timeoutMs ?? 8e3}ms` + (lastError instanceof Error ? ` (last error: ${lastError.message})` : "") : "no remote participant joined the room before the timeout \u2014 nothing to register with"
+    throw new ToolRegistrationError(
+      sawCandidate ? `no participant accepted the tool manifest \u2014 either this session was not minted with the \`client_tools\` capability (a server-side grant), or the agent never armed registration within ${options.timeoutMs ?? 8e3}ms` + (lastError instanceof Error ? ` (last error: ${lastError.message})` : "") : "no remote participant joined the room before the timeout \u2014 nothing to register with",
+      { retryable: true, cause: lastError ?? void 0 }
     );
   } catch (error) {
     dispose();
@@ -164,11 +184,31 @@ async function attachAvatarTools(room, tools, options = {}) {
 }
 
 // ../client/src/react/use-character-tools.ts
+var CHARACTER_TOOLS_RETRY_DELAYS_MS = [1e3, 3e3];
+function manifestKey(tools) {
+  return JSON.stringify(Object.entries(tools).map(([name, tool]) => [name, tool.description, tool.parameters ?? null]));
+}
 function useCharacterTools(tools, options = {}) {
   const room = useRoomContext();
   const connection = useConnectionState();
   const callback = useRef(options.onResult);
   callback.current = options.onResult;
+  const latest = useRef(tools);
+  latest.current = tools;
+  const key = manifestKey(tools);
+  const stable = useMemo(() => Object.fromEntries(
+    Object.entries(latest.current).map(([name, tool]) => [
+      name,
+      // A tool without a callable `execute` is passed as it is, so the manifest still rejects it.
+      typeof tool.execute !== "function" ? tool : {
+        description: tool.description,
+        parameters: tool.parameters,
+        execute: (args, context) => latest.current[name]?.execute(args, context)
+      }
+    ])
+    // `key` IS the dependency: it changes exactly when the manifest does.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  ), [key]);
   const [state, setState] = useState({ status: "idle", registered: [], rejected: [] });
   useEffect(() => {
     if (connection !== ConnectionState.Connected) {
@@ -176,28 +216,42 @@ function useCharacterTools(tools, options = {}) {
       return;
     }
     const abort = new AbortController();
-    setState({ status: "registering", registered: [], rejected: [] });
-    void attachAvatarTools(room, tools, {
-      signal: abort.signal,
-      onResult: (event) => {
-        if (!abort.signal.aborted) callback.current?.(event);
-      }
-    }).then((result) => {
-      if (abort.signal.aborted) {
-        result.dispose();
-        return;
-      }
-      setState({ status: "ready", registered: result.accepted, rejected: result.rejected });
-    }).catch((error) => {
-      if (!abort.signal.aborted) setState({
-        status: "error",
-        registered: [],
-        rejected: [],
-        error: error instanceof Error ? error.message : "Tool registration failed"
+    let timer;
+    const register = (attempt) => {
+      setState({ status: "registering", registered: [], rejected: [], attempt });
+      void attachAvatarTools(room, stable, {
+        signal: abort.signal,
+        onResult: (event) => {
+          if (!abort.signal.aborted) callback.current?.(event);
+        }
+      }).then((result) => {
+        if (abort.signal.aborted) {
+          result.dispose();
+          return;
+        }
+        setState({ status: "ready", registered: result.accepted, rejected: result.rejected, attempt });
+      }).catch((error) => {
+        if (abort.signal.aborted) return;
+        const delay = CHARACTER_TOOLS_RETRY_DELAYS_MS[attempt - 1];
+        if (error instanceof ToolRegistrationError && error.retryable && delay !== void 0) {
+          timer = setTimeout(() => register(attempt + 1), delay);
+          return;
+        }
+        setState({
+          status: "error",
+          registered: [],
+          rejected: [],
+          attempt,
+          error: error instanceof Error ? error.message : "Tool registration failed"
+        });
       });
-    });
-    return () => abort.abort();
-  }, [room, tools, connection]);
+    };
+    register(1);
+    return () => {
+      abort.abort();
+      if (timer !== void 0) clearTimeout(timer);
+    };
+  }, [room, stable, connection]);
   return state;
 }
 
@@ -852,6 +906,11 @@ function useLiveKitAvatarGrant(input) {
   });
   const stateRef = useRef(state);
   stateRef.current = state;
+  const wantedRef = useRef(active);
+  wantedRef.current = active;
+  useEffect(() => () => {
+    wantedRef.current = false;
+  }, []);
   const [tabVisible, setTabVisible] = useState(
     () => typeof document === "undefined" || document.visibilityState === "visible"
   );
@@ -892,6 +951,8 @@ function useLiveKitAvatarGrant(input) {
         if (cancelled) {
           if (result.status !== "busy") {
             void client.releaseLiveKitSession(result.grant.session_id, "superseded");
+          } else if (!wantedRef.current && result.busy.queue_ticket_id) {
+            void client.releaseLiveKitQueueTicket(result.busy.queue_ticket_id, "unmount");
           }
           return;
         }
@@ -1016,13 +1077,16 @@ function RealtimeAvatarLiveKitRoom(props) {
       serverUrl: grant?.livekit_url,
       token: grant?.participant_token,
       connect: shouldConnect,
-      audio: audio ?? grant?.stt_mode === "server",
+      audio: audio ?? publishesMicrophoneByDefault(grant),
       video: cameraPublishOptions(grant, video),
       options: roomOptions
     },
     createElement(Fragment, null, cushion, children, roomAudio)
   );
 }
+function publishesMicrophoneByDefault(grant) {
+  return grant?.stt_mode === "server";
+}
 var capacityErrorFromBusy = (busy) => {
   return new RealtimeAvatarCapacityError(busy.message, busy);
 };
@@ -1754,16 +1818,16 @@ function AvatarVideoSurface(props) {
     !live || connectionState === ConnectionState.Disconnected
   );
   useLiveResumeOnProducing(liveWrapRef, trackProducing);
-  const fitClass = fit === "cover" ? AVATAR_VIDEO_FIT_COVER : AVATAR_VIDEO_FIT_CONTAIN;
+  const fitStyle = 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 backFitStyle = fitStyle;
   const posterLayer = layers.showPoster ? createElement("img", {
     key: "poster",
     src: poster,
     alt: "",
     "aria-hidden": true,
-    className: joinClass(AVATAR_VIDEO_LAYER, backFitClass),
+    style: backFitStyle,
     "data-testid": "avatar-poster"
   }) : null;
   const idleLayer = layers.showIdleVideo ? createElement("video", {
@@ -1781,7 +1845,7 @@ function AvatarVideoSurface(props) {
     playsInline: true,
     autoPlay: true,
     preload: "auto",
-    className: joinClass(AVATAR_VIDEO_LAYER, backFitClass),
+    style: backFitStyle,
     "data-testid": "avatar-idle-video"
   }) : null;
   const frontLayer = createElement(
@@ -1789,17 +1853,17 @@ function AvatarVideoSurface(props) {
     {
       key: "live",
       ref: liveWrapRef,
-      className: joinClass(AVATAR_VIDEO_LIVE_WRAP, showLive ? void 0 : "pointer-events-none"),
       style: {
+        ...AVATAR_VIDEO_LIVE_WRAP,
         opacity: showLive ? 1 : 0,
-        transitionDuration: "0ms"
+        pointerEvents: showLive ? void 0 : "none"
       },
       "data-testid": "avatar-live-layer",
       "aria-hidden": !showLive
     },
     videoTrack ? createElement(VideoTrack, {
       trackRef: videoTrack,
-      className: joinClass(AVATAR_VIDEO_LAYER, fitClass),
+      style: fitStyle,
       playsInline: true,
       autoPlay: true,
       muted: true,
@@ -1808,16 +1872,16 @@ function AvatarVideoSurface(props) {
   );
   const badge = showLiveBadge && showLive ? createElement(
     "span",
-    { key: "badge", className: AVATAR_VIDEO_BADGE },
-    createElement("span", { key: "dot", className: AVATAR_VIDEO_BADGE_DOT, "aria-hidden": true }),
+    { key: "badge", style: AVATAR_VIDEO_BADGE },
+    createElement("span", { key: "dot", style: 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
+      className,
+      style: boxAspect ? { ...AVATAR_VIDEO_BOX, aspectRatio: boxAspect, ...style } : { ...AVATAR_VIDEO_BOX, ...style },
+      "data-testid": testId ?? "avatar-video-surface"
     },
     // 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
@@ -1826,7 +1890,9 @@ function AvatarVideoSurface(props) {
     idleLayer,
     frontLayer,
     badge,
-    children
+    // Above BOTH media layers and the badge. Appended bare, a consumer's positioned child with
+    // no z-index painted under the z-20 live layer, which then took its clicks once live.
+    children == null || children === false ? null : createElement("div", { key: "overlay", style: AVATAR_VIDEO_OVERLAY, "data-testid": "avatar-overlay" }, children)
   );
 }
 function resolveSurfaceLayers(input) {
@@ -2138,16 +2204,45 @@ function useLiveResumeOnProducing(wrapRef, producing) {
     };
   }, [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 AVATAR_VIDEO_BOX = { position: "relative", width: "100%", height: "100%", overflow: "hidden", isolation: "isolate" };
+var AVATAR_VIDEO_LAYER = {
+  position: "absolute",
+  inset: 0,
+  width: "100%",
+  height: "100%",
+  transform: "translateZ(0)",
+  imageRendering: "auto",
+  objectPosition: "center 22%"
+};
+var AVATAR_VIDEO_FIT_CONTAIN = { ...AVATAR_VIDEO_LAYER, objectFit: "contain" };
+var AVATAR_VIDEO_FIT_COVER = { ...AVATAR_VIDEO_LAYER, objectFit: "cover" };
+var AVATAR_VIDEO_LIVE_WRAP = {
+  position: "absolute",
+  inset: 0,
+  zIndex: 20,
+  width: "100%",
+  height: "100%",
+  transitionProperty: "opacity",
+  transitionDuration: "0ms"
+};
+var AVATAR_VIDEO_BADGE = {
+  position: "absolute",
+  top: 8,
+  right: 8,
+  zIndex: 30,
+  display: "inline-flex",
+  alignItems: "center",
+  gap: 6,
+  borderRadius: 6,
+  background: "rgb(0 0 0 / 0.55)",
+  padding: "2px 6px",
+  fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
+  fontSize: 10,
+  color: "rgb(255 255 255 / 0.85)",
+  backdropFilter: "blur(8px)"
+};
+var AVATAR_VIDEO_BADGE_DOT = { width: 6, height: 6, borderRadius: 9999, background: "#34d399" };
+var AVATAR_VIDEO_OVERLAY = { position: "absolute", inset: 0, zIndex: 40 };
 var RECORDED_MEDIA_MODES = ["audio", "video", "audio_video"];
 var recordingModeSchema = z.enum(["off", ...RECORDED_MEDIA_MODES, "participants"]).describe("Server-owned recording policy; omitted means off. Legacy audio includes user and avatar audio. participants saves one continuous audio/video file per participant, without mixing their voices.");
 var RECORDING_STATUSES = ["pending", "recording", "processing", "ready", "failed", "expired"];
@@ -2681,6 +2776,169 @@ function createConnectionHistoryCollector(input) {
   return { enqueue, flush, dispose };
 }
 
+// ../browser/src/microphone.ts
+var HINTS = {
+  "insecure-origin": "The browser only exposes microphones on a secure origin. Serve the page over https, or open it on http://localhost \u2014 a LAN address like http://192.168.1.5 will not do.",
+  "no-answer": "The permission prompt is probably still open, or was dismissed without an answer. Look for it in the address bar, answer it, and try again.",
+  "denied-by-browser": "This site is blocked from using the microphone. Click the icon at the left of the address bar, set Microphone to Allow, and reload.",
+  "denied-by-os": "The operating system is blocking the browser itself, so no site can record. On macOS: System Settings > Privacy & Security > Microphone, enable your browser, then RESTART it \u2014 the change does not apply to a running browser.",
+  "no-device": "No microphone is available. Connect one, and if you are on Bluetooth headphones check they are in a mode that has a microphone.",
+  "device-in-use": "Another application or browser tab is holding the microphone. Close it \u2014 including any call from this page you did not hang up \u2014 and try again.",
+  "device-lost": "The microphone stopped during the call: it was unplugged, or access to it was turned off. Reconnect it or allow access again, then turn the microphone back on.",
+  unknown: "Try again, and if it persists include the message above in your report."
+};
+function isOperatingSystemDenial(message) {
+  return /\bby system\b|system permission/i.test(message);
+}
+function classify(error) {
+  if (error instanceof TypeError && /mediaDevices|undefined/i.test(error.message)) {
+    return { reason: "insecure-origin", message: error.message };
+  }
+  const name = typeof error === "object" && error !== null && "name" in error ? String(error.name) : "";
+  const message = typeof error === "object" && error !== null && "message" in error && error.message ? String(error.message) : String(error);
+  switch (name) {
+    case "NotAllowedError":
+    case "PermissionDeniedError":
+      return {
+        reason: isOperatingSystemDenial(message) ? "denied-by-os" : "denied-by-browser",
+        message
+      };
+    case "NotFoundError":
+    case "DevicesNotFoundError":
+    case "OverconstrainedError":
+    case "ConstraintNotSatisfiedError":
+      return { reason: "no-device", message };
+    case "NotReadableError":
+    case "TrackStartError":
+    case "AbortError":
+      return { reason: "device-in-use", message };
+    case "SecurityError":
+      return { reason: "insecure-origin", message };
+    default:
+      return { reason: "unknown", message };
+  }
+}
+function describeMicrophoneFailure(error) {
+  const { reason, message } = classify(error);
+  return { reason, message, hint: HINTS[reason] };
+}
+function microphoneLost(message) {
+  return { reason: "device-lost", message, hint: HINTS["device-lost"] };
+}
+
+// ../client/src/react/call-media.ts
+var DEVICE_LOST_MESSAGE = "The microphone track ended during the call.";
+function callMicrophoneFrom(facts, intent) {
+  if (!facts.wanted) return { status: "off" };
+  const { publication } = facts;
+  if (publication) {
+    if (publication.ended) {
+      return publication.muted ? { status: "unavailable", ...microphoneLost(DEVICE_LOST_MESSAGE) } : { status: "pending" };
+    }
+    return publication.muted ? { status: "muted" } : { status: "on" };
+  }
+  if (intent.muted) return { status: "muted" };
+  if (facts.enabling) return { status: "pending" };
+  const error = facts.deviceError;
+  if (error) {
+    const problem = describeMicrophoneFailure(error);
+    const blocked = problem.reason === "denied-by-browser" || problem.reason === "denied-by-os" || problem.reason === "insecure-origin";
+    return blocked ? { status: "blocked", ...problem } : { status: "unavailable", ...problem };
+  }
+  return facts.connected ? { status: "pending" } : { status: "off" };
+}
+function microphoneFacts(room, wanted, connected, enabling, staleError) {
+  const publication = room.localParticipant.getTrackPublication(Track.Source.Microphone);
+  const track = publication?.track;
+  return {
+    wanted,
+    connected,
+    enabling,
+    publication: track ? { muted: publication.isMuted, ended: track.mediaStreamTrack?.readyState === "ended" } : null,
+    deviceError: room.localParticipant.lastMicrophoneError !== staleError && room.localParticipant.lastMicrophoneError || null
+  };
+}
+function useCallMedia(room, options) {
+  const { setMicrophoneFacts, setAudioPlayback, registerMediaControls, microphoneWanted, connectionState, callKey } = options;
+  const connected = connectionState === ConnectionState.Connected;
+  const scope = useMemo(
+    () => ({ room, callKey, stale: room.localParticipant.lastMicrophoneError }),
+    [room, callKey]
+  );
+  const [enabling, setEnabling] = useState(false);
+  const [version, setVersion] = useState(0);
+  const sinksRef = useRef({ setMicrophoneFacts, setAudioPlayback });
+  sinksRef.current = { setMicrophoneFacts, setAudioPlayback };
+  useEffect(() => {
+    if (!setMicrophoneFacts) return;
+    const bump = () => setVersion((value) => value + 1);
+    const participant = room.localParticipant;
+    let watched = null;
+    const watchTrack = () => {
+      watched?.off();
+      const track = participant.getTrackPublication(Track.Source.Microphone)?.track;
+      if (!track) {
+        watched = null;
+        return;
+      }
+      track.on(TrackEvent.Ended, bump).on(TrackEvent.Restarted, bump).on(TrackEvent.Muted, bump).on(TrackEvent.Unmuted, bump);
+      watched = { off: () => {
+        track.off(TrackEvent.Ended, bump).off(TrackEvent.Restarted, bump).off(TrackEvent.Muted, bump).off(TrackEvent.Unmuted, bump);
+      } };
+    };
+    const onPublications = () => {
+      watchTrack();
+      bump();
+    };
+    room.on(RoomEvent.MediaDevicesError, bump).on(RoomEvent.LocalTrackPublished, onPublications).on(RoomEvent.LocalTrackUnpublished, onPublications);
+    participant.on(ParticipantEvent.TrackMuted, bump).on(ParticipantEvent.TrackUnmuted, bump);
+    watchTrack();
+    return () => {
+      watched?.off();
+      room.off(RoomEvent.MediaDevicesError, bump).off(RoomEvent.LocalTrackPublished, onPublications).off(RoomEvent.LocalTrackUnpublished, onPublications);
+      participant.off(ParticipantEvent.TrackMuted, bump).off(ParticipantEvent.TrackUnmuted, bump);
+    };
+  }, [room, setMicrophoneFacts]);
+  useEffect(() => {
+    sinksRef.current.setMicrophoneFacts?.(microphoneFacts(room, microphoneWanted, connected, enabling, scope.stale));
+  }, [room, microphoneWanted, connected, enabling, version, scope]);
+  const { canPlayAudio } = useAudioPlayback(room);
+  useEffect(() => {
+    sinksRef.current.setAudioPlayback?.(!canPlayAudio ? "blocked" : connected ? "allowed" : "unknown");
+  }, [canPlayAudio, connected]);
+  const unlockTriedRef = useRef(null);
+  const connecting = connectionState === ConnectionState.Connecting || connected;
+  useEffect(() => {
+    if (!setAudioPlayback || !connecting || unlockTriedRef.current === room) return;
+    unlockTriedRef.current = room;
+    void room.startAudio().catch(() => void 0);
+  }, [room, setAudioPlayback, connecting]);
+  const controls = useMemo(() => ({
+    startAudio: async () => {
+      try {
+        await room.startAudio();
+      } catch {
+      }
+      return room.canPlaybackAudio;
+    },
+    setMicrophoneEnabled: async (enabled) => {
+      if (enabled) setEnabling(true);
+      try {
+        await room.localParticipant.setMicrophoneEnabled(enabled);
+      } catch {
+      } finally {
+        if (enabled) setEnabling(false);
+        setVersion((value) => value + 1);
+      }
+    }
+  }), [room]);
+  useEffect(() => {
+    if (!registerMediaControls) return;
+    registerMediaControls(controls);
+    return () => registerMediaControls(null);
+  }, [controls, registerMediaControls]);
+}
+
 // ../client/src/react/session-lifecycle.ts
 function phaseForReason(reason) {
   switch (reason) {
@@ -2846,10 +3104,13 @@ function useSessionLifecycle(input) {
   const reconnectPolicyRef = useRef(reconnectPolicy);
   reconnectPolicyRef.current = reconnectPolicy;
   const connectWatchdogMs = typeof connectWatchdogSeconds === "number" && Number.isFinite(connectWatchdogSeconds) ? Math.max(0, Math.floor(connectWatchdogSeconds)) * 1e3 : DEFAULT_CONNECT_WATCHDOG_SECONDS * 1e3;
+  const [userEnded, setUserEnded] = useState(false);
+  const userEndedRef = useRef(false);
+  const phaseRef = useRef({ kind: "idle" });
   const grantState = useLiveKitAvatarGrant({
     client,
     session,
-    active,
+    active: active && !userEnded,
     autoRetryBusy,
     requestOptions
   });
@@ -2866,6 +3127,8 @@ function useSessionLifecycle(input) {
   refreshRef.current = grantState.refresh;
   const releaseRef = useRef(grantState.release);
   releaseRef.current = grantState.release;
+  const clearRef = useRef(grantState.clear);
+  clearRef.current = grantState.clear;
   const capacityRef = useRef(capacity);
   capacityRef.current = capacity;
   const refreshBaselineCapacityRef = useRef(null);
@@ -2892,13 +3155,16 @@ function useSessionLifecycle(input) {
     refreshBaselineCapacityRef.current = null;
     attemptRef.current = 0;
     setAttempt(0);
-    setRecovery({ kind: "connected" });
+    setRecovery(userEndedRef.current ? { kind: "ended", reason: "user" } : { kind: "connected" });
     setConnected(false);
     setAgentPresentState(false);
     lastActivityRef.current = Date.now();
   }, [clearTimer]);
   useEffect(() => {
-    if (!active) reset();
+    if (active) return;
+    userEndedRef.current = false;
+    setUserEnded(false);
+    reset();
   }, [active, reset]);
   const markActivity = useCallback(() => {
     lastActivityRef.current = Date.now();
@@ -2929,6 +3195,7 @@ function useSessionLifecycle(input) {
     leaveRoomRef.current?.();
   }, [clearTimer]);
   const onConnected = useCallback(() => {
+    if (userEndedRef.current) return;
     clearTimer();
     connectedRef.current = true;
     manualReconnectPendingRef.current = false;
@@ -2941,7 +3208,7 @@ function useSessionLifecycle(input) {
   }, [clearTimer]);
   const onDisconnected = useCallback(
     (reason) => {
-      if (!active) return;
+      if (!active || userEndedRef.current) return;
       const action = disconnectAction(reason, connectedRef.current);
       if (action === "noop") return;
       if (action === "reset") {
@@ -2966,7 +3233,7 @@ function useSessionLifecycle(input) {
   );
   const onConnectionError = useCallback(
     (error) => {
-      if (!active || !isRecoverableConnectionError(error)) return;
+      if (!active || userEndedRef.current || !isRecoverableConnectionError(error)) return;
       connectedRef.current = false;
       setConnected(false);
       setAgentPresentState(false);
@@ -2979,6 +3246,9 @@ function useSessionLifecycle(input) {
     },
     [active]
   );
+  useEffect(() => {
+    if (capacity.kind === "error" && recovery.kind === "connected") manualReconnectPendingRef.current = false;
+  }, [capacity, recovery]);
   useEffect(() => {
     if (recovery.kind !== "refreshing" || capacity.kind !== "error") return;
     const baseline = refreshBaselineCapacityRef.current;
@@ -2988,7 +3258,7 @@ function useSessionLifecycle(input) {
   }, [capacity, recovery]);
   const onConnectionStateChange = useCallback(
     (state) => {
-      if (!active) return;
+      if (!active || userEndedRef.current) return;
       if (state === "connected") {
         onConnected();
         return;
@@ -3036,8 +3306,30 @@ function useSessionLifecycle(input) {
     }, step2.delayMs);
     return clearTimer;
   }, [recovery.kind, active, attempt, clearTimer]);
+  const end = useCallback(() => {
+    if (!active || userEndedRef.current || phaseRef.current.kind === "ended") return;
+    userEndedRef.current = true;
+    clearTimer();
+    connectedRef.current = false;
+    manualReconnectPendingRef.current = false;
+    refreshBaselineCapacityRef.current = null;
+    setUserEnded(true);
+    setConnected(false);
+    setAgentPresentState(false);
+    setRecovery({ kind: "ended", reason: "user" });
+    clearRef.current();
+    leaveRoomRef.current?.();
+  }, [active, clearTimer]);
   const reconnect = useCallback(() => {
-    if (!active || manualReconnectPendingRef.current || recovery.kind === "in-place-reconnecting") return;
+    if (!active) return;
+    if (userEndedRef.current) {
+      userEndedRef.current = false;
+      setUserEnded(false);
+      reset();
+      manualReconnectPendingRef.current = true;
+      return;
+    }
+    if (manualReconnectPendingRef.current || recovery.kind === "in-place-reconnecting") return;
     manualReconnectPendingRef.current = true;
     clearTimer();
     attemptRef.current = 0;
@@ -3046,7 +3338,7 @@ function useSessionLifecycle(input) {
     releaseRef.current("superseded");
     setRecovery({ kind: "refreshing", attempt: 0 });
     refreshRef.current();
-  }, [active, clearTimer, recovery.kind]);
+  }, [active, clearTimer, recovery.kind, reset]);
   const endIdleRef = useRef(endIdle);
   endIdleRef.current = endIdle;
   useEffect(() => {
@@ -3078,6 +3370,7 @@ function useSessionLifecycle(input) {
     () => lifecyclePhaseFrom({ capacity, recovery, idle, connected, agentPresent }),
     [capacity, recovery, idle, connected, agentPresent]
   );
+  phaseRef.current = phase;
   const onBehaviorChangeRef = useRef(onBehaviorChange);
   onBehaviorChangeRef.current = onBehaviorChange;
   const lastBehaviorRef = useRef(null);
@@ -3103,6 +3396,7 @@ function useSessionLifecycle(input) {
       stayConnected,
       markActivity,
       reconnect,
+      end,
       onConnected,
       onDisconnected,
       onConnectionError,
@@ -3121,6 +3415,7 @@ function useSessionLifecycle(input) {
       stayConnected,
       markActivity,
       reconnect,
+      end,
       onConnected,
       onDisconnected,
       onConnectionError,
@@ -3135,7 +3430,8 @@ function useSessionLifecycle(input) {
 function SessionLifecycleRoomBridge({
   lifecycle,
   onConnectionDetailsChange,
-  onMediaModeChange
+  onMediaModeChange,
+  microphone
 }) {
   const {
     onConnectionStateChange,
@@ -3146,12 +3442,23 @@ function SessionLifecycleRoomBridge({
     registerDataPublisher,
     registerTurnSender,
     setTurnState,
-    setMedia
+    setMedia,
+    setMicrophoneFacts,
+    setAudioPlayback,
+    registerMediaControls
   } = lifecycle;
   const connectionState = useConnectionState();
   const assistant = useVoiceAssistant();
   const transcriptions = useTranscriptions();
   const room = useRoomContext();
+  useCallMedia(room, {
+    setMicrophoneFacts,
+    setAudioPlayback,
+    registerMediaControls,
+    microphoneWanted: microphone ?? publishesMicrophoneByDefault(lifecycle.grant),
+    connectionState,
+    callKey: lifecycle.grant?.session_id
+  });
   const mediaModeCallbackRef = useRef(onMediaModeChange);
   mediaModeCallbackRef.current = onMediaModeChange;
   const mediaModeEnabled = onMediaModeChange !== void 0 && lifecycle.grant !== null;
@@ -3425,6 +3732,8 @@ function resolveEndReason(workerLabel, innerReason) {
       return "idle";
     case "error":
       return "failed";
+    case "user":
+      return "user_ended";
     default:
       return "disconnected";
   }
@@ -3480,6 +3789,16 @@ function useRealtimeSession(input) {
   const [turn, setTurn] = useState("quiet");
   const [media, setMediaState] = useState({ video: "connecting", audio: "silent" });
   const [behavior, setBehavior] = useState(null);
+  const [microphoneFacts2, setMicrophoneFactsState] = useState({
+    wanted: false,
+    connected: false,
+    enabling: false,
+    publication: null,
+    deviceError: null
+  });
+  const [microphoneMuted, setMicrophoneMuted] = useState(false);
+  const [audioPlayback, setAudioPlaybackState] = useState("unknown");
+  const mediaControlsRef = useRef(null);
   const lastBehaviorRef = useRef(null);
   const lastLabeledEndReasonRef = useRef(null);
   const pendingClipsRef = useRef(/* @__PURE__ */ new Map());
@@ -3586,6 +3905,31 @@ function useRealtimeSession(input) {
   const setMedia = useCallback((next) => {
     setMediaState((prev) => prev.video === next.video && prev.audio === next.audio ? prev : next);
   }, []);
+  const microphoneFactsRef = useRef(microphoneFacts2);
+  microphoneFactsRef.current = microphoneFacts2;
+  const setMicrophoneFacts = useCallback((facts) => setMicrophoneFactsState(facts), []);
+  const setAudioPlayback = useCallback((playback) => setAudioPlaybackState(playback), []);
+  const registerMediaControls = useCallback((controls) => {
+    mediaControlsRef.current = controls;
+  }, []);
+  const startAudio = useCallback(async () => {
+    const controls = mediaControlsRef.current;
+    return controls ? controls.startAudio() : false;
+  }, []);
+  const callEnded = lifecycle.phase.kind === "ended";
+  const callEndedRef = useRef(callEnded);
+  callEndedRef.current = callEnded;
+  const setMicrophoneEnabled = useCallback(async (enabled) => {
+    if (callEndedRef.current) return;
+    setMicrophoneMuted(!enabled);
+    if (!microphoneFactsRef.current.connected) return;
+    await mediaControlsRef.current?.setMicrophoneEnabled(enabled);
+  }, []);
+  const microphone = useMemo(
+    () => callEnded ? { status: "off" } : callMicrophoneFrom(microphoneFacts2, { muted: microphoneMuted }),
+    [callEnded, microphoneFacts2, microphoneMuted]
+  );
+  const callAudioPlayback = callEnded ? "unknown" : audioPlayback;
   useEffect(() => {
     if (phaseKind === "idle" || phaseKind === "ended") return;
     const timer = window.setInterval(() => {
@@ -3730,11 +4074,23 @@ function useRealtimeSession(input) {
     void sendResolvedTurn(last.text, last.attributes, last.id).catch(() => void 0);
   }, [sendResolvedTurn]);
   const end = useCallback((reason) => {
+    if (phaseKind === "ended") return;
     if (reason) lastLabeledEndReasonRef.current = reason;
     lastTurnRef.current = null;
     requestGracefulClose();
-    lifecycle.reset();
-  }, [lifecycle, requestGracefulClose]);
+    lifecycle.end();
+  }, [lifecycle, phaseKind, requestGracefulClose]);
+  const active = inner.active ?? true;
+  useEffect(() => {
+    if (active) return;
+    lastLabeledEndReasonRef.current = null;
+    setMicrophoneMuted(false);
+  }, [active]);
+  const innerReconnect = lifecycle.reconnect;
+  const reconnect = useCallback(() => {
+    if (phaseKind === "ended") lastLabeledEndReasonRef.current = null;
+    innerReconnect();
+  }, [innerReconnect, phaseKind]);
   const performAction = useCallback(
     (actionId, opts) => {
       const requestId = newTurnId();
@@ -3780,6 +4136,7 @@ function useRealtimeSession(input) {
     approachingFiredRef.current = false;
     creditsLowFiredRef.current = false;
     lastTurnRef.current = null;
+    setMicrophoneMuted(false);
     lifecycle.reset();
   }, [lifecycle]);
   return useMemo(
@@ -3793,6 +4150,12 @@ function useRealtimeSession(input) {
       endsAt,
       graceWindow,
       media,
+      microphone,
+      audioPlayback: callAudioPlayback,
+      startAudio,
+      setMicrophoneEnabled,
+      microphoneMuted,
+      reconnect,
       lifecycle,
       sendClosingTurn,
       requestGracefulClose,
@@ -3808,6 +4171,9 @@ function useRealtimeSession(input) {
       registerTurnSender,
       setTurnState,
       setMedia,
+      setMicrophoneFacts,
+      setAudioPlayback,
+      registerMediaControls,
       reset
     }),
     [
@@ -3817,6 +4183,12 @@ function useRealtimeSession(input) {
       endsAt,
       graceWindow,
       media,
+      microphone,
+      callAudioPlayback,
+      startAudio,
+      setMicrophoneEnabled,
+      microphoneMuted,
+      reconnect,
       sendClosingTurn,
       requestGracefulClose,
       extend,
@@ -3831,6 +4203,9 @@ function useRealtimeSession(input) {
       registerTurnSender,
       setTurnState,
       setMedia,
+      setMicrophoneFacts,
+      setAudioPlayback,
+      registerMediaControls,
       reset
     ]
   );
@@ -3863,9 +4238,31 @@ function handleFor(session) {
       session.sendClosingTurn(text);
     },
     keepAlive: session.stayConnected,
-    end: () => session.end("user_ended")
+    end: () => session.end("user_ended"),
+    microphone: session.microphone,
+    audio: session.audioPlayback,
+    startAudio: session.startAudio,
+    setMicrophoneEnabled: session.setMicrophoneEnabled,
+    retryMicrophone: () => session.setMicrophoneEnabled(true)
   };
 }
+var UNLOCK_REGION = {
+  position: "absolute",
+  top: 16,
+  left: "50%",
+  transform: "translateX(-50%)",
+  zIndex: 1
+};
+var UNLOCK_BUTTON = {
+  padding: "10px 16px",
+  border: "none",
+  borderRadius: 9999,
+  background: "rgb(0 0 0 / 0.7)",
+  color: "white",
+  font: "inherit",
+  fontSize: 14,
+  cursor: "pointer"
+};
 function useAvatarCall(props) {
   const sessionRef = useRef(null);
   const session = useRealtimeSession({
@@ -3889,11 +4286,36 @@ function useAvatarCall(props) {
     lastStatusRef.current = call.status;
     onStatusChange?.(call.status);
   }, [call.status, onStatusChange]);
+  const microphone = call.microphone;
+  const problemKey = microphone.status === "blocked" || microphone.status === "unavailable" ? `${microphone.status}:${microphone.reason}:${microphone.message}` : null;
+  const lastProblemRef = useRef(null);
+  const onMicrophoneProblemRef = useRef(props.onMicrophoneProblem);
+  onMicrophoneProblemRef.current = props.onMicrophoneProblem;
+  useEffect(() => {
+    if (problemKey === lastProblemRef.current) return;
+    lastProblemRef.current = problemKey;
+    if (microphone.status === "blocked" || microphone.status === "unavailable") onMicrophoneProblemRef.current?.(microphone);
+  }, [problemKey]);
+  const prompt = props.audioUnlockPrompt ?? true;
+  const unlock = prompt === false ? null : createElement(
+    "div",
+    { key: "audio-unlock-region", role: "status", "aria-live": "polite", style: UNLOCK_REGION, "data-testid": "avatar-audio-unlock-region" },
+    call.audio !== "blocked" ? null : typeof prompt === "function" ? prompt(call) : createElement(
+      "button",
+      { type: "button", style: UNLOCK_BUTTON, onClick: () => {
+        void call.startAudio();
+      }, "data-testid": "avatar-audio-unlock" },
+      "Tap to turn on sound"
+    )
+  );
+  const overlay = props.children ? props.children(call) : null;
   const view = createElement(
     RealtimeAvatarLiveKitRoom,
     {
       grant: session.grant,
-      audio: props.listen !== false,
+      // LiveKit captures the microphone on connect from this value, so a mute chosen while
+      // waiting is honoured rather than overridden when the call goes live.
+      audio: props.listen !== false && !session.microphoneMuted,
       onConnected: session.onConnected,
       onDisconnected: session.onDisconnected,
       onError: session.onConnectionError
@@ -3901,6 +4323,7 @@ function useAvatarCall(props) {
     createElement(SessionLifecycleRoomBridge, {
       key: "bridge",
       lifecycle: session,
+      microphone: props.listen !== false,
       onConnectionDetailsChange: props.onConnectionDetailsChange
     }),
     createElement(
@@ -3910,9 +4333,10 @@ function useAvatarCall(props) {
         idleVideoUrl: props.idleVideoUrl ?? null,
         poster: props.poster ?? null,
         fit: props.fit ?? "cover",
-        className: props.className
+        className: props.className,
+        style: props.style
       },
-      props.children ? props.children(call) : null
+      overlay === null && unlock === null ? null : createElement(Fragment, null, overlay, unlock)
     )
   );
   return { call, view };
@@ -3931,6 +4355,8 @@ function createProxyClient(options) {
   const base = normalize(options.proxyUrl);
   const doFetch = options.fetch ?? globalThis.fetch?.bind(globalThis);
   const timeoutMs = options.timeoutMs ?? PROXY_CLIENT_TIMEOUT_MS;
+  const credentials = options.credentials;
+  const withCredentials = credentials === void 0 ? {} : { credentials };
   const post = async (path, body, request) => {
     if (!doFetch) throw new Error("realtime-avatar: no fetch available \u2014 pass one via `fetch`.");
     const caller = request?.signal;
@@ -3938,6 +4364,7 @@ function createProxyClient(options) {
     try {
       return await doFetch(`${base}${path}`, {
         method: "POST",
+        ...withCredentials,
         headers: { "content-type": "application/json", ...request?.headers ?? {} },
         body: JSON.stringify(body),
         signal: timer && caller ? AbortSignal.any([caller, timer]) : timer ?? caller
@@ -3947,18 +4374,38 @@ function createProxyClient(options) {
       throw cause;
     }
   };
-  const beacon = (path, body) => {
+  const pageHide = (body) => {
+    const page = globalThis.location?.href;
+    let target;
+    try {
+      target = new URL(`${base}/end`, page);
+    } catch {
+      return false;
+    }
+    const payload = JSON.stringify(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" }));
+    const sameOrigin = page !== void 0 && target.origin === new URL(page).origin;
+    if (send && (sameOrigin || credentials === "include")) {
+      if (send(target.href, new Blob([payload], { type: "application/json" }))) return true;
+    }
+    if (!doFetch) return false;
+    try {
+      void doFetch(target.href, {
+        method: "POST",
+        keepalive: true,
+        ...withCredentials,
+        headers: { "content-type": "application/json" },
+        body: payload
+      }).catch(() => void 0);
+      return true;
+    } catch {
+      return false;
+    }
   };
   return {
     async createLiveKitSessionOrBusy(input, requestOptions) {
-      const response = await post(
-        "/connect",
-        { avatarId: input.avatarId, mode: input.mode },
-        requestOptions
-      );
+      const connect = { avatarId: input.avatarId, mode: input.mode };
+      const response = await post("/connect", connect, requestOptions);
       if (response.status === 429) {
         const value = await response.clone().json().catch(() => null);
         if (value && typeof value === "object" && !Array.isArray(value)) {
@@ -3976,7 +4423,8 @@ function createProxyClient(options) {
     async releaseLiveKitSession(sessionId, reason, requestOptions) {
       if (!sessionId) return false;
       try {
-        const response = await post("/end", { session_id: sessionId, reason }, requestOptions);
+        const body = { session_id: sessionId, reason };
+        const response = await post("/end", body, requestOptions);
         return response.ok;
       } catch {
         return false;
@@ -3984,12 +4432,13 @@ function createProxyClient(options) {
     },
     releaseLiveKitSessionBeacon(sessionId, reason) {
       if (!sessionId) return false;
-      return beacon("/end", { session_id: sessionId, reason: reason ?? "page_hide" });
+      return pageHide({ 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);
+        const body = { queue_ticket_id: queueTicketId, reason };
+        const response = await post("/end", body, requestOptions);
         return response.ok;
       } catch {
         return false;
@@ -3997,7 +4446,7 @@ function createProxyClient(options) {
     },
     releaseLiveKitQueueTicketBeacon(queueTicketId, reason) {
       if (!queueTicketId) return false;
-      return beacon("/end", { queue_ticket_id: queueTicketId, reason: reason ?? "page_hide" });
+      return pageHide({ queue_ticket_id: queueTicketId, reason: reason ?? "page_hide" });
     }
   };
 }