Remove Suspense, simplify loading experience

- AvatarCall now handles all loading states internally
- No need for <Suspense> wrappers - just render AvatarCall
- useCredentials uses regular state instead of throwing promises
- Added LoadingSessionProvider for seamless context during credential fetch
- Added default loading spinner to AvatarVideo
- onError callback triggered imperatively instead of via useEffect
- Removed suspense-resource.ts utility
- Updated all documentation to reflect new API

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: robinandeer

CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-02-10
+
+### Changed
+
+- **Breaking:** `AvatarCall` no longer uses React Suspense. Loading states are now handled internally for a seamless experience. Remove any `<Suspense>` wrappers around `AvatarCall`.
+
+### Removed
+
+- Removed Suspense-based credential fetching from `AvatarCall` — loading is now handled internally
+- Removed `suspense-resource.ts` utility (no longer needed)
+
+### Fixed
+
+- Fixed "Requested device not found" error when connecting or toggling mic/camera on devices without those peripherals
+- Fixed awkward loading state gap between Suspense resolution and video becoming ready
+- Added default loading spinner to AvatarVideo during connecting/waiting states
+- Fixed loading spinner positioning — now properly centered with absolute positioning
+- Fixed hooks (`useLocalMedia`, `useAvatar`) crashing when called outside LiveKitRoom context during credential loading
+
 ## [0.5.0] - 2026-02-10
 
 ### Changed
@@ -30,7 +49,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added missing `data-avatar-enabled` attribute to screen-share and end-call control buttons
 - Added missing `toggleScreenShare` function to ControlBar render prop state
 - Blurred background now fades out smoothly when video becomes ready
-- Fixed "Requested device not found" error when connecting or toggling mic/camera on devices without those peripherals
 
 ## [0.4.0] - 2026-02-09
 

docs/api/components.md

@@ -18,7 +18,7 @@
 
 High-level component that handles the complete session lifecycle. **Recommended for most use cases.**
 
-**Suspends during credential fetching** — wrap in `<Suspense>` to show loading UI while the server creates the session. See the [Loading States guide](../guides/loading-states.md) for details.
+Handles credential fetching and loading states internally — just render it and the SDK manages the rest. See the [Loading States guide](../guides/loading-states.md) for details.
 
 ### Props
 
@@ -30,60 +30,55 @@ High-level component that handles the complete session lifecycle. **Recommended
 | `sessionId` | `string` | ✓* | Session ID (use with `sessionKey`) |
 | `sessionKey` | `string` | ✓* | Session key (use with `sessionId`) |
 | `credentials` | `SessionCredentials` | ✓* | Pre-fetched credentials |
-| `baseUrl` | `string` | | Runway API base URL (defaults to `https://api.dev.runwayml.com`) |
-| `avatarImageUrl` | `string` | | Avatar image URL (available as `--avatar-image` CSS variable) |
+| `baseUrl` | `string` | | Runway API base URL (defaults to `https://api.runwayml.com`) |
+| `avatarImageUrl` | `string` | | Avatar image URL for loading placeholder (available as `--avatar-image` CSS variable) |
 | `className` | `string` | | CSS class name |
 | `style` | `CSSProperties` | | Inline styles |
 | `onEnd` | `() => void` | | Called when session ends |
-| `onError` | `(error: Error) => void` | | Called on WebRTC error |
+| `onError` | `(error: Error) => void` | | Called on credential or WebRTC error |
 | `children` | `ReactNode` | | Custom layout (defaults to AvatarVideo + UserVideo + ControlBar) |
 
 *One of these is required: `connectUrl`, `connect`, `sessionId`+`sessionKey`, or `credentials`.
 
 ### Basic Usage
 
 ```tsx
-<Suspense fallback={<p>Connecting to avatar...</p>}>
-  <AvatarCall
-    avatarId="game-host"
-    connectUrl="/api/avatar/connect"
-  />
-</Suspense>
+<AvatarCall
+  avatarId="game-host"
+  connectUrl="/api/avatar/connect"
+  avatarImageUrl="/avatars/game-host.png"
+/>
 ```
 
 ### Custom Connect Function
 
 ```tsx
-<Suspense fallback={<LoadingScreen />}>
-  <AvatarCall
-    avatarId="game-host"
-    connect={async (avatarId) => {
-      const res = await fetch('/api/avatar/connect', {
-        method: 'POST',
-        headers: {
-          'Authorization': `Bearer ${token}`,
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({ avatarId }),
-      });
-      return res.json();
-    }}
-  />
-</Suspense>
+<AvatarCall
+  avatarId="game-host"
+  connect={async (avatarId) => {
+    const res = await fetch('/api/avatar/connect', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ avatarId }),
+    });
+    return res.json();
+  }}
+/>
 ```
 
 ### Custom Layout
 
 ```tsx
-<Suspense fallback={<LoadingScreen />}>
-  <AvatarCall avatarId="game-host" connectUrl="/api/avatar/connect">
-    <div className="my-layout">
-      <AvatarVideo className="main-video" />
-      <UserVideo className="pip" />
-      <ControlBar className="bottom-bar" />
-    </div>
-  </AvatarCall>
-</Suspense>
+<AvatarCall avatarId="game-host" connectUrl="/api/avatar/connect">
+  <div className="my-layout">
+    <AvatarVideo className="main-video" />
+    <UserVideo className="pip" />
+    <ControlBar className="bottom-bar" />
+  </div>
+</AvatarCall>
 ```
 
 ### Data Attributes

docs/api/types.md

@@ -37,7 +37,7 @@ interface SessionCredentials {
 
 ### AvatarCallProps
 
-Suspends during credential fetching — wrap in `<Suspense>` to show loading UI.
+Handles credential fetching and loading states internally.
 
 ```typescript
 interface AvatarCallProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'onError'> {

docs/getting-started.md

@@ -27,18 +27,15 @@ Get your API secret from the [Runway Developer Portal](https://dev.runwayml.com/
 ### Client Component
 
 ```tsx
-import { Suspense } from 'react';
 import { AvatarCall } from '@runwayml/avatars-react';
 import '@runwayml/avatars-react/styles.css'; // Optional default styles
 
 function App() {
   return (
-    <Suspense fallback={<p>Setting up avatar session...</p>}>
-      <AvatarCall
-        avatarId="game-host"
-        connectUrl="/api/avatar/connect"
-      />
-    </Suspense>
+    <AvatarCall
+      avatarId="game-host"
+      connectUrl="/api/avatar/connect"
+    />
   );
 }
 ```
@@ -102,7 +99,7 @@ export async function POST(req: Request) {
 4. `AvatarCall` establishes a real-time video connection (~1–5 seconds)
 5. User sees and talks to the AI avatar
 
-> **Note:** Session creation (step 2) can take 10–30 seconds. `AvatarCall` **suspends** during this wait — wrap it in `<Suspense>` to show a loading fallback. See the [Loading States guide](guides/loading-states.md) for details.
+> **Note:** Session creation (step 2) can take 10–30 seconds. `AvatarCall` handles loading states internally — use `avatarImageUrl` and the default styles for a polished loading experience. See the [Loading States guide](guides/loading-states.md) for details.
 
 ## Session States