@runwayml/avatars-react 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -124,7 +124,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, video, onEnd, onError, __unstable_roomOptions, }: AvatarSessionProps): react_jsx_runtime.JSX.Element;
+declare function AvatarSession({ credentials, children, audio: requestAudio, video: requestVideo, onEnd, onError, __unstable_roomOptions, }: AvatarSessionProps): react_jsx_runtime.JSX.Element;
 
 /**
  * useAvatarStatus Hook
@@ -273,6 +273,10 @@ type UseAvatarSessionReturn = {
  */
 declare function useAvatarSession(): UseAvatarSessionReturn;
 
+/**
+ * Hook for local media controls (mic, camera, screen share).
+ * Returns safe defaults when called outside of LiveKitRoom context.
+ */
 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 };

package/dist/index.d.ts

@@ -124,7 +124,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, video, onEnd, onError, __unstable_roomOptions, }: AvatarSessionProps): react_jsx_runtime.JSX.Element;
+declare function AvatarSession({ credentials, children, audio: requestAudio, video: requestVideo, onEnd, onError, __unstable_roomOptions, }: AvatarSessionProps): react_jsx_runtime.JSX.Element;
 
 /**
  * useAvatarStatus Hook
@@ -273,6 +273,10 @@ type UseAvatarSessionReturn = {
  */
 declare function useAvatarSession(): UseAvatarSessionReturn;
 
+/**
+ * Hook for local media controls (mic, camera, screen share).
+ * Returns safe defaults when called outside of LiveKitRoom context.
+ */
 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 };

package/dist/index.js

@@ -1,8 +1,8 @@
-import { LiveKitRoom, RoomAudioRenderer, useRoomContext, useConnectionState, useRemoteParticipants, useTracks, isTrackReference, VideoTrack, useLocalParticipant, useMediaDevices, TrackToggle } from '@livekit/components-react';
+import { LiveKitRoom, RoomAudioRenderer, useRoomContext, useConnectionState, useMaybeRoomContext, useRemoteParticipants, useTracks, isTrackReference, VideoTrack, useLocalParticipant, useMediaDevices, TrackToggle } from '@livekit/components-react';
 export { RoomAudioRenderer as AudioRenderer, VideoTrack } from '@livekit/components-react';
-import { createContext, useRef, useCallback, useContext, useEffect } from 'react';
+import { createContext, useRef, useCallback, useState, useEffect, useContext } from 'react';
 import { Track, ConnectionState } from 'livekit-client';
-import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
 // src/api/config.ts
 var DEFAULT_BASE_URL = "https://api.dev.runwayml.com";
@@ -26,44 +26,15 @@ async function consumeSession(options) {
   }
   return response.json();
 }
-
-// src/utils/suspense-resource.ts
-function createSuspenseResource(promise) {
-  let status = "pending";
-  let result;
-  let error;
-  const suspender = promise.then(
-    (value) => {
-      status = "fulfilled";
-      result = value;
-    },
-    (err) => {
-      status = "rejected";
-      error = err;
-    }
-  );
-  return {
-    read() {
-      switch (status) {
-        case "pending":
-          throw suspender;
-        case "rejected":
-          throw error;
-        case "fulfilled":
-          return result;
-      }
-    }
-  };
+function useLatest(value) {
+  const ref = useRef(value);
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref;
 }
 
 // src/hooks/useCredentials.ts
-var resourceCache = /* @__PURE__ */ new Map();
-function computeKey(options) {
-  if (options.credentials) return `direct:${options.credentials.sessionId}`;
-  if (options.sessionId && options.sessionKey)
-    return `session:${options.sessionId}`;
-  return `connect:${options.avatarId}:${options.connectUrl ?? "custom"}`;
-}
 async function fetchCredentials(options) {
   const { avatarId, sessionId, sessionKey, connectUrl, connect, baseUrl } = options;
   if (sessionId && sessionKey) {
@@ -94,28 +65,106 @@ async function fetchCredentials(options) {
   );
 }
 function useCredentials(options) {
-  const key = computeKey(options);
+  const {
+    credentials: directCredentials,
+    avatarId,
+    sessionId,
+    sessionKey,
+    connectUrl,
+    connect,
+    baseUrl,
+    onError
+  } = options;
+  const onErrorRef = useLatest(onError);
+  const [state, setState] = useState(() => {
+    if (directCredentials) {
+      return { status: "ready", credentials: directCredentials, error: null };
+    }
+    return { status: "loading", credentials: null, error: null };
+  });
   useEffect(() => {
+    if (directCredentials) {
+      setState({
+        status: "ready",
+        credentials: directCredentials,
+        error: null
+      });
+      return;
+    }
+    let cancelled = false;
+    setState({ status: "loading", credentials: null, error: null });
+    async function load() {
+      try {
+        const fetchOptions = {
+          avatarId,
+          sessionId,
+          sessionKey,
+          connectUrl,
+          connect,
+          baseUrl
+        };
+        const credentials = await fetchCredentials(fetchOptions);
+        if (!cancelled) {
+          setState({ status: "ready", credentials, error: null });
+        }
+      } catch (err) {
+        if (!cancelled) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          setState({ status: "error", credentials: null, error });
+          onErrorRef.current?.(error);
+        }
+      }
+    }
+    load();
     return () => {
-      resourceCache.delete(key);
+      cancelled = true;
     };
-  }, [key]);
-  if (options.credentials) {
-    return options.credentials;
-  }
-  let resource = resourceCache.get(key);
-  if (!resource) {
-    resource = createSuspenseResource(fetchCredentials(options));
-    resourceCache.set(key, resource);
+  }, [
+    directCredentials,
+    avatarId,
+    sessionId,
+    sessionKey,
+    connectUrl,
+    connect,
+    baseUrl
+  ]);
+  return state;
+}
+async function hasMediaDevice(kind) {
+  try {
+    const devices = await navigator.mediaDevices.enumerateDevices();
+    return devices.some((device) => device.kind === kind);
+  } catch {
+    return false;
   }
-  return resource.read();
 }
-function useLatest(value) {
-  const ref = useRef(value);
+function useDeviceAvailability(requestAudio, requestVideo) {
+  const [state, setState] = useState({
+    audio: false,
+    video: false,
+    isChecking: true
+  });
   useEffect(() => {
-    ref.current = value;
-  }, [value]);
-  return ref;
+    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,
+          isChecking: false
+        });
+      }
+    }
+    checkDevices();
+    return () => {
+      cancelled = true;
+    };
+  }, [requestAudio, requestVideo]);
+  return state;
 }
 var DEFAULT_ROOM_OPTIONS = {
   adaptiveStream: false,
@@ -141,13 +190,14 @@ var AvatarSessionContext = createContext(
 function AvatarSession({
   credentials,
   children,
-  audio = true,
-  video = true,
+  audio: requestAudio = true,
+  video: requestVideo = true,
   onEnd,
   onError,
   __unstable_roomOptions
 }) {
   const errorRef = useRef(null);
+  const deviceAvailability = useDeviceAvailability(requestAudio, requestVideo);
   const handleError = (error) => {
     errorRef.current = error;
     onError?.(error);
@@ -156,14 +206,29 @@ function AvatarSession({
     ...DEFAULT_ROOM_OPTIONS,
     ...__unstable_roomOptions
   };
+  if (deviceAvailability.isChecking) {
+    return /* @__PURE__ */ jsx(
+      AvatarSessionContext.Provider,
+      {
+        value: {
+          state: "connecting",
+          sessionId: credentials.sessionId,
+          error: null,
+          end: async () => {
+          }
+        },
+        children
+      }
+    );
+  }
   return /* @__PURE__ */ jsxs(
     LiveKitRoom,
     {
       serverUrl: credentials.serverUrl,
       token: credentials.token,
       connect: true,
-      audio,
-      video,
+      audio: deviceAvailability.audio,
+      video: deviceAvailability.video,
       onDisconnected: () => onEnd?.(),
       onError: handleError,
       options: roomOptions,
@@ -222,14 +287,34 @@ function useAvatarSessionContext() {
   }
   return context;
 }
+function LoadingSessionProvider({
+  state,
+  error,
+  children
+}) {
+  const contextValue = {
+    state,
+    sessionId: "",
+    error,
+    end: async () => {
+    }
+  };
+  return /* @__PURE__ */ jsx(AvatarSessionContext.Provider, { value: contextValue, children });
+}
 function useAvatar() {
-  const remoteParticipants = useRemoteParticipants();
+  const room = useMaybeRoomContext();
+  const hasRoomContext = room !== void 0;
+  const remoteParticipants = useRemoteParticipants({ room });
   const avatarParticipant = remoteParticipants[0] ?? null;
   const videoTracks = useTracks(
     [{ source: Track.Source.Camera, withPlaceholder: true }],
-    { onlySubscribed: true, updateOnlyOn: [] }
+    {
+      onlySubscribed: true,
+      updateOnlyOn: [],
+      room: hasRoomContext ? room : void 0
+    }
   ).filter((ref) => !ref.participant.isLocal);
-  const videoTrackRef = videoTracks[0] ?? null;
+  const videoTrackRef = hasRoomContext ? videoTracks[0] ?? null : null;
   const hasVideo = videoTrackRef !== null && isTrackReference(videoTrackRef);
   return {
     participant: avatarParticipant,
@@ -282,37 +367,46 @@ function AvatarVideo({ children, ...props }) {
   );
 }
 function useLocalMedia() {
-  const { localParticipant } = useLocalParticipant();
+  const room = useMaybeRoomContext();
+  const hasRoomContext = room !== void 0;
+  const { localParticipant } = useLocalParticipant({ room });
   const audioDevices = useMediaDevices({ kind: "audioinput" });
   const videoDevices = useMediaDevices({ kind: "videoinput" });
-  const hasMic = audioDevices.length > 0;
-  const hasCamera = videoDevices.length > 0;
+  const hasMic = audioDevices?.length > 0;
+  const hasCamera = videoDevices?.length > 0;
   const isMicEnabled = localParticipant?.isMicrophoneEnabled ?? false;
   const isCameraEnabled = localParticipant?.isCameraEnabled ?? false;
   const isScreenShareEnabled = localParticipant?.isScreenShareEnabled ?? false;
   const isMicEnabledRef = useLatest(isMicEnabled);
   const isCameraEnabledRef = useLatest(isCameraEnabled);
   const isScreenShareEnabledRef = useLatest(isScreenShareEnabled);
+  const hasMicRef = useLatest(hasMic);
+  const hasCameraRef = useLatest(hasCamera);
   const toggleMic = useCallback(() => {
-    localParticipant?.setMicrophoneEnabled(!isMicEnabledRef.current);
-  }, [localParticipant, isMicEnabledRef]);
+    if (hasMicRef.current || isMicEnabledRef.current) {
+      localParticipant?.setMicrophoneEnabled(!isMicEnabledRef.current);
+    }
+  }, [localParticipant]);
   const toggleCamera = useCallback(() => {
-    localParticipant?.setCameraEnabled(!isCameraEnabledRef.current);
-  }, [localParticipant, isCameraEnabledRef]);
+    if (hasCameraRef.current || isCameraEnabledRef.current) {
+      localParticipant?.setCameraEnabled(!isCameraEnabledRef.current);
+    }
+  }, [localParticipant]);
   const toggleScreenShare = useCallback(() => {
     localParticipant?.setScreenShareEnabled(!isScreenShareEnabledRef.current);
-  }, [localParticipant, isScreenShareEnabledRef]);
+  }, [localParticipant]);
   const tracks = useTracks(
     [{ source: Track.Source.Camera, withPlaceholder: true }],
     {
       onlySubscribed: false,
-      updateOnlyOn: []
+      updateOnlyOn: [],
+      room: hasRoomContext ? room : void 0
     }
   );
   const localIdentity = localParticipant?.identity;
-  const localVideoTrackRef = tracks.find(
+  const localVideoTrackRef = hasRoomContext ? tracks.find(
     (trackRef) => trackRef.participant.identity === localIdentity && trackRef.source === Track.Source.Camera
-  ) ?? null;
+  ) ?? null : null;
   return {
     hasMic,
     hasCamera,
@@ -516,19 +610,44 @@ function AvatarCall({
   ...props
 }) {
   const onErrorRef = useLatest(onError);
-  const credentials = useCredentials({
+  const credentialsState = useCredentials({
     avatarId,
     sessionId,
     sessionKey,
     credentials: directCredentials,
     connectUrl,
     connect,
-    baseUrl
+    baseUrl,
+    onError: (err) => onErrorRef.current?.(err)
   });
   const handleSessionError = (err) => {
     onErrorRef.current?.(err);
   };
   const backgroundStyle = avatarImageUrl ? { "--avatar-image": `url(${avatarImageUrl})` } : void 0;
+  const defaultChildren = /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(AvatarVideo, {}),
+    /* @__PURE__ */ jsx(UserVideo, {}),
+    /* @__PURE__ */ jsx(ControlBar, {})
+  ] });
+  if (credentialsState.status !== "ready") {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        ...props,
+        "data-avatar-call": "",
+        "data-avatar-id": avatarId,
+        style: { ...props.style, ...backgroundStyle },
+        children: /* @__PURE__ */ jsx(
+          LoadingSessionProvider,
+          {
+            state: credentialsState.status === "error" ? "error" : "connecting",
+            error: credentialsState.error,
+            children: children ?? defaultChildren
+          }
+        )
+      }
+    );
+  }
   return /* @__PURE__ */ jsx(
     "div",
     {
@@ -539,15 +658,11 @@ function AvatarCall({
       children: /* @__PURE__ */ jsx(
         AvatarSession,
         {
-          credentials,
+          credentials: credentialsState.credentials,
           onEnd,
           onError: handleSessionError,
           __unstable_roomOptions,
-          children: children ?? /* @__PURE__ */ jsxs(Fragment, { children: [
-            /* @__PURE__ */ jsx(AvatarVideo, {}),
-            /* @__PURE__ */ jsx(UserVideo, {}),
-            /* @__PURE__ */ jsx(ControlBar, {})
-          ] })
+          children: children ?? defaultChildren
         }
       )
     }
@@ -557,15 +672,17 @@ function ScreenShareVideo({
   children,
   ...props
 }) {
-  const { localParticipant } = useLocalParticipant();
+  const room = useMaybeRoomContext();
+  const hasRoomContext = room !== void 0;
+  const { localParticipant } = useLocalParticipant({ room });
   const tracks = useTracks(
     [{ source: Track.Source.ScreenShare, withPlaceholder: false }],
-    { onlySubscribed: false }
+    { onlySubscribed: false, room: hasRoomContext ? room : void 0 }
   );
   const localIdentity = localParticipant?.identity;
-  const screenShareTrackRef = tracks.find(
+  const screenShareTrackRef = hasRoomContext ? tracks.find(
     (trackRef) => trackRef.participant.identity === localIdentity && trackRef.source === Track.Source.ScreenShare
-  ) ?? null;
+  ) ?? null : null;
   const isSharing = screenShareTrackRef !== null && isTrackReference(screenShareTrackRef);
   const state = {
     isSharing,