@convai/embody 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -1,30 +1,24 @@
 # @convai/embody
 
-## 0.4.2
+## 0.6.0
 
-### Patch Changes
+### Minor Changes
 
-- 532c49e: Swapping the body under a fixed character id now reaches the screen.
+- b9b1e4c: **embody is the 3D character only.** `@convai/embody/react` no longer re-exports `ConvaiWidget`, `AudioRenderer` or `AudioContext`: `@convai/web-sdk` 2.0 moved its chat UI to `@convai/web-widget`, so import them from `@convai/web-widget/react` and install it next to embody. `useWidgetClient` stays: hand its result to the widget so the chat and the character share one connection.
 
-  `useCharacter` rebuilt the character only when the character id, credentials
-  or base url changed. The **resolver** was not among them, and the effect read
-  its options from a ref — so an authoring tool that holds one avatar id and
-  swaps the block underneath (preview release 3, then release 4) got nothing:
-  the old GLB stayed on the canvas and it read as a stubborn cache. Nothing was
-  cached. The loader was never asked for the new url.
+  ```diff
+  - import { ConvaiCharacter, ConvaiWidget, useWidgetClient } from '@convai/embody/react'
+  + import { ConvaiCharacter, useWidgetClient } from '@convai/embody/react'
+  + import { ConvaiWidget } from '@convai/web-widget/react'
+  ```
 
-  The resolver decides WHICH body a character id resolves to, so it belongs in
-  the rebuild set, and now is.
+  The `@convai/web-sdk` peer range now also admits the 2.0 prereleases (`>=1.8.0-beta.4 || >=2.0.0-beta.0`); `>=1.8.0-beta.4` alone made npm refuse `2.0.0-beta.x` with ERESOLVE.
 
-  This makes the resolver's identity part of the contract: **memoize it**, and
-  change it exactly when the body should change. A resolver rebuilt inline on
-  every render would rebuild the character on every render. The README's new
-  "Swapping the body under a fixed character id" section shows the shape.
+## 0.5.0
+
+### Minor Changes
 
-  Also documented, unchanged in behaviour: the `orbit` prop (shipped in 0.4.0
-  and previously absent from the README), which backend each npm tag talks to,
-  and the correct release-branch names — the table named three branches that do
-  not exist.
+- 249a96f: Optional corrective map for one-morph-per-control bodies. A table fitted from the body's MetaHuman DNA re-weights each lipsync frame toward the full rig (PSD correctives, joint arcs). Pass `correctiveMap` (from `compileCorrectiveMap`) to `createCharacter` or the React components; it is off by default and swaps live through the prop or `character.lipsync.correctiveMap`.
 
 ## 0.4.1
 

package/README.md

@@ -2,7 +2,7 @@
 
 **Give a Convai character a body.**
 
-[![npm](https://img.shields.io/npm/v/@convai/embody/latest?label=npm&color=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)
 
@@ -12,31 +12,28 @@ lipsync, gaze, breathing and blink. Layered on
 
 ---
 
-> **Branch: `main`** — this branch defaults to the production backend and
-> publishes the `latest` tag. `stg` targets staging, which has its own
-> character database.
+> **Branch: `stg`** — this branch defaults to the staging backend, which has
+> its own character database. Use `main` or `prod` for production.
 >
 > **Status: early release.** The front door — a credential plus a
 > `characterId` — is settled; what is still moving is listed in
 > [Roadmap](#roadmap).
 
-> **Which backend a build talks to is fixed at publish time.** The `latest`
-> and `beta` tags point at `https://api.convai.com`; the `stg` tag points at
-> `https://api-stg.convai.com`. Character ids are per-environment and not
-> interchangeable — a staging id against production returns *"Character not
-> found or doesn't belong to user"*, which reads like a permissions problem
-> and is a wrong-host one. Override with `baseUrl` only if you know why.
-
 ## Install
 
 ```bash
-pnpm add @convai/embody three
+pnpm add @convai/embody @convai/web-sdk three
 # React consumers also need:
 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.
+`@convai/web-sdk` and `three` are peer dependencies. `react` and
+`@react-three/fiber` are optional peers — the root `@convai/embody` entry
+point needs neither. Node.js 18 or later.
+
+A character renders only if its avatar has a published web body, or a default
+body applies to it. Otherwise loading fails with *"Character has no 3D
+embodiment configured"* — a data problem, not a code one.
 
 ## Quick start
 
@@ -66,32 +63,6 @@ For anything user-facing, mint a short-lived auth token server-side and pass
 <ConvaiCharacter token={token} characterId={characterId} />
 ```
 
-### Moving the camera
-
-Drag to turn the character, scroll to move in and out. On by default — a 3D
-character you cannot walk around is a picture of one.
-
-```tsx
-<ConvaiCharacter apiKey={apiKey} characterId={characterId} orbit={false} />
-```
-
-Pass an object to tune the limits instead of turning it off:
-
-```tsx
-<ConvaiCharacter
-  apiKey={apiKey}
-  characterId={characterId}
-  orbit={{ maxDistance: 6, autoRotate: true, autoRotateSpeed: 0.8 }}
-/>
-```
-
-`minDistance`, `maxDistance`, `minPolarAngle`, `maxPolarAngle`, `enablePan`,
-`enableZoom`, `autoRotate`, `autoRotateSpeed`. The defaults are tuned for one
-subject — a standing human — not for a general scene viewer: panning is off
-because it only ever slides the character out of frame, and the vertical sweep
-stops just below eye level because orbiting under the floor shows the inside
-of a head.
-
 ### In a scene you already have
 
 `ConvaiCharacter` brings its own canvas. When the character should join a
@@ -114,9 +85,8 @@ 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'
+import { ConvaiCharacter, useWidgetClient, type ConvaiClient } from '@convai/embody/react'
+import { ConvaiWidget } from '@convai/web-widget/react'
 
 function App() {
   const [client, setClient] = useState<ConvaiClient | null>(null)
@@ -134,8 +104,9 @@ function App() {
 }
 ```
 
-`ConvaiWidget` and `ConvaiClient` are re-exported from `@convai/web-sdk`, so
-`@convai/embody` is the only import your app needs. `useWidgetClient` adapts
+embody is the 3D character only; the chat panel is
+[`@convai/web-widget`](https://www.npmjs.com/package/@convai/web-widget)
+(`npm install @convai/web-widget`). `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.
@@ -207,28 +178,33 @@ The defaults cover the normal case; each of these exists for a specific one.
 | `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. |
+| `correctiveMap` | A table fitted from the body's MetaHuman DNA (`compileCorrectiveMap(json)`) that re-weights each lipsync frame toward what the full rig shows: PSD correctives and joint arcs that one-morph-per-control bodies lack. Off by default. Changing the prop, or `character.lipsync.correctiveMap`, swaps it live. In `pnpm dev`, the demo lists `*.map.json` tables from `../open-rig-dna/maps` (or `$EMBODY_CORRECTIVE_MAPS`) for A/B: **C** toggles, **F** frames the face. |
 
-### Swapping the body under a fixed character id
-
-`resolver` is how an authoring tool previews a body that is not published — or
-not even saved. Its **identity is part of the rebuild contract**: memoize it,
-and change it exactly when the body should change.
-
-```tsx
-const resolver = useMemo(
-  () => ({ async resolve() { return bundle } }),
-  [bundle],
-)
-
-<ConvaiCharacter characterId={avatarId} resolver={resolver} connect={false} />
-```
-
-Changing the resolver rebuilds the character; keeping it stable does not. A
-resolver rebuilt inline on every render would reload the GLB on every render.
+## Documentation
 
-## Docs
+**User documentation** is published on docs.convai.com under *Web Plugins →
+Convai Embody*. Its source is [`docs/site/`](./docs/site) in this repository:
 
-Design, plan and decision history live in [`docs/`](./docs):
+| | |
+|---|---|
+| [Add a 3D character to a React app](./docs/site/convai-embody/add-a-3d-character-to-a-react-app.md) | install, render, verify, troubleshoot |
+| [Add a 3D character to a three.js scene](./docs/site/convai-embody/add-a-3d-character-to-a-three-js-scene.md) | the framework-free API |
+| [Add a chat widget to a character](./docs/site/convai-embody/add-a-chat-widget-to-a-character.md) | one connection for body and chat |
+| [React API reference](./docs/site/convai-embody/react-api-reference.md) | every prop and default |
+| [createCharacter reference](./docs/site/convai-embody/createcharacter-reference.md) | every option, the handle, the errors |
+| [How Convai Embody works](./docs/site/convai-embody/how-convai-embody-works.md) | resolution, the frame pipeline, environments |
+
+Edit those pages here, not in the documentation repository. **Docs are part of every change:** CI runs the same sync into a throwaway checkout of Convai-Documentation and lints every page with that repository's `check_page.py`, so a page that would fail the docs gate fails the PR. Section path, version variable and sidebar placement live in [`docs/site/docs.config.json`](./docs/site/docs.config.json); page order, including nested groups, in [`docs/site/sidebar.json`](./docs/site/sidebar.json). Every publish to
+npm `latest` runs [`docs-sync.yml`](./.github/workflows/docs-sync.yml), which
+opens a pull request against `Conv-AI/Convai-Documentation` (`staging`) with
+the pages, their sidebar entries, `last_reviewed`, and the `embody_version`
+GitBook variable. Merging that pull request publishes to the GitBook **Staging**
+Space for review; the pages reach docs.convai.com only when a human then merges
+`staging` into `main` in that repository. Run the workflow by hand for a
+docs-only fix. The pages follow that repository's authoring rules, recorded for
+this package in [`docs/site/pack.md`](./docs/site/pack.md).
+
+**Design, plan and decision history** live in [`docs/`](./docs):
 
 | | |
 |---|---|
@@ -251,8 +227,14 @@ The backend host is a source constant, `DEFAULT_BASE_URL` in
 | `stg` | `https://api-stg.convai.com` | `stg` |
 
 Beta points at **production** — it is the first line of testing against real
-infrastructure, not a staging channel. Only `stg-release` targets staging,
-which has its own character database.
+infrastructure, not a staging channel. Only `stg` targets staging, which has
+its own character database. Character IDs belong to one environment: a staging
+ID against production returns a not-found error that reads like a permissions
+problem.
+
+Promotion has a silent failure mode: merging `stg` into `main` carries the
+staging `DEFAULT_BASE_URL` across with no conflict, because only `stg` ever
+edits that line. `pnpm check:hosts` is what catches it.
 
 `scripts/check-hosts.mjs` enforces this. Each channel build asserts the policy
 for the release it claims to be, so a staging artifact cannot be cut from
@@ -269,7 +251,7 @@ pnpm check:hosts   # auto-detects the current branch
 
 ```bash
 pnpm install
-pnpm test         # 220 tests
+pnpm test         # vitest
 pnpm typecheck
 pnpm check:tests  # every src/ module has a named test — see docs/testing-spec.md
 pnpm build        # emits dist/ with .d.ts
@@ -298,4 +280,4 @@ feature and adding its test are the same commit.
 
 ## License
 
-Apache-2.0. See [LICENSE](./LICENSE).
+Licensed under the [Apache License 2.0](./LICENSE). Copyright 2026 Convai.

package/dist/character/createCharacter.d.ts

@@ -9,6 +9,7 @@ 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';
+import type { CorrectiveMap } from '../speech/correctiveMap.js';
 import { type CharacterDecorator } from '../decorate/types.js';
 import type { BlendshapeQueue } from '@convai/web-sdk/core';
 import { Pipeline } from './pipeline.js';
@@ -87,6 +88,11 @@ export interface CreateCharacterOptions {
     targetHeight?: number;
     groundY?: number;
     mouth?: MouthTuning;
+    /**
+     * A corrective map fitted from this body's DNA (`compileCorrectiveMap`).
+     * Off by default. Swap it later through `handle.lipsync.correctiveMap`.
+     */
+    correctiveMap?: CorrectiveMap | null;
     /** Tier-2 customization: run once after load, before first frame. */
     decorators?: CharacterDecorator[];
     /** Extra local clips (name → url), merged OVER manifest clips by name. */

package/dist/character/createCharacter.js

@@ -223,7 +223,7 @@ export async function createCharacter(opts) {
     const idle = pickIdleClip(animations.names, opts.idleClip);
     if (idle)
         animations.play(idle);
-    const lipsync = new LipsyncSystem(opts.mouth);
+    const lipsync = new LipsyncSystem(opts.mouth, opts.correctiveMap ?? null);
     lipsync.bind(root);
     for (const d of opts.decorators ?? []) {
         d({ root, bundle, representation: rep, materials: collectMaterials(root) });

package/dist/index.d.ts

@@ -28,6 +28,8 @@ export { AnimationController } from './clips/animations.js';
 export type { ClipTransition } from './clips/animations.js';
 export { LipsyncSystem } from './speech/lipsync.js';
 export type { MouthTuning } from './speech/lipsync.js';
+export { compileCorrectiveMap, applyCorrectiveMap, CORRECTIVE_MAP_FORMAT } from './speech/correctiveMap.js';
+export type { CorrectiveMap, CorrectiveMapTable } from './speech/correctiveMap.js';
 export { createUnitNormalizer } from './rig/units.js';
 export { collectMaterials } from './decorate/types.js';
 export type { CharacterDecorator, DecoratorContext } from './decorate/types.js';

package/dist/index.js

@@ -25,6 +25,7 @@ export { httpResolver, pickRepresentation, DEFAULT_BASE_URL } from './resolve/re
 export { createCharacter } from './character/createCharacter.js';
 export { AnimationController } from './clips/animations.js';
 export { LipsyncSystem } from './speech/lipsync.js';
+export { compileCorrectiveMap, applyCorrectiveMap, CORRECTIVE_MAP_FORMAT } from './speech/correctiveMap.js';
 export { createUnitNormalizer } from './rig/units.js';
 export { collectMaterials } from './decorate/types.js';
 export { Pipeline } from './character/pipeline.js';

package/dist/react/index.d.ts

@@ -9,20 +9,23 @@
  * </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.
+ * embody is the 3D character only. For a chat panel, install
+ * `@convai/web-widget` and hand it the character's own client — one session,
+ * not two. `useWidgetClient` adapts that client to the widget's props.
  *
  * 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
+ * import { ConvaiWidget } from '@convai/web-widget/react'
+ *
  * const [client, setClient] = useState<ConvaiClient | null>(null)
+ * const widgetClient = useWidgetClient(client)
  * <Canvas>
  *   <ConvaiCharacter apiKey={apiKey} characterId={characterId}
  *                    onReady={(c) => setClient(c.client)} />
  * </Canvas>
- * {client && <ConvaiWidget convaiClient={client} />}
+ * {widgetClient && <ConvaiWidget convaiClient={widgetClient} />}
  * ```
  */
 export { useCharacter } from './useCharacter.js';
@@ -35,6 +38,6 @@ export { OrbitRig } from './OrbitRig.js';
 export type { OrbitOptions, OrbitRigProps } from './OrbitRig.js';
 export { useWidgetClient } from './useWidgetClient.js';
 export type { WidgetClient } from './useWidgetClient.js';
-export { ConvaiWidget, useConvaiClient, AudioRenderer, AudioContext } from '@convai/web-sdk/react';
+export { useConvaiClient } 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

@@ -9,20 +9,23 @@
  * </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.
+ * embody is the 3D character only. For a chat panel, install
+ * `@convai/web-widget` and hand it the character's own client — one session,
+ * not two. `useWidgetClient` adapts that client to the widget's props.
  *
  * 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
+ * import { ConvaiWidget } from '@convai/web-widget/react'
+ *
  * const [client, setClient] = useState<ConvaiClient | null>(null)
+ * const widgetClient = useWidgetClient(client)
  * <Canvas>
  *   <ConvaiCharacter apiKey={apiKey} characterId={characterId}
  *                    onReady={(c) => setClient(c.client)} />
  * </Canvas>
- * {client && <ConvaiWidget convaiClient={client} />}
+ * {widgetClient && <ConvaiWidget convaiClient={widgetClient} />}
  * ```
  */
 export { useCharacter } from './useCharacter.js';
@@ -32,6 +35,7 @@ export { CharacterModel } from './CharacterModel.js';
 // still want the orbit behaviour ConvaiCharacter gives for free.
 export { OrbitRig } from './OrbitRig.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';
+// ── The client, re-exported from @convai/web-sdk ──────────────────────────
+// No UI: ConvaiWidget, AudioRenderer and AudioContext are @convai/web-widget's.
+export { useConvaiClient } from '@convai/web-sdk/react';
 export { ConvaiClient } from '@convai/web-sdk/core';

package/dist/react/useCharacter.d.ts

@@ -7,12 +7,6 @@ export interface UseCharacterOptions extends CreateCharacterOptions {
      */
     queue?: BlendshapeQueue;
 }
-/**
- * NOTE ON `resolver` (inherited from CreateCharacterOptions): its identity is
- * part of this hook's dependency set. Memoize it, and change it precisely
- * when the body should change — an inline `{ resolve() {...} }` is a new
- * object every render and would rebuild the character every render.
- */
 export interface UseCharacterResult {
     character: CharacterHandle | null;
     /**

package/dist/react/useCharacter.js

@@ -35,27 +35,22 @@ export function useCharacter(opts) {
             setError(null);
         }, (c) => setCharacter(c), (e) => setError(e));
         return () => lifecycle.cancel();
-        // Re-create when the identity of the character, the credentials, OR the
-        // resolver change.
-        //
-        // The resolver belongs here because it decides WHICH BODY this character
-        // id resolves to. An authoring tool holds the character id fixed and
-        // swaps the block underneath — preview release 3, then release 4 — and
-        // without this dependency none of that reached the screen: the effect
-        // never re-ran, so the old GLB stayed on the canvas and the change looked
-        // like a stubborn cache. Nothing was cached; the loader was simply never
-        // asked for the new url.
-        //
-        // This makes the resolver's IDENTITY part of the contract: pass a stable
-        // one (`useMemo`) and change it exactly when the body should change. A
-        // resolver rebuilt inline on every render would rebuild the character on
-        // every render.
+        // 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.apiKey, opts.authToken, opts.token, opts.baseUrl, opts.resolver]);
+    }, [opts.characterId, opts.apiKey, opts.authToken, opts.token, opts.baseUrl]);
     useEffect(() => {
         if (character)
             character.camera = camera;
     }, [character, camera]);
+    // Live, unlike the props above: swapping the map must not reload the body,
+    // or an A/B on live speech would drop the turn it is comparing.
+    const correctiveMap = opts.correctiveMap ?? null;
+    useEffect(() => {
+        if (character)
+            character.lipsync.correctiveMap = correctiveMap;
+    }, [character, correctiveMap]);
     useFrame((_, delta) => character?.update(delta, queueRef.current));
     return {
         character,

package/dist/react/useWidgetClient.js

@@ -1,5 +1,5 @@
 /**
- * Makes embody's client usable by the SDK's `<ConvaiWidget/>`.
+ * Makes embody's client usable by `<ConvaiWidget/>` from `@convai/web-widget`.
  *
  * The widget wants `IConvaiClient` plus four pieces of reactive UI state
  * (`activity`, `isAudioMuted`, `isVideoEnabled`, `isScreenShareActive`). The

package/dist/resolve/resolver.d.ts

@@ -53,7 +53,7 @@ export interface CharacterResolver {
  * not pass `baseUrl` to the wrong backend, which is why it is checked rather
  * than trusted.
  */
-export declare const DEFAULT_BASE_URL = "https://api.convai.com";
+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;

package/dist/resolve/resolver.js

@@ -20,7 +20,7 @@
  * not pass `baseUrl` to the wrong backend, which is why it is checked rather
  * than trusted.
  */
-export const DEFAULT_BASE_URL = 'https://api.convai.com';
+export const DEFAULT_BASE_URL = 'https://api-stg.convai.com';
 /** Shared so `createCharacter` and the resolver cannot drift apart. */
 export const MISSING_CREDENTIAL = '@convai/embody: a credential is required — pass `token` (recommended for ' +
     'browsers) or `apiKey`. There is no anonymous access to Convai.';

package/dist/speech/correctiveMap.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Corrective map — re-weights Convai's 251 face controls so that a body with
+ * one baked morph per control lands closer to what the full MetaHuman rig
+ * shows.
+ *
+ * RigLogic fires correctives (PSDs) when controls combine, and its face joints
+ * rotate, so the skin moves along arcs; a sum of straight-line morphs follows
+ * neither. A table fitted from the character's DNA (convai-embody-console's
+ * tools/corrective-mapping/fit_mapping.py) corrects each frame before the
+ * mouth layer sees it:
+ *
+ *     w = x + clamp(A · φ(x), ±limit)
+ *
+ * φ(x) is one activation per corrective (Π clamp01(x_i), weighted and capped
+ * at 1, as RigLogic computes it) and, in version 2 tables, each x_i² and each
+ * x_i · jawOpen. The table holds no geometry: feature definitions and
+ * coefficients only. Format and maths match the console's
+ * corrective-mapping.mjs, so a table fitted there loads here unchanged.
+ */
+export declare const CORRECTIVE_MAP_FORMAT = "convai-corrective-map";
+/** One corrective's inputs (channel indices) and per-input weights. */
+interface PsdDef {
+    inputs: number[];
+    weights: number[];
+}
+/** The JSON fit_mapping.py writes. */
+export type CorrectiveMapTable = {
+    format: typeof CORRECTIVE_MAP_FORMAT;
+    version: 1;
+    channels: number;
+    /** One row per corrective: its definition and the channels it corrects. */
+    rows: (PsdDef & {
+        a: [number, number][];
+    })[];
+} | {
+    format: typeof CORRECTIVE_MAP_FORMAT;
+    version: 2;
+    channels: number;
+    features: {
+        psd: PsdDef[];
+        squares?: boolean;
+        jaw?: number;
+    };
+    /** [feature index, [[channel, coefficient], …]] */
+    coefficients: [number, [number, number][]][];
+    limit?: number;
+};
+interface Column {
+    targets: Int16Array;
+    coeffs: Float32Array;
+}
+/** A validated table packed into typed arrays for the per-frame loop. */
+export interface CorrectiveMap {
+    readonly channels: number;
+    readonly psd: {
+        inputs: Int16Array;
+        weights: Float32Array;
+    }[];
+    readonly squares: boolean;
+    /** jawOpen's channel index, or -1 when the table has no jaw features. */
+    readonly jaw: number;
+    readonly columns: (Column | null)[];
+    readonly limit: number;
+    /** Scratch for the per-frame delta; one map serves one frame at a time. */
+    readonly delta: Float32Array;
+}
+/** Validate a table and pack it. Throws on anything malformed, at load rather than mid-speech. */
+export declare function compileCorrectiveMap(table: CorrectiveMapTable): CorrectiveMap;
+/**
+ * Map one frame into `out` (allocated when omitted) and return it. `frame` is
+ * not modified. A frame of the wrong width is returned unmapped: a table
+ * fitted for another channel layout must not scribble over this one.
+ */
+export declare function applyCorrectiveMap(frame: Float32Array, map: CorrectiveMap, out?: Float32Array): Float32Array;
+export {};

package/dist/speech/correctiveMap.js

@@ -0,0 +1,125 @@
+/**
+ * Corrective map — re-weights Convai's 251 face controls so that a body with
+ * one baked morph per control lands closer to what the full MetaHuman rig
+ * shows.
+ *
+ * RigLogic fires correctives (PSDs) when controls combine, and its face joints
+ * rotate, so the skin moves along arcs; a sum of straight-line morphs follows
+ * neither. A table fitted from the character's DNA (convai-embody-console's
+ * tools/corrective-mapping/fit_mapping.py) corrects each frame before the
+ * mouth layer sees it:
+ *
+ *     w = x + clamp(A · φ(x), ±limit)
+ *
+ * φ(x) is one activation per corrective (Π clamp01(x_i), weighted and capped
+ * at 1, as RigLogic computes it) and, in version 2 tables, each x_i² and each
+ * x_i · jawOpen. The table holds no geometry: feature definitions and
+ * coefficients only. Format and maths match the console's
+ * corrective-mapping.mjs, so a table fitted there loads here unchanged.
+ */
+export const CORRECTIVE_MAP_FORMAT = 'convai-corrective-map';
+const clamp01 = (v) => (v > 0 ? (v < 1 ? v : 1) : 0);
+function checkIndex(i, channels, what) {
+    if (!Number.isInteger(i) || i < 0 || i >= channels)
+        throw new Error(`${what} ${i} is outside 0..${channels - 1}.`);
+}
+function compilePsd(defs, channels) {
+    return defs.map((d) => {
+        d.inputs.forEach((i) => checkIndex(i, channels, 'A corrective input'));
+        return { inputs: Int16Array.from(d.inputs), weights: Float32Array.from(d.weights) };
+    });
+}
+function column(entries, channels) {
+    entries.forEach(([i]) => checkIndex(i, channels, 'A target channel'));
+    return { targets: Int16Array.from(entries.map(([i]) => i)), coeffs: Float32Array.from(entries.map(([, c]) => c)) };
+}
+/** Validate a table and pack it. Throws on anything malformed, at load rather than mid-speech. */
+export function compileCorrectiveMap(table) {
+    if (!table || table.format !== CORRECTIVE_MAP_FORMAT)
+        throw new Error(`Not a ${CORRECTIVE_MAP_FORMAT} table.`);
+    const channels = table.channels;
+    const delta = new Float32Array(channels);
+    if (table.version === 1) {
+        const psd = compilePsd(table.rows, channels);
+        const columns = table.rows.map((row) => column(row.a, channels));
+        return { channels, psd, squares: false, jaw: -1, columns, limit: Infinity, delta };
+    }
+    if (table.version === 2) {
+        const f = table.features;
+        const psd = compilePsd(f.psd, channels);
+        const jaw = f.jaw ?? -1;
+        if (jaw >= 0)
+            checkIndex(jaw, channels, 'The jaw channel');
+        const size = psd.length + (f.squares ? channels : 0) + (jaw >= 0 ? channels : 0);
+        const columns = Array.from({ length: size }, () => null);
+        for (const [feature, entries] of table.coefficients) {
+            checkIndex(feature, size, 'Feature');
+            columns[feature] = column(entries, channels);
+        }
+        return { channels, psd, squares: Boolean(f.squares), jaw, columns, limit: table.limit ?? Infinity, delta };
+    }
+    throw new Error(`Unsupported ${CORRECTIVE_MAP_FORMAT} version ${table.version}.`);
+}
+function addColumn(delta, col, value) {
+    if (!col)
+        return;
+    for (let k = 0; k < col.targets.length; k++)
+        delta[col.targets[k]] += value * col.coeffs[k];
+}
+/**
+ * Map one frame into `out` (allocated when omitted) and return it. `frame` is
+ * not modified. A frame of the wrong width is returned unmapped: a table
+ * fitted for another channel layout must not scribble over this one.
+ */
+export function applyCorrectiveMap(frame, map, out = new Float32Array(frame.length)) {
+    const n = map.channels;
+    if (frame.length !== n) {
+        out.set(frame);
+        return out;
+    }
+    const delta = map.delta;
+    delta.fill(0);
+    let f = 0;
+    for (const psd of map.psd) {
+        let prod = 1;
+        for (let k = 0; k < psd.inputs.length; k++) {
+            const v = frame[psd.inputs[k]];
+            if (!(v > 0)) {
+                prod = 0;
+                break;
+            }
+            prod *= v < 1 ? v : 1;
+        }
+        if (prod !== 0) {
+            let p = 0;
+            for (let k = 0; k < psd.weights.length; k++)
+                p += Math.min(1, psd.weights[k] * prod);
+            addColumn(delta, map.columns[f], p);
+        }
+        f++;
+    }
+    if (map.squares) {
+        for (let i = 0; i < n; i++) {
+            const v = clamp01(frame[i]);
+            if (v !== 0)
+                addColumn(delta, map.columns[f + i], v * v);
+        }
+        f += n;
+    }
+    if (map.jaw >= 0) {
+        const jaw = clamp01(frame[map.jaw]);
+        if (jaw !== 0) {
+            for (let i = 0; i < n; i++) {
+                const v = clamp01(frame[i]);
+                if (v !== 0)
+                    addColumn(delta, map.columns[f + i], v * jaw);
+            }
+        }
+    }
+    const limit = map.limit;
+    for (let i = 0; i < n; i++) {
+        const d = delta[i] > limit ? limit : delta[i] < -limit ? -limit : delta[i];
+        out[i] = frame[i] + d;
+    }
+    return out;
+}

package/dist/speech/lipsync.d.ts

@@ -15,6 +15,7 @@
  */
 import type * as THREE from 'three';
 import type { BlendshapeQueue } from '@convai/web-sdk/core';
+import { type CorrectiveMap } from './correctiveMap.js';
 /** Tier-1 customization: the mouth knobs, per character. Defaults = pagoda-act's tuned values. */
 export interface MouthTuning {
     /** Hard cap on jawOpen; peak excursions read exaggerated on camera. */
@@ -46,10 +47,18 @@ export declare class LipsyncSystem {
     energy: number;
     /** True while the bot owns the mouth; body layers read it. */
     speaking: boolean;
+    /**
+     * Corrective map for this body, or null to play the stream as sent. Applied
+     * to each frame as it comes off the queue, before the SDK's shaping and the
+     * mouth layer. Mutable so a viewer can A/B it on live speech.
+     */
+    correctiveMap: CorrectiveMap | null;
+    private mapped;
     private readonly ch;
-    constructor(tuning?: MouthTuning);
+    constructor(tuning?: MouthTuning, correctiveMap?: CorrectiveMap | null);
     /** Bind every morph-bearing mesh under root. Returns matched channel count. */
     bind(root: THREE.Object3D): number;
+    private correct;
     /** Tick each frame. Pass the queue only if this character owns the turn. */
     update(delta: number, q: BlendshapeQueue | undefined): void;
 }

package/dist/speech/lipsync.js

@@ -1,4 +1,5 @@
 import { createLipsyncProcessor, mhaChannelIndex, } from '@convai/web-sdk/lipsync-helpers';
+import { applyCorrectiveMap } from './correctiveMap.js';
 const DEFAULTS = {
     jawCap: 0.55,
     sealCeiling: 0.5,
@@ -10,7 +11,7 @@ const DEFAULTS = {
     gainOverrides: { mouthLowerLipDepressL: 0.28, mouthLowerLipDepressR: 0.28 },
 };
 export class LipsyncSystem {
-    constructor(tuning = {}) {
+    constructor(tuning = {}, correctiveMap = null) {
         this.bindings = [];
         this.accum = 0;
         this.lastFrame = null;
@@ -20,6 +21,8 @@ export class LipsyncSystem {
         this.energy = 0;
         /** True while the bot owns the mouth; body layers read it. */
         this.speaking = false;
+        this.mapped = null;
+        this.correctiveMap = correctiveMap;
         this.t = { ...DEFAULTS, ...tuning, gainOverrides: { ...DEFAULTS.gainOverrides, ...tuning.gainOverrides } };
         this.processor = createLipsyncProcessor('mha', {
             skipEyeChannels: true,
@@ -43,6 +46,14 @@ export class LipsyncSystem {
         this.bindings = this.processor.bindAll(root);
         return this.bindings.reduce((s, b) => s + b.matched, 0);
     }
+    correct(frame) {
+        const map = this.correctiveMap;
+        if (!map)
+            return frame;
+        if (this.mapped?.length !== frame.length)
+            this.mapped = new Float32Array(frame.length);
+        return applyCorrectiveMap(frame, map, this.mapped);
+    }
     /** Tick each frame. Pass the queue only if this character owns the turn. */
     update(delta, q) {
         if (!this.bindings.length)
@@ -74,7 +85,7 @@ export class LipsyncSystem {
             if (this.accum > 0.25)
                 this.accum = 0.25; // a starved queue banks no debt
             if (fresh)
-                this.lastFrame = fresh;
+                this.lastFrame = this.correct(fresh);
         }
         else {
             this.accum = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convai/embody",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Give a Convai character a body: resolve 3D characters by characterId and drive them with lipsync and animation. Layered on @convai/web-sdk.",
   "license": "Apache-2.0",
   "author": "Convai <support@convai.com>",
@@ -58,7 +58,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@convai/web-sdk": ">=1.8.0-beta.4",
+    "@convai/web-sdk": ">=1.8.0-beta.4 || >=2.0.0-beta.0",
     "@react-three/fiber": ">=8",
     "react": ">=18",
     "three": ">=0.160"
@@ -73,7 +73,8 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.27.0",
-    "@convai/web-sdk": "1.8.0-beta.4",
+    "@convai/web-sdk": "2.0.0-beta.0",
+    "@convai/web-widget": "0.2.1",
     "@react-three/fiber": "^8.18.0",
     "@types/react": "^18.3.31",
     "@types/react-dom": "^19.2.7",
@@ -99,7 +100,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "verify": "pnpm check:hosts && pnpm check:tests && pnpm typecheck && pnpm test && pnpm build",
+    "verify": "pnpm check:hosts && pnpm check:tests && pnpm typecheck && pnpm test && pnpm test:scripts && pnpm build",
     "changeset": "changeset",
     "version": "changeset version",
     "release": "pnpm build:prod && changeset publish",
@@ -109,6 +110,7 @@
     "build:stg": "pnpm clean && BRANCH=stg node scripts/check-hosts.mjs && pnpm build",
     "release:stg": "pnpm build:stg && changeset publish --tag stg",
     "docs": "typedoc",
-    "docs:watch": "typedoc --watch"
+    "docs:watch": "typedoc --watch",
+    "test:scripts": "node --test scripts/sync-docs.test.mjs"
   }
 }