@runwayml/avatars-react 0.10.0-beta.0 → 0.11.0

package/README.md

@@ -46,17 +46,20 @@ import '@runwayml/avatars-react/styles.css';
 The styles use CSS custom properties for easy customization:
 
 ```css
-:root {
-  --avatar-bg: #a78bfa;           /* Video background color */
-  --avatar-radius: 16px;          /* Container border radius */
-  --avatar-control-size: 48px;    /* Control button size */
-  --avatar-end-call-bg: #ef4444;  /* End call button color */
+[data-avatar-call] {
+  --avatar-bg-connecting: #8b5cf6;         /* Video background color */
+  --avatar-radius: 16px;                   /* Container border radius */
+  --avatar-control-size: 40px;             /* Control button size */
+  --avatar-end-call-bg: #ff552f;           /* End call button color */
+  --avatar-screen-share-active-bg: #fff;   /* Active share button background */
 }
 ```
 
 See [`examples/`](./examples) for complete working examples:
 - [`nextjs`](./examples/nextjs) - Next.js App Router
 - [`nextjs-client-events`](./examples/nextjs-client-events) - Client event tools (trivia game)
+- [`nextjs-rpc`](./examples/nextjs-rpc) - Backend RPC + client events (trivia with server-side questions)
+- [`nextjs-rpc-weather`](./examples/nextjs-rpc-weather) - Backend RPC only (weather assistant)
 - [`nextjs-server-actions`](./examples/nextjs-server-actions) - Next.js with Server Actions
 - [`react-router`](./examples/react-router) - React Router v7 framework mode
 - [`express`](./examples/express) - Express + Vite
@@ -151,38 +154,41 @@ import { AvatarCall, AvatarVideo, ControlBar, UserVideo } from '@runwayml/avatar
 
 ### Render Props
 
-All components support render props for complete control:
+All display components support render props for complete control. `AvatarVideo` receives a discriminated union with `status`:
 
 ```tsx
 <AvatarVideo>
-  {({ hasVideo, isConnecting, trackRef }) => (
-    <div>
-      {isConnecting && <Spinner />}
-      {hasVideo && <VideoTrack trackRef={trackRef} />}
-    </div>
-  )}
+  {(avatar) => {
+    switch (avatar.status) {
+      case 'connecting': return <Spinner />;
+      case 'waiting': return <Placeholder />;
+      case 'ready': return <VideoTrack trackRef={avatar.videoTrackRef} />;
+    }
+  }}
 </AvatarVideo>
 ```
 
 ### CSS Styling with Data Attributes
 
-Style connection states with CSS:
+Style components with the namespaced `data-avatar-*` attributes:
 
 ```tsx
 <AvatarCall avatarId="music-superstar" connectUrl="/api/avatar/connect" className="my-avatar" />
 ```
 
 ```css
-.my-avatar[data-state="connecting"] {
+/* Style avatar video by connection status */
+[data-avatar-video][data-avatar-status="connecting"] {
   opacity: 0.5;
 }
 
-.my-avatar[data-state="error"] {
-  border: 2px solid red;
+[data-avatar-video][data-avatar-status="ready"] {
+  opacity: 1;
 }
 
-.my-avatar[data-state="connected"] {
-  border: 2px solid green;
+/* Style control buttons */
+[data-avatar-control][data-avatar-enabled="false"] {
+  opacity: 0.5;
 }
 ```
 
@@ -233,6 +239,8 @@ Enable the screen share button by passing `showScreenShare` to `ControlBar`, and
 </AvatarCall>
 ```
 
+While sharing is active, the default `ControlBar` UI shows a sharing banner with a quick `Stop` action.
+
 You can also start screen sharing automatically by passing a pre-captured stream via `initialScreenStream`. This is useful when you want to prompt the user for screen share permission before the session connects:
 
 ```tsx
@@ -346,6 +354,8 @@ function MediaControls() {
 
 ## Client Events
 
+> **Compatibility:** Client events (tool calling) are supported on avatars that use a **preset voice**. Custom voice avatars do not currently support client events.
+
 Avatars can trigger UI events via tool calls sent over the data channel. Define tools, pass them when creating a session, and subscribe on the client:
 
 ```ts

package/dist/index.cjs

@@ -170,53 +170,6 @@ function parseClientEvent(payload) {
     return null;
   }
 }
-async function hasMediaDevice(kind, timeoutMs = 1e3) {
-  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]);
-  } catch {
-    return false;
-  }
-}
-function useDeviceAvailability(requestAudio, requestVideo) {
-  const [state, setState] = react.useState({
-    audio: requestAudio,
-    // Optimistically assume devices exist
-    video: requestVideo
-  });
-  react.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
@@ -238,6 +191,7 @@ function mapConnectionState(connectionState) {
 var AvatarSessionContext = react.createContext(
   null
 );
+var MediaDeviceErrorContext = react.createContext(null);
 function AvatarSession({
   credentials,
   children,
@@ -250,12 +204,9 @@ function AvatarSession({
   __unstable_roomOptions
 }) {
   const errorRef = react.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,
@@ -267,8 +218,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,
@@ -280,6 +231,8 @@ function AvatarSession({
           AvatarSessionContextInner,
           {
             sessionId: credentials.sessionId,
+            requestAudio,
+            requestVideo,
             onEnd,
             onClientEvent,
             errorRef,
@@ -294,6 +247,8 @@ function AvatarSession({
 }
 function AvatarSessionContextInner({
   sessionId,
+  requestAudio,
+  requestVideo,
   onEnd,
   onClientEvent,
   errorRef,
@@ -329,6 +284,64 @@ function AvatarSessionContextInner({
       });
     };
   }, [connectionState, initialScreenStream, room]);
+  const [micError, setMicError] = react.useState(null);
+  const [cameraError, setCameraError] = react.useState(null);
+  const mediaEnabledRef = react.useRef(false);
+  react.useEffect(() => {
+    if (connectionState !== livekitClient.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]);
+  react.useEffect(() => {
+    function handleMediaDevicesError(error, kind) {
+      if (kind === "audioinput") {
+        setMicError(error);
+      } else if (kind === "videoinput") {
+        setCameraError(error);
+      }
+    }
+    room.on(livekitClient.RoomEvent.MediaDevicesError, handleMediaDevicesError);
+    return () => {
+      room.off(livekitClient.RoomEvent.MediaDevicesError, handleMediaDevicesError);
+    };
+  }, [room]);
+  const retryMic = react.useCallback(async () => {
+    try {
+      await room.localParticipant.setMicrophoneEnabled(true);
+      setMicError(null);
+    } catch (err) {
+      if (err instanceof Error) setMicError(err);
+    }
+  }, [room]);
+  const retryCamera = react.useCallback(async () => {
+    try {
+      await room.localParticipant.setCameraEnabled(true);
+      setCameraError(null);
+    } catch (err) {
+      if (err instanceof Error) setCameraError(err);
+    }
+  }, [room]);
+  const mediaDeviceErrors = react.useMemo(
+    () => ({ micError, cameraError, retryMic, retryCamera }),
+    [micError, cameraError, retryMic, retryCamera]
+  );
   react.useEffect(() => {
     function handleDataReceived(payload) {
       const event = parseClientEvent(payload);
@@ -357,7 +370,7 @@ function AvatarSessionContextInner({
     error: errorRef.current,
     end
   };
-  return /* @__PURE__ */ jsxRuntime.jsx(AvatarSessionContext.Provider, { value: contextValue, children });
+  return /* @__PURE__ */ jsxRuntime.jsx(AvatarSessionContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsxRuntime.jsx(MediaDeviceErrorContext.Provider, { value: mediaDeviceErrors, children }) });
 }
 function useAvatarSessionContext() {
   const context = react.useContext(AvatarSessionContext);
@@ -368,6 +381,9 @@ function useAvatarSessionContext() {
   }
   return context;
 }
+function useMediaDeviceErrorContext() {
+  return react.useContext(MediaDeviceErrorContext);
+}
 function useAvatar() {
   const remoteParticipants = componentsReact.useRemoteParticipants();
   const avatarParticipant = remoteParticipants[0] ?? null;
@@ -433,8 +449,24 @@ function AvatarVideo({ children, ...props }) {
     }
   );
 }
+var NOOP_ASYNC = async () => {
+};
+function createCaptureController() {
+  if (typeof window === "undefined" || !("CaptureController" in window)) {
+    return void 0;
+  }
+  const controller = new window.CaptureController();
+  controller.setFocusBehavior("no-focus-change");
+  return controller;
+}
 function useLocalMedia() {
   const { localParticipant } = componentsReact.useLocalParticipant();
+  const {
+    micError = null,
+    cameraError = null,
+    retryMic = NOOP_ASYNC,
+    retryCamera = NOOP_ASYNC
+  } = useMediaDeviceErrorContext() ?? {};
   const audioDevices = componentsReact.useMediaDevices({ kind: "audioinput" });
   const videoDevices = componentsReact.useMediaDevices({ kind: "videoinput" });
   const hasMic = audioDevices?.length > 0;
@@ -458,7 +490,16 @@ function useLocalMedia() {
     }
   }, [localParticipant]);
   const toggleScreenShare = react.useCallback(() => {
-    localParticipant?.setScreenShareEnabled(!isScreenShareEnabledRef.current);
+    const next = !isScreenShareEnabledRef.current;
+    if (next) {
+      const controller = createCaptureController();
+      localParticipant?.setScreenShareEnabled(true, {
+        controller,
+        surfaceSwitching: "include"
+      });
+    } else {
+      localParticipant?.setScreenShareEnabled(false);
+    }
   }, [localParticipant]);
   const tracks = componentsReact.useTracks(
     [{ source: livekitClient.Track.Source.Camera, withPlaceholder: true }],
@@ -480,7 +521,11 @@ function useLocalMedia() {
     toggleMic,
     toggleCamera,
     toggleScreenShare,
-    localVideoTrackRef
+    localVideoTrackRef,
+    micError,
+    cameraError,
+    retryMic,
+    retryCamera
   };
 }
 function ControlBar({
@@ -498,9 +543,17 @@ function ControlBar({
     isScreenShareEnabled,
     toggleMic,
     toggleCamera,
-    toggleScreenShare
+    toggleScreenShare,
+    micError,
+    cameraError,
+    retryMic,
+    retryCamera
   } = useLocalMedia();
   const isActive = session.state === "active";
+  const handleStopScreenShare = react.useCallback(() => {
+    if (!isScreenShareEnabled) return;
+    toggleScreenShare();
+  }, [isScreenShareEnabled, toggleScreenShare]);
   const state = {
     isMicEnabled,
     isCameraEnabled,
@@ -509,7 +562,11 @@ function ControlBar({
     toggleCamera,
     toggleScreenShare,
     endCall: session.end,
-    isActive
+    isActive,
+    micError,
+    cameraError,
+    retryMic,
+    retryCamera
   };
   if (children) {
     return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: children(state) });
@@ -518,57 +575,71 @@ function ControlBar({
     return null;
   }
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { ...props, "data-avatar-control-bar": "", "data-avatar-active": isActive, children: [
-    showMicrophone && /* @__PURE__ */ jsxRuntime.jsx(
-      "button",
-      {
-        type: "button",
-        onClick: toggleMic,
-        "data-avatar-control": "microphone",
-        "data-avatar-enabled": isMicEnabled,
-        "aria-label": isMicEnabled ? "Mute microphone" : "Unmute microphone",
-        children: microphoneIcon
-      }
-    ),
-    showCamera && /* @__PURE__ */ jsxRuntime.jsx(
-      "button",
-      {
-        type: "button",
-        onClick: toggleCamera,
-        "data-avatar-control": "camera",
-        "data-avatar-enabled": isCameraEnabled,
-        "aria-label": isCameraEnabled ? "Turn off camera" : "Turn on camera",
-        children: cameraIcon
-      }
-    ),
-    showScreenShare && /* @__PURE__ */ jsxRuntime.jsx(
-      componentsReact.TrackToggle,
-      {
-        source: livekitClient.Track.Source.ScreenShare,
-        showIcon: false,
-        "data-avatar-control": "screen-share",
-        "data-avatar-enabled": isScreenShareEnabled,
-        "aria-label": "Toggle screen share",
-        children: screenShareIcon
-      }
-    ),
-    showEndCall && /* @__PURE__ */ jsxRuntime.jsx(
-      "button",
-      {
-        type: "button",
-        onClick: session.end,
-        "data-avatar-control": "end-call",
-        "data-avatar-enabled": true,
-        "aria-label": "End call",
-        children: phoneIcon
-      }
-    )
+    showScreenShare && isScreenShareEnabled && /* @__PURE__ */ jsxRuntime.jsxs("div", { "data-avatar-share-indicator": "", "aria-live": "polite", children: [
+      /* @__PURE__ */ jsxRuntime.jsx("span", { "data-avatar-share-label": "", children: "You're sharing your screen" }),
+      /* @__PURE__ */ jsxRuntime.jsx("div", { "data-avatar-share-actions": "", children: /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          type: "button",
+          onClick: handleStopScreenShare,
+          "data-avatar-share-action": "stop",
+          children: "Stop"
+        }
+      ) })
+    ] }),
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { "data-avatar-controls": "", children: [
+      showMicrophone && /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          type: "button",
+          onClick: toggleMic,
+          "data-avatar-control": "microphone",
+          "data-avatar-enabled": isMicEnabled,
+          "aria-label": isMicEnabled ? "Mute microphone" : "Unmute microphone",
+          children: microphoneIcon
+        }
+      ),
+      showCamera && /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          type: "button",
+          onClick: toggleCamera,
+          "data-avatar-control": "camera",
+          "data-avatar-enabled": isCameraEnabled,
+          "aria-label": isCameraEnabled ? "Turn off camera" : "Turn on camera",
+          children: cameraIcon
+        }
+      ),
+      showScreenShare && /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          type: "button",
+          onClick: toggleScreenShare,
+          "data-avatar-control": "screen-share",
+          "data-avatar-enabled": isScreenShareEnabled,
+          "aria-label": isScreenShareEnabled ? "Stop sharing screen" : "Share screen",
+          children: screenShareIcon
+        }
+      ),
+      showEndCall && /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          type: "button",
+          onClick: session.end,
+          "data-avatar-control": "end-call",
+          "data-avatar-enabled": true,
+          "aria-label": "End call",
+          children: phoneIcon
+        }
+      )
+    ] })
   ] });
 }
 var microphoneIcon = /* @__PURE__ */ jsxRuntime.jsxs(
   "svg",
   {
-    width: "20",
-    height: "20",
+    width: "16",
+    height: "16",
     viewBox: "0 0 24 24",
     fill: "none",
     stroke: "currentColor",
@@ -586,8 +657,8 @@ var microphoneIcon = /* @__PURE__ */ jsxRuntime.jsxs(
 var cameraIcon = /* @__PURE__ */ jsxRuntime.jsxs(
   "svg",
   {
-    width: "20",
-    height: "20",
+    width: "16",
+    height: "16",
     viewBox: "0 0 24 24",
     fill: "none",
     stroke: "currentColor",
@@ -604,8 +675,8 @@ var cameraIcon = /* @__PURE__ */ jsxRuntime.jsxs(
 var screenShareIcon = /* @__PURE__ */ jsxRuntime.jsxs(
   "svg",
   {
-    width: "20",
-    height: "20",
+    width: "16",
+    height: "16",
     viewBox: "0 0 24 24",
     fill: "none",
     stroke: "currentColor",
@@ -614,17 +685,19 @@ var screenShareIcon = /* @__PURE__ */ jsxRuntime.jsxs(
     strokeLinejoin: "round",
     "aria-hidden": "true",
     children: [
-      /* @__PURE__ */ jsxRuntime.jsx("rect", { width: "20", height: "14", x: "2", y: "3", rx: "2" }),
-      /* @__PURE__ */ jsxRuntime.jsx("line", { x1: "8", x2: "16", y1: "21", y2: "21" }),
-      /* @__PURE__ */ jsxRuntime.jsx("line", { x1: "12", x2: "12", y1: "17", y2: "21" })
+      /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M13 3H4a2 2 0 0 0-2 2v10a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-3" }),
+      /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M8 21h8" }),
+      /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M12 17v4" }),
+      /* @__PURE__ */ jsxRuntime.jsx("path", { d: "m17 8 5-5" }),
+      /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M17 3h5v5" })
     ]
   }
 );
 var phoneIcon = /* @__PURE__ */ jsxRuntime.jsx(
   "svg",
   {
-    width: "20",
-    height: "20",
+    width: "16",
+    height: "16",
     viewBox: "8 14 24 12",
     fill: "currentColor",
     "aria-hidden": "true",