@convai/embody 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @convai/embody
 
+## 0.2.1
+
+### Patch Changes
+
+- Add a `default` condition to the package exports map.
+
+  The map previously declared only `types` and `import`, so any resolver using
+  CommonJS semantics could not resolve the package at all — Jest's default
+  resolver failed to resolve `@convai/embody/react` even to mock it, and
+  Next.js's `next/dynamic` build transform (which resolves its target via
+  `require.resolveWeak`) failed with "Package path './react' is not exported".
+  The first real consumer needed three separate workarounds for this one
+  omission. `default` points at the same ESM files; resolvers that only need
+  resolution now succeed, and runtimes with `require(esm)` can load them.
+
+## 0.2.0
+
+### Minor Changes
+
+- 32ea2de: **Breaking.** The front door is now a credential and a character id. Everything
+  else has a working default.
+
+  ```tsx
+  import ConvaiCharacter from "@convai/embody/react";
+
+  <ConvaiCharacter apiKey={apiKey} characterId={characterId} />;
+  ```
+
+  That renders the character: no `<Canvas>`, no lights, no camera, no
+  `ConvaiClient`, no resolver, no frame loop, no lipsync queue. embody resolves
+  the body, opens the `@convai/web-sdk` connection, renders its audio and drives
+  lipsync, gaze, breathing and blink.
+
+  Previously an app had to build a resolver, hand it in, construct its _own_
+  `ConvaiClient` with the same credentials, connect it, attach an
+  `AudioRenderer`, and thread `client.blendshapeQueue` through every frame —
+  two connections and two copies of the credentials for one character.
+
+  - `createCharacter` takes `apiKey` / `token` / `authToken` and builds the
+    resolver itself. `character.client` is the SDK client, and `update(delta)`
+    no longer needs a queue argument.
+  - `ConvaiCharacter` (default export of `/react`) brings its own canvas.
+    `CharacterModel` is the in-scene form for apps composing their own scene.
+  - The SDK's conversational surface is re-exported, so `@convai/embody` is the
+    only import an app needs. `useWidgetClient` adapts embody's client to
+    `<ConvaiWidget/>` — the SDK's `useConvaiClient` would construct a second
+    client, and so a second connection.
+  - Escape hatches for everything the old API required: `resolver`, `client`,
+    `connect: false`, `session`, and an explicit `queue` on `update()`.
+
+  Fixes, all found by running it rather than by typechecking it:
+
+  - **Draco assets could not load.** A GLB declaring
+    `KHR_draco_mesh_compression` failed outright with "No DRACOLoader instance
+    provided", which took out the entire default male body. A decoder is now
+    wired; `dracoDecoderPath` overrides where its wasm comes from.
+  - **Characters loaded in their bind pose**, arms out, until the app called
+    `play()`. An idle clip now starts automatically; `idleClip` overrides it.
+  - **Auth tokens were being dropped.** The resolver sent
+    `Authorization: Bearer`, which the backend ignores, silently downgrading the
+    request. It now sends `API-AUTH-TOKEN`, matching the SDK.
+  - **A missing credential is refused** before any request. There is no
+    anonymous access to Convai, and the SDK does not use the backend's guest
+    path either.
+  - `CharacterBundle.fallback` is typed. The backend has always returned it;
+    without it no consumer could tell a placeholder body from the character's
+    own.
+  - Resolver failures now carry the backend's message. "Character has no 3D
+    embodiment configured" points at the avatar config; a bare `HTTP 404` sends
+    people to check the character id.
+
+- 266904e: `httpResolver`'s `baseUrl` is now optional, defaulting to `DEFAULT_BASE_URL` —
+  a source constant pinned per release branch, mirroring how `@convai/web-sdk`
+  pins its connect host.
+
+  `stable-release` and `beta-release` target production; `stg-release` targets
+  staging. `scripts/check-hosts.mjs` enforces it, and `build:stg` / `build:beta` /
+  `build:prod` each assert the policy for the release they claim to be, so a
+  staging artifact cannot be cut from prod-host source.
+
+- f972846: Initial motion slice: rig abstraction, staged frame pipeline, and the behaviours
+  that make a character read as alive.
+
+  - `RigProfile` / `resolveRig` — bone and morph roles as data, `convai-mha-1` registered
+  - `Pipeline` — explicit six-stage frame order (normalize, mixer, gaze, additive, ik, attach, morph);
+    intra-stage order is the contract that puts blink after lipsync
+  - `GazeSystem` — head/neck solve, idle drift, look-away shifts, turn banking,
+    camera lock and clip deviation pull-back
+  - `BreathingSystem`, `BlinkSystem`, `EyeGazeSystem`
+  - `prefers-reduced-motion` support across every additive layer
+  - Thin React binding: `<ConvaiCharacter/>` and `useCharacter()`, with the
+    create/cancel/dispose lifecycle extracted framework-free
+
 All notable changes are recorded here. Versions are managed with
 [changesets](https://github.com/changesets/changesets); add one with
 `pnpm changeset` and the release flow writes this file.

package/README.md

@@ -2,7 +2,7 @@
 
 **Give a Convai character a body.**
 
-[![npm](https://img.shields.io/badge/npm-0.1.0-blue)](https://www.npmjs.com/package/@convai/embody)
+[![npm](https://img.shields.io/npm/v/@convai/embody/stg?label=npm%20stg&color=blue)](https://www.npmjs.com/package/@convai/embody)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-3178C6)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green)](./LICENSE)
 
@@ -15,8 +15,9 @@ lipsync, gaze, breathing and blink. Layered on
 > **Branch: `stg`** — this branch defaults to the staging backend, which has
 > its own character database. Use `main` or `prod` for production.
 >
-> **Status: early release (`0.1.0`).** The front-door API is still moving —
-> see [Roadmap](#roadmap).
+> **Status: early release.** The front door — a credential plus a
+> `characterId` — is settled; what is still moving is listed in
+> [Roadmap](#roadmap).
 
 ## Install
 
@@ -29,40 +30,105 @@ pnpm add @react-three/fiber react
 `three` and `@convai/web-sdk` are peer dependencies. `react` and
 `@react-three/fiber` are optional peers — the `/core` path needs neither.
 
-## Quick start — React
+## Quick start
 
 ```tsx
-import { ConvaiCharacter } from '@convai/embody/react'
-import { httpResolver } from '@convai/embody'
-
-<ConvaiCharacter
-  resolver={httpResolver({ apiKey })}          // host defaults per release channel
-  characterId={characterId}
-  queue={client.blendshapeQueue}   // only while this character owns the turn
-/>
+import ConvaiCharacter from '@convai/embody/react'
+
+export default function App() {
+  return <ConvaiCharacter apiKey={apiKey} characterId={characterId} />
+}
 ```
 
-## Quick start — core (plain three.js)
+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.
+
+### Credentials
+
+`apiKey` is the fastest way to see something on screen, and it is what the
+demo uses. It is a **workspace-wide** credential, so treat a build that ships
+it as trusted-only.
+
+For anything user-facing, mint a short-lived auth token server-side and pass
+`token` instead — same component, one prop different:
+
+```tsx
+<ConvaiCharacter token={token} characterId={characterId} />
+```
+
+### In a scene you already have
+
+`ConvaiCharacter` brings its own canvas. When the character should join a
+scene you are composing yourself, use `CharacterModel` inside your `<Canvas>`:
+
+```tsx
+import { CharacterModel } from '@convai/embody/react'
+
+<Canvas>
+  <MyLights />
+  <CharacterModel apiKey={apiKey} characterId={characterId} />
+  <MyProps />
+</Canvas>
+```
+
+### Talking to the character
+
+`character.client` is the `@convai/web-sdk` client — the same connection, not
+a second one. Lift it out with `onReady`; chat UI is DOM, so it lives outside
+the canvas:
+
+```tsx
+import {
+  ConvaiCharacter, ConvaiWidget, useWidgetClient, type ConvaiClient,
+} from '@convai/embody/react'
+
+function App() {
+  const [client, setClient] = useState<ConvaiClient | null>(null)
+  const widgetClient = useWidgetClient(client)
+  return (
+    <>
+      <ConvaiCharacter
+        apiKey={apiKey}
+        characterId={characterId}
+        onReady={(c) => setClient(c.client)}
+      />
+      {widgetClient && <ConvaiWidget convaiClient={widgetClient} />}
+    </>
+  )
+}
+```
+
+`ConvaiWidget` and `ConvaiClient` are re-exported from `@convai/web-sdk`, so
+`@convai/embody` is the only import your app needs. `useWidgetClient` adapts
+embody's client to the widget's props — the SDK's own `useConvaiClient` would
+*construct a second client*, and so open a second connection, which is exactly
+what embody exists to avoid.
+
+## Without React
+
+The root entry is framework-free — it pulls in neither React nor
+`@react-three/fiber`, so a vanilla three.js app can use it directly:
 
 ```ts
-import { createCharacter, httpResolver } from '@convai/embody'
+import { createCharacter } from '@convai/embody'
 
-const character = await createCharacter({
-  resolver: httpResolver({ apiKey }),   // host defaults per release channel
-  characterId,
-})
+const character = await createCharacter({ apiKey, characterId })
 
 scene.add(character.root)
 character.camera = camera
+character.client?.sendUserTextMessage('hello')
 
 renderer.setAnimationLoop(() => {
-  character.update(clock.getDelta(), client?.blendshapeQueue)
+  character.update(clock.getDelta())
   renderer.render(scene, camera)
 })
 ```
 
 `character.dispose()` releases the model, its materials and textures, the
-mixer, and the reduced-motion listener.
+mixer, and the reduced-motion listener, and closes the connection embody
+opened. A client you passed in yourself is left alone.
 
 ## What it does
 
@@ -95,12 +161,18 @@ load-bearing, not incidental:
 ships but is deliberately not registered. Bone and morph names are data on the
 profile, so a new rig is a value rather than a code change.
 
-## The resolver seam
+## Escape hatches
 
-`CharacterResolver` is the plug point between this package and the asset
-backend. `httpResolver` talks to `GET /character/{id}/embodiment`, but anything
-returning a `CharacterBundle` works — the demo ships an offline fixture
-resolver for backend-free development.
+The defaults cover the normal case; each of these exists for a specific one.
+
+| Option | For |
+|---|---|
+| `resolver` | A private asset backend, a fixture in tests, or a pre-fetched manifest. Anything returning a `CharacterBundle` works — the demo ships an offline fixture resolver for backend-free development. `httpResolver` (the default) talks to `GET /character/{id}/embodiment`. |
+| `client` | An SDK client your app already created and connected. embody drives lipsync from it and never disconnects it. |
+| `connect: false` | A body with no mind — thumbnails, previews, asset review tools. `character.client` is then `null`. |
+| `session` | Extra SDK options (voice, memory, transport, `endUserId`). Credentials and `characterId` are not repeated here. |
+| `baseUrl` | A different backend environment. Defaults per release channel. |
+| `queue` on `update()` | One client driving several bodies, when you are deciding which owns the current turn. |
 
 ## Docs
 
@@ -112,6 +184,7 @@ Design, plan and decision history live in [`docs/`](./docs):
 | [motion-implementation-plan.md](./docs/motion-implementation-plan.md) | the 12-task TDD plan |
 | [motion-decisions.md](./docs/motion-decisions.md) | 73 rulings, each with its cost if wrong |
 | [motion-execution-ledger.md](./docs/motion-execution-ledger.md) | the full execution record |
+| [testing-spec.md](./docs/testing-spec.md) | standing policy: the module → test manifest CI enforces |
 
 ## Release channels
 
@@ -144,19 +217,30 @@ pnpm check:hosts   # auto-detects the current branch
 
 ```bash
 pnpm install
-pnpm test         # 86 tests
+pnpm test         # 183 tests
 pnpm typecheck
+pnpm check:tests  # every src/ module has a named test — see docs/testing-spec.md
 pnpm build        # emits dist/ with .d.ts
-pnpm verify       # hosts + typecheck + test + build
+pnpm verify       # hosts + test manifest + typecheck + test + build
 pnpm dev          # the demo (see demo/verify.md)
 ```
 
+Every module in `src/` has a row in [`docs/testing-spec.md`](./docs/testing-spec.md)
+naming its test and what that test must prove, and `pnpm check:tests` enforces
+it in CI. A new file under `src/` with no row fails the build, so adding a
+feature and adding its test are the same commit.
+
 ## Roadmap
 
-- **Credential-first API.** `apiKey` / `authToken` + `characterId` should be
-  enough; the resolver should become optional and be constructed internally.
-  The default host now exists, so this is the remaining half.
+- **Zero requests of our own.** Return the body manifest from the connection
+  the SDK already opens, so embody makes no API call at all. Designed in
+  [`docs/manifest-in-connect.md`](./docs/manifest-in-connect.md); the work is
+  mostly in `core-service`.
 - **Retry on expired asset URLs** — re-resolve and retry once on a 403.
+- **More rigs.** `convai-mha-1` is the only registered profile, so a character
+  on any other rig has no body.
+- **Compressed assets.** The default bodies are ~30 MB; the manifest already
+  has `lod` and `encodings` fields that nothing fills in.
 - Foot lock, locomotion, hair physics, idle gestures.
 - Eye saccades and the speech lock.
 

package/dist/character/createCharacter.d.ts

@@ -4,6 +4,8 @@
  */
 import * as THREE from 'three';
 import { type CharacterResolver, type CharacterBundle, type Representation } from '../resolve/resolver.js';
+import { type SessionOptions } from '../connect/session.js';
+import type { ConvaiClient } from '@convai/web-sdk/core';
 import { type UnitNormalizer } from '../rig/units.js';
 import { AnimationController } from '../clips/animations.js';
 import { LipsyncSystem, type MouthTuning } from '../speech/lipsync.js';
@@ -16,9 +18,69 @@ import { type BreathingConfig } from '../motion/breathe.js';
 import { type EyeGazeConfig } from '../motion/eyeGaze.js';
 import { type BlinkConfig } from '../motion/blink.js';
 import { type ReducedMotion } from '../motion/reducedMotion.js';
+/**
+ * Where the Draco decoder is fetched from. Google's versioned CDN, which is
+ * what three's own examples use and is served with permissive CORS.
+ *
+ * Override via `dracoDecoderPath` to self-host — required for air-gapped
+ * deployments, or any app whose CSP does not allow gstatic.
+ */
+export declare const DEFAULT_DRACO_DECODER_PATH = "https://www.gstatic.com/draco/versioned/decoders/1.5.7/";
 export interface CreateCharacterOptions {
-    resolver: CharacterResolver;
+    /**
+     * The character to embody. This plus a credential is the whole required
+     * API — everything below has a working default.
+     */
     characterId: string;
+    /**
+     * Convai auth token — the credential a browser app should ship, since it
+     * is scoped and short-lived. Alias of `authToken`; supply either.
+     */
+    token?: string;
+    /** Convai API key. Server-side or trusted contexts. */
+    apiKey?: string;
+    /** Same as `token`, under the name @convai/web-sdk uses. */
+    authToken?: string;
+    /**
+     * Backend host. Defaults to the release channel's host (see
+     * `DEFAULT_BASE_URL`); override only to point at a different environment.
+     */
+    baseUrl?: string;
+    /**
+     * Escape hatch: resolve the body manifest yourself. Almost nobody needs
+     * this — with credentials above, embody builds an `httpResolver` for you.
+     * Supply it for a private asset backend, a fixture in tests, or a
+     * pre-fetched manifest.
+     */
+    resolver?: CharacterResolver;
+    /**
+     * Extra @convai/web-sdk connection options (voice, memory, transport,
+     * `endUserId`, …). `characterId`, `apiKey` and `authToken` come from
+     * above and are not repeated here.
+     */
+    session?: Omit<SessionOptions, 'characterId' | 'apiKey' | 'authToken'>;
+    /**
+     * Reuse a client the app already created and connected, instead of having
+     * embody open one. embody drives lipsync from it but never disconnects it.
+     *
+     * Read once, when the character is created. In React that means it must be
+     * present on the first render that mounts the character — a client supplied
+     * later is not picked up, because re-reading it would mean rebuilding the
+     * character and re-downloading its model. Gate the mount on your client
+     * being ready.
+     */
+    client?: ConvaiClient;
+    /**
+     * Set `false` for a body with no mind — no SDK connection, no audio, no
+     * lipsync source. Useful for thumbnails, previews and asset review tools
+     * that only need to render the model. Default `true`.
+     */
+    connect?: boolean;
+    /**
+     * Base URL for the Draco decoder files. Defaults to
+     * `DEFAULT_DRACO_DECODER_PATH`; set this to self-host them.
+     */
+    dracoDecoderPath?: string;
     /** Rig profiles this build understands, in preference order. */
     supportedRigs?: string[];
     targetHeight?: number;
@@ -28,6 +90,13 @@ export interface CreateCharacterOptions {
     decorators?: CharacterDecorator[];
     /** Extra local clips (name → url), merged OVER manifest clips by name. */
     animations?: Record<string, string>;
+    /**
+     * Which clip to play on load. Defaults to a clip named "idle"
+     * (case-insensitive), falling back to the first clip the character ships,
+     * so a character is never left standing in its bind pose. Pass `false` to
+     * start paused and drive playback yourself.
+     */
+    idleClip?: string | false;
     /** Stage 2 head/neck gaze tracking config. */
     gaze?: GazeConfig;
     /** Stage 6 eyelid/blink config. */
@@ -51,11 +120,31 @@ export interface CharacterHandle {
     rig: ResolvedRig;
     pipeline: Pipeline;
     gaze: GazeSystem;
+    /**
+     * The live @convai/web-sdk client — the character's mind. `null` only when
+     * `connect: false`. Use it for everything conversational:
+     *
+     * ```ts
+     * character.client?.sendUserTextMessage('hello')
+     * character.client?.on('transcript', (t) => console.log(t))
+     * ```
+     */
+    client: ConvaiClient | null;
     /** Set by the app once its camera exists; gaze tracking no-ops without one. */
     camera?: THREE.Camera;
-    /** Tick every frame; pass the queue only when this character owns the turn. */
+    /**
+     * Tick every frame. The lipsync queue comes from this character's own
+     * session, so a single-character app passes nothing.
+     *
+     * Pass `queue` explicitly only when one client drives several bodies and
+     * you are deciding which of them owns the current turn; it overrides the
+     * session queue for that frame.
+     */
     update(delta: number, queue?: BlendshapeQueue): void;
-    /** Stop the reduced-motion media-query watcher. Call on teardown. */
+    /**
+     * Release GPU resources and, when embody opened the connection, close it.
+     * A client passed in as `client` is left alone — the app owns its lifetime.
+     */
     dispose(): void;
 }
 /**
@@ -76,6 +165,22 @@ export declare function buildPipeline(deps: {
     pipeline: Pipeline;
     gaze: GazeSystem;
 };
+/**
+ * Which clip a freshly loaded character should play, if any.
+ *
+ * Extracted as its own seam (same rationale as `buildPipeline`) so the
+ * choice can be tested without a GLB.
+ *
+ * `requested` is `CreateCharacterOptions.idleClip`: a name to insist on,
+ * `false` to start paused, or undefined for the default. Clip names come from
+ * the manifest and are not guaranteed, so the default prefers a clip actually
+ * called idle and otherwise falls back to whatever the character shipped
+ * first — anything is better than the bind pose.
+ *
+ * A requested name that the character does not have returns null rather than
+ * silently substituting: the caller asked for something specific.
+ */
+export declare function pickIdleClip(names: string[], requested?: string | false): string | null;
 /**
  * The teardown block, factored out as its own seam (same rationale as
  * `buildPipeline` above) so it can be tested without a GLB — real,

package/dist/character/createCharacter.js

@@ -1,5 +1,7 @@
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
-import { pickRepresentation } from '../resolve/resolver.js';
+import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
+import { pickRepresentation, httpResolver, MISSING_CREDENTIAL } from '../resolve/resolver.js';
+import { createSession, adoptSession } from '../connect/session.js';
 import { createUnitNormalizer } from '../rig/units.js';
 import { AnimationController } from '../clips/animations.js';
 import { LipsyncSystem } from '../speech/lipsync.js';
@@ -12,6 +14,14 @@ import { BreathingSystem } from '../motion/breathe.js';
 import { EyeGazeSystem } from '../motion/eyeGaze.js';
 import { BlinkSystem } from '../motion/blink.js';
 import { createReducedMotion } from '../motion/reducedMotion.js';
+/**
+ * Where the Draco decoder is fetched from. Google's versioned CDN, which is
+ * what three's own examples use and is served with permissive CORS.
+ *
+ * Override via `dracoDecoderPath` to self-host — required for air-gapped
+ * deployments, or any app whose CSP does not allow gstatic.
+ */
+export const DEFAULT_DRACO_DECODER_PATH = 'https://www.gstatic.com/draco/versioned/decoders/1.5.7/';
 /**
  * The registration block, factored out as its own seam so it can be tested
  * without a GLB or a network resolver — it only needs objects of the right
@@ -41,6 +51,28 @@ export function buildPipeline(deps, opts) {
     }
     return { pipeline, gaze };
 }
+/**
+ * Which clip a freshly loaded character should play, if any.
+ *
+ * Extracted as its own seam (same rationale as `buildPipeline`) so the
+ * choice can be tested without a GLB.
+ *
+ * `requested` is `CreateCharacterOptions.idleClip`: a name to insist on,
+ * `false` to start paused, or undefined for the default. Clip names come from
+ * the manifest and are not guaranteed, so the default prefers a clip actually
+ * called idle and otherwise falls back to whatever the character shipped
+ * first — anything is better than the bind pose.
+ *
+ * A requested name that the character does not have returns null rather than
+ * silently substituting: the caller asked for something specific.
+ */
+export function pickIdleClip(names, requested) {
+    if (requested === false)
+        return null;
+    if (requested)
+        return names.includes(requested) ? requested : null;
+    return names.find((n) => n.toLowerCase() === 'idle') ?? names[0] ?? null;
+}
 /** Every material property that can hold a disposable `THREE.Texture`. */
 const TEXTURE_PROPS = [
     'map', 'normalMap', 'roughnessMap', 'metalnessMap', 'emissiveMap',
@@ -95,9 +127,52 @@ export function disposeCharacter(deps) {
     reducedMotion.dispose();
 }
 export async function createCharacter(opts) {
-    const bundle = await opts.resolver.resolve(opts.characterId);
+    // The resolver is an escape hatch, not a requirement: the common path is
+    // credentials in, character out. Same credentials for body and mind, so
+    // the caller never supplies them twice.
+    // `token` is the name the API is documented under; `authToken` is what the
+    // SDK config calls the same thing. Accept both, resolve once, here.
+    const authToken = opts.token ?? opts.authToken;
+    // Fail before the connection and a multi-megabyte download rather than
+    // after. Only the DEFAULT resolver needs this — a caller supplying their
+    // own resolver (fixtures, a private backend) authenticates it themselves.
+    if (!opts.resolver && !authToken && !opts.apiKey)
+        throw new Error(MISSING_CREDENTIAL);
+    const resolver = opts.resolver ??
+        httpResolver({ baseUrl: opts.baseUrl, apiKey: opts.apiKey, authToken });
+    // Body and mind are started together — the connection is the slower of the
+    // two and the GLB is tens of megabytes, so serialising them would add the
+    // whole handshake to time-to-first-frame for no reason.
+    const wantsSession = opts.connect !== false;
+    const sessionPromise = !wantsSession
+        ? Promise.resolve(null)
+        : opts.client
+            ? Promise.resolve(adoptSession(opts.client))
+            : createSession({
+                ...opts.session,
+                characterId: opts.characterId,
+                apiKey: opts.apiKey,
+                authToken,
+            });
+    // Nothing awaits this yet, so an early connection failure would be an
+    // unhandled rejection while the GLB is still downloading. Park the outcome
+    // and re-throw it below, after the body has settled.
+    const settledSession = sessionPromise.then((s) => ({ session: s, error: null }), (e) => ({ session: null, error: e }));
+    const bundle = await resolver.resolve(opts.characterId);
     const rep = pickRepresentation(bundle, opts.supportedRigs ?? ['convai-mha-1']);
+    // Draco is not optional: japanese-m-animations.glb — the default male body's
+    // clips — declares KHR_draco_mesh_compression in extensionsRequired, and a
+    // GLTFLoader without a decoder fails it outright ("No DRACOLoader instance
+    // provided"). Any compressed asset the art pipeline produces will be the
+    // same, so the decoder is wired unconditionally rather than sniffed for.
+    //
+    // The decoder itself is fetched at load time from `dracoDecoderPath`; three
+    // does not bundle the wasm, and shipping it inside this package would put a
+    // binary in every consumer's bundle whether or not their character uses it.
     const loader = new GLTFLoader();
+    const draco = new DRACOLoader();
+    draco.setDecoderPath(opts.dracoDecoderPath ?? DEFAULT_DRACO_DECODER_PATH);
+    loader.setDRACOLoader(draco);
     const modelUrl = rep.model[0].url;
     // clip sources: manifest clips, with local overrides winning by name
     const clipUrls = new Map();
@@ -106,10 +181,20 @@ export async function createCharacter(opts) {
     for (const [name, url] of Object.entries(opts.animations ?? {}))
         clipUrls.set(name, url);
     const uniqueUrls = [...new Set(clipUrls.values())];
-    const [modelGltf, ...clipGltfs] = await Promise.all([
-        loader.loadAsync(modelUrl),
-        ...uniqueUrls.map((u) => loader.loadAsync(u)),
-    ]);
+    let modelGltf, clipGltfs;
+    try {
+        ;
+        [modelGltf, ...clipGltfs] = await Promise.all([
+            loader.loadAsync(modelUrl),
+            ...uniqueUrls.map((u) => loader.loadAsync(u)),
+        ]);
+    }
+    finally {
+        // Frees the decoder's worker pool. Safe once every loadAsync above has
+        // settled, and it must run on the failure path too or a character that
+        // fails to load leaks workers.
+        draco.dispose();
+    }
     const root = modelGltf.scene;
     // gather every clip whose name the manifest/overrides declared
     const wanted = new Set(clipUrls.keys());
@@ -120,6 +205,17 @@ export async function createCharacter(opts) {
                 clips.push(a);
     const animations = new AnimationController(root);
     animations.register(clips);
+    // Start idling. Without this a zero-config character stands in its bind
+    // pose — arms out, visibly wrong — until the app happens to call play().
+    // Making the caller do that is exactly the kind of required extra step
+    // this API is meant not to have.
+    //
+    // Name resolution is by convention with a fallback, because clip names come
+    // from the manifest and are not guaranteed: prefer a clip actually called
+    // idle, otherwise just play the first one the character shipped.
+    const idle = pickIdleClip(animations.names, opts.idleClip);
+    if (idle)
+        animations.play(idle);
     const lipsync = new LipsyncSystem(opts.mouth);
     lipsync.bind(root);
     for (const d of opts.decorators ?? []) {
@@ -142,12 +238,23 @@ export async function createCharacter(opts) {
         energy: 0,
         reducedMotion: false,
     };
+    // The body is ready; now surface any connection failure. Ordering matters:
+    // reporting it here means a mind that fails to connect never leaks a
+    // half-built body — we dispose what we loaded before throwing.
+    const { session, error: sessionError } = await settledSession;
+    if (sessionError) {
+        disposeCharacter({ root, mixer: animations.mixer, reducedMotion: reduced });
+        throw sessionError;
+    }
     const handle = {
         root, bundle, representation: rep, animations, lipsync, rig, pipeline, gaze,
+        client: session?.client ?? null,
         camera: undefined,
         update(delta, queue) {
             frameCtx.camera = handle.camera;
-            frameCtx.queue = queue;
+            // An explicit queue wins — that is the multi-body turn-ownership case.
+            // Otherwise this character listens to its own session.
+            frameCtx.queue = queue ?? session?.queue;
             // Produced in stage 6 last frame — deliberately one frame stale (see
             // FrameContext's doc comment on `speaking`/`energy`).
             frameCtx.speaking = lipsync.speaking;
@@ -157,6 +264,10 @@ export async function createCharacter(opts) {
         },
         dispose() {
             disposeCharacter({ root, mixer: animations.mixer, reducedMotion: reduced });
+            // Fire-and-forget: `dispose()` is called from React cleanup and
+            // `requestAnimationFrame` teardown, neither of which can await. The
+            // session swallows its own double-dispose.
+            void session?.dispose();
         },
     };
     return handle;