@runwayml/avatars-react 0.9.0 → 0.10.0-beta.1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _livekit_components_react from '@livekit/components-react';
-import { TrackReferenceOrPlaceholder } from '@livekit/components-react';
-export { RoomAudioRenderer as AudioRenderer, VideoTrack } from '@livekit/components-react';
+import { TrackReference, TrackReferenceOrPlaceholder } from '@livekit/components-react';
+export { RoomAudioRenderer as AudioRenderer, VideoTrack, isTrackReference } from '@livekit/components-react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as livekit_client from 'livekit-client';
 import { ComponentPropsWithoutRef, ReactNode } from 'react';
@@ -30,7 +30,7 @@ interface SessionCredentials {
 /**
  * Props for the AvatarSession component
  */
-interface AvatarSessionProps {
+interface AvatarSessionProps<E extends ClientEvent = ClientEvent> {
     /** Connection credentials from Runway API */
     credentials: SessionCredentials;
     /** Children to render inside the session */
@@ -43,6 +43,8 @@ interface AvatarSessionProps {
     onEnd?: () => void;
     /** Callback when an error occurs */
     onError?: (error: Error) => void;
+    /** Callback when a client event is received from the avatar */
+    onClientEvent?: ClientEventHandler<E>;
     /**
      * Pre-captured screen share stream (from getDisplayMedia).
      * When provided, screen sharing activates automatically once the session connects.
@@ -57,7 +59,7 @@ interface AvatarSessionProps {
 /**
  * Props for the AvatarCall component
  */
-interface AvatarCallProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'onError'> {
+interface AvatarCallProps<E extends ClientEvent = ClientEvent> extends Omit<React.ComponentPropsWithoutRef<'div'>, 'onError'> {
     /** The avatar ID to connect to */
     avatarId: string;
     /** Session ID (use with sessionKey - package will call consumeSession) */
@@ -82,6 +84,8 @@ interface AvatarCallProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'o
     onEnd?: () => void;
     /** Callback when an error occurs */
     onError?: (error: Error) => void;
+    /** Callback when a client event is received from the avatar */
+    onClientEvent?: ClientEventHandler<E>;
     /** Custom children - defaults to AvatarVideo + ControlBar if not provided */
     children?: React.ReactNode;
     /**
@@ -106,10 +110,24 @@ interface UseAvatarReturn {
     /** Whether the avatar has video */
     hasVideo: boolean;
 }
+/**
+ * Media device error state exposed to consumers.
+ * Populated when getUserMedia fails (e.g. device held by Zoom).
+ */
+interface MediaDeviceErrors {
+    /** Error from acquiring the microphone, if any */
+    micError: Error | null;
+    /** Error from acquiring the camera, if any */
+    cameraError: Error | null;
+    /** Re-attempt microphone acquisition (e.g. after closing Zoom) */
+    retryMic: () => Promise<void>;
+    /** Re-attempt camera acquisition */
+    retryCamera: () => Promise<void>;
+}
 /**
  * Return type for useLocalMedia hook
  */
-interface UseLocalMediaReturn {
+interface UseLocalMediaReturn extends MediaDeviceErrors {
     /** Whether a microphone device is available */
     hasMic: boolean;
     /** Whether a camera device is available */
@@ -129,8 +147,51 @@ interface UseLocalMediaReturn {
     /** The local video track reference */
     localVideoTrackRef: _livekit_components_react.TrackReferenceOrPlaceholder | null;
 }
+/**
+ * Client event received from the avatar via the data channel.
+ * These are fire-and-forget events triggered by the avatar model.
+ *
+ * @typeParam T - The tool name (defaults to string for untyped usage)
+ * @typeParam A - The args type (defaults to Record<string, unknown>)
+ *
+ * @example
+ * ```typescript
+ * // Untyped usage
+ * const event: ClientEvent = { type: 'client_event', tool: 'show_caption', args: { text: 'Hello' } };
+ *
+ * // Typed usage with discriminated union
+ * type MyEvent = ClientEvent<'show_caption', { text: string }>;
+ * ```
+ */
+interface ClientEvent<T extends string = string, A = Record<string, unknown>> {
+    type: 'client_event';
+    tool: T;
+    args: A;
+}
+/**
+ * Handler function for client events
+ */
+type ClientEventHandler<E extends ClientEvent = ClientEvent> = (event: E) => void;
+/**
+ * A transcription segment received from the session.
+ * SDK-owned type wrapping the underlying transport's transcription data.
+ */
+interface TranscriptionEntry {
+    /** Unique segment identifier */
+    id: string;
+    /** Transcribed text */
+    text: string;
+    /** Whether this is a final (non-streaming) segment */
+    final: boolean;
+    /** Identity of the participant who spoke */
+    participantIdentity: string;
+}
+/**
+ * Handler function for transcription events
+ */
+type TranscriptionHandler = (entry: TranscriptionEntry) => void;
 
-declare function AvatarCall({ avatarId, sessionId, sessionKey, credentials: directCredentials, connectUrl, connect, baseUrl, audio, video, avatarImageUrl, onEnd, onError, children, initialScreenStream, __unstable_roomOptions, ...props }: AvatarCallProps): react_jsx_runtime.JSX.Element;
+declare function AvatarCall<E extends ClientEvent = ClientEvent>({ avatarId, sessionId, sessionKey, credentials: directCredentials, connectUrl, connect, baseUrl, audio, video, avatarImageUrl, onEnd, onError, onClientEvent, children, initialScreenStream, __unstable_roomOptions, ...props }: AvatarCallProps<E>): react_jsx_runtime.JSX.Element;
 
 /**
  * AvatarSession component - the main entry point for avatar sessions
@@ -138,7 +199,7 @@ declare function AvatarCall({ avatarId, sessionId, sessionKey, credentials: dire
  * Establishes a WebRTC connection and provides session state to children.
  * This is a headless component that renders minimal DOM.
  */
-declare function AvatarSession({ credentials, children, audio: requestAudio, video: requestVideo, onEnd, onError, initialScreenStream, __unstable_roomOptions, }: AvatarSessionProps): react_jsx_runtime.JSX.Element;
+declare function AvatarSession<E extends ClientEvent = ClientEvent>({ credentials, children, audio: requestAudio, video: requestVideo, onEnd, onError, onClientEvent, initialScreenStream, __unstable_roomOptions, }: AvatarSessionProps<E>): react_jsx_runtime.JSX.Element;
 
 /**
  * useAvatarStatus Hook
@@ -176,7 +237,7 @@ type AvatarStatus = {
     status: 'waiting';
 } | {
     status: 'ready';
-    videoTrackRef: TrackReferenceOrPlaceholder;
+    videoTrackRef: TrackReference;
 } | {
     status: 'ending';
 } | {
@@ -209,6 +270,10 @@ interface ControlBarState {
     toggleScreenShare: () => void;
     endCall: () => Promise<void>;
     isActive: boolean;
+    micError: Error | null;
+    cameraError: Error | null;
+    retryMic: () => Promise<void>;
+    retryCamera: () => Promise<void>;
 }
 interface ControlBarProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
     showMicrophone?: boolean;
@@ -292,6 +357,70 @@ type UseAvatarSessionReturn = {
  */
 declare function useAvatarSession(): UseAvatarSessionReturn;
 
+type EventArgs<E extends ClientEvent, T extends E['tool']> = Extract<E, {
+    tool: T;
+}>['args'];
+/**
+ * Subscribe to a single client event type by tool name.
+ *
+ * Returns the latest args as React state (`null` before the first event),
+ * and optionally fires a callback on each event for side effects.
+ *
+ * Must be used within an AvatarSession or AvatarCall component.
+ *
+ * @example
+ * ```tsx
+ * // State only — returns latest args
+ * const score = useClientEvent<TriviaEvent, 'update_score'>('update_score');
+ * // score: { score: number; streak: number } | null
+ *
+ * // State + side effect
+ * const result = useClientEvent<TriviaEvent, 'reveal_answer'>('reveal_answer', (args) => {
+ *   if (args.correct) fireConfetti();
+ * });
+ *
+ * // Side effect only — ignore the return value
+ * useClientEvent<TriviaEvent, 'play_sound'>('play_sound', (args) => {
+ *   new Audio(SOUNDS[args.sound]).play();
+ * });
+ * ```
+ */
+declare function useClientEvent<E extends ClientEvent, T extends E['tool']>(toolName: T, onEvent?: (args: EventArgs<E, T>) => void): EventArgs<E, T> | null;
+
+/**
+ * Hook to listen for all client events from the avatar.
+ *
+ * Use this hook in child components to handle client events without prop drilling.
+ * Must be used within an AvatarSession or AvatarCall component.
+ *
+ * @typeParam E - The expected event type (defaults to ClientEvent for untyped usage)
+ *
+ * @example
+ * ```tsx
+ * // Untyped usage
+ * useClientEvents((event) => {
+ *   console.log('Received:', event.tool, event.args);
+ * });
+ *
+ * // Type-safe usage with discriminated union
+ * type MyEvents =
+ *   | ClientEvent<'show_caption', { text: string }>
+ *   | ClientEvent<'play_sound', { url: string }>;
+ *
+ * useClientEvents<MyEvents>((event) => {
+ *   switch (event.tool) {
+ *     case 'show_caption':
+ *       setCaption(event.args.text); // TypeScript knows this is string
+ *       break;
+ *     case 'play_sound':
+ *       new Audio(event.args.url).play();
+ *       break;
+ *   }
+ * });
+ * ```
+ */
+declare function useClientEvents<E extends ClientEvent = ClientEvent>(handler: ClientEventHandler<E>): void;
+
 /**
  * Hook for local media controls (mic, camera, screen share).
  *
@@ -301,4 +430,81 @@ declare function useAvatarSession(): UseAvatarSessionReturn;
  */
 declare function useLocalMedia(): UseLocalMediaReturn;
 
-export { AvatarCall, type AvatarCallProps, AvatarSession, type AvatarStatus, AvatarVideo, type AvatarVideoStatus, ControlBar, ScreenShareVideo, type SessionCredentials, type SessionState, UserVideo, useAvatar, useAvatarSession, useAvatarStatus, useLocalMedia };
+/**
+ * Hook to listen for transcription events from the session.
+ *
+ * Fires the handler for each transcription segment received. By default,
+ * only final segments are delivered. Pass `{ interim: true }` to also
+ * receive partial/streaming segments.
+ *
+ * Must be used within an AvatarSession or AvatarCall component.
+ *
+ * @example
+ * ```tsx
+ * useTranscription((entry) => {
+ *   console.log(`${entry.participantIdentity}: ${entry.text}`);
+ * });
+ *
+ * // Include interim (non-final) segments
+ * useTranscription((entry) => {
+ *   console.log(entry.final ? 'FINAL' : 'partial', entry.text);
+ * }, { interim: true });
+ * ```
+ */
+declare function useTranscription(handler: TranscriptionHandler, options?: {
+    interim?: boolean;
+}): void;
+
+/**
+ * A standalone client tool definition. Composable — combine into arrays
+ * and derive event types with `ClientEventsFrom`.
+ *
+ * At runtime this is just `{ type, name, description }`. The `Args` generic
+ * is phantom — it only exists at the TypeScript level for type narrowing.
+ */
+interface ClientToolDef<Name extends string = string, Args = unknown> {
+    readonly type: 'client_event';
+    readonly name: Name;
+    readonly description: string;
+    /** @internal phantom field — always `undefined` at runtime */
+    readonly _args?: Args;
+}
+/**
+ * Derive a discriminated union of ClientEvent types from an array of tools.
+ *
+ * @example
+ * ```typescript
+ * const tools = [showQuestion, playSound];
+ * type MyEvent = ClientEventsFrom<typeof tools>;
+ * ```
+ */
+type ClientEventsFrom<T extends ReadonlyArray<ClientToolDef>> = T[number] extends infer U ? U extends ClientToolDef<infer Name, infer Args> ? ClientEvent<Name, Args> : never : never;
+/**
+ * Define a single client tool.
+ *
+ * Returns a standalone object that can be composed into arrays and passed
+ * to `realtimeSessions.create({ tools })`.
+ *
+ * @example
+ * ```typescript
+ * const showQuestion = clientTool('show_question', {
+ *   description: 'Display a trivia question',
+ *   args: {} as { question: string; options: Array<string> },
+ * });
+ *
+ * const playSound = clientTool('play_sound', {
+ *   description: 'Play a sound effect',
+ *   args: {} as { sound: 'correct' | 'incorrect' },
+ * });
+ *
+ * // Combine and derive types
+ * const tools = [showQuestion, playSound];
+ * type MyEvent = ClientEventsFrom<typeof tools>;
+ * ```
+ */
+declare function clientTool<Name extends string, Args>(name: Name, config: {
+    description: string;
+    args: Args;
+}): ClientToolDef<Name, Args>;
+
+export { AvatarCall, type AvatarCallProps, AvatarSession, type AvatarStatus, AvatarVideo, type AvatarVideoStatus, type ClientEvent, type ClientEventHandler, type ClientEventsFrom, type ClientToolDef, ControlBar, type MediaDeviceErrors, ScreenShareVideo, type SessionCredentials, type SessionState, type TranscriptionEntry, type TranscriptionHandler, UserVideo, clientTool, useAvatar, useAvatarSession, useAvatarStatus, useClientEvent, useClientEvents, useLocalMedia, useTranscription };

package/dist/index.js

@@ -1,7 +1,7 @@
 import { LiveKitRoom, RoomAudioRenderer, useRoomContext, useConnectionState, useRemoteParticipants, useTracks, isTrackReference, VideoTrack, useLocalParticipant, useMediaDevices, TrackToggle } from '@livekit/components-react';
-export { RoomAudioRenderer as AudioRenderer, VideoTrack } from '@livekit/components-react';
-import { createContext, useRef, useEffect, useCallback, useState, useContext, useSyncExternalStore } from 'react';
-import { ConnectionState, Track } from 'livekit-client';
+export { RoomAudioRenderer as AudioRenderer, VideoTrack, isTrackReference } from '@livekit/components-react';
+import { createContext, useRef, useEffect, useState, useCallback, useMemo, useContext, useSyncExternalStore } from 'react';
+import { ConnectionState, Track, RoomEvent } from 'livekit-client';
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 
 // src/api/config.ts
@@ -153,53 +153,22 @@ function useLatest(value) {
   }, [value]);
   return ref;
 }
-async function hasMediaDevice(kind, timeoutMs = 1e3) {
+
+// src/utils/parseClientEvent.ts
+function isAckMessage(args) {
+  return "status" in args && args.status === "event_sent";
+}
+function parseClientEvent(payload) {
   try {
-    const timeoutPromise = new Promise(
-      (resolve) => setTimeout(() => resolve(false), timeoutMs)
-    );
-    const checkPromise = navigator.mediaDevices.enumerateDevices().then((devices) => devices.some((device) => device.kind === kind));
-    return await Promise.race([checkPromise, timeoutPromise]);
+    const message = JSON.parse(new TextDecoder().decode(payload));
+    if (message?.type === "client_event" && typeof message.tool === "string" && message.args != null && typeof message.args === "object" && !isAckMessage(message.args)) {
+      return message;
+    }
+    return null;
   } catch {
-    return false;
+    return null;
   }
 }
-function useDeviceAvailability(requestAudio, requestVideo) {
-  const [state, setState] = useState({
-    audio: requestAudio,
-    // Optimistically assume devices exist
-    video: requestVideo
-  });
-  useEffect(() => {
-    let cancelled = false;
-    async function checkDevices() {
-      const [hasAudio, hasVideo] = await Promise.all([
-        requestAudio ? hasMediaDevice("audioinput") : Promise.resolve(false),
-        requestVideo ? hasMediaDevice("videoinput") : Promise.resolve(false)
-      ]);
-      if (!cancelled) {
-        setState({
-          audio: requestAudio && hasAudio,
-          video: requestVideo && hasVideo
-        });
-      }
-    }
-    checkDevices();
-    return () => {
-      cancelled = true;
-    };
-  }, [requestAudio, requestVideo]);
-  return state;
-}
-var MEDIA_DEVICE_ERROR_NAMES = /* @__PURE__ */ new Set([
-  "NotAllowedError",
-  "NotFoundError",
-  "NotReadableError",
-  "OverconstrainedError"
-]);
-function isMediaDeviceError(error) {
-  return MEDIA_DEVICE_ERROR_NAMES.has(error.name);
-}
 var DEFAULT_ROOM_OPTIONS = {
   adaptiveStream: false,
   dynacast: false
@@ -221,6 +190,7 @@ function mapConnectionState(connectionState) {
 var AvatarSessionContext = createContext(
   null
 );
+var MediaDeviceErrorContext = createContext(null);
 function AvatarSession({
   credentials,
   children,
@@ -228,16 +198,14 @@ function AvatarSession({
   video: requestVideo = true,
   onEnd,
   onError,
+  onClientEvent,
   initialScreenStream,
   __unstable_roomOptions
 }) {
   const errorRef = useRef(null);
-  const deviceAvailability = useDeviceAvailability(requestAudio, requestVideo);
   const handleError = (error) => {
     onError?.(error);
-    if (!isMediaDeviceError(error)) {
-      errorRef.current = error;
-    }
+    errorRef.current = error;
   };
   const roomOptions = {
     ...DEFAULT_ROOM_OPTIONS,
@@ -249,8 +217,8 @@ function AvatarSession({
       serverUrl: credentials.serverUrl,
       token: credentials.token,
       connect: true,
-      audio: deviceAvailability.audio,
-      video: deviceAvailability.video,
+      audio: false,
+      video: false,
       onDisconnected: () => onEnd?.(),
       onError: handleError,
       options: roomOptions,
@@ -262,7 +230,10 @@ function AvatarSession({
           AvatarSessionContextInner,
           {
             sessionId: credentials.sessionId,
+            requestAudio,
+            requestVideo,
             onEnd,
+            onClientEvent,
             errorRef,
             initialScreenStream,
             children
@@ -275,7 +246,10 @@ function AvatarSession({
 }
 function AvatarSessionContextInner({
   sessionId,
+  requestAudio,
+  requestVideo,
   onEnd,
+  onClientEvent,
   errorRef,
   initialScreenStream,
   children
@@ -284,6 +258,8 @@ function AvatarSessionContextInner({
   const connectionState = useConnectionState();
   const onEndRef = useRef(onEnd);
   onEndRef.current = onEnd;
+  const onClientEventRef = useRef(onClientEvent);
+  onClientEventRef.current = onClientEvent;
   const publishedRef = useRef(false);
   useEffect(() => {
     if (connectionState !== ConnectionState.Connected) return;
@@ -307,6 +283,76 @@ function AvatarSessionContextInner({
       });
     };
   }, [connectionState, initialScreenStream, room]);
+  const [micError, setMicError] = useState(null);
+  const [cameraError, setCameraError] = useState(null);
+  const mediaEnabledRef = useRef(false);
+  useEffect(() => {
+    if (connectionState !== ConnectionState.Connected) return;
+    if (mediaEnabledRef.current) return;
+    mediaEnabledRef.current = true;
+    async function enableMedia() {
+      if (requestAudio) {
+        try {
+          await room.localParticipant.setMicrophoneEnabled(true);
+        } catch (err) {
+          if (err instanceof Error) setMicError(err);
+        }
+      }
+      if (requestVideo) {
+        try {
+          await room.localParticipant.setCameraEnabled(true);
+        } catch (err) {
+          if (err instanceof Error) setCameraError(err);
+        }
+      }
+    }
+    enableMedia();
+  }, [connectionState, room, requestAudio, requestVideo]);
+  useEffect(() => {
+    function handleMediaDevicesError(error, kind) {
+      if (kind === "audioinput") {
+        setMicError(error);
+      } else if (kind === "videoinput") {
+        setCameraError(error);
+      }
+    }
+    room.on(RoomEvent.MediaDevicesError, handleMediaDevicesError);
+    return () => {
+      room.off(RoomEvent.MediaDevicesError, handleMediaDevicesError);
+    };
+  }, [room]);
+  const retryMic = useCallback(async () => {
+    try {
+      await room.localParticipant.setMicrophoneEnabled(true);
+      setMicError(null);
+    } catch (err) {
+      if (err instanceof Error) setMicError(err);
+    }
+  }, [room]);
+  const retryCamera = useCallback(async () => {
+    try {
+      await room.localParticipant.setCameraEnabled(true);
+      setCameraError(null);
+    } catch (err) {
+      if (err instanceof Error) setCameraError(err);
+    }
+  }, [room]);
+  const mediaDeviceErrors = useMemo(
+    () => ({ micError, cameraError, retryMic, retryCamera }),
+    [micError, cameraError, retryMic, retryCamera]
+  );
+  useEffect(() => {
+    function handleDataReceived(payload) {
+      const event = parseClientEvent(payload);
+      if (event) {
+        onClientEventRef.current?.(event);
+      }
+    }
+    room.on(RoomEvent.DataReceived, handleDataReceived);
+    return () => {
+      room.off(RoomEvent.DataReceived, handleDataReceived);
+    };
+  }, [room]);
   const end = useCallback(async () => {
     try {
       const encoder = new TextEncoder();
@@ -323,7 +369,7 @@ function AvatarSessionContextInner({
     error: errorRef.current,
     end
   };
-  return /* @__PURE__ */ jsx(AvatarSessionContext.Provider, { value: contextValue, children });
+  return /* @__PURE__ */ jsx(AvatarSessionContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsx(MediaDeviceErrorContext.Provider, { value: mediaDeviceErrors, children }) });
 }
 function useAvatarSessionContext() {
   const context = useContext(AvatarSessionContext);
@@ -334,6 +380,9 @@ function useAvatarSessionContext() {
   }
   return context;
 }
+function useMediaDeviceErrorContext() {
+  return useContext(MediaDeviceErrorContext);
+}
 function useAvatar() {
   const remoteParticipants = useRemoteParticipants();
   const avatarParticipant = remoteParticipants[0] ?? null;
@@ -369,7 +418,10 @@ function useAvatarStatus() {
       return { status: "connecting" };
     case "active":
       if (hasVideo && videoTrackRef) {
-        return { status: "ready", videoTrackRef };
+        return {
+          status: "ready",
+          videoTrackRef
+        };
       }
       return { status: "waiting" };
     case "ending":
@@ -396,8 +448,16 @@ function AvatarVideo({ children, ...props }) {
     }
   );
 }
+var NOOP_ASYNC = async () => {
+};
 function useLocalMedia() {
   const { localParticipant } = useLocalParticipant();
+  const {
+    micError = null,
+    cameraError = null,
+    retryMic = NOOP_ASYNC,
+    retryCamera = NOOP_ASYNC
+  } = useMediaDeviceErrorContext() ?? {};
   const audioDevices = useMediaDevices({ kind: "audioinput" });
   const videoDevices = useMediaDevices({ kind: "videoinput" });
   const hasMic = audioDevices?.length > 0;
@@ -443,7 +503,11 @@ function useLocalMedia() {
     toggleMic,
     toggleCamera,
     toggleScreenShare,
-    localVideoTrackRef
+    localVideoTrackRef,
+    micError,
+    cameraError,
+    retryMic,
+    retryCamera
   };
 }
 function ControlBar({
@@ -461,7 +525,11 @@ function ControlBar({
     isScreenShareEnabled,
     toggleMic,
     toggleCamera,
-    toggleScreenShare
+    toggleScreenShare,
+    micError,
+    cameraError,
+    retryMic,
+    retryCamera
   } = useLocalMedia();
   const isActive = session.state === "active";
   const state = {
@@ -472,7 +540,11 @@ function ControlBar({
     toggleCamera,
     toggleScreenShare,
     endCall: session.end,
-    isActive
+    isActive,
+    micError,
+    cameraError,
+    retryMic,
+    retryCamera
   };
   if (children) {
     return /* @__PURE__ */ jsx(Fragment, { children: children(state) });
@@ -634,6 +706,7 @@ function AvatarCall({
   avatarImageUrl,
   onEnd,
   onError,
+  onClientEvent,
   children,
   initialScreenStream,
   __unstable_roomOptions,
@@ -687,6 +760,7 @@ function AvatarCall({
           video,
           onEnd,
           onError: handleSessionError,
+          onClientEvent,
           initialScreenStream,
           __unstable_roomOptions,
           children: children ?? defaultChildren
@@ -721,7 +795,79 @@ function ScreenShareVideo({
   }
   return /* @__PURE__ */ jsx("div", { ...props, "data-avatar-screen-share": "", "data-avatar-sharing": isSharing, children: screenShareTrackRef && isTrackReference(screenShareTrackRef) && /* @__PURE__ */ jsx(VideoTrack, { trackRef: screenShareTrackRef }) });
 }
+function useClientEvent(toolName, onEvent) {
+  const room = useRoomContext();
+  const [state, setState] = useState(null);
+  const onEventRef = useRef(onEvent);
+  onEventRef.current = onEvent;
+  useEffect(() => {
+    function handleDataReceived(payload) {
+      const event = parseClientEvent(payload);
+      if (event && event.tool === toolName) {
+        const args = event.args;
+        setState(args);
+        onEventRef.current?.(args);
+      }
+    }
+    room.on(RoomEvent.DataReceived, handleDataReceived);
+    return () => {
+      room.off(RoomEvent.DataReceived, handleDataReceived);
+    };
+  }, [room, toolName]);
+  return state;
+}
+function useClientEvents(handler) {
+  const room = useRoomContext();
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+  useEffect(() => {
+    function handleDataReceived(payload) {
+      const event = parseClientEvent(payload);
+      if (event) {
+        handlerRef.current(event);
+      }
+    }
+    room.on(RoomEvent.DataReceived, handleDataReceived);
+    return () => {
+      room.off(RoomEvent.DataReceived, handleDataReceived);
+    };
+  }, [room]);
+}
+function useTranscription(handler, options) {
+  const room = useRoomContext();
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+  const interimRef = useRef(options?.interim ?? false);
+  interimRef.current = options?.interim ?? false;
+  useEffect(() => {
+    function handleTranscription(segments, participant) {
+      const identity = participant?.identity ?? "unknown";
+      for (const segment of segments) {
+        if (!interimRef.current && !segment.final) continue;
+        handlerRef.current({
+          id: segment.id,
+          text: segment.text,
+          final: segment.final,
+          participantIdentity: identity
+        });
+      }
+    }
+    room.on(RoomEvent.TranscriptionReceived, handleTranscription);
+    return () => {
+      room.off(RoomEvent.TranscriptionReceived, handleTranscription);
+    };
+  }, [room]);
+}
+
+// src/tools.ts
+function clientTool(name, config) {
+  return {
+    type: "client_event",
+    name,
+    description: config.description
+  };
+}
 
-export { AvatarCall, AvatarSession, AvatarVideo, ControlBar, ScreenShareVideo, UserVideo, useAvatar, useAvatarSession, useAvatarStatus, useLocalMedia };
+export { AvatarCall, AvatarSession, AvatarVideo, ControlBar, ScreenShareVideo, UserVideo, clientTool, useAvatar, useAvatarSession, useAvatarStatus, useClientEvent, useClientEvents, useLocalMedia, useTranscription };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map