Resolves #391

Author: haydenbleasel

.changeset/fix-persona-vite-strict-mode.md

@@ -0,0 +1,5 @@
+---
+"ai-elements": patch
+---
+
+Fix Persona crashing in Vite dev mode by deferring WebGL2 context creation to avoid exhausting browser context limits during React Strict Mode's double-mount cycle.

apps/docs/content/components/(voice)/persona.mdx

@@ -118,6 +118,14 @@ The Persona component responds to five distinct states, each triggering differen
 - **speaking**: Active when the AI is delivering a response (e.g., text-to-speech output)
 - **asleep**: A dormant state for when the AI is inactive or in low-power mode
 
+## React Strict Mode (Vite)
+
+The Persona component uses WebGL2 for rendering. Browsers limit the number of active WebGL2 contexts (~8–16), and React Strict Mode (enabled by default in Vite dev) double-mounts components, which can exhaust that limit and crash the page.
+
+The component includes a built-in guard that defers WebGL2 initialization by one frame, preventing context creation during Strict Mode's throw-away mount. This means the component works in Vite dev mode out of the box — no configuration needed.
+
+If you still experience crashes (for example, when rendering many Persona instances simultaneously), reduce the number of concurrent Persona components on screen.
+
 ## Usage Examples
 
 ### Basic Usage

packages/elements/__tests__/persona.test.tsx

@@ -39,6 +39,15 @@ vi.mock<typeof import("@rive-app/react-webgl2")>(
   })
 );
 
+// Mock requestAnimationFrame to fire synchronously so that
+// useStrictModeSafeInit's deferred init completes within the render cycle.
+// oxlint-disable-next-line eslint-plugin-promise(prefer-await-to-callbacks)
+vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+  cb(0); // oxlint-disable-line eslint-plugin-promise(prefer-await-to-callbacks)
+  return 0;
+});
+vi.stubGlobal("cancelAnimationFrame", vi.fn());
+
 // Setup function for persona tests
 const setupPersonaTests = () => {
   vi.spyOn(console, "warn").mockImplementation(vi.fn());
@@ -506,8 +515,8 @@ describe("persona - Callback Execution", () => {
     const onLoad = vi.fn();
 
     mockUseRive.mockImplementation((params) => {
-      // Simulate calling onLoad
-      params.onLoad?.({ artboard: "test" });
+      // Simulate calling onLoad (params is null before deferred init)
+      params?.onLoad?.({ artboard: "test" });
       return {
         RiveComponent: MockRiveComponent,
         rive: {},
@@ -525,8 +534,8 @@ describe("persona - Callback Execution", () => {
     const testError = new Error("Test error");
 
     mockUseRive.mockImplementation((params) => {
-      // Simulate calling onLoadError
-      params.onLoadError?.(testError);
+      // Simulate calling onLoadError (params is null before deferred init)
+      params?.onLoadError?.(testError);
       return {
         RiveComponent: MockRiveComponent,
         rive: {},
@@ -543,8 +552,8 @@ describe("persona - Callback Execution", () => {
     const onReady = vi.fn();
 
     mockUseRive.mockImplementation((params) => {
-      // Simulate calling onRiveReady
-      params.onRiveReady?.();
+      // Simulate calling onRiveReady (params is null before deferred init)
+      params?.onRiveReady?.();
       return {
         RiveComponent: MockRiveComponent,
         rive: {},
@@ -562,7 +571,7 @@ describe("persona - Callback Execution", () => {
     const pauseEvent = { type: "pause" };
 
     mockUseRive.mockImplementation((params) => {
-      params.onPause?.(pauseEvent);
+      params?.onPause?.(pauseEvent);
       return {
         RiveComponent: MockRiveComponent,
         rive: {},
@@ -580,7 +589,7 @@ describe("persona - Callback Execution", () => {
     const playEvent = { type: "play" };
 
     mockUseRive.mockImplementation((params) => {
-      params.onPlay?.(playEvent);
+      params?.onPlay?.(playEvent);
       return {
         RiveComponent: MockRiveComponent,
         rive: {},
@@ -598,7 +607,7 @@ describe("persona - Callback Execution", () => {
     const stopEvent = { type: "stop" };
 
     mockUseRive.mockImplementation((params) => {
-      params.onStop?.(stopEvent);
+      params?.onStop?.(stopEvent);
       return {
         RiveComponent: MockRiveComponent,
         rive: {},

packages/elements/src/persona.tsx

@@ -12,6 +12,23 @@ import {
 import type { FC, ReactNode } from "react";
 import { memo, useEffect, useMemo, useRef, useState } from "react";
 
+// Delays Rive initialization by one frame so that React Strict Mode's
+// immediate unmount cycle never creates a WebGL2 context. Only the
+// second (real) mount will initialise, avoiding context exhaustion.
+const useStrictModeSafeInit = () => {
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    const id = requestAnimationFrame(() => setReady(true));
+    return () => {
+      cancelAnimationFrame(id);
+      setReady(false);
+    };
+  }, []);
+
+  return ready;
+};
+
 export type PersonaState =
   | "idle"
   | "listening"
@@ -230,17 +247,25 @@ export const Persona: FC<PersonaProps> = memo(
       []
     );
 
-    const { rive, RiveComponent } = useRive({
-      autoplay: true,
-      onLoad: stableCallbacks.onLoad,
-      onLoadError: stableCallbacks.onLoadError,
-      onPause: stableCallbacks.onPause,
-      onPlay: stableCallbacks.onPlay,
-      onRiveReady: stableCallbacks.onReady,
-      onStop: stableCallbacks.onStop,
-      src: source.source,
-      stateMachines: stateMachine,
-    });
+    // Delay initialisation by one frame to avoid creating (and leaking)
+    // a WebGL2 context during React Strict Mode's first throw-away mount.
+    const ready = useStrictModeSafeInit();
+
+    const { rive, RiveComponent } = useRive(
+      ready
+        ? {
+            autoplay: true,
+            onLoad: stableCallbacks.onLoad,
+            onLoadError: stableCallbacks.onLoadError,
+            onPause: stableCallbacks.onPause,
+            onPlay: stableCallbacks.onPlay,
+            onRiveReady: stableCallbacks.onReady,
+            onStop: stableCallbacks.onStop,
+            src: source.source,
+            stateMachines: stateMachine,
+          }
+        : null
+    );
 
     const listeningInput = useStateMachineInput(
       rive,