@convai/embody 0.1.0 → 0.2.1

package/dist/connect/session.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The MIND half of a character: the @convai/web-sdk connection.
+ *
+ * embody is a wrapper package, so an app should never have to stand up its
+ * own `ConvaiClient` alongside ours — that is two connections, two copies of
+ * the credentials, and a `blendshapeQueue` the app has to hand-plumb into
+ * every frame. This module owns that connection so `createCharacter` can
+ * hand back one object that is both body and mind.
+ *
+ * Nothing here is embody-specific: it is the exact three-step dance the SDK
+ * asks for (construct, connect, attach audio), plus teardown in the reverse
+ * order. Apps that already own a client pass it in as `client` and this
+ * module steps aside entirely.
+ */
+import { ConvaiClient, type BlendshapeQueue, type ConvaiConfig } from '@convai/web-sdk/core';
+export interface SessionOptions extends ConvaiConfig {
+    /**
+     * Attach an `AudioRenderer` to the room so the character is audible.
+     * Default `true`. Set `false` when the app renders SDK audio itself —
+     * React apps using the SDK's `<AudioRenderer/>` component, for instance,
+     * or anything doing its own WebAudio routing.
+     */
+    audio?: boolean;
+}
+export interface SessionHandle {
+    /**
+     * The live SDK client. Everything the SDK can do — `sendUserTextMessage`,
+     * `on('transcript', …)`, mic control, memory — is reached through here;
+     * embody deliberately does not re-wrap that surface.
+     */
+    client: ConvaiClient;
+    /** Lipsync frames for the turn currently being spoken. */
+    readonly queue: BlendshapeQueue;
+    /** Whether this session owns the client (and so should close it). */
+    readonly owned: boolean;
+    dispose(): Promise<void>;
+}
+/**
+ * Connect a client and make it audible.
+ *
+ * `audio` is attached only after `connect()` resolves: `AudioRenderer` takes
+ * the LiveKit room and subscribes to its track events, so it needs a room
+ * that exists. Attaching earlier silently produces a mute character.
+ */
+export declare function createSession(opts: SessionOptions): Promise<SessionHandle>;
+/**
+ * Adopt a client the app already created and connected. embody will drive
+ * lipsync from its queue but will not disconnect it on teardown — the app
+ * owns its own client's lifetime.
+ */
+export declare function adoptSession(client: ConvaiClient): SessionHandle;

package/dist/connect/session.js

@@ -0,0 +1,62 @@
+/**
+ * The MIND half of a character: the @convai/web-sdk connection.
+ *
+ * embody is a wrapper package, so an app should never have to stand up its
+ * own `ConvaiClient` alongside ours — that is two connections, two copies of
+ * the credentials, and a `blendshapeQueue` the app has to hand-plumb into
+ * every frame. This module owns that connection so `createCharacter` can
+ * hand back one object that is both body and mind.
+ *
+ * Nothing here is embody-specific: it is the exact three-step dance the SDK
+ * asks for (construct, connect, attach audio), plus teardown in the reverse
+ * order. Apps that already own a client pass it in as `client` and this
+ * module steps aside entirely.
+ */
+import { ConvaiClient } from '@convai/web-sdk/core';
+import { AudioRenderer } from '@convai/web-sdk/vanilla';
+/**
+ * Connect a client and make it audible.
+ *
+ * `audio` is attached only after `connect()` resolves: `AudioRenderer` takes
+ * the LiveKit room and subscribes to its track events, so it needs a room
+ * that exists. Attaching earlier silently produces a mute character.
+ */
+export async function createSession(opts) {
+    const { audio = true, ...config } = opts;
+    const client = new ConvaiClient(config);
+    await client.connect();
+    const renderer = audio ? new AudioRenderer(client.room) : null;
+    return wrapSession(client, renderer, true);
+}
+/**
+ * Adopt a client the app already created and connected. embody will drive
+ * lipsync from its queue but will not disconnect it on teardown — the app
+ * owns its own client's lifetime.
+ */
+export function adoptSession(client) {
+    return wrapSession(client, null, false);
+}
+function wrapSession(client, renderer, owned) {
+    let disposed = false;
+    return {
+        client,
+        owned,
+        // A getter, not a snapshot: the SDK replaces the queue across
+        // reconnects, and a captured reference would go quietly stale — the
+        // character would keep rendering frames from a dead turn.
+        get queue() {
+            return client.blendshapeQueue;
+        },
+        async dispose() {
+            // Idempotent: React StrictMode double-invokes cleanup, and a second
+            // disconnect on an already-closed client throws.
+            if (disposed)
+                return;
+            disposed = true;
+            renderer?.destroy();
+            // Only close what we opened.
+            if (owned)
+                await client.disconnect();
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,24 @@
+/**
+ * @convai/embody — 3D bodies for Convai characters.
+ *
+ * embody wraps @convai/web-sdk rather than sitting beside it: one credential,
+ * one character id, one connection. Apps should not need to depend on the SDK
+ * directly, so its conversational surface is re-exported below.
+ *
+ * ```ts
+ * import { createCharacter } from '@convai/embody'
+ *
+ * const character = await createCharacter({ apiKey, characterId })
+ * scene.add(character.root)
+ * character.client?.sendUserTextMessage('hello')
+ * // per frame:
+ * character.update(delta)
+ * ```
+ */
+export { ConvaiClient, BlendshapeQueue, AudioManager, VideoManager, ScreenShareManager, MemoryManager, getDisconnectReasonMessage, } from '@convai/web-sdk/core';
+export type { ConvaiConfig, ConvaiClientType, TurnStats } from '@convai/web-sdk/core';
+export { createSession, adoptSession } from './connect/session.js';
+export type { SessionOptions, SessionHandle } from './connect/session.js';
 export { httpResolver, pickRepresentation, DEFAULT_BASE_URL } from './resolve/resolver.js';
 export type { HttpResolverOptions } from './resolve/resolver.js';
 export type { CharacterResolver, CharacterBundle, Representation, ModelVariant } from './resolve/resolver.js';

package/dist/index.js

@@ -1,3 +1,26 @@
+/**
+ * @convai/embody — 3D bodies for Convai characters.
+ *
+ * embody wraps @convai/web-sdk rather than sitting beside it: one credential,
+ * one character id, one connection. Apps should not need to depend on the SDK
+ * directly, so its conversational surface is re-exported below.
+ *
+ * ```ts
+ * import { createCharacter } from '@convai/embody'
+ *
+ * const character = await createCharacter({ apiKey, characterId })
+ * scene.add(character.root)
+ * character.client?.sendUserTextMessage('hello')
+ * // per frame:
+ * character.update(delta)
+ * ```
+ */
+// ── The conversational half, re-exported from @convai/web-sdk ──────────────
+// Everything an app needs to drive the conversation, so `@convai/embody` is
+// the only import. These are the SDK's own types — not wrappers — so they
+// stay in step with it and interop with an SDK client the app already has.
+export { ConvaiClient, BlendshapeQueue, AudioManager, VideoManager, ScreenShareManager, MemoryManager, getDisconnectReasonMessage, } from '@convai/web-sdk/core';
+export { createSession, adoptSession } from './connect/session.js';
 export { httpResolver, pickRepresentation, DEFAULT_BASE_URL } from './resolve/resolver.js';
 export { createCharacter } from './character/createCharacter.js';
 export { AnimationController } from './clips/animations.js';

package/dist/motion/breathe.d.ts

@@ -22,7 +22,7 @@ export interface BreathingConfig {
  * A FIRST fix composed `rest * breath` absolutely every frame, using the
  * bone's bind pose captured once at `resolveRig` time. That bounded the
  * no-clip case but silently broke the WITH-clip case: every clip in
- * `demo/fixtures/japanese-f-animations.glb` (Idle included, which the demo
+ * `convai-playhouse/pagoda-act/public/japanese-f-animations.glb` (Idle included, which the demo
  * actually plays) animates `spine_02`/`spine_04` — the exact two bones this
  * system drives — so composing onto a STATIC captured rest pose discarded
  * the clip's own spine motion outright, every frame, on the normal

package/dist/motion/breathe.js

@@ -18,7 +18,7 @@ function freshAnchor() {
  * A FIRST fix composed `rest * breath` absolutely every frame, using the
  * bone's bind pose captured once at `resolveRig` time. That bounded the
  * no-clip case but silently broke the WITH-clip case: every clip in
- * `demo/fixtures/japanese-f-animations.glb` (Idle included, which the demo
+ * `convai-playhouse/pagoda-act/public/japanese-f-animations.glb` (Idle included, which the demo
  * actually plays) animates `spine_02`/`spine_04` — the exact two bones this
  * system drives — so composing onto a STATIC captured rest pose discarded
  * the clip's own spine motion outright, every frame, on the normal

package/dist/react/CharacterModel.d.ts

@@ -0,0 +1,8 @@
+import { type UseCharacterOptions } from './useCharacter.js';
+import type { CharacterHandle } from '../character/createCharacter.js';
+export interface CharacterModelProps extends UseCharacterOptions {
+    /** Called once the body is loaded and the connection is live. */
+    onReady?: (character: CharacterHandle) => void;
+    onError?: (error: Error) => void;
+}
+export declare function CharacterModel({ onReady, onError, ...opts }: CharacterModelProps): import("react").JSX.Element | null;

package/dist/react/CharacterModel.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The character as a scene object, for an app that already has its own
+ * `<Canvas>`, lighting and camera. Must be rendered INSIDE a `<Canvas>`.
+ *
+ * Most apps want the default export of `@convai/embody/react` instead, which
+ * brings its own canvas and needs nothing around it. Reach for this one when
+ * the character joins a scene you are already composing.
+ *
+ * ```tsx
+ * <Canvas>
+ *   <MyLights />
+ *   <CharacterModel token={token} characterId={characterId} />
+ *   <MyProps />
+ * </Canvas>
+ * ```
+ *
+ * Thin wiring only — all lifecycle/tick behaviour lives in `useCharacter`
+ * (which delegates cancellation to `../character/lifecycle`). This adds
+ * nothing but the `<primitive>` render and the onReady/onError plumbing.
+ */
+import { useEffect } from 'react';
+import { useCharacter } from './useCharacter.js';
+export function CharacterModel({ onReady, onError, ...opts }) {
+    const { character, error } = useCharacter(opts);
+    useEffect(() => {
+        if (character && onReady)
+            onReady(character);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [character, onReady]);
+    useEffect(() => {
+        if (error && onError)
+            onError(error);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [error, onError]);
+    if (!character)
+        return null;
+    return _jsx("primitive", { object: character.root });
+}

package/dist/react/ConvaiCharacter.d.ts

@@ -1,7 +1,21 @@
-import { type UseCharacterOptions } from './useCharacter.js';
-import type { CharacterHandle } from '../character/createCharacter.js';
-export interface ConvaiCharacterProps extends UseCharacterOptions {
-    onReady?: (character: CharacterHandle) => void;
-    onError?: (error: Error) => void;
+import { type CharacterModelProps } from './CharacterModel.js';
+export interface ConvaiCharacterProps extends CharacterModelProps {
+    /** Wrapper style. Defaults to filling the parent. */
+    style?: React.CSSProperties;
+    className?: string;
+    /** Scene background. `null` renders transparent, to composite over a page. */
+    background?: string | null;
+    /**
+     * Camera framing, in metres, tuned for a standing human-scale character:
+     * eye-level and about three and a half metres back.
+     */
+    camera?: {
+        position?: [number, number, number];
+        fov?: number;
+        target?: [number, number, number];
+    };
+    /** Rendered while the body is still loading. */
+    fallback?: React.ReactNode;
 }
-export declare function ConvaiCharacter({ onReady, onError, ...opts }: ConvaiCharacterProps): import("react").JSX.Element | null;
+export declare function ConvaiCharacter({ style, className, background, camera, fallback, ...character }: ConvaiCharacterProps): import("react").JSX.Element;
+export default ConvaiCharacter;

package/dist/react/ConvaiCharacter.js

@@ -1,25 +1,40 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
- * Thin wiring only. All lifecycle/tick behaviour lives in `useCharacter`
- * (which itself delegates cancellation to `../character/lifecycle`) — this
- * component adds nothing but the `<primitive>` render and the
- * onReady/onError callback plumbing.
+ * The whole package in one component.
+ *
+ * ```tsx
+ * import ConvaiCharacter from '@convai/embody/react'
+ *
+ * export default function App() {
+ *   return <ConvaiCharacter token={token} characterId={characterId} />
+ * }
+ * ```
+ *
+ * That renders the character. Nothing else is needed — no `<Canvas>`, no
+ * lights, no camera, no `ConvaiClient`, no resolver, no frame loop. embody
+ * resolves the body, opens the @convai/web-sdk connection, renders its audio
+ * and drives lipsync, gaze, breathing and blink.
+ *
+ * It fills its parent, so give that parent a size (the default is a full
+ * viewport when the parent has no height of its own).
+ *
+ * When the character should join a scene you are already composing, use the
+ * named `CharacterModel` export inside your own `<Canvas>` instead.
  */
-import { useEffect } from 'react';
-import { useCharacter } from './useCharacter.js';
-export function ConvaiCharacter({ onReady, onError, ...opts }) {
-    const { character, error } = useCharacter(opts);
-    useEffect(() => {
-        if (character && onReady)
-            onReady(character);
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [character, onReady]);
-    useEffect(() => {
-        if (error && onError)
-            onError(error);
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [error, onError]);
-    if (!character)
-        return null;
-    return _jsx("primitive", { object: character.root });
+import { Suspense } from 'react';
+import { Canvas } from '@react-three/fiber';
+import { CharacterModel } from './CharacterModel.js';
+const DEFAULT_POSITION = [0, 1.45, 3.6];
+const DEFAULT_TARGET = [0, 0.92, 0];
+export function ConvaiCharacter({ style, className, background = '#17181c', camera, fallback = null, ...character }) {
+    const position = camera?.position ?? DEFAULT_POSITION;
+    const target = camera?.target ?? DEFAULT_TARGET;
+    return (_jsxs("div", { className: className, style: { width: '100%', height: '100%', minHeight: '100vh', ...style }, children: [_jsxs(Canvas, { camera: { position, fov: camera?.fov ?? 35, near: 0.05, far: 100 }, 
+                // Transparent when background is null, so the character can sit over
+                // existing page content rather than in a box of its own.
+                gl: { antialias: true, alpha: background === null }, 
+                // Aim at the character's head rather than the origin at its feet;
+                // r3f points the camera at [0,0,0] otherwise.
+                onCreated: ({ camera: cam }) => cam.lookAt(...target), children: [background !== null && _jsx("color", { attach: "background", args: [background] }), _jsx("hemisphereLight", { args: [0xffffff, 0x334455, 1.4] }), _jsx("directionalLight", { position: [2, 4, 3], intensity: 2.2 }), _jsx(Suspense, { fallback: null, children: _jsx(CharacterModel, { ...character }) })] }), fallback] }));
 }
+export default ConvaiCharacter;

package/dist/react/index.d.ts

@@ -1,4 +1,38 @@
+/**
+ * React entry point.
+ *
+ * ```tsx
+ * import { ConvaiCharacter } from '@convai/embody/react'
+ *
+ * <Canvas>
+ *   <ConvaiCharacter apiKey={apiKey} characterId={characterId} />
+ * </Canvas>
+ * ```
+ *
+ * The SDK's own React surface is re-exported so an app can build chat UI
+ * without adding a second dependency — or a second connection. `ConvaiWidget`
+ * takes a client, and `character.client` is one.
+ *
+ * Chat UI is DOM and the character is a `<Canvas>` child, so lift the client
+ * out rather than rendering the widget from inside the scene:
+ *
+ * ```tsx
+ * const [client, setClient] = useState<ConvaiClient | null>(null)
+ * <Canvas>
+ *   <ConvaiCharacter apiKey={apiKey} characterId={characterId}
+ *                    onReady={(c) => setClient(c.client)} />
+ * </Canvas>
+ * {client && <ConvaiWidget convaiClient={client} />}
+ * ```
+ */
 export { useCharacter } from './useCharacter.js';
 export type { UseCharacterOptions, UseCharacterResult } from './useCharacter.js';
-export { ConvaiCharacter } from './ConvaiCharacter.js';
+export { ConvaiCharacter, default } from './ConvaiCharacter.js';
 export type { ConvaiCharacterProps } from './ConvaiCharacter.js';
+export { CharacterModel } from './CharacterModel.js';
+export type { CharacterModelProps } from './CharacterModel.js';
+export { useWidgetClient } from './useWidgetClient.js';
+export type { WidgetClient } from './useWidgetClient.js';
+export { ConvaiWidget, useConvaiClient, AudioRenderer, AudioContext } from '@convai/web-sdk/react';
+export { ConvaiClient } from '@convai/web-sdk/core';
+export type { ConvaiConfig } from '@convai/web-sdk/core';

package/dist/react/index.js

@@ -1,2 +1,34 @@
+/**
+ * React entry point.
+ *
+ * ```tsx
+ * import { ConvaiCharacter } from '@convai/embody/react'
+ *
+ * <Canvas>
+ *   <ConvaiCharacter apiKey={apiKey} characterId={characterId} />
+ * </Canvas>
+ * ```
+ *
+ * The SDK's own React surface is re-exported so an app can build chat UI
+ * without adding a second dependency — or a second connection. `ConvaiWidget`
+ * takes a client, and `character.client` is one.
+ *
+ * Chat UI is DOM and the character is a `<Canvas>` child, so lift the client
+ * out rather than rendering the widget from inside the scene:
+ *
+ * ```tsx
+ * const [client, setClient] = useState<ConvaiClient | null>(null)
+ * <Canvas>
+ *   <ConvaiCharacter apiKey={apiKey} characterId={characterId}
+ *                    onReady={(c) => setClient(c.client)} />
+ * </Canvas>
+ * {client && <ConvaiWidget convaiClient={client} />}
+ * ```
+ */
 export { useCharacter } from './useCharacter.js';
-export { ConvaiCharacter } from './ConvaiCharacter.js';
+export { ConvaiCharacter, default } from './ConvaiCharacter.js';
+export { CharacterModel } from './CharacterModel.js';
+export { useWidgetClient } from './useWidgetClient.js';
+// ── Chat / conversation surface, re-exported from @convai/web-sdk/react ────
+export { ConvaiWidget, useConvaiClient, AudioRenderer, AudioContext } from '@convai/web-sdk/react';
+export { ConvaiClient } from '@convai/web-sdk/core';

package/dist/react/useCharacter.d.ts

@@ -1,11 +1,22 @@
-import type { BlendshapeQueue } from '@convai/web-sdk/core';
+import type { BlendshapeQueue, ConvaiClient } from '@convai/web-sdk/core';
 import { type CharacterHandle, type CreateCharacterOptions } from '../character/createCharacter.js';
 export interface UseCharacterOptions extends CreateCharacterOptions {
-    /** Pass the queue only while this character owns the conversational turn. */
+    /**
+     * Override which turn this body lipsyncs to. Only needed when one client
+     * drives several characters; otherwise the character uses its own session.
+     */
     queue?: BlendshapeQueue;
 }
 export interface UseCharacterResult {
     character: CharacterHandle | null;
+    /**
+     * The connected SDK client, once ready — the same object as
+     * `character.client`, lifted out so chat UI can be written without
+     * null-checking the body first.
+     */
+    client: ConvaiClient | null;
     error: Error | null;
+    /** `loading` until body and mind are both up, then `ready` or `error`. */
+    status: 'loading' | 'ready' | 'error';
 }
 export declare function useCharacter(opts: UseCharacterOptions): UseCharacterResult;

package/dist/react/useCharacter.js

@@ -2,10 +2,13 @@
  * Thin wiring only — see the module doc on `../character/lifecycle` for why
  * the cancel/dispose behaviour lives there and not here. This hook does
  * nothing `createCharacterLifecycle` doesn't already own: it creates a
- * lifecycle per `characterId`, feeds it `createCharacter`, cancels it on
- * unmount/re-run, and forwards the two pieces of state React needs
- * (`character`, `error`). Ticking and camera assignment are similarly
- * one-line pass-throughs to `CharacterHandle.update`/`.camera`.
+ * lifecycle per identity, feeds it `createCharacter`, cancels it on
+ * unmount/re-run, and forwards the state React needs. Ticking and camera
+ * assignment are one-line pass-throughs to `CharacterHandle.update`/`.camera`.
+ *
+ * The lipsync queue is NOT a prop: the character owns its own connection, so
+ * it already knows which frames are its own. Apps driving several bodies from
+ * one client pass `queue` to take that decision back.
  */
 import { useEffect, useRef, useState } from 'react';
 import { useFrame, useThree } from '@react-three/fiber';
@@ -32,14 +35,20 @@ export function useCharacter(opts) {
             setError(null);
         }, (c) => setCharacter(c), (e) => setError(e));
         return () => lifecycle.cancel();
-        // Re-create only when the identity of the character changes — matching
-        // the lifecycle contract of one `start` per instance.
+        // Re-create when the identity of the character OR the credentials change
+        // — a new key/token means a different session, and reusing the old one
+        // would leave the body talking over a connection the app has revoked.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [opts.characterId]);
+    }, [opts.characterId, opts.apiKey, opts.authToken, opts.token, opts.baseUrl]);
     useEffect(() => {
         if (character)
             character.camera = camera;
     }, [character, camera]);
     useFrame((_, delta) => character?.update(delta, queueRef.current));
-    return { character, error };
+    return {
+        character,
+        client: character?.client ?? null,
+        error,
+        status: error ? 'error' : character ? 'ready' : 'loading',
+    };
 }

package/dist/react/useWidgetClient.d.ts

@@ -0,0 +1,18 @@
+import type { ConvaiClient } from '@convai/web-sdk/core';
+/** The shape `<ConvaiWidget convaiClient={…} />` requires. */
+export type WidgetClient = ConvaiClient & {
+    activity: string;
+    isAudioMuted: boolean;
+    isVideoEnabled: boolean;
+    isScreenShareActive: boolean;
+};
+/**
+ * ```tsx
+ * const { client } = useCharacter({ apiKey, characterId })
+ * const widgetClient = useWidgetClient(client)
+ * return widgetClient && <ConvaiWidget convaiClient={widgetClient} />
+ * ```
+ *
+ * Returns `null` until the character's connection exists.
+ */
+export declare function useWidgetClient(client: ConvaiClient | null): WidgetClient | null;

package/dist/react/useWidgetClient.js

@@ -0,0 +1,105 @@
+/**
+ * Makes embody's client usable by the SDK's `<ConvaiWidget/>`.
+ *
+ * The widget wants `IConvaiClient` plus four pieces of reactive UI state
+ * (`activity`, `isAudioMuted`, `isVideoEnabled`, `isScreenShareActive`). The
+ * SDK supplies those through `useConvaiClient`, but that hook CONSTRUCTS its
+ * own client — using it next to embody would open a second connection, which
+ * is the whole thing embody exists to avoid.
+ *
+ * So this hook does the same composition against a client that already
+ * exists. It mirrors `useConvaiClient`'s subscriptions exactly: `stateChange`
+ * for activity, and the three control emitters for the toggles.
+ */
+import { useEffect, useMemo, useState } from 'react';
+/** Priority order matches the SDK's: speaking > listening > thinking > connected. */
+function activityOf(state) {
+    if (state.isSpeaking)
+        return 'Speaking';
+    if (state.isListening)
+        return 'Listening';
+    if (state.isThinking)
+        return 'Thinking';
+    if (state.isConnected)
+        return 'Connected';
+    return 'Idle';
+}
+/**
+ * ```tsx
+ * const { client } = useCharacter({ apiKey, characterId })
+ * const widgetClient = useWidgetClient(client)
+ * return widgetClient && <ConvaiWidget convaiClient={widgetClient} />
+ * ```
+ *
+ * Returns `null` until the character's connection exists.
+ */
+export function useWidgetClient(client) {
+    const c = client;
+    const [activity, setActivity] = useState('Idle');
+    const [isAudioMuted, setAudioMuted] = useState(false);
+    const [isVideoEnabled, setVideoEnabled] = useState(false);
+    const [isScreenShareActive, setScreenShareActive] = useState(false);
+    useEffect(() => {
+        if (!c)
+            return;
+        // Seed from the current values: the client may already be connected and
+        // mid-turn by the time this hook mounts, and waiting for the next event
+        // would show a stale "Idle" until the user did something.
+        setActivity(activityOf(c.state));
+        setAudioMuted(c.audioControls.isAudioMuted);
+        setVideoEnabled(c.videoControls.isVideoEnabled);
+        setScreenShareActive(c.screenShareControls.isScreenShareActive);
+        const unsubs = [
+            c.on('stateChange', (s) => setActivity(activityOf(s))),
+            c.audioControls.on('audioStateChange', (s) => {
+                if (s.isAudioMuted !== undefined)
+                    setAudioMuted(s.isAudioMuted);
+            }),
+            c.videoControls.on('videoStateChange', (s) => {
+                if (s.isVideoEnabled !== undefined)
+                    setVideoEnabled(s.isVideoEnabled);
+            }),
+            c.screenShareControls.on('screenShareStateChange', (s) => {
+                if (s.isScreenShareActive !== undefined)
+                    setScreenShareActive(s.isScreenShareActive);
+            }),
+        ];
+        return () => unsubs.forEach((u) => u());
+    }, [c]);
+    // A view over the client, never a mutation of it: the same client drives
+    // the 3D character and anything else the app holds, and stamping React
+    // state onto it would make those views disagree.
+    //
+    // A Proxy rather than `Object.create` + assign, because the widget calls
+    // methods on this object. Under `Object.create` any `this.x = y` inside a
+    // method writes to the derived object instead of the client, silently
+    // losing the mutation. Here reads, writes and `this` all reach the real
+    // client; only the four UI fields are intercepted.
+    //
+    // Re-created when those four change so a memoised widget re-renders, and
+    // stable between changes so it does not re-render for nothing.
+    return useMemo(() => {
+        if (!client)
+            return null;
+        const overrides = {
+            activity,
+            isAudioMuted,
+            isVideoEnabled,
+            isScreenShareActive,
+        };
+        return new Proxy(client, {
+            get(target, prop, receiver) {
+                if (typeof prop === 'string' && prop in overrides)
+                    return overrides[prop];
+                // Receiver is the TARGET, not the proxy, so getters and methods run
+                // with `this` bound to the real client.
+                const value = Reflect.get(target, prop, target);
+                return typeof value === 'function' ? value.bind(target) : value;
+            },
+            set(target, prop, value) {
+                return Reflect.set(target, prop, value, target);
+            },
+        });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, activity, isAudioMuted, isVideoEnabled, isScreenShareActive]);
+}

package/dist/resolve/resolver.d.ts

@@ -26,6 +26,15 @@ export interface CharacterBundle {
     release?: number;
     representations: Representation[];
     thumbnail?: string;
+    /**
+     * `true` when this is a stand-in body, not the character's own: the
+     * character exists and is viewable, but has no finished embodiment, so the
+     * backend served the configured default for its gender.
+     *
+     * Worth surfacing. A placeholder that nobody notices is a character
+     * shipping as visibly the wrong person.
+     */
+    fallback?: boolean;
 }
 export interface CharacterResolver {
     resolve(characterId: string): Promise<CharacterBundle>;
@@ -48,9 +57,13 @@ export declare const DEFAULT_BASE_URL = "https://api-stg.convai.com";
 export interface HttpResolverOptions {
     /** Base url of the embodiment backend. Defaults to the release branch's host. */
     baseUrl?: string;
-    /** Optional CONVAI-API-KEY; public characters resolve as guest without it. */
+    /** CONVAI-API-KEY. Supply this or `authToken`. */
     apiKey?: string;
+    /** Convai auth token. Takes precedence over `apiKey` when both are set. */
+    authToken?: string;
 }
+/** Shared so `createCharacter` and the resolver cannot drift apart. */
+export declare const MISSING_CREDENTIAL: string;
 export declare function httpResolver(opts?: HttpResolverOptions): CharacterResolver;
 /** Pick the representation for a rig profile this build of embody understands. */
 export declare function pickRepresentation(bundle: CharacterBundle, supported: string[]): Representation;