@chatlychat/world 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# @chatlychat/world
+
+## 0.2.0 — 2026-10-26
+
+Not yet published.
+
+- VRM avatars. An avatar with `format: 'vrm'`, or a glTF carrying the `VRM` / `VRMC_vrm` extension, loads through `@pixiv/three-vrm`'s `VRMLoaderPlugin`. `@pixiv/three-vrm` (`^3.5.5`) is an OPTIONAL peer dependency, loaded by dynamic import; a glTF-only host does not install or bundle it. Missing, it is a `WorldError` with code `missing_peer` naming the package. Bundlers: pass `loadVrm: () => import('@pixiv/three-vrm')`.
+- The mouth on a VRM avatar is driven through the `aa` / `ih` / `ou` / `ee` / `oh` expression bindings (`VISEME_TO_VRM`), not morph targets.
+- `embodiment.expression` maps to the `happy`, `sad` and `surprised` presets (`EXPRESSION_TO_VRM`); gestures stay clips. Automatic blink (off under reduced motion).
+- `lookAt` drives VRM's `lookAt.target` and the humanoid head bone. `vrm.update(delta)` runs every frame.
+- `ModelLoader` takes an optional second argument `{ format }`; `LoadedModel` has an optional `vrm`; `WorldErrorCode` gains `missing_peer`; new `loadVrm` option and `gltfLoader({ loadVrm })`.
+- The glTF morph-target path is unchanged.
+
+## 0.1.0 — 2026-10-25
+
+Unpublished. The first version: a Chatly conversation rendered into your three.js scene.
+
+- `createWorld({ conversation, camera, … })` → `world.root` (add it to your scene) and `world.update(dt)` (call it from your loop).
+- Picks: a `card_grid` laid out as `arc`, `shelf`, `wall` or `table`; `card.model` loaded with three's `GLTFLoader` (scale and anchor honoured); pedestal, beam, price label and selection ring from `worldTheme`. Tapping a pick selects it in the conversation (a postback) and the selection is shared with the host.
+- Speech bubbles anchored to a speaker (never head-locked), scaled by distance, with a typing indicator.
+- A world-space panel and composer; `fixed`, `lazy` and `wrist` follow; a `locked` placement is honoured as `lazy`.
+- Hand, controller (`attachController`), gaze-dwell (`attachGaze`) and pointer (`pickAtPointer`) picking. The host keeps input.
+- An embodied agent body: avatar model, `idle`/`listening`/`thinking`/`speaking` clips, expression and `lookAt` cues, viseme-driven mouth when a message carries `metadata.visemes`.
+- Host capabilities: `world.walk_to`, `avatar.try_on`, `scene.highlight`, `scene.spawn` and custom names, dispatched to handlers you register; bot-fired invocations are answered into the thread; every action keeps its `equivalent`.
+- Replaceable `renderCard`, `renderPick`, `renderBubble`, `renderPanel`, `renderComposer`, `renderAgent`, with a named, versioned object contract (`WORLD_CONTRACT`).
+- `worldTheme` applied to panel, type, cards, speech, agent, sound cues and motion; reduced motion always wins.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chatly Engineering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# @chatlychat/world
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Chatly conversation, rendered into **your** three.js scene. You keep the scene,
+the avatars, the input and the wayfinding; this draws what the conversation
+contains and sends the visitor's taps back.
+
+```bash
+pnpm add @chatlychat/world @chatlychat/core three
+```
+
+`three` (>= 0.160) and `@chatlychat/core` are peer dependencies. The only other
+is **optional**: `@pixiv/three-vrm`, for VRM avatars (see below). Nothing here
+touches the web widget.
+
+```ts
+import { createChatlyCore } from '@chatlychat/core';
+import { createWorld } from '@chatlychat/world';
+import { Clock } from 'three';
+
+const core = createChatlyCore({ publicId: 'pub_xxx', socket: io });
+const conversation = await core.startConversation('Do you have this in blue?');
+
+const world = createWorld({
+  conversation,
+  camera, // the camera (or XR camera) the visitor sees through
+  theme: core.worldTheme, // the channel's worldTheme
+  scene: 'light', // what your scene's light is, for colorScheme "auto"
+  reducedMotion: () => false, // return your viewer's reduced-motion setting
+  presences: { '*': { name: 'Mia', avatar: { url: 'https://cdn.example/mia.glb' } } },
+});
+scene.add(world.root);
+
+const clock = new Clock();
+renderer.setAnimationLoop(() => {
+  world.update(clock.getDelta()); // seconds
+  renderer.render(scene, camera);
+});
+```
+
+## What it draws
+
+- **Picks.** A `card_grid` with `placement` `arc`, `shelf`, `wall` or `table`;
+  a card with a `model` becomes a glTF object (`scale` and `anchor` honoured)
+  with the theme's pedestal, beam, price label and selection ring. Tapping one
+  selects it: a postback to the conversation, a ring on the card, the object in
+  hand. `world.selection` is shared — selecting from your own UI is the same event
+  (`await world.select(key)`; keys from `world.cardKeys()`).
+- **Speech bubbles** over a speaker, turned to the viewer and scaled by distance —
+  positioned from the speaker, never from the camera. Typing indicator per
+  `typingLook`. History is not replayed as speech.
+- **A world-space panel and composer.** Never head-locked: `fixed`, `lazy` (an
+  eased follow with a dead zone) or `wrist` (carried on a controller you pass).
+  `follow: 'locked'` in a placement is honoured as `lazy`.
+  Typing is yours: fill `world.composer.setDraft(text)` from your keyboard, mic or
+  overlay (`onComposeRequest` fires when the field is pressed), then it sends.
+- **An agent body**: avatar model (glTF or VRM; `usdz` is refused with a typed error),
+  `idle`/`listening`/`thinking`/`speaking` clips from `presence.clips`, one-shot
+  `expressions`, `lookAt` cues resolved through `anchors.resolve(ref)`, and a mouth
+  driven by `message.metadata.visemes` (`[{ t: ms, v: 'aa', w?: 0..1 }]`) when
+  present. `presence.idle` and `personalSpaceMetres` are yours to honour.
+
+## VRM avatars
+
+An avatar whose `format` is `vrm` (or whose file carries the VRM extension) is
+loaded through `@pixiv/three-vrm`'s `VRMLoaderPlugin`. The package is an
+**optional** peer dependency: a glTF-only host does not install it, and nothing
+of it is in your bundle.
+
+```bash
+npm install @pixiv/three-vrm   # ^3.5.5; VRM avatars only
+```
+
+If you bundle, hand the import over so your bundler can see the package:
+
+```ts
+createWorld({ conversation, camera, loadVrm: () => import('@pixiv/three-vrm') });
+```
+
+Without it installed, a VRM avatar reports a `WorldError` with code `missing_peer`
+to `onError`, names the package, and the placeholder body stays.
+
+**Mouth.** Chatly visemes drive VRM's five expression bindings
+(`aa`, `ih`, `ou`, `ee`, `oh`) instead of morph targets. Names are case-insensitive
+and a `viseme_` prefix is ignored.
+
+| Chatly viseme                 | VRM expression | Opening                    |
+| ----------------------------- | -------------- | -------------------------- |
+| `aa`                          | `aa`           | full                       |
+| `ih`, `I`                     | `ih`           | full                       |
+| `ou`, `U`                     | `ou`           | full                       |
+| `ee`, `E`                     | `ee`           | full                       |
+| `oh`, `O`                     | `oh`           | full                       |
+| `FF`, `TH`, `SS`              | `ih`           | 0.4, 0.5, 0.5              |
+| `DD`, `kk`                    | `aa`           | 0.4                        |
+| `CH`, `RR`                    | `ou`           | 0.5                        |
+| `nn`                          | `ih`           | 0.3                        |
+| `PP`, `sil`, anything unknown | none           | closed (all five set to 0) |
+
+The opening is multiplied by the track's own `w`. The five are always set
+together, so a released mouth closes.
+
+**Face.** `embodiment.expression` maps to a VRM preset where one exists:
+
+| Expression  | Preset      | Weight |
+| ----------- | ----------- | ------ |
+| `smile`     | `happy`     | 0.7    |
+| `laugh`     | `happy`     | 1      |
+| `surprised` | `surprised` | 1      |
+| `concerned` | `sad`       | 0.6    |
+
+The face eases in over 0.12 s, holds 2.5 s and fades over 0.5 s. `nod`,
+`shake_head`, `point`, `wave`, `shrug` and `think` are gestures with no preset:
+they play only as your own clip from `presence.expressions`, as on a glTF avatar.
+A preset and a host clip both play if both exist. No Chatly expression is
+`angry` or `relaxed`, so those presets are never driven. `blink` is automatic
+(every 4 s) and off under reduced motion; there, a face is applied and removed
+without easing.
+
+**Gaze.** A `lookAt` cue sets VRM's `lookAt.target` (eyes) and turns the humanoid
+`head` bone toward it, clamped to about 20 degrees up or down and 34 degrees sideways.
+The body still turns on the spot as before. **Clips.** State and expression clips
+in the file play on the model as they do for glTF; the SDK does not retarget
+clips from other rigs (such as separate VRMA files) — load those yourself.
+`vrm.update(delta)` runs every `world.update`.
+
+The glTF morph-target path (`v`, `viseme_v`, `Viseme_v`) is unchanged.
+
+## Input
+
+The host owns input; the world only knows which of its objects a ray hit.
+
+```ts
+world.attachController(xrController); // your XR controller object: trigger or hand pinch
+const gaze = world.attachGaze({ dwellMs: 1500 }); // call gaze.update(ms) per frame
+const hit = world.pickAtPointer(ndcX, ndcY); // mouse / touch
+if (hit) world.activate(hit);
+```
+
+## Host capabilities
+
+```ts
+world.capabilities.register(
+  'world.walk_to', // also: avatar.try_on, scene.highlight, scene.spawn, or your own
+  async () => true, // do your own movement here; return false or throw to refuse
+  { equivalent: { kind: 'text', text: 'The shop is on level 2.' }, unprompted: true },
+);
+await core.setSurface(world.capabilities.surface({ room: 'atrium' }));
+```
+
+A bot-fired invocation reaches your handler and is answered into the thread
+(`done`, or `failed` + `refused: true`). The `equivalent` is required and is
+announced (`announce`) whenever the handler is missing, refuses or throws.
+
+## Replaceable renderers
+
+`renderCard`, `renderPick`, `renderBubble`, `renderPanel`, `renderComposer`,
+`renderAgent` — each receives the typed block (or message, or agent view), the
+resolved `theme` and `placement`, `reducedMotion`, and for blocks the Chatly
+handlers `select`, `press` and `react`. Return any `Object3D`.
+
+```ts
+createWorld({ …, renderers: { contract: 1, renderCard: (p) => yourShelfMesh } });
+```
+
+The world names an override's node `cl3-card` etc. if you did not, and routes
+taps on it to selection (set `userData.cl3Handled = true` to take taps yourself).
+Object names and the renderer set are versioned in `WORLD_CONTRACT`; pinning
+`contract: N` fails loudly on a world that speaks another N.
+
+## Theme and reduced motion
+
+Every `worldTheme` token is applied: panel material/colour/emissive, type
+(`fontUrl`, weight, outline, `textScale`), cards, speech, agent, sound (as
+`onSound` cues — you play them) and motion. `world.setTheme`, `setScene` and
+`setReducedMotion` re-apply live. **Reduced motion always wins:** entrances and
+trails off, lazy follow and gaze snap, expression clips skipped, clips held on
+their first frame.
+
+## Tests without WebGL
+
+three builds a scene graph with no GL context, so you can test your integration in
+Node: see `src/world.spec.ts` for a fake conversation and the assertions.
+`pnpm --filter @chatlychat/world example` runs a scripted demo.
+
+MIT.

package/dist/agent.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The embodied agent's body: a model, four state clips, one-shot expressions,
+ * a gaze and a mouth.
+ *
+ * What it does NOT do is walk. `presence.idle` (`stand`/`wander`/`follow`) and
+ * `personalSpaceMetres` are facts about where the agent may go, and wayfinding
+ * is the host's — they are readable on `presence` and honoured by nobody here.
+ *
+ * Reduced motion always wins: state clips are held on their first frame (a
+ * pose, not a loop), expression one-shots are not played, gaze snaps rather
+ * than turns, and there is no crossfade. The mouth still follows visemes —
+ * speech is not decorative motion, and a mouth that never moves on a speaking
+ * agent would read as a broken one.
+ */
+import { Group, Vector3, type Camera, type Object3D } from 'three';
+import { type ModelLoader } from './model.js';
+import { type VisemeTrack } from './visemes.js';
+import type { AgentExpression, AgentPresenceState, AgentWorldPresence } from '@chatlychat/core';
+import type { ResolvedWorldTheme } from '@chatlychat/core';
+export type GazeTarget = Object3D | Vector3 | 'visitor' | null;
+export declare class AgentBody {
+    private theme;
+    private readonly loadModel;
+    private readonly onError;
+    readonly root: Group;
+    presence: AgentWorldPresence | null;
+    reduced: boolean;
+    private model;
+    private mixer;
+    private clips;
+    private current;
+    private avatarUrl;
+    private tag;
+    private gaze;
+    private track;
+    private trackStart;
+    private morphs;
+    private rig;
+    private lastState;
+    private refused;
+    constructor(theme: ResolvedWorldTheme, loadModel: ModelLoader, onError: (e: unknown) => void, reduced: boolean);
+    get hasModel(): boolean;
+    get activeClip(): string | null;
+    setTheme(theme: ResolvedWorldTheme): void;
+    private placeholder;
+    setPresence(presence: AgentWorldPresence | null): void;
+    private setTag;
+    private swapModel;
+    private action;
+    /** Move to the state's clip — the host's own name for it, from `presence.clips`. */
+    setState(state: AgentPresenceState): void;
+    /** Play a one-shot expression clip. Skipped entirely under reduced motion. */
+    playExpression(clipName: string | null): boolean;
+    /** A face for a cue, on a VRM avatar. False for a gesture or a glTF avatar: the host's clip is all there is. */
+    express(e: AgentExpression | null): boolean;
+    get isVrm(): boolean;
+    lookAt(target: GazeTarget): void;
+    setVisemes(track: VisemeTrack | null, nowMs: number): void;
+    private applyViseme;
+    update(dtMs: number, nowMs: number, camera: Camera): void;
+    dispose(): void;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAIL,KAAK,EAIL,OAAO,EAEP,KAAK,MAAM,EACX,KAAK,QAAQ,EACd,MAAM,OAAO,CAAC;AAEf,OAAO,EAAY,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAKxD,OAAO,EAA2B,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAGzE,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAK3D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC;AAO/D,qBAAa,SAAS;IAmBlB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IApB1B,SAAgB,IAAI,QAAe;IAC5B,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAQ;IAC3C,OAAO,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,GAAG,CAAyB;IACpC,OAAO,CAAC,IAAI,CAAoB;IAChC,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,GAAG,CAAuB;IAClC,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,OAAO,CAAuB;gBAG5B,KAAK,EAAE,kBAAkB,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,EAC9C,OAAO,EAAE,OAAO;IAOlB,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED,IAAW,UAAU,IAAI,MAAM,GAAG,IAAI,CAErC;IAEM,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAIhD,OAAO,CAAC,WAAW;IAWZ,WAAW,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,GAAG,IAAI;IAiC7D,OAAO,CAAC,MAAM;IAad,OAAO,CAAC,SAAS;IAkCjB,OAAO,CAAC,MAAM;IAQd,oFAAoF;IAC7E,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAiBhD,8EAA8E;IACvE,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAYvD,gHAAgH;IACzG,OAAO,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,GAAG,OAAO;IAIlD,IAAW,KAAK,IAAI,OAAO,CAE1B;IAEM,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAIhC,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAQjE,OAAO,CAAC,WAAW;IA0BZ,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAiCzD,OAAO,IAAI,IAAI;CAIvB"}

package/dist/agent.js

@@ -0,0 +1,251 @@
+/**
+ * The embodied agent's body: a model, four state clips, one-shot expressions,
+ * a gaze and a mouth.
+ *
+ * What it does NOT do is walk. `presence.idle` (`stand`/`wander`/`follow`) and
+ * `personalSpaceMetres` are facts about where the agent may go, and wayfinding
+ * is the host's — they are readable on `presence` and honoured by nobody here.
+ *
+ * Reduced motion always wins: state clips are held on their first frame (a
+ * pose, not a loop), expression one-shots are not played, gaze snaps rather
+ * than turns, and there is no crossfade. The mouth still follows visemes —
+ * speech is not decorative motion, and a mouth that never moves on a speaking
+ * agent would read as a broken one.
+ */
+import { AnimationClip, AnimationMixer, CapsuleGeometry, Group, LoopOnce, Mesh, SphereGeometry, Vector3, } from 'three';
+import { fitModel } from './model.js';
+import { wrapAngle } from './panel.js';
+import { createTextMesh } from './text.js';
+import { accentMaterial } from './theme-apply.js';
+import { WORLD_CONTRACT, WorldError } from './types.js';
+import { morphNamesFor, visemeAt } from './visemes.js';
+import { gazePoint, VrmRig } from './vrm.js';
+const TURN_RATE = 6;
+const FADE_S = 0.25;
+export class AgentBody {
+    theme;
+    loadModel;
+    onError;
+    root = new Group();
+    presence = null;
+    reduced;
+    model = null;
+    mixer = null;
+    clips = [];
+    current = null;
+    avatarUrl = null;
+    tag = null;
+    gaze = null;
+    track = null;
+    trackStart = 0;
+    morphs = [];
+    rig = null;
+    lastState = null;
+    refused = null;
+    constructor(theme, loadModel, onError, reduced) {
+        this.theme = theme;
+        this.loadModel = loadModel;
+        this.onError = onError;
+        this.reduced = reduced;
+        this.root.name = WORLD_CONTRACT.objects.agent;
+        this.root.add(this.placeholder());
+    }
+    get hasModel() {
+        return this.model !== null;
+    }
+    get activeClip() {
+        return this.current?.getClip().name ?? null;
+    }
+    setTheme(theme) {
+        this.theme = theme;
+    }
+    placeholder() {
+        const g = new Group();
+        g.name = 'cl3-agent-placeholder';
+        const body = new Mesh(new CapsuleGeometry(0.2, 0.7, 4, 12), accentMaterial(this.theme));
+        body.position.y = 0.55;
+        const head = new Mesh(new SphereGeometry(0.17, 16, 12), accentMaterial(this.theme));
+        head.position.y = 1.3;
+        g.add(body, head);
+        return g;
+    }
+    setPresence(presence) {
+        this.presence = presence;
+        this.setTag(presence === null ? null : (presence.nameTag ?? presence.name));
+        const a = presence?.avatar;
+        if (a?.format === 'usdz' && this.refused !== a.url) {
+            this.refused = a.url;
+            this.onError(new WorldError('unsupported_format', 'usdz avatars are not loadable by three.js; showing the placeholder'));
+        }
+        const url = a !== undefined && a.format !== 'usdz' ? a.url : null;
+        if (url === this.avatarUrl) {
+            return;
+        }
+        this.avatarUrl = url;
+        if (url === null || a === undefined) {
+            this.swapModel(null, []);
+            return;
+        }
+        this.loadModel(url, a.format === undefined ? undefined : { format: a.format }).then((m) => {
+            if (this.avatarUrl === url) {
+                this.swapModel(fitModel(m.scene, a.scale ?? 1, a.anchor ?? 'base'), m.animations, m.vrm ?? null);
+            }
+        }, this.onError);
+    }
+    setTag(text) {
+        if (this.tag !== null) {
+            this.root.remove(this.tag);
+            this.tag = null;
+        }
+        if (text !== null) {
+            this.tag = createTextMesh(text, this.theme, { maxWidthMetres: 0.8, size: 0.8 });
+            this.tag.name = 'cl3-agent-nametag';
+            this.tag.position.y = 1.75;
+            this.root.add(this.tag);
+        }
+    }
+    swapModel(model, clips, vrm = null) {
+        this.mixer?.stopAllAction();
+        this.mixer = null;
+        this.current = null;
+        for (const c of [...this.root.children]) {
+            if (c !== this.tag) {
+                this.root.remove(c);
+            }
+        }
+        this.model = model;
+        this.clips = clips;
+        this.morphs = [];
+        this.rig = vrm === null || model === null ? null : new VrmRig(vrm, this.reduced);
+        if (model === null) {
+            this.root.add(this.placeholder());
+            return;
+        }
+        this.root.add(model);
+        model.traverse((o) => {
+            if (o.morphTargetDictionary !== undefined) {
+                this.morphs.push(o);
+            }
+        });
+        this.mixer = new AnimationMixer(model);
+        // The state was set before the model arrived; its clip could not play then.
+        if (this.lastState !== null) {
+            this.setState(this.lastState);
+        }
+    }
+    action(name) {
+        if (this.mixer === null || name === null || name === undefined) {
+            return null;
+        }
+        const clip = AnimationClip.findByName([...this.clips], name);
+        return clip === null ? null : this.mixer.clipAction(clip);
+    }
+    /** Move to the state's clip — the host's own name for it, from `presence.clips`. */
+    setState(state) {
+        this.lastState = state;
+        const next = this.action(this.presence?.clips?.[state]);
+        if (next === null || next === this.current) {
+            return;
+        }
+        next.reset();
+        next.play();
+        if (this.reduced) {
+            next.paused = true; // a held pose, not a loop
+            this.current?.stop();
+        }
+        else if (this.current !== null) {
+            next.crossFadeFrom(this.current, FADE_S, false);
+        }
+        this.current = next;
+    }
+    /** Play a one-shot expression clip. Skipped entirely under reduced motion. */
+    playExpression(clipName) {
+        const a = this.reduced ? null : this.action(clipName);
+        if (a === null) {
+            return false;
+        }
+        a.reset();
+        a.setLoop(LoopOnce, 1);
+        a.clampWhenFinished = true;
+        a.play();
+        return true;
+    }
+    /** A face for a cue, on a VRM avatar. False for a gesture or a glTF avatar: the host's clip is all there is. */
+    express(e) {
+        return this.rig?.express(e) ?? false;
+    }
+    get isVrm() {
+        return this.rig !== null;
+    }
+    lookAt(target) {
+        this.gaze = target;
+    }
+    setVisemes(track, nowMs) {
+        this.track = track;
+        this.trackStart = nowMs;
+        if (track === null) {
+            this.applyViseme(null, 0);
+        }
+    }
+    applyViseme(v, w) {
+        if (this.rig !== null) {
+            this.rig.setMouth(v, w);
+            return;
+        }
+        for (const m of this.morphs) {
+            const dict = m.morphTargetDictionary;
+            const inf = m.morphTargetInfluences;
+            if (dict === undefined || inf === undefined) {
+                continue;
+            }
+            // Zero every viseme-ish target first so a released mouth closes.
+            for (const [name, idx] of Object.entries(dict)) {
+                if (/^(viseme_|Viseme_)/.test(name) || ['aa', 'ih', 'ou', 'ee', 'oh'].includes(name)) {
+                    inf[idx] = 0;
+                }
+            }
+            if (v !== null) {
+                const hit = morphNamesFor(v).find((n) => dict[n] !== undefined);
+                if (hit !== undefined) {
+                    inf[dict[hit]] = w;
+                }
+            }
+        }
+    }
+    update(dtMs, nowMs, camera) {
+        this.mixer?.update(dtMs / 1000);
+        if (this.track !== null) {
+            const e = visemeAt(this.track, nowMs - this.trackStart);
+            this.applyViseme(e?.v ?? null, e?.w ?? 0);
+        }
+        if (this.gaze !== null) {
+            const here = this.root.getWorldPosition(new Vector3());
+            const at = this.gaze === 'visitor'
+                ? camera.getWorldPosition(new Vector3())
+                : this.gaze instanceof Vector3
+                    ? this.gaze
+                    : this.gaze.getWorldPosition(new Vector3());
+            const want = Math.atan2(at.x - here.x, at.z - here.z);
+            const err = wrapAngle(want - this.root.rotation.y);
+            const step = TURN_RATE * (dtMs / 1000);
+            this.root.rotation.y =
+                this.reduced || Math.abs(err) <= step ? want : this.root.rotation.y + Math.sign(err) * step;
+        }
+        if (this.rig !== null) {
+            this.rig.reduced = this.reduced;
+            this.rig.gazeAt(this.root, gazePoint(this.gaze, camera), dtMs / 1000);
+            this.rig.update(dtMs / 1000);
+        }
+        if (this.tag !== null) {
+            // The tag turns to the viewer regardless of where the body faces.
+            const cam = camera.getWorldPosition(new Vector3());
+            const t = this.tag.getWorldPosition(new Vector3());
+            this.tag.rotation.y = Math.atan2(cam.x - t.x, cam.z - t.z) - this.root.rotation.y;
+        }
+    }
+    dispose() {
+        this.mixer?.stopAllAction();
+        this.root.removeFromParent();
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/bubble.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Speech bubbles, anchored to a speaker in space.
+ *
+ * A bubble is positioned from its SPEAKER'S world position — never from the
+ * camera, so it cannot be head-locked — and only turned to face the viewer.
+ * Its size grows with distance (clamped) so type stays legible across a room,
+ * which is why the text itself is built at one size and the whole bubble is
+ * scaled.
+ */
+import { Group, Vector3, type Camera, type Object3D } from 'three';
+import type { BubbleRenderProps, ConversationMessage, ResolvedWorldTheme } from '@chatlychat/core';
+export declare const MAX_BUBBLES = 3;
+/** Uniform scale for a bubble `distance` metres from the viewer. */
+export declare const bubbleScale: (distance: number) => number;
+export declare function defaultBubble(props: BubbleRenderProps): Object3D;
+/** The typing indicator: three dots, one pulsing dot, or nothing (`avatar`/`none` live on the body). */
+export declare function createTyping(theme: ResolvedWorldTheme): Group;
+/** Bob or pulse the dots. With reduced motion they sit still: a static ellipsis still says "typing". */
+export declare function animateTyping(typing: Object3D, nowMs: number, reduced: boolean): void;
+/** World-space point above a speaker's head. */
+export declare function headPoint(speaker: Object3D): Vector3;
+export interface LiveBubble {
+    readonly messageId: string;
+    readonly speaker: Object3D;
+    node: Object3D;
+    body: string;
+    readonly bornAt: number;
+}
+/**
+ * Re-anchor `node` over `speaker`: stack slot `slot` above the head, turned to
+ * the camera, scaled by distance. Called every frame, so a walking speaker
+ * carries its bubble.
+ */
+export declare function anchorBubble(node: Object3D, speaker: Object3D, camera: Camera, slot: number, parent: Object3D): void;
+export declare const speakerKind: (m: ConversationMessage) => "visitor" | "agent" | null;
+//# sourceMappingURL=bubble.d.ts.map

package/dist/bubble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bubble.d.ts","sourceRoot":"","sources":["../src/bubble.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAGL,KAAK,EAGL,OAAO,EACP,KAAK,MAAM,EACX,KAAK,QAAQ,EACd,MAAM,OAAO,CAAC;AAMf,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAOnG,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B,oEAAoE;AACpE,eAAO,MAAM,WAAW,aAAc,MAAM,KAAG,MACwB,CAAC;AAExE,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,GAAG,QAAQ,CAwBhE;AAED,wGAAwG;AACxG,wBAAgB,YAAY,CAAC,KAAK,EAAE,kBAAkB,GAAG,KAAK,CAW7D;AAED,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAiBrF;AAED,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAKpD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,QAAQ,GACf,IAAI,CAUN;AAED,eAAO,MAAM,WAAW,MAAO,mBAAmB,KAAG,SAAS,GAAG,OAAO,GAAG,IAK/D,CAAC"}