@convai/embody 1.0.1-beta.0 → 1.1.0-beta.0

package/dist/clips/sources.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Clip files → the clips a body plays.
+ *
+ * A clip authored on the body's own skeleton plays as it is (its tracks name
+ * the body's bones). A clip from a skeleton `readRigNames` recognises —
+ * Mixamo, the Unreal mannequin, Rigify — is retargeted onto the body at load
+ * time (`retarget.ts`). Anything else is handed on unchanged, and
+ * `AnimationController.register` reports what it cannot bind.
+ *
+ * FBX files are read with three's `FBXLoader`, imported only when an `.fbx`
+ * URL is actually requested, so an app that never loads FBX does not ship it.
+ */
+import * as THREE from 'three';
+import { type RetargetOptions } from './retarget.js';
+/** A loaded animation file. */
+export interface ClipFile {
+    /** The file's scene: the GLTF `scene`, or the FBX group. */
+    root: THREE.Object3D;
+    animations: THREE.AnimationClip[];
+}
+/** True for a URL whose path ends in `.fbx` (any case, query and hash ignored). */
+export declare const isFbxUrl: (url: string) => boolean;
+/**
+ * Loads one animation file: FBX through a lazily imported `FBXLoader`,
+ * anything else through `gltf` (which carries the app's Draco decoder).
+ */
+export declare function loadClipFile(url: string, gltf: {
+    loadAsync(url: string): Promise<{
+        scene: THREE.Object3D;
+        animations: THREE.AnimationClip[];
+    }>;
+}): Promise<ClipFile>;
+/**
+ * A clip authored on `model`'s skeleton. When the body's hips bone is known
+ * (`hips`), a clip that animates it is: clip files often carry a richer rig
+ * than the body (the convai-mha-1 packs animate ~580 finger, twist and
+ * corrective bones a body may lack), so a share of matching tracks says
+ * little. Otherwise, most of its transform tracks must name the body's bones.
+ */
+export declare function targetsModel(clip: THREE.AnimationClip, modelBones: ReadonlySet<string>, hips?: string): boolean;
+/** What became of one requested clip. */
+export interface ClipNote {
+    name: string;
+    url: string;
+    /**
+     * `as-is`: on the body's skeleton. `retargeted`: from `from`'s skeleton.
+     * `not-in-file`: the file has no animation by that name (`available`).
+     * `not-loaded`: the file did not load. `foreign`: another skeleton that
+     * could not be retargeted, played as it is. `failed`: retargeting threw.
+     */
+    status: 'as-is' | 'retargeted' | 'not-in-file' | 'not-loaded' | 'foreign' | 'failed';
+    from?: string;
+    available?: string[];
+    detail?: string;
+}
+/**
+ * The clips `wanted` (clip name → file URL) asks for, from the loaded
+ * `files`, ready to register on `model`.
+ *
+ * - On the body's own skeleton: the animation with that name, or the file's
+ *   only animation, as it is.
+ * - On a recognised foreign skeleton: the animation with that name, or the
+ *   file's only animation (Mixamo names every clip `mixamo.com`), retargeted
+ *   onto the body and named as asked.
+ * - Otherwise: the animation with that name, as it is.
+ *
+ * The target is read from `model`'s bind pose once and shared by every
+ * retargeted clip.
+ */
+export declare function gatherClips(model: THREE.Object3D, files: ReadonlyMap<string, ClipFile>, wanted: ReadonlyMap<string, string>, opts?: Omit<RetargetOptions, 'name'>, notes?: ClipNote[]): THREE.AnimationClip[];

package/dist/clips/sources.js

@@ -0,0 +1,119 @@
+/**
+ * Clip files → the clips a body plays.
+ *
+ * A clip authored on the body's own skeleton plays as it is (its tracks name
+ * the body's bones). A clip from a skeleton `readRigNames` recognises —
+ * Mixamo, the Unreal mannequin, Rigify — is retargeted onto the body at load
+ * time (`retarget.ts`). Anything else is handed on unchanged, and
+ * `AnimationController.register` reports what it cannot bind.
+ *
+ * FBX files are read with three's `FBXLoader`, imported only when an `.fbx`
+ * URL is actually requested, so an app that never loads FBX does not ship it.
+ */
+import * as THREE from 'three';
+import { createAnimationSource, createTargetRig, readRigNames, retargetClip } from './retarget.js';
+/** True for a URL whose path ends in `.fbx` (any case, query and hash ignored). */
+export const isFbxUrl = (url) => /\.fbx$/i.test(url.split(/[?#]/, 1)[0]);
+/**
+ * Loads one animation file: FBX through a lazily imported `FBXLoader`,
+ * anything else through `gltf` (which carries the app's Draco decoder).
+ */
+export async function loadClipFile(url, gltf) {
+    if (isFbxUrl(url)) {
+        const { FBXLoader } = await import('three/examples/jsm/loaders/FBXLoader.js');
+        const group = await new FBXLoader().loadAsync(url);
+        return { root: group, animations: group.animations };
+    }
+    const g = await gltf.loadAsync(url);
+    return { root: g.scene, animations: g.animations };
+}
+/**
+ * A clip authored on `model`'s skeleton. When the body's hips bone is known
+ * (`hips`), a clip that animates it is: clip files often carry a richer rig
+ * than the body (the convai-mha-1 packs animate ~580 finger, twist and
+ * corrective bones a body may lack), so a share of matching tracks says
+ * little. Otherwise, most of its transform tracks must name the body's bones.
+ */
+export function targetsModel(clip, modelBones, hips) {
+    let bones = 0;
+    let hit = 0;
+    for (const t of clip.tracks) {
+        const { nodeName, propertyName } = THREE.PropertyBinding.parseTrackName(t.name);
+        if (propertyName !== 'quaternion' && propertyName !== 'position' && propertyName !== 'scale')
+            continue;
+        if (hips && nodeName === hips)
+            return true;
+        bones++;
+        if (modelBones.has(nodeName))
+            hit++;
+    }
+    return bones > 0 && hit * 2 >= bones;
+}
+/**
+ * The clips `wanted` (clip name → file URL) asks for, from the loaded
+ * `files`, ready to register on `model`.
+ *
+ * - On the body's own skeleton: the animation with that name, or the file's
+ *   only animation, as it is.
+ * - On a recognised foreign skeleton: the animation with that name, or the
+ *   file's only animation (Mixamo names every clip `mixamo.com`), retargeted
+ *   onto the body and named as asked.
+ * - Otherwise: the animation with that name, as it is.
+ *
+ * The target is read from `model`'s bind pose once and shared by every
+ * retargeted clip.
+ */
+export function gatherClips(model, files, wanted, opts = {}, notes = []) {
+    const modelBones = new Set();
+    model.traverse((o) => { if (o.isBone)
+        modelBones.add(o.name); });
+    const hips = readRigNames([...modelBones])?.fromCanon.get('Hips');
+    let target;
+    const sources = new Map();
+    const out = [];
+    for (const [name, url] of wanted) {
+        const file = files.get(url);
+        if (!file) {
+            notes.push({ name, url, status: 'not-loaded' });
+            continue;
+        }
+        const named = file.animations.find((a) => a.name === name);
+        const candidate = named ?? (file.animations.length === 1 ? file.animations[0] : undefined);
+        if (!candidate) {
+            notes.push({ name, url, status: 'not-in-file', available: file.animations.map((a) => a.name) });
+            continue;
+        }
+        if (targetsModel(candidate, modelBones, hips)) {
+            // A file's only clip is the one asked for, whatever it is called.
+            if (named)
+                out.push(named);
+            else {
+                const clip = candidate.clone();
+                clip.name = name;
+                out.push(clip);
+            }
+            notes.push({ name, url, status: 'as-is' });
+            continue;
+        }
+        if (!sources.has(file))
+            sources.set(file, createAnimationSource(file.root, file.animations));
+        const source = sources.get(file);
+        if (source && target === undefined)
+            target = createTargetRig(model);
+        if (!source || !target) {
+            // Reported by the caller (inspectCharacter), with the fix.
+            notes.push({ name, url, status: 'foreign', from: source?.names.kind, detail: source ? "the body's skeleton is not one embody can retarget onto" : 'its skeleton is neither the body\'s nor one embody recognises' });
+            if (named)
+                out.push(named);
+            continue;
+        }
+        try {
+            out.push(retargetClip(source, candidate, target, { ...opts, name }));
+            notes.push({ name, url, status: 'retargeted', from: source.names.kind });
+        }
+        catch (e) {
+            notes.push({ name, url, status: 'failed', from: source.names.kind, detail: e.message });
+        }
+    }
+    return out;
+}

package/dist/connect/session.d.ts

@@ -13,6 +13,7 @@
  * module steps aside entirely.
  */
 import { ConvaiClient, type BlendshapeQueue, type ConvaiConfig } from '@convai/web-sdk/core';
+import type { VoiceReceiver } from '../speech/voiceClock.js';
 export interface SessionOptions extends ConvaiConfig {
     /**
      * Attach an `AudioRenderer` to the room so the character is audible.
@@ -31,6 +32,11 @@ export interface SessionHandle {
     client: ConvaiClient;
     /** Lipsync frames for the turn currently being spoken. */
     readonly queue: BlendshapeQueue;
+    /**
+     * The receiver of the character's voice track, read live (it changes on
+     * reconnect), or null before one is subscribed. Lipsync follows its clock.
+     */
+    voiceReceiver(): VoiceReceiver | null;
     /** Whether this session owns the client (and so should close it). */
     readonly owned: boolean;
     dispose(): Promise<void>;
@@ -49,3 +55,8 @@ export declare function createSession(opts: SessionOptions): Promise<SessionHand
  * owns its own client's lifetime.
  */
 export declare function adoptSession(client: ConvaiClient): SessionHandle;
+/**
+ * The first subscribed remote audio track's RTCRtpReceiver: the character's
+ * voice. In a one-character session it is the only remote audio.
+ */
+export declare function voiceReceiverOf(client: Pick<ConvaiClient, 'room'>): VoiceReceiver | null;

package/dist/connect/session.js

@@ -61,6 +61,7 @@ function wrapSession(client, renderer, owned) {
         get queue() {
             return client.blendshapeQueue;
         },
+        voiceReceiver: () => voiceReceiverOf(client),
         async dispose() {
             // Idempotent: React StrictMode double-invokes cleanup, and a second
             // disconnect on an already-closed client throws.
@@ -74,3 +75,24 @@ function wrapSession(client, renderer, owned) {
         },
     };
 }
+/**
+ * The first subscribed remote audio track's RTCRtpReceiver: the character's
+ * voice. In a one-character session it is the only remote audio.
+ */
+export function voiceReceiverOf(client) {
+    let room;
+    try {
+        room = client.room;
+    }
+    catch {
+        return null;
+    }
+    for (const p of room?.remoteParticipants?.values() ?? []) {
+        for (const pub of p.audioTrackPublications?.values() ?? []) {
+            const receiver = pub.track?.receiver;
+            if (receiver && typeof receiver.getSynchronizationSources === 'function')
+                return receiver;
+        }
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -28,11 +28,25 @@ export { createCharacter } from './character/createCharacter.js';
 export type { CharacterHandle, CreateCharacterOptions } from './character/createCharacter.js';
 export { AnimationController } from './clips/animations.js';
 export type { ClipTransition } from './clips/animations.js';
+export { retargetClip, createTargetRig, createAnimationSource, detectRig, readRigNames, UPRIGHT_DEG } from './clips/retarget.js';
+export type { TargetRig, AnimationSource, RetargetOptions, RetargetReport, RigNames, RigKind } from './clips/retarget.js';
+export { loadClipFile, isFbxUrl } from './clips/sources.js';
+export type { ClipFile, ClipNote } from './clips/sources.js';
+export { inspectModel } from './inspect/inspectModel.js';
+export type { InspectModelOptions } from './inspect/inspectModel.js';
+export { formatReport } from './inspect/report.js';
+export type { CharacterReport, CharacterIssue, IssueLevel } from './inspect/report.js';
+export { matchMorphs, applyMorphMap, normalizeMorphName, ARKIT_FOR } from './inspect/morphMap.js';
+export type { MorphMatch, FaceNaming } from './inspect/morphMap.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 { createPortraitRig, placePortraitRig, keyAzimuth, PORTRAIT_TONE } from './render/portraitRig.js';
+export type { PortraitRig } from './render/portraitRig.js';
+export { applySurfaces, shadeScalp, shadeHairDepth, meanSkinColor, patchSkinShader, poreDetailTexture, LASH_MALE } from './render/surfaces.js';
+export type { SurfaceTuning, SkinTuning, SurfaceReport } from './render/surfaces.js';
 export { collectMaterials } from './decorate/types.js';
 export type { CharacterDecorator, DecoratorContext } from './decorate/types.js';
 export { Pipeline } from './character/pipeline.js';
@@ -44,6 +58,13 @@ export type { ResolvedRig, MorphBinding } from './rig/resolve.js';
 export { GazeSystem } from './motion/gaze.js';
 export type { GazeConfig } from './motion/gaze.js';
 export { EyeGazeSystem } from './motion/eyeGaze.js';
+export { EyeAim } from './motion/eyeAim.js';
+export { restHairOnShoulders } from './motion/hair.js';
+export { VoiceClock } from './speech/voiceClock.js';
+export type { VoiceReceiver } from './speech/voiceClock.js';
+export { MouthFinish } from './speech/mouthFinish.js';
+export { Expression } from './speech/expression.js';
+export type { Mood } from './speech/expression.js';
 export type { EyeGazeConfig } from './motion/eyeGaze.js';
 export { BlinkSystem } from './motion/blink.js';
 export type { BlinkConfig } from './motion/blink.js';
@@ -52,4 +73,4 @@ export type { BreathingConfig } from './motion/breathe.js';
 export { createReducedMotion } from './motion/reducedMotion.js';
 export type { ReducedMotion } from './motion/reducedMotion.js';
 export type { GazeDirection, EyeGazeDirection, GazeSource } from './motion/types.js';
-export type { UnitNormalizer } from './rig/units.js';
+export type { UnitNormalizer, UnitNormalizerOptions, Grounding } from './rig/units.js';

package/dist/index.js

@@ -25,15 +25,27 @@ export { httpResolver, pickRepresentation, DEFAULT_BASE_URL } from './resolve/re
 export { pickModelVariant, detectDevice, MORPH_UNIFORM_RESERVE } from './resolve/modelVariant.js';
 export { createCharacter } from './character/createCharacter.js';
 export { AnimationController } from './clips/animations.js';
+export { retargetClip, createTargetRig, createAnimationSource, detectRig, readRigNames, UPRIGHT_DEG } from './clips/retarget.js';
+export { loadClipFile, isFbxUrl } from './clips/sources.js';
+export { inspectModel } from './inspect/inspectModel.js';
+export { formatReport } from './inspect/report.js';
+export { matchMorphs, applyMorphMap, normalizeMorphName, ARKIT_FOR } from './inspect/morphMap.js';
 export { LipsyncSystem } from './speech/lipsync.js';
 export { compileCorrectiveMap, applyCorrectiveMap, CORRECTIVE_MAP_FORMAT } from './speech/correctiveMap.js';
 export { createUnitNormalizer } from './rig/units.js';
+export { createPortraitRig, placePortraitRig, keyAzimuth, PORTRAIT_TONE } from './render/portraitRig.js';
+export { applySurfaces, shadeScalp, shadeHairDepth, meanSkinColor, patchSkinShader, poreDetailTexture, LASH_MALE } from './render/surfaces.js';
 export { collectMaterials } from './decorate/types.js';
 export { Pipeline } from './character/pipeline.js';
 export { setLookQuat, CONVAI_MHA_1, CC4_LEGACY, CC4_BASIS, UE_BASIS, REGISTERED_PROFILES } from './rig/profile.js';
 export { resolveRig, writeMorph, REQUIRED_BONES } from './rig/resolve.js';
 export { GazeSystem } from './motion/gaze.js';
 export { EyeGazeSystem } from './motion/eyeGaze.js';
+export { EyeAim } from './motion/eyeAim.js';
+export { restHairOnShoulders } from './motion/hair.js';
+export { VoiceClock } from './speech/voiceClock.js';
+export { MouthFinish } from './speech/mouthFinish.js';
+export { Expression } from './speech/expression.js';
 export { BlinkSystem } from './motion/blink.js';
 export { BreathingSystem } from './motion/breathe.js';
 export { createReducedMotion } from './motion/reducedMotion.js';

package/dist/inspect/inspectModel.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Check a model before wiring a conversation to it: load it exactly as
+ * `createCharacter` would (same shading, morph map, clip gathering), without
+ * a connection, and return its report.
+ *
+ * ```ts
+ * const report = await inspectModel('/my-avatar.glb', { animations: { Idle: '/idle.fbx' } })
+ * console.log(formatReport(report))
+ * ```
+ */
+import { type CreateCharacterOptions } from '../character/createCharacter.js';
+import type { CharacterReport } from './report.js';
+export type InspectModelOptions = Pick<CreateCharacterOptions, 'animations' | 'morphMap' | 'dracoDecoderPath' | 'idleClip' | 'diagnostics'>;
+export declare function inspectModel(url: string, opts?: InspectModelOptions): Promise<CharacterReport>;

package/dist/inspect/inspectModel.js

@@ -0,0 +1,26 @@
+/**
+ * Check a model before wiring a conversation to it: load it exactly as
+ * `createCharacter` would (same shading, morph map, clip gathering), without
+ * a connection, and return its report.
+ *
+ * ```ts
+ * const report = await inspectModel('/my-avatar.glb', { animations: { Idle: '/idle.fbx' } })
+ * console.log(formatReport(report))
+ * ```
+ */
+import { createCharacter } from '../character/createCharacter.js';
+export async function inspectModel(url, opts = {}) {
+    const character = await createCharacter({
+        characterId: 'inspect',
+        resolver: {
+            resolve: async (characterId) => ({ characterId, avatarId: url, representations: [{ rig: 'convai-mha-1', model: [{ url }] }] }),
+        },
+        connect: false,
+        modelVariant: 'full',
+        diagnostics: false,
+        ...opts,
+    });
+    const { report } = character;
+    character.dispose();
+    return report;
+}

package/dist/inspect/morphMap.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Morph maps: a face whose blendshapes are not named as the MetaHuman stream
+ * names them, driven anyway.
+ *
+ * The stream (and so lipsync, blink and eye gaze) addresses MetaHuman
+ * expression channels, `CTRL_expressions_jawOpen` and 250 more. A model
+ * exported elsewhere carries the same shapes under other names, or similar
+ * shapes from another standard:
+ *
+ *  · renamed MetaHuman: a prefix (`head_lod0.CTRL_expressions_jawOpen`), the
+ *    short name (`jawOpen`), or Character Creator's extended set, which is
+ *    MetaHuman's channel list in snake case (`Mouth_Corner_Pull_L`);
+ *  · ARKit's 52 (Ready Player Me, Apple face capture, most VRM and CC
+ *    exports): different shapes for the same motions, mapped by meaning
+ *    (`mouthCornerPullL` → `mouthSmileLeft`), several channels onto one shape
+ *    where ARKit has one (the four funnel quadrants → `mouthFunnel`);
+ *  · visemes (`viseme_aa`, `V_Open`): mouth poses per sound. The stream sends
+ *    expression channels, not visemes, so nothing maps onto them.
+ *
+ * A map is channel short name → the model's morph name, and applying it
+ * aliases the channel's full name onto that morph in every mesh's
+ * `morphTargetDictionary`, so every system that resolves by name finds it.
+ * Names are compared ignoring case, separators, side spelling (`Left`/`L`), a
+ * namespace (`mesh.`, `mesh:`, `mesh|`), and a numbering prefix (`A25_`).
+ */
+import type * as THREE from 'three';
+/** Every MetaHuman expression channel, short name (no prefix). */
+export declare const CHANNELS: readonly string[];
+/** MetaHuman channel → the ARKit blendshape that carries the same motion. */
+export declare const ARKIT_FOR: Readonly<Record<string, string>>;
+/** A morph name reduced to what identifies it. */
+export declare function normalizeMorphName(name: string): string;
+/** Every morph name on any mesh under `root`. */
+export declare function morphNames(root: THREE.Object3D): Set<string>;
+export type FaceNaming = 'metahuman' | 'metahuman-renamed' | 'arkit' | 'visemes' | 'custom' | 'none';
+export interface MorphMatch {
+    /** Channels the model already carries under their MetaHuman names. */
+    native: number;
+    /** Channel → model morph, for the rest that can be found. */
+    map: Record<string, string>;
+    /** How each mapped channel was found. */
+    via: Record<string, 'renamed' | 'arkit'>;
+    naming: FaceNaming;
+    /** The model's viseme shapes, which the stream cannot drive. */
+    visemes: string[];
+}
+/** Find this model's shape for every MetaHuman channel it does not carry by name. */
+export declare function matchMorphs(root: THREE.Object3D): MorphMatch;
+/**
+ * Alias each channel's full MetaHuman name onto the model's morph, on every
+ * mesh carrying that morph. A name the mesh already has is never replaced.
+ * Returns the channels aliased on at least one mesh.
+ */
+export declare function applyMorphMap(root: THREE.Object3D, map: Readonly<Record<string, string>>): string[];

package/dist/inspect/morphMap.js

@@ -0,0 +1,140 @@
+import { MHA_PROFILE } from '@convai/web-sdk/lipsync-helpers';
+const PREFIX = 'CTRL_expressions_';
+/** Every MetaHuman expression channel, short name (no prefix). */
+export const CHANNELS = MHA_PROFILE.channelNames.map((n) => n.replace(PREFIX, ''));
+/** MetaHuman channel → the ARKit blendshape that carries the same motion. */
+export const ARKIT_FOR = (() => {
+    const t = {
+        jawOpen: 'jawOpen', jawLeft: 'jawLeft', jawRight: 'jawRight', jawFwd: 'jawForward',
+        mouthLeft: 'mouthLeft', mouthRight: 'mouthRight',
+    };
+    // Not mouthLipsTogether → mouthClose: the stream keeps lipsTogether at or
+    // above jawOpen (a MetaHuman coupling, harmless there because the shape
+    // only acts with the jaw), and ARKit's mouthClose seals the lips outright,
+    // so the mapped mouth pinched shut whenever it opened (measured live:
+    // mouthClose peaked at 0.80 against a 0.19 jaw on a Ready Player Me head).
+    // Closures come from mouthPress and MouthFinish's jaw instead.
+    const quad = ['UL', 'UR', 'DL', 'DR'];
+    for (const q of quad) {
+        t[`mouthFunnel${q}`] = 'mouthFunnel';
+        t[`mouthLipsPurse${q}`] = 'mouthPucker';
+        t[`mouthPress${q}`] = q.endsWith('L') ? 'mouthPressLeft' : 'mouthPressRight';
+    }
+    for (const [s, side] of [['L', 'Left'], ['R', 'Right']]) {
+        Object.assign(t, {
+            [`browDown${s}`]: `browDown${side}`,
+            [`browRaiseIn${s}`]: 'browInnerUp',
+            [`browRaiseOuter${s}`]: `browOuterUp${side}`,
+            [`eyeBlink${s}`]: `eyeBlink${side}`,
+            [`eyeWiden${s}`]: `eyeWide${side}`,
+            [`eyeSquintInner${s}`]: `eyeSquint${side}`,
+            [`eyeCheekRaise${s}`]: `cheekSquint${side}`,
+            [`eyeLookUp${s}`]: `eyeLookUp${side}`,
+            [`eyeLookDown${s}`]: `eyeLookDown${side}`,
+            [`mouthCornerPull${s}`]: `mouthSmile${side}`,
+            [`mouthCornerDepress${s}`]: `mouthFrown${side}`,
+            [`mouthDimple${s}`]: `mouthDimple${side}`,
+            [`mouthStretch${s}`]: `mouthStretch${side}`,
+            [`mouthUpperLipRaise${s}`]: `mouthUpperUp${side}`,
+            [`mouthLowerLipDepress${s}`]: `mouthLowerDown${side}`,
+            [`mouthUpperLipRollIn${s}`]: 'mouthRollUpper',
+            [`mouthLowerLipRollIn${s}`]: 'mouthRollLower',
+            [`mouthCheekBlow${s}`]: 'cheekPuff',
+            [`noseWrinkle${s}`]: `noseSneer${side}`,
+        });
+    }
+    // MetaHuman names eye look by the character's own left/right; ARKit by
+    // in (toward the nose) and out. The left eye looking left looks out.
+    Object.assign(t, {
+        eyeLookLeftL: 'eyeLookOutLeft', eyeLookRightL: 'eyeLookInLeft',
+        eyeLookLeftR: 'eyeLookInRight', eyeLookRightR: 'eyeLookOutRight',
+        jawChinRaiseDL: 'mouthShrugLower', jawChinRaiseDR: 'mouthShrugLower',
+        jawChinRaiseUL: 'mouthShrugUpper', jawChinRaiseUR: 'mouthShrugUpper',
+    });
+    return t;
+})();
+/** The 52 ARKit names, for recognising an ARKit face. */
+const ARKIT_NAMES = new Set([...Object.values(ARKIT_FOR), 'tongueOut', 'mouthClose']);
+/** A morph name reduced to what identifies it. */
+export function normalizeMorphName(name) {
+    return name
+        .replace(/^.*[.:|]/, '') // namespace
+        .replace(/^[A-Za-z]\d+_/, '') // numbering, as A25_Jaw_Open
+        .replace(/^CTRL_expressions_?/i, '')
+        .replace(/^blendShape\d*_?/i, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]/g, '')
+        .replace(/left/g, 'l')
+        .replace(/right/g, 'r');
+}
+/** Every morph name on any mesh under `root`. */
+export function morphNames(root) {
+    const out = new Set();
+    root.traverse((o) => {
+        const dict = o.morphTargetDictionary;
+        if (dict)
+            for (const k of Object.keys(dict))
+                out.add(k);
+    });
+    return out;
+}
+/** Find this model's shape for every MetaHuman channel it does not carry by name. */
+export function matchMorphs(root) {
+    const names = morphNames(root);
+    const byNorm = new Map();
+    for (const n of names)
+        if (!byNorm.has(normalizeMorphName(n)))
+            byNorm.set(normalizeMorphName(n), n);
+    const map = {};
+    const via = {};
+    let native = 0;
+    for (const c of CHANNELS) {
+        if (names.has(PREFIX + c)) {
+            native++;
+            continue;
+        }
+        const direct = byNorm.get(normalizeMorphName(c));
+        if (direct) {
+            map[c] = direct;
+            via[c] = 'renamed';
+            continue;
+        }
+        const arkit = ARKIT_FOR[c] && byNorm.get(normalizeMorphName(ARKIT_FOR[c]));
+        if (arkit) {
+            map[c] = arkit;
+            via[c] = 'arkit';
+        }
+    }
+    const visemes = [...names].filter((n) => /^(viseme_|V_)/i.test(n.replace(/^.*[.:|]/, '')));
+    const arkitHits = [...ARKIT_NAMES].filter((a) => byNorm.has(normalizeMorphName(a))).length;
+    const renamed = Object.values(via).filter((v) => v === 'renamed').length;
+    const naming = names.size === 0 ? 'none'
+        : native >= 100 ? 'metahuman'
+            : renamed >= 60 ? 'metahuman-renamed'
+                : arkitHits >= 30 ? 'arkit'
+                    : visemes.length > 0 && visemes.length * 2 >= names.size ? 'visemes'
+                        : 'custom';
+    return { native, map, via, naming, visemes };
+}
+/**
+ * Alias each channel's full MetaHuman name onto the model's morph, on every
+ * mesh carrying that morph. A name the mesh already has is never replaced.
+ * Returns the channels aliased on at least one mesh.
+ */
+export function applyMorphMap(root, map) {
+    const done = new Set();
+    root.traverse((o) => {
+        const dict = o.morphTargetDictionary;
+        if (!dict)
+            return;
+        for (const [channel, morph] of Object.entries(map)) {
+            const full = channel.startsWith(PREFIX) ? channel : PREFIX + channel;
+            const index = dict[morph];
+            if (index === undefined || dict[full] !== undefined)
+                continue;
+            dict[full] = index;
+            done.add(channel.replace(PREFIX, ''));
+        }
+    });
+    return [...done];
+}

package/dist/inspect/report.d.ts

@@ -0,0 +1,88 @@
+/**
+ * What a loaded character can and cannot do, said to the developer who
+ * brought it, with the config that fixes what can be fixed.
+ *
+ * Embody drives a body by names: bones for gaze and breathing, MetaHuman
+ * expression channels for lipsync, blink and eye gaze, clip tracks for
+ * animation. A model from anywhere else loads and renders whatever its names
+ * are, and the parts that do not match simply never move. That failure is
+ * silent, so this says it: once at load, as `handle.report`, and on the
+ * console when anything is wrong.
+ *
+ * Levels: `error`, a core behaviour cannot work (no mouth shapes, a clip that
+ * landed on nothing); `warning`, it works partly or not at all for a part
+ * (no blink, no gaze bones); `info`, what was done for it (a morph map
+ * applied, clips retargeted).
+ */
+import * as THREE from 'three';
+import type { ClipNote } from '../clips/sources.js';
+import { type ResolvedRig } from '../rig/resolve.js';
+import { type FaceNaming, type MorphMatch } from './morphMap.js';
+export type IssueLevel = 'error' | 'warning' | 'info';
+export interface CharacterIssue {
+    level: IssueLevel;
+    area: 'face' | 'skeleton' | 'animation';
+    message: string;
+    /** Config or a change to the file that fixes it, when there is one. */
+    fix?: string;
+}
+export interface CharacterReport {
+    /** No errors: everything embody needs was found or mapped. */
+    ok: boolean;
+    face: {
+        /** Morph targets across the model's meshes (distinct names). */
+        morphTargets: number;
+        naming: FaceNaming;
+        /** MetaHuman channels the face answers to, natively or through the map. */
+        channels: {
+            bound: number;
+            of: number;
+        };
+        /** Speech motions, and whether the face can make each. */
+        mouth: Record<string, boolean>;
+        blink: boolean;
+        eyeLook: boolean;
+        /** The morph map in effect (channel → the model's morph name). */
+        morphMap: Record<string, string>;
+    };
+    skeleton: {
+        kind: 'convai-mha-1' | 'unreal' | 'mixamo' | 'rigify' | 'character-creator' | 'unknown' | 'none';
+        bones: number;
+        /** Bones gaze and breathing drive that the model lacks. */
+        missing: string[];
+    };
+    animations: {
+        clips: (ClipNote & {
+            tracks?: number;
+            dropped?: number;
+        })[];
+        /** The clip playing at rest, or null (the body holds its bind pose). */
+        idle: string | null;
+    };
+    issues: CharacterIssue[];
+}
+export interface InspectInput {
+    root: THREE.Object3D;
+    rig: ResolvedRig;
+    match: MorphMatch;
+    /** The map applied, and whether embody chose it (`auto`) or the app passed it. */
+    morphMap: {
+        map: Record<string, string>;
+        source: 'auto' | 'app' | 'off';
+        unknown: string[];
+    };
+    clipNotes: ClipNote[];
+    registered: {
+        name: string;
+        kept: number;
+        dropped: number;
+    }[];
+    idle: string | null;
+    /** Clips taken from the model file itself because none were declared. */
+    embedded: number;
+    /** `idleClip` as the app passed it. */
+    idleRequested?: string;
+}
+export declare function inspectCharacter(input: InspectInput): CharacterReport;
+/** The report as console text: a summary line, then each issue with its fix. */
+export declare function formatReport(report: CharacterReport, label?: string): string;