@convai/embody 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @convai/embody
 
+## 0.4.2
+
+### Patch Changes
+
+- 532c49e: Swapping the body under a fixed character id now reaches the screen.
+
+  `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.
+
+  The resolver decides WHICH body a character id resolves to, so it belongs in
+  the rebuild set, and now is.
+
+  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.
+
+  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.
+
+## 0.4.1
+
+### Patch Changes
+
+- 62deba9: `useWidgetClient` hides the server's `user-transcription` echo of a typed message, so `<ConvaiWidget/>` shows each sent message once instead of twice.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -2,7 +2,7 @@
 
 **Give a Convai character a body.**
 
-[![npm](https://img.shields.io/npm/v/@convai/embody/stg?label=npm%20stg&color=blue)](https://www.npmjs.com/package/@convai/embody)
+[![npm](https://img.shields.io/npm/v/@convai/embody/latest?label=npm&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,13 +12,21 @@ 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.
+> **Branch: `main`** — this branch defaults to the production backend and
+> publishes the `latest` tag. `stg` targets staging, which has its own
+> character database.
 >
 > **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
@@ -58,6 +66,32 @@ 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
@@ -174,6 +208,24 @@ The defaults cover the normal case; each of these exists for a specific one.
 | `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. |
 
+### 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.
+
 ## Docs
 
 Design, plan and decision history live in [`docs/`](./docs):
@@ -194,9 +246,9 @@ The backend host is a source constant, `DEFAULT_BASE_URL` in
 
 | Branch | Host | npm tag |
 |---|---|---|
-| `stable-release` | `https://api.convai.com` | `latest` |
-| `beta-release` | `https://api.convai.com` | `beta` |
-| `stg-release` | `https://api-stg.convai.com` | `stg` |
+| `main` / `prod` | `https://api.convai.com` | `latest` |
+| `beta` | `https://api.convai.com` | `beta` |
+| `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,
@@ -217,7 +269,7 @@ pnpm check:hosts   # auto-detects the current branch
 
 ```bash
 pnpm install
-pnpm test         # 183 tests
+pnpm test         # 220 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

package/dist/react/useCharacter.d.ts

@@ -7,6 +7,12 @@ 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,11 +35,23 @@ export function useCharacter(opts) {
             setError(null);
         }, (c) => setCharacter(c), (e) => setError(e));
         return () => lifecycle.cancel();
-        // 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.
+        // 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.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [opts.characterId, opts.apiKey, opts.authToken, opts.token, opts.baseUrl]);
+    }, [opts.characterId, opts.apiKey, opts.authToken, opts.token, opts.baseUrl, opts.resolver]);
     useEffect(() => {
         if (character)
             character.camera = camera;

package/dist/react/useWidgetClient.d.ts

@@ -6,6 +6,31 @@ export type WidgetClient = ConvaiClient & {
     isVideoEnabled: boolean;
     isScreenShareActive: boolean;
 };
+type ChatMessage = ConvaiClient['chatMessages'][number];
+/**
+ * How long after a typed message its server echo can still arrive. Measured
+ * at ~2 s on staging; the window is generous because a slow turn is still an
+ * echo, while the same words said aloud half a minute later are a new message.
+ */
+export declare const TYPED_ECHO_WINDOW_MS = 30000;
+/**
+ * The transcript without the server's echo of typed messages.
+ *
+ * `sendUserTextMessage` appends the text locally as `user-llm-text`, and the
+ * SDK drops the server's `user-llm-text` echo so the message appears once.
+ * But the server ALSO answers typed text with a final `user-transcription`
+ * carrying the same words — with no `logicalTurnId` to correlate on — which
+ * the SDK stores as a new message and `<ConvaiWidget/>` renders as a second
+ * "You" bubble. Every typed message showed twice; every reply once. Verified
+ * on web-sdk 1.8.0 and 1.9.0-beta.3, which filter identically.
+ *
+ * A transcription is an echo when an unmatched typed message with the same
+ * trimmed text precedes it within the window; each typed message cancels at
+ * most one. Spoken turns never produce a `user-llm-text`, so a real
+ * transcription is never dropped. An echo that streams in chunks can show
+ * its partial text until the final chunk matches — a flicker, not a duplicate.
+ */
+export declare function withoutTypedEchoes(messages: readonly ChatMessage[]): ChatMessage[];
 /**
  * ```tsx
  * const { client } = useCharacter({ apiKey, characterId })
@@ -16,3 +41,4 @@ export type WidgetClient = ConvaiClient & {
  * Returns `null` until the character's connection exists.
  */
 export declare function useWidgetClient(client: ConvaiClient | null): WidgetClient | null;
+export {};

package/dist/react/useWidgetClient.js

@@ -12,6 +12,47 @@
  * for activity, and the three control emitters for the toggles.
  */
 import { useEffect, useMemo, useState } from 'react';
+/**
+ * How long after a typed message its server echo can still arrive. Measured
+ * at ~2 s on staging; the window is generous because a slow turn is still an
+ * echo, while the same words said aloud half a minute later are a new message.
+ */
+export const TYPED_ECHO_WINDOW_MS = 30_000;
+/**
+ * The transcript without the server's echo of typed messages.
+ *
+ * `sendUserTextMessage` appends the text locally as `user-llm-text`, and the
+ * SDK drops the server's `user-llm-text` echo so the message appears once.
+ * But the server ALSO answers typed text with a final `user-transcription`
+ * carrying the same words — with no `logicalTurnId` to correlate on — which
+ * the SDK stores as a new message and `<ConvaiWidget/>` renders as a second
+ * "You" bubble. Every typed message showed twice; every reply once. Verified
+ * on web-sdk 1.8.0 and 1.9.0-beta.3, which filter identically.
+ *
+ * A transcription is an echo when an unmatched typed message with the same
+ * trimmed text precedes it within the window; each typed message cancels at
+ * most one. Spoken turns never produce a `user-llm-text`, so a real
+ * transcription is never dropped. An echo that streams in chunks can show
+ * its partial text until the final chunk matches — a flicker, not a duplicate.
+ */
+export function withoutTypedEchoes(messages) {
+    const pending = [];
+    return messages.filter((m) => {
+        const content = m.content.trim();
+        const at = Date.parse(m.timestamp);
+        if (m.type === 'user-llm-text') {
+            pending.push({ content, at });
+            return true;
+        }
+        if (m.type !== 'user-transcription')
+            return true;
+        const i = pending.findIndex((t) => t.content === content && at - t.at >= 0 && at - t.at <= TYPED_ECHO_WINDOW_MS);
+        if (i === -1)
+            return true;
+        pending.splice(i, 1);
+        return false;
+    });
+}
 /** Priority order matches the SDK's: speaking > listening > thinking > connected. */
 function activityOf(state) {
     if (state.isSpeaking)
@@ -89,6 +130,9 @@ export function useWidgetClient(client) {
         };
         return new Proxy(client, {
             get(target, prop, receiver) {
+                // The widget renders straight from this; see withoutTypedEchoes.
+                if (prop === 'chatMessages')
+                    return withoutTypedEchoes(Reflect.get(target, prop, target));
                 if (typeof prop === 'string' && prop in overrides)
                     return overrides[prop];
                 // Receiver is the TARGET, not the proxy, so getters and methods run

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-stg.convai.com";
+export declare const DEFAULT_BASE_URL = "https://api.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-stg.convai.com';
+export const DEFAULT_BASE_URL = 'https://api.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convai/embody",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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>",