@lovelace_lol/polymer 0.0.7 → 0.0.8

package/dist/index.d.ts

@@ -1,14 +1,523 @@
+// This hand-authored declaration file is package source. `pnpm build` copies it
+// into dist/ beside the generated ClojureScript artifacts.
 import type {
-  Embody,
-  EmbodyRuntime,
-  HairAppearanceState,
-  HairColorAppearance,
-  HairPhysicsRuntimeConfig,
-  HairPhysicsRuntimeConfigUpdate,
-  MeshInfo,
-  Profile,
-} from '@lovelace_lol/embody';
-import type { Object3D } from 'three';
+  AnimationClip,
+  Camera,
+  ColorRepresentation,
+  Mesh,
+  Object3D,
+  PerspectiveCamera,
+  Scene,
+  Texture,
+  Vector3,
+  WebGLRenderer,
+} from 'three';
+import type { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import type { ThreeModelReferencePose as EmbodyModelReferencePose } from '@lovelace_lol/embody/three';
+export type ThreeModelReferencePose = EmbodyModelReferencePose;
+import type {
+  CharacterSceneRenderer,
+  CharacterSceneBackend,
+  DefaultCharacterSceneAsyncOptions,
+  ReadyDefaultCharacterScene,
+  DefaultCharacterSceneRuntime,
+  DefaultCharacterSceneRuntimeOptions,
+  CharacterSceneRenderingController,
+} from '@lovelace_lol/embody/three';
+export type {
+  CharacterSceneRendererPreference,
+  CharacterSceneRenderer,
+  CharacterSceneBackend,
+  DefaultCharacterSceneAsyncOptions,
+  ReadyDefaultCharacterScene,
+  DefaultCharacterSceneRuntime,
+  DefaultCharacterSceneRuntimeOptions,
+  CharacterSceneRenderingSettings,
+  CharacterSceneRenderingStatus,
+  CharacterSceneRenderingSnapshot,
+  CharacterSceneRenderingController,
+  CharacterSceneRendererLease,
+} from '@lovelace_lol/embody/three';
+
+
+/** Capture before playback or profile application; retain for engine recreation. */
+export declare function captureModelReferencePose(model: Object3D): ThreeModelReferencePose;
+
+export type PresetType = 'cc4' | 'fish' | string;
+export type BoneAxisKey = 'pitch' | 'yaw' | 'roll';
+export type BoneAxisDirection = 'negative' | 'positive';
+export type BoneAxisDirectionScale = -1 | 1;
+export type RotationChannel = 'rx' | 'ry' | 'rz';
+export type BilateralBoneAxisScope = 'shared' | 'left' | 'right';
+export type BoneControlFamily = 'Horizontal Gaze' | 'Vertical Gaze';
+export type BoneControlScope = 'Both Eyes' | 'Left Eye Only' | 'Right Eye Only';
+export type HumanoidSkeletonTemplateVec3 = readonly [number, number, number];
+export type HumanoidSkeletonTemplateBounds = readonly [number, number, number, number, number, number];
+export type MorphTargetRef = string | number;
+export type MeshCategory = 'body' | 'eye' | 'eyeOcclusion' | 'tearLine' | 'teeth' | 'tongue' | 'hair' | 'eyebrow' | 'cornea' | 'eyelash';
+export type BlendingMode = 'Normal' | 'Additive' | 'Subtractive' | 'Multiply' | 'None';
+
+export interface MorphTargetsBySide {
+  left: MorphTargetRef[];
+  right: MorphTargetRef[];
+  center: MorphTargetRef[];
+}
+
+export interface BoneBinding {
+  node: string;
+  channel: 'rx' | 'ry' | 'rz' | 'tx' | 'ty' | 'tz';
+  scale: BoneAxisDirectionScale;
+  maxDegrees?: number;
+  maxUnits?: number;
+  side?: 'left' | 'right';
+}
+
+export interface AUInfo {
+  id: string;
+  name: string;
+  muscularBasis?: string;
+  links?: string[];
+  faceArea?: 'Upper' | 'Lower' | 'Body';
+  facePart?: string;
+}
+
+export interface RotationAxis {
+  aus: number[];
+  axis: RotationChannel;
+  negative?: number | number[];
+  positive?: number | number[];
+}
+
+export interface CompositeRotation {
+  node: string;
+  pitch: RotationAxis | null;
+  yaw: RotationAxis | null;
+  roll: RotationAxis | null;
+}
+
+export interface VisemeSlotFeatures {
+  jawOpen?: number;
+  lipClosed?: number;
+  lipRound?: number;
+  lipSpread?: number;
+  tongueTip?: number;
+  fricative?: number;
+  nasal?: number;
+}
+
+export interface VisemeSlot {
+  id: string;
+  label: string;
+  order?: number;
+  providerIds?: Record<string, Array<string | number>>;
+  phonemes?: string[];
+  matchers?: string[];
+  features?: VisemeSlotFeatures;
+  defaultJawAmount?: number;
+}
+
+export type VisemeTongueTarget = Record<string, number>;
+
+export interface VisemeBindingTarget {
+  morph: MorphTargetRef;
+  weight?: number;
+}
+
+export interface VisemeBinding {
+  targets?: VisemeBindingTarget[];
+  morph?: MorphTargetRef;
+  jawAmount?: number;
+  note?: string;
+  sharedWith?: string[];
+}
+
+export interface ResolvedVisemeSlot extends Omit<VisemeSlot, 'label'> {
+  label?: string;
+  [extension: string]: unknown;
+}
+/** Model-independent authored resolution. Array indices equal Embody runtime slot indices. */
+export interface ResolvedVisemeProfile {
+  routingMode: 'explicit' | 'legacy';
+  /** Stock canonical sound index to runtime slot index, including reordered stock profiles. */
+  canonicalSlotIndices?: number[];
+  visemeSlots: ResolvedVisemeSlot[];
+  visemeBindingTargets: Array<Array<Required<VisemeBindingTarget>>>;
+  visemeJawAmounts: number[];
+  visemeTongueTargets: VisemeTongueTarget[];
+  visemeMeshNames: string[];
+  visemeMeshCategory: string;
+}
+/** Requires initEmbodyCore(); does not verify target existence on a loaded model. */
+export declare function resolveVisemeProfile(profile: Partial<Profile>): ResolvedVisemeProfile;
+
+export interface MappingEditorSection {
+  id: string;
+  label: string;
+  kind: 'au' | 'viseme' | 'lipSync' | 'hair' | 'unmapped' | 'custom';
+  order: number;
+  meshCategory?: string;
+  facePart?: string;
+}
+
+export interface MeshMaterialSettings {
+  renderOrder?: number;
+  transparent?: boolean;
+  opacity?: number;
+  depthWrite?: boolean;
+  depthTest?: boolean;
+  blending?: BlendingMode;
+}
+
+export interface MeshInfo {
+  name?: string;
+  visible?: boolean;
+  category: MeshCategory;
+  morphCount: number;
+  material?: MeshMaterialSettings;
+}
+
+export type HairMorphAxis = 'yaw' | 'pitch' | 'roll';
+export interface HairMorphTargetMapping { key: string; axis: HairMorphAxis; }
+export interface HairMorphTargetValueMapping { value: number; axis: HairMorphAxis; }
+export interface HairPhysicsProfileConfig {
+  enabled?: boolean;
+  stiffness?: number;
+  damping?: number;
+  inertia?: number;
+  gravity?: number;
+  responseScale?: number;
+  idleSwayAmount?: number;
+  idleSwaySpeed?: number;
+  windStrength?: number;
+  windDirectionX?: number;
+  windDirectionZ?: number;
+  windTurbulence?: number;
+  windFrequency?: number;
+  idleClipDuration?: number;
+  impulseClipDuration?: number;
+  direction?: { yawSign?: 1 | -1; pitchSign?: 1 | -1 };
+  morphTargets?: {
+    swayLeft?: HairMorphTargetMapping;
+    swayRight?: HairMorphTargetMapping;
+    swayFront?: HairMorphTargetMapping;
+    fluffRight?: HairMorphTargetMapping;
+    fluffBottom?: HairMorphTargetMapping;
+    headUp?: Record<string, HairMorphTargetValueMapping>;
+    headDown?: Record<string, HairMorphTargetValueMapping>;
+  };
+}
+
+export type VRMHumanoidRole =
+  | 'hips' | 'spine' | 'chest' | 'upperChest' | 'neck' | 'head' | 'leftEye' | 'rightEye' | 'jaw'
+  | 'leftShoulder' | 'leftUpperArm' | 'leftLowerArm' | 'leftHand'
+  | 'rightShoulder' | 'rightUpperArm' | 'rightLowerArm' | 'rightHand'
+  | 'leftUpperLeg' | 'leftLowerLeg' | 'leftFoot' | 'leftToes'
+  | 'rightUpperLeg' | 'rightLowerLeg' | 'rightFoot' | 'rightToes'
+  | 'leftThumbMetacarpal' | 'leftThumbProximal' | 'leftThumbDistal'
+  | 'rightThumbMetacarpal' | 'rightThumbProximal' | 'rightThumbDistal'
+  | 'leftIndexProximal' | 'leftIndexIntermediate' | 'leftIndexDistal'
+  | 'rightIndexProximal' | 'rightIndexIntermediate' | 'rightIndexDistal'
+  | 'leftMiddleProximal' | 'leftMiddleIntermediate' | 'leftMiddleDistal'
+  | 'rightMiddleProximal' | 'rightMiddleIntermediate' | 'rightMiddleDistal'
+  | 'leftRingProximal' | 'leftRingIntermediate' | 'leftRingDistal'
+  | 'rightRingProximal' | 'rightRingIntermediate' | 'rightRingDistal'
+  | 'leftLittleProximal' | 'leftLittleIntermediate' | 'leftLittleDistal'
+  | 'rightLittleProximal' | 'rightLittleIntermediate' | 'rightLittleDistal';
+
+/** A standard bone role; motion axes/ranges belong to the authored rig profile. */
+export interface HumanoidBoneDefinition {
+  role: VRMHumanoidRole;
+  label: string;
+  section: 'Torso' | 'Head' | 'Arms' | 'Hands' | 'Legs' | 'Feet';
+  parent: VRMHumanoidRole | null;
+  required: boolean;
+  /** This optional parent must be mapped when the child is mapped. */
+  requiresParent: boolean;
+}
+
+export interface HumanoidSpecification {
+  standard: 'VRMC_vrm-1.0';
+  bones: HumanoidBoneDefinition[];
+}
+
+export interface HumanoidRoleBinding {
+  nodeKey: string;
+  /** Literal model bone selected by the role editor, before preset prefix lookup. */
+  exactBoneName?: string;
+  source?: string;
+  confidence?: number;
+}
+
+export interface HumanoidCharacterization {
+  schemaVersion: 1;
+  standard: 'VRMC_vrm-1.0';
+  status: 'verified-vrm' | 'characterized' | 'incomplete';
+  /** Explicitly edited role catalogs are authoritative across preset upgrades. */
+  authored?: boolean;
+  roles: Partial<Record<VRMHumanoidRole, HumanoidRoleBinding>>;
+}
+
+export interface HumanoidCharacterizationResolution {
+  schemaVersion: number | null;
+  standard: string | null;
+  status: string | null;
+  roles: Record<string, { nodeKey: string; boneName: string; source: string | null; confidence: number | null }>;
+  missingRequiredRoles: string[];
+  errors: string[];
+  warnings: string[];
+  valid: boolean;
+}
+
+/** Semantic body actions reuse the AU bone/morph evaluator. VRM names identify targets. */
+export interface BodyControlDefinition {
+  label: string;
+  section: string;
+  auId: number;
+  negativeAuId?: number | null;
+  bilateral: boolean;
+  roles: VRMHumanoidRole[];
+  order?: number;
+}
+
+export interface BodyControlDescriptor {
+  id: string;
+  label: string;
+  section: string;
+  auId: number;
+  negativeAuId: number | null;
+  auIds: number[];
+  bilateral: boolean;
+  roles: VRMHumanoidRole[];
+  order: number;
+  boneBindings: Array<BoneBinding & { auId: number; boneName: string }>;
+  morphBindings: MorphTargetsBySide;
+  meshNames: string[];
+  hasBones: boolean;
+  hasMorphs: boolean;
+  isMixed: boolean;
+  available: boolean;
+  diagnostics: string[];
+}
+
+/** Pose values are normalized authored action amounts, never world Euler angles. */
+export interface SemanticPoseChannel {
+  intensity: number;
+  /** -1 = character's left, 0 = both, +1 = character's right. */
+  balance?: number;
+  /** Morph contribution only; bone activation remains intensity. Defaults to profile. */
+  morphStrength?: number;
+}
+export interface SemanticPose {
+  version: 1;
+  controls: Array<{ controlId: string; positive?: SemanticPoseChannel; negative?: SemanticPoseChannel }>;
+}
+export interface SemanticPoseDirection {
+  auId: number; label: string; available: boolean; availableSides?: Array<'left' | 'right' | 'center'>; hasBones: boolean; hasMorphs: boolean; morphStrength: number;
+}
+export interface SemanticPoseControl {
+  id: string; label: string; section: string; roles: string[]; bilateral: boolean;
+  boneNames: string[]; morphNames: string[];
+  positive: SemanticPoseDirection; negative?: SemanticPoseDirection;
+}
+export interface SemanticAnimation {
+  version: 1;
+  durationSeconds: number;
+  tracks: Array<{ controlId: string; direction: 'positive' | 'negative'; balance?: number; morphStrength?: number;
+    keyframes: Array<{ time: number; intensity: number }> }>;
+}
+export interface SemanticAnimationOptions extends Record<string, unknown> {
+  faceCurves?: Record<string, Array<{ time: number; intensity: number; inherit?: boolean }>>;
+}
+
+export interface Profile {
+  name?: string;
+  animalType?: string;
+  emoji?: string;
+  auToMorphs: Record<number, MorphTargetsBySide>;
+  auToBones: Record<number, BoneBinding[]>;
+  boneNodes: Record<string, string>;
+  bonePrefix?: string;
+  boneSuffix?: string;
+  morphPrefix?: string;
+  morphSuffix?: string;
+  suffixPattern?: string;
+  leftMorphSuffixes?: string[];
+  rightMorphSuffixes?: string[];
+  morphToMesh: Record<string, string[]>;
+  auFacePartToMeshCategory?: Record<string, string>;
+  mappingSections?: MappingEditorSection[];
+  visemeKeys: MorphTargetRef[];
+  visemeSystemId?: string;
+  visemeSlots?: VisemeSlot[];
+  visemeBindings?: Record<string, VisemeBinding>;
+  visemeMeshCategory?: string;
+  visemeJawAmounts?: number[];
+  /** Per-viseme tongue AU targets in canonical slot order. */
+  visemeTongueTargets?: VisemeTongueTarget[];
+  auMixDefaults?: Record<number, number>;
+  auInfo?: Record<string, AUInfo>;
+  eyeMeshNodes?: { LEFT: string; RIGHT: string };
+  compositeRotations?: CompositeRotation[];
+  meshes?: Record<string, MeshInfo>;
+  continuumPairs?: Record<number, {
+    pairId: number;
+    isNegative: boolean;
+    axis: BoneAxisKey;
+    node: string;
+  }>;
+  continuumLabels?: Record<string, string>;
+  annotationRegions?: Region[];
+  disabledRegions?: string[];
+  hairPhysics?: HairPhysicsProfileConfig;
+  gazeCalibration?: {
+    head?: { opticalAxis?: PolymerVector3 };
+    leftEye?: { opticalAxis?: PolymerVector3 };
+    rightEye?: { opticalAxis?: PolymerVector3 };
+    /** Authored model coordinate units per physical meter, before root scaling. */
+    modelUnitsPerMeter?: number;
+  };
+  humanoidCharacterization?: HumanoidCharacterization;
+  /** Authored overrides may patch individual fields; null removes a preset control. */
+  bodyControls?: Record<string, Partial<BodyControlDefinition> | null>;
+}
+
+export interface ProfileRuntimeConfig extends Partial<Profile> {
+  profilePresetId?: PresetType;
+  presetId?: PresetType;
+  baseProfileId?: PresetType;
+  auPresetType?: PresetType;
+  profile?: Partial<Profile>;
+  defaultRegion?: string;
+  regions?: Region[];
+  markerStyle?: MarkerStyle;
+  playIntroOnLoad?: boolean;
+  modelOffset?: { x?: number; y?: number; z?: number };
+  modelRotation?: { x?: number; y?: number; z?: number };
+  modelScale?: number;
+  modelGroundClearance?: number;
+  deletedBakedAnimationClips?: string[];
+  markerGroups?: MarkerGroup[];
+  lineDefaults?: LineConfig;
+  markerDefaults?: Partial<MarkerStyleOverrides>;
+}
+
+export interface CharacterProfile extends ProfileRuntimeConfig {
+  characterId?: string;
+  characterName?: string;
+  modelPath?: string;
+}
+
+export type CharacterConfig = CharacterProfile & {
+  characterId: string;
+  characterName: string;
+  modelPath: string;
+  regions: Region[];
+};
+
+export type LineStyle = 'solid' | 'dashed' | 'dotted';
+export type LineCurve = 'straight' | 'bezier' | 'arc';
+export type NamedDirection = 'radial' | 'camera' | 'up' | 'down' | 'left' | 'right' | 'forward' | 'backward';
+export interface LineConfig { style?: LineStyle; curve?: LineCurve; arrowHead?: boolean; thickness?: number; length?: number; }
+export interface MarkerStyleOverrides {
+  markerColor?: number;
+  markerRadius?: number;
+  lineColor?: number;
+  labelColor?: string;
+  labelBackground?: string;
+  labelFontSize?: number;
+  opacity?: number;
+  lineDirection?: NamedDirection | { x: number; y: number; z: number };
+  line?: LineConfig;
+}
+export type ExpandAnimation = 'outward' | 'staggered';
+export interface ExpandedRegionState { regionName: string; isExpanded: boolean; children: string[]; }
+export interface FallbackConfig { fallbackMarker?: string; clickBehavior?: 'fit-all' | 'rotate'; }
+export interface MarkerGroup { groupId: string; regions: string[]; fallback?: FallbackConfig; }
+export interface Region {
+  name: string;
+  bones?: string[];
+  meshes?: string[];
+  objects?: string[];
+  paddingFactor?: number;
+  cameraAngle?: number;
+  cameraOffset?: { x?: number; y?: number; z?: number };
+  parent?: string;
+  children?: string[];
+  expandAnimation?: ExpandAnimation;
+  style?: MarkerStyleOverrides;
+  groupId?: string;
+  isFallback?: boolean;
+  customPosition?: { x: number; y: number; z: number };
+}
+export type MarkerStyle = 'html' | '3d';
+
+export interface HairColorAppearance { name: string; baseColor: string; emissive: string; emissiveIntensity: number; }
+export interface HairAppearanceState { hairColor: HairColorAppearance; eyebrowColor: HairColorAppearance; showOutline: boolean; outlineColor: string; outlineOpacity: number; }
+export interface HairPhysicsRuntimeConfig { enabled: boolean; [key: string]: any; }
+export type HairPhysicsRuntimeConfigUpdate = Partial<HairPhysicsRuntimeConfig>;
+export interface TransitionHandle { promise: Promise<void>; pause(): void; resume(): void; cancel(): void; }
+
+export interface BoneAxisBindingUpdate {
+  channel?: RotationChannel;
+  positiveAuId?: number | null;
+  negativeAuId?: number | null;
+  positiveMaxDegrees?: number | null;
+  negativeMaxDegrees?: number | null;
+  positiveScale?: BoneAxisDirectionScale | null;
+  negativeScale?: BoneAxisDirectionScale | null;
+  positiveLeftScale?: BoneAxisDirectionScale | null;
+  positiveRightScale?: BoneAxisDirectionScale | null;
+  negativeLeftScale?: BoneAxisDirectionScale | null;
+  negativeRightScale?: BoneAxisDirectionScale | null;
+}
+export interface BoneAxisBindingState { axis: BoneAxisKey; channel: RotationChannel; nodeKey: string; positiveAuId: number | null; negativeAuId: number | null; positiveMaxDegrees: number | null; negativeMaxDegrees: number | null; positiveScale: BoneAxisDirectionScale | null; negativeScale: BoneAxisDirectionScale | null; }
+export interface AUBoneBindingState { auId: number; boneName: string | null; nodeKey: string | null; axis: BoneAxisKey; direction: BoneAxisDirection; channel: RotationChannel | null; maxDegrees: number | null; oppositeAuId: number | null; oppositeMaxDegrees: number | null; hasBinding: boolean; hasMultipleBindings: boolean; }
+export interface BilateralAxisDirectionScaleState { left: BoneAxisDirectionScale | null; right: BoneAxisDirectionScale | null; }
+export interface BilateralAxisScopeBindingState { scope: BilateralBoneAxisScope; label: string; negativeAuId: number | null; positiveAuId: number | null; negativeMaxDegrees: number | null; positiveMaxDegrees: number | null; negativeScale: BilateralAxisDirectionScaleState; positiveScale: BilateralAxisDirectionScaleState; }
+export interface BilateralAxisBindingState { axis: BoneAxisKey; familyLabel: string; leftBoneName: string; leftNodeKey: string; rightBoneName: string; rightNodeKey: string; selectedSide: 'left' | 'right'; shared: BilateralAxisScopeBindingState; left: BilateralAxisScopeBindingState; right: BilateralAxisScopeBindingState; }
+export interface ChiralBoneNamePair { leftBoneName: string; rightBoneName: string; selectedSide: 'left' | 'right'; familyLabel: string; }
+export interface CreatedBoneAxisAu { auId: number; profile: Profile; }
+
+export interface BoneInfo { name: string; parent: string | null; children: string[]; worldPosition: { x: number; y: number; z: number }; depth: number; }
+export interface TrackInfo { name: string; targetName: string; property: string; type: string; keyframeCount: number; valueRange?: { min: number[]; max: number[] }; }
+export interface AnimationInfo { name: string; duration: number; tracks: TrackInfo[]; animatedBones: string[]; animatedMorphs: string[]; }
+export interface ModelData { bones: BoneInfo[]; morphs: Array<{ name: string; meshName: string; index: number }>; meshes: Array<{ name: string; hasMorphTargets: boolean; morphCount: number }>; animations: AnimationInfo[]; boneNames: string[]; morphNames: string[]; meshNames: string[]; }
+export interface MappingCorrection { type: 'bone' | 'morph' | 'viseme' | 'mesh'; source: string; target: string; confidence: number; reason: string; applied: boolean; auId?: number; key?: string; }
+export interface ValidationResult { valid: boolean; score: number; missingMorphs: string[]; missingBones: string[]; foundMorphs: string[]; foundBones: string[]; unmappedMorphs: string[]; unmappedBones: string[]; missingMeshes: string[]; foundMeshes: string[]; unmappedMeshes: string[]; warnings: string[]; suggestedConfig?: Profile; corrections?: MappingCorrection[]; unresolved?: MappingCorrection[]; }
+export interface ModelAnalysisReport { model: ModelData; validation?: ValidationResult; animations: { count: number; hasIdleCandidate: boolean; clips: unknown[] }; overallScore: number; summary: string; }
+
+export interface AnnotationLaterality { leftSideX: 1 | -1; confidence: number; evidence: string[]; }
+export interface BoneResolutionProfile { bonePrefix?: string; boneSuffix?: string; boneNodes?: Record<string, string>; suffixPattern?: string; }
+export interface CameraRelativeGazeOffset { x: number; y: number; }
+export interface CameraRelativeGazeOptions { yawWeight?: number; pitchWeight?: number; epsilon?: number; }
+export interface MarkerEndpointSeparationOptions { starts: ArrayLike<number>; ends: ArrayLike<number>; modelCenter: { x: number; y: number; z: number }; modelHeight: number; }
+
+export interface HumanoidSkeletonTemplateBone { readonly name: string; readonly parent: string | null; readonly translation: HumanoidSkeletonTemplateVec3; }
+export interface HumanoidSkeletonTemplate { readonly id: string; readonly sourceCharacterId: string; readonly sourceAsset: string; readonly sourceSkinName: string; readonly bones: readonly HumanoidSkeletonTemplateBone[]; }
+
+export interface CharacterModelLoadOptions { onProgress?: (progress: number) => void; castShadows?: boolean; dracoDecoderPath?: string; }
+export interface CharacterModelLoadResult { model: Object3D; meshes: Mesh[]; animations: AnimationClip[]; gltf: GLTF | null; }
+export interface CharacterModelTransform { modelOffset?: { x?: number; y?: number; z?: number }; modelRotation?: { x?: number; y?: number; z?: number }; modelScale?: number; modelGroundClearance?: number; }
+export interface DefaultCharacterLightingSettings { envMapEnabled: boolean; environmentIntensity: number; environmentBlur: number; exposure: number; ambientIntensity: number; keyIntensity: number; fillIntensity: number; rimIntensity: number; shadowOpacity: number; }
+export type DefaultCharacterLightingPresetId = 'cleanStudio' | 'softFill' | 'inspection' | 'contrast';
+export type CharacterSceneTypeId = 'studio' | 'showcase' | 'inspection' | 'void';
+export interface CharacterSceneTypeDefinition { id: CharacterSceneTypeId; label: string; description: string; background: number | null; lightingPreset: DefaultCharacterLightingPresetId; shadowPlane: boolean; }
+export interface DefaultCharacterLightingController { getSettings(): DefaultCharacterLightingSettings; getEnvironmentTexture(): Texture | null; setSettings(patch: Partial<DefaultCharacterLightingSettings>): DefaultCharacterLightingSettings; setPreset(id: DefaultCharacterLightingPresetId): DefaultCharacterLightingSettings; subscribe(listener: (settings: DefaultCharacterLightingSettings) => void): () => void; dispose(): void; }
+export interface DefaultCharacterSceneOptions { type?: CharacterSceneTypeId; cameraFov?: number; pixelRatioCap?: number; shadows?: boolean; shadowPlane?: boolean; background?: ColorRepresentation | null; lighting?: Partial<DefaultCharacterLightingSettings>; lightingPreset?: DefaultCharacterLightingPresetId; manageResize?: boolean; }
+export interface DefaultCharacterScene { container: HTMLElement; scene: Scene; renderer: WebGLRenderer; camera: PerspectiveCamera; lighting: DefaultCharacterLightingController; shadowPlane: Mesh | null; sceneType: CharacterSceneTypeId; ownsScene: true; resize(): void; dispose(): void; }
+export interface CharacterHostCharacterOptions extends CharacterModelTransform { modelUrl: string; presetType?: PresetType; profile?: Profile; }
+export interface CharacterHostExternalScene { scene: Scene; renderer: CharacterSceneRenderer; backend?: CharacterSceneBackend; rendering?: CharacterSceneRenderingController; camera: Camera; mountCanvas?: boolean; manageResize?: boolean; }
+/** Cancellation applies only until creation resolves; dispose the resolved host explicitly. */
+export interface CharacterHostOptions { signal?: AbortSignal; container: HTMLElement; character: CharacterHostCharacterOptions; embody?: RustEmbodyHostConfig; scene?: Omit<DefaultCharacterSceneAsyncOptions, 'signal'>; external?: CharacterHostExternalScene; loader?: CharacterModelLoadOptions; autoStart?: boolean; renderLoop?: boolean; autoFrame?: boolean; }
+export interface CharacterHost { engine: Embody; scene: Scene; readonly renderer: CharacterSceneRenderer; readonly backend: CharacterSceneBackend | null; readonly rendering: CharacterSceneRenderingController | null; camera: Camera | PerspectiveCamera; model: Object3D; meshes: Mesh[]; animations: AnimationClip[]; lighting: DefaultCharacterLightingController | null; ownsScene: boolean; container: HTMLElement; setCharacter(character: CharacterHostCharacterOptions, loader?: CharacterModelLoadOptions): Promise<void>; resize(): void; dispose(): Promise<void>; }
+
+export interface CharacterRegistry { characters: CharacterConfig[]; defaultCharacter?: string; }
+export type AnimationSource = 'baked' | 'clip' | 'snippet';
+export type AnimationBlendMode = 'replace' | 'additive';
+export type BakedClipChannel = 'face' | 'body' | 'scene';
+export interface AnimationClipInfo { name: string; duration: number; trackCount: number; source?: AnimationSource; channels?: BakedClipChannelInfo[]; }
+export interface ThreeMaterialConfig extends MeshMaterialSettings {}
+export interface ThreeResolvedMaterialConfig { renderOrder: number; transparent: boolean; opacity: number; depthWrite: boolean; depthTest: boolean; blending: BlendingMode; }
 
 /** Direct Embody Wasm core accessors (via @lovelace_lol/embody/wasm). */
 export declare function initEmbodyCore(): Promise<EmbodyCoreWasmModule>;
@@ -94,11 +603,14 @@ export interface WasmRuntimeCore {
   set_au(id: number, value: number, balance: number): void;
   set_au_signed(id: number, value: number, balance: number): void;
   get_au(id: number): number;
+  get_au_balance(id: number): number;
   set_continuum(negAu: number, posAu: number, value: number, balance: number): void;
   get_continuum(negAu: number, posAu: number): number;
   set_au_mix_weight(id: number, weight: number): void;
   set_viseme(index: number, value: number): void;
   set_viseme_jaw_scale(index: number, jawScale: number): void;
+  get_viseme(index: number): number;
+  get_viseme_jaw_scale(index: number): number;
   set_viseme_slot_count(count: number): void;
   transition_au(id: number, to: number, durationMs: number, balance: number): void;
   transition_viseme(index: number, to: number, durationMs: number, jawScale: number): void;
@@ -142,6 +654,19 @@ export interface EmbodyCoreWasmModule {
     manualScale: number,
     manualTranslation: Float32Array
   ): Float32Array;
+  solve_profile_screen_space_gaze(
+    profileJson: string,
+    screenTarget: Float32Array,
+    cameraPosition: Float32Array,
+    cameraQuaternion: Float32Array,
+    gazeOrigin: Float32Array,
+    modelQuaternion: Float32Array,
+    verticalFovDegrees: number,
+    aspect: number,
+    eyesEnabled: boolean,
+    headEnabled: boolean,
+    headFollowFraction: number
+  ): Float32Array;
   default_hair_physics_config_values(): Float32Array;
   list_presets(): string[];
   has_preset(presetId: string): boolean;
@@ -161,13 +686,18 @@ export type RustEmbodyHostConfig =
       presetType?: string;
       profile?: Partial<Profile>;
       meshes?: unknown[];
+      /** Reference for the first model bound to this host. */
+      referencePose?: ThreeModelReferencePose;
     }
   | {
       profileMode: 'profile';
-      profile: Profile;
+      /** Exact profile; an empty object renders an unmapped model for authoring. */
+      profile: Partial<Profile>;
       presetId?: never;
       presetType?: never;
       meshes?: unknown[];
+      /** Reference for the first model bound to this host. */
+      referencePose?: ThreeModelReferencePose;
     };
 
 /**
@@ -181,8 +711,12 @@ export interface PolymerCharacterRuntime {
   readonly meshes: unknown[];
   readonly meshByName: Map<string, unknown>;
   readonly bones: Record<string, unknown>;
-  onReady(options: { model: unknown; meshes?: unknown[] }): void;
+  /** First bind captures the model reference unless an explicit capture is supplied. */
+  onReady(options: { model: unknown; meshes?: unknown[]; animations?: unknown[]; referencePose?: ThreeModelReferencePose }): void;
+  /** Rebind using the original reference; incompatible hierarchy edits throw. */
   bindModel(meshes?: unknown[]): void;
+  /** Explicitly include appended nodes without recapturing existing posed nodes. */
+  extendReferencePose(): ThreeModelReferencePose;
   setProfile(profile: Profile): void;
   getProfile(): Profile;
   getProfileMode(): RustEmbodyProfileMode;
@@ -190,24 +724,44 @@ export interface PolymerCharacterRuntime {
   supportsPreset(presetId?: string): boolean;
   setAU(id: number, value: number, balance?: number): void;
   getAU(id: number): number;
+  /** Current procedural left/right balance (-1..1), or zero after clear. */
+  getAUBalance(id: number): number;
+  /** Resolve body controls from the configured Rust profile/model; no scene traversal. */
+  getBodyControls(): BodyControlDescriptor[];
+  getSemanticPoseCatalog(): SemanticPoseControl[];
+  captureSemanticPose(): SemanticPose;
+  validateSemanticPose(pose: SemanticPose): SemanticPose;
+  applySemanticPose(pose: SemanticPose): void;
+  validateSemanticAnimation(animation: SemanticAnimation, options?: SemanticAnimationOptions): void;
+  semanticAnimationToClip(name: string, animation: SemanticAnimation, options?: SemanticAnimationOptions): AnimationPlaybackHandle;
+  /** Reset configured body actions atomically and apply one procedural frame. */
+  resetBodyControls(): void;
   setContinuum(negAU: number, posAU: number, value: number, balance?: number): void;
   getContinuum(negAU: number, posAU: number): number;
-  transitionAU(id: number, to: number, durationMs?: number, balance?: number): void;
+  /** Mixer-timed live control; defaults to 200 ms. getAU reports its destination immediately. */
+  transitionAU(id: number, to: number, durationMs?: number, balance?: number): TransitionHandle;
   setViseme(index: number, value: number, jawScale?: number): void;
+  /** Canonical direct viseme value; unset, cleared or out-of-range slots return 0. Does not sample mixer output. */
+  getViseme(index: number): number;
+  /** Canonical direct jaw scale; unset, cleared or out-of-range slots return 1. */
+  getVisemeJawScale(index: number): number;
   setVisemeById(slotId: string, value: number, jawScale?: number): void;
-  transitionViseme(index: number, to: number, durationMs?: number, jawScale?: number): void;
-  transitionVisemeById(slotId: string, to: number, durationMs?: number, jawScale?: number): void;
+  /** Mixer-timed live control; defaults to 80 ms. getViseme reports the sampled direct value. */
+  transitionViseme(index: number, to: number, durationMs?: number, jawScale?: number): TransitionHandle;
+  transitionVisemeById(slotId: string, to: number, durationMs?: number, jawScale?: number): TransitionHandle;
   setAUMixWeight(id: number, weight: number): void;
   getAUMixWeight(id: number): number;
   hasLeftRightBones(id: number): boolean;
   setMorph(key: string | number, value: number, meshNames?: string[]): void;
   setMorphOnMeshes(meshNames: string[], key: string | number, value: number): void;
+  /** Relinquish a direct morph override so current AU/viseme/clip output can resume. */
+  releaseMorph(key: string | number, meshNames?: string[]): void;
   transitionMorph(
     key: string | number,
     value: number,
     durationMs?: number,
     meshNames?: string[]
-  ): ReturnType<Embody['transitionMorph']>;
+  ): TransitionHandle;
   getMorphTargets(): Record<string, string[]>;
   getMorphTargetIndices(): Record<string, Array<{ index: number; name: string }>>;
   getHairMorphTargets(meshName: string): string[];
@@ -216,10 +770,10 @@ export interface PolymerCharacterRuntime {
   getBones(): Record<string, unknown>;
   setMeshVisible(meshName: string, visible: boolean): void;
   highlightMesh(meshName: string | null, color?: number, intensity?: number): void;
-  getMeshMaterialConfig(meshName: string): ReturnType<Embody['getMeshMaterialConfig']>;
+  getMeshMaterialConfig(meshName: string): ThreeResolvedMaterialConfig | null;
   setMeshMaterialConfig(
     meshName: string,
-    config: Parameters<Embody['setMeshMaterialConfig']>[1]
+    config: ThreeMaterialConfig
   ): void;
   registerHairObjects(
     objects: Object3D[]
@@ -240,28 +794,42 @@ export interface PolymerCharacterRuntime {
   validateHairMorphTargets(): string[];
   updateHairPhysics(dtSeconds: number): void;
   loadAnimationClips(clips: unknown[]): void;
-  getAnimationClips(): ReturnType<Embody['getAnimationClips']>;
+  /**
+   * Register additional baked sources on a bound model without starting clips
+   * or interrupting playback. Identical sources are ignored; a replacement
+   * under the same name takes effect on the next play. Sources survive rebinds.
+   */
+  registerAnimationClips(clips: unknown[]): void;
+  /** Remove a source and its active action, including the source retained for rebinding. */
+  removeAnimationClip(clipName: string): boolean;
+  getAnimationClips(): AnimationClipInfo[];
   playAnimation(
     clipName: string,
-    options?: Parameters<Embody['playAnimation']>[1]
-  ): ReturnType<Embody['playAnimation']>;
+    options?: Record<string, unknown>
+  ): AnimationPlaybackHandle;
   stopAnimation(clipName: string): void;
   stopAllAnimations(): void;
   playTypedSnippet(
-    snippet: Parameters<Embody['playTypedSnippet']>[0],
-    options?: Parameters<Embody['playTypedSnippet']>[1]
-  ): ReturnType<Embody['playTypedSnippet']>;
+    snippet: Record<string, unknown>,
+    options?: Record<string, unknown>
+  ): AnimationPlaybackHandle;
   buildTypedClip(
     clipName: string,
-    channels: Parameters<Embody['buildTypedClip']>[1],
-    options?: Parameters<Embody['buildTypedClip']>[2]
-  ): ReturnType<Embody['buildTypedClip']>;
+    channels: unknown[],
+    options?: Record<string, unknown>
+  ): AnimationPlaybackHandle;
   buildClip(
     clipName: string,
-    curves: Parameters<Embody['buildClip']>[1],
-    options?: Parameters<Embody['buildClip']>[2]
-  ): ReturnType<Embody['buildClip']>;
+    curves: Record<string, unknown>,
+    options?: Record<string, unknown>
+  ): AnimationPlaybackHandle;
   cleanupSnippet(name: string): void;
+  /** Read-only seed for gaze motor controls in the current evaluated pose. */
+  getGazeControlState(options?: { worldTarget?: PolymerVector3; headIntensity?: number; eyeIntensity?: number }): GazeControlState | null;
+  /** Last evaluated optical-ray diagnostics; null without active focus controls. */
+  getGazeFocusDiagnostics(): GazeFocusDiagnostics | null;
+  /** Fresh immutable copy of the last positive-dt pose update; polling does not renew its stamp. */
+  getGazeObservation(): GazeObservation | null;
   update(dtSeconds: number): void;
   start(): void;
   stop(): void;
@@ -270,6 +838,24 @@ export interface PolymerCharacterRuntime {
   dispose(): void;
 }
 
+export interface AnimationPlaybackHandle extends TransitionHandle {
+  name: string;
+  actionId?: string;
+  play(): AnimationPlaybackHandle;
+  stop(): AnimationPlaybackHandle;
+  setWeight(value: number): AnimationPlaybackHandle;
+  setSpeed(value: number): AnimationPlaybackHandle;
+  setTime(value: number): AnimationPlaybackHandle;
+  subscribe(listener: ((event: unknown) => void) | { next(event: unknown): void }): () => void;
+}
+
+export interface EmbodyRuntime extends PolymerCharacterRuntime {}
+export declare class Embody {
+  constructor(config?: RustEmbodyHostConfig);
+  static create(config?: RustEmbodyHostConfig): Promise<Embody>;
+  [key: string]: any;
+}
+
 export declare function createRustEmbodyHost(
   model: unknown,
   config?: RustEmbodyHostConfig
@@ -281,172 +867,102 @@ export declare function createRustEmbodyHostUnbound(
 
 export declare function supportsRustEmbodyPreset(presetId?: string): boolean;
 
-export {
-  Embody,
-  BLENDING_MODES,
-  THREE_BLENDING_MODES,
-  collectMorphMeshes,
-  analyzeModel,
-  extractModelData,
-  getPreset,
-  validateMappings,
-  extendCharacterConfigWithPreset,
-  extractProfileOverrides,
-  mergeCharacterRegionsByName,
-  applyAUBoneBindingUpdate,
-  applyBilateralAxisBindingUpdate,
-  applyBoneAxisBindingUpdate,
-  buildBoneAuOptions,
-  classifyAuAsJointControl,
-  createBilateralBoneAxisAu,
-  createBoneAxisAu,
-  DEFAULT_AXIS_TO_CHANNEL,
-  DEFAULT_BONE_MAX_DEGREES,
-  ensureBilateralBoneNodeKeys,
-  ensureBoneNodeKey,
-  findNodeKeyForBone,
-  formatAxisDirectionLabel,
-  formatAxisLabel,
-  getAUBoneBindingState,
-  getAxisFromChannel,
-  getBilateralAxisBindingState,
-  getBoneAxisBindingState,
-  inferChiralBoneNamePair,
-  inferEyeControlFamily,
-  inferEyeControlScope,
-  isJointControlAuInfo,
-  isMaxDegreesOnlyAxisBindingUpdate,
-  JOINT_CONTROL_SECTION,
-  resolveBoneAxisChannel,
-  resolveBoneNameForNodeKey,
-  resolveContinuumDisplayLabel,
-  stripConfiguredBoneAffixes,
-  computeCameraRelativeGazeOffset,
-  detectAnnotationLaterality,
-  fuzzyNameMatch,
-  getDefaultAnnotationLaterality,
-  getMeshNamesForAUProfile,
-  getModelLocalOrbitAngle,
-  getSemanticHorizontalSign,
-  getSemanticHorizontalSignForSide,
-  getWorldDirectionForCameraAngle,
-  hasLeftRightMorphs,
-  isMixedAU,
-  passesMarkerCameraAngleGate,
-  resolveBoneNames,
-  resolveFaceCenter,
-  resolveRegionCameraAngle,
-  resolveRegionVisibilityCameraAngle,
-  toWorldDirection,
-  RustAnnotationCameraCore,
-  createRustAnnotationCameraCore,
-  CC4_BONES,
-  VISEME_KEYS,
-  HAIR_COLOR_PRESETS,
-  DEFAULT_HAIR_COLOR_APPEARANCE,
-  normalizeHairColorAppearance,
-  HUMANOID_SKELETON_TEMPLATES,
-  JONATHAN_HUMANOID_SKELETON_TEMPLATE,
-  getHumanoidSkeletonTemplate,
-  getHumanoidSkeletonTemplateBoneNames,
-  createValidationSkeletonFromHumanoidTemplate,
-  computeHumanoidSkeletonTemplateRestBounds,
-  extractHumanoidSkeletonTemplateFromModel,
-  createCharacterHost,
-  createDefaultCharacterScene,
-  createDefaultCharacterLighting,
-  createShadowPlane,
-  loadCharacterModel,
-  parseCharacterModel,
-  applyCharacterModelTransform,
-  disposeCharacterModel,
-  DEFAULT_CHARACTER_LIGHTING_PRESET_ID,
-  DEFAULT_CHARACTER_LIGHTING_PRESET_IDS,
-  DEFAULT_CHARACTER_LIGHTING_PRESETS,
-  DEFAULT_CHARACTER_LIGHTING_SETTINGS,
-  normalizeDefaultCharacterLightingSettings,
-  CHARACTER_SCENE_TYPES,
-  CHARACTER_SCENE_TYPE_IDS,
-  DEFAULT_CHARACTER_SCENE_TYPE_ID,
-} from '@lovelace_lol/embody';
-
-export type {
-  CharacterHost,
-  CharacterHostCharacterOptions,
-  CharacterHostExternalScene,
-  CharacterHostOptions,
-  CharacterModelLoadOptions,
-  CharacterModelLoadResult,
-  CharacterModelTransform,
-  CharacterSceneTypeDefinition,
-  CharacterSceneTypeId,
-  DefaultCharacterLightingController,
-  DefaultCharacterLightingPresetId,
-  DefaultCharacterLightingSettings,
-  DefaultCharacterScene,
-  DefaultCharacterSceneOptions,
-  HairAppearanceState,
-  HairColorAppearance,
-  HairPhysicsRuntimeConfig,
-  HairPhysicsRuntimeConfigUpdate,
-  MarkerEndpointSeparationOptions,
-} from '@lovelace_lol/embody';
-
-export type {
-  AUBoneBindingState,
-  AUInfo,
-  AnimationClipInfo,
-  AnimationInfo,
-  AnnotationLaterality,
-  BilateralAxisBindingState,
-  BilateralAxisDirectionScaleState,
-  BilateralAxisScopeBindingState,
-  BilateralBoneAxisScope,
-  BoneAxisBindingState,
-  BoneAxisBindingUpdate,
-  BoneAxisDirection,
-  BoneAxisDirectionScale,
-  BoneAxisKey,
-  BoneBinding,
-  BoneControlFamily,
-  BoneControlScope,
-  BoneInfo,
-  CameraRelativeGazeOffset,
-  CameraRelativeGazeOptions,
-  CharacterConfig,
-  CharacterRegistry,
-  ChiralBoneNamePair,
-  CompositeRotation,
-  CreatedBoneAxisAu,
-  ExpandAnimation,
-  ExpandedRegionState,
-  FallbackConfig,
-  LineConfig,
-  LineCurve,
-  LineStyle,
-  EmbodyRuntime,
-  MarkerGroup,
-  MarkerStyle,
-  MarkerStyleOverrides,
-  MeshInfo,
-  ModelAnalysisReport,
-  ModelData,
-  MorphTargetsBySide,
-  NamedDirection,
-  PresetType,
-  Profile,
-  Region,
-  RotationAxis,
-  RotationChannel,
-  TrackInfo,
-  TransitionHandle,
-  ValidationResult,
-  VisemeSlot,
-  HumanoidSkeletonTemplate,
-  HumanoidSkeletonTemplateBone,
-  HumanoidSkeletonTemplateBounds,
-  HumanoidSkeletonTemplateVec3,
-} from '@lovelace_lol/embody';
+export declare const BLENDING_MODES: Record<BlendingMode, number>;
+export declare const THREE_BLENDING_MODES: Record<BlendingMode, number>;
+export declare function collectMorphMeshes(root: Object3D): Mesh[];
+export declare function analyzeModel(options: {
+  source: { type: 'gltf'; gltf: GLTF } | { type: 'runtime'; model: Object3D; meshes: Mesh[]; animations: AnimationClip[] };
+  preset?: Profile;
+  suggestCorrections?: boolean;
+}): Promise<ModelAnalysisReport>;
+export declare function extractModelData(model: Object3D, meshes?: Mesh[], animations?: AnimationClip[]): ModelData;
+export declare function getPreset(presetId: PresetType): Profile;
+export declare function validateMappings(meshes: unknown[], skeleton: unknown, profile: Profile, options?: Record<string, unknown>): ValidationResult;
+export declare function validateHumanoidCharacterization(model: Object3D, profile: Profile): HumanoidCharacterizationResolution;
+export declare function extendCharacterConfigWithPreset(config: CharacterConfig): CharacterConfig;
+export declare function extractProfileOverrides(config: CharacterConfig): Partial<Profile>;
+export declare function mergeCharacterRegionsByName(base?: Region[], override?: Region[]): Region[];
+export declare function applyAUBoneBindingUpdate(profile: Profile, auId: number, update: { boneName: string | null; axis: BoneAxisKey; direction: BoneAxisDirection; maxDegrees: number | null }): Profile;
+export declare function applyBilateralAxisBindingUpdate(profile: Profile, boneName: string, axis: BoneAxisKey, scope: BilateralBoneAxisScope, update: BoneAxisBindingUpdate): Profile;
+export declare function applyBoneAxisBindingUpdate(profile: Profile, boneName: string, axis: BoneAxisKey, update: BoneAxisBindingUpdate): Profile;
+export declare function buildBoneAuOptions(profile: Profile): Array<{ value: string; label: string; detail?: string }>;
+export declare function classifyAuAsJointControl(profile: Profile, auId: number, options?: { boneName?: string | null; nodeKey?: string | null }): Profile;
+export declare function createBilateralBoneAxisAu(profile: Profile, boneName: string, axis: BoneAxisKey, scope: BilateralBoneAxisScope, direction: BoneAxisDirection, options?: { name?: string }): CreatedBoneAxisAu;
+export declare function createBoneAxisAu(profile: Profile, boneName: string, axis: BoneAxisKey, direction: BoneAxisDirection, options?: { name?: string }): CreatedBoneAxisAu;
+export declare const DEFAULT_AXIS_TO_CHANNEL: Record<BoneAxisKey, RotationChannel>;
+export declare const DEFAULT_BONE_MAX_DEGREES: number;
+export declare function ensureBilateralBoneNodeKeys(profile: Profile, leftBoneName: string, rightBoneName: string): Profile;
+export declare function ensureBoneNodeKey(profile: Profile, boneName: string): { nodeKey: string; boneNodes: Record<string, string> };
+export declare function findNodeKeyForBone(boneName: string, profile: Profile | null): string | null;
+export declare function formatAxisDirectionLabel(axis: BoneAxisKey, direction: BoneAxisDirection): string;
+export declare function formatAxisLabel(axis: BoneAxisKey): string;
+export declare function getAUBoneBindingState(profile: Profile, auId: number): AUBoneBindingState;
+export declare function getAxisFromChannel(channel?: string): BoneAxisKey | null;
+export declare function getBilateralAxisBindingState(profile: Profile, boneName: string, axis: BoneAxisKey): BilateralAxisBindingState | null;
+export declare function getBoneAxisBindingState(profile: Profile, boneName: string, axis: BoneAxisKey): BoneAxisBindingState | null;
+export declare function inferChiralBoneNamePair(boneNames: string[], selectedBoneName: string): ChiralBoneNamePair | null;
+export declare function inferEyeControlFamily(binding: Pick<BoneAxisBindingState, 'nodeKey' | 'axis'>): BoneControlFamily | null;
+export declare function inferEyeControlScope(profile: Pick<Profile, 'auToBones'>, binding: Pick<BoneAxisBindingState, 'nodeKey' | 'negativeAuId' | 'positiveAuId'>): BoneControlScope | null;
+export declare function isJointControlAuInfo(info?: Pick<AUInfo, 'facePart'> | null): boolean;
+export declare function isMaxDegreesOnlyAxisBindingUpdate(update: BoneAxisBindingUpdate): boolean;
+export declare const JOINT_CONTROL_SECTION: string;
+export declare function resolveBoneAxisChannel(profile: Profile, boneName: string, axis: BoneAxisKey): RotationChannel;
+export declare function resolveBoneNameForNodeKey(profile: Profile, nodeKey: string): string | null;
+export declare function resolveContinuumDisplayLabel(profile: Pick<Profile, 'continuumPairs' | 'continuumLabels' | 'auInfo' | 'boneNodes' | 'bonePrefix' | 'boneSuffix'>, negativeAuId: number, positiveAuId: number): string;
+export declare function stripConfiguredBoneAffixes(profile: { bonePrefix?: string; boneSuffix?: string } | null | undefined, boneName: string): string;
+export declare function computeCameraRelativeGazeOffset(model: Object3D | null, cameraPosition: { x: number; y: number; z: number }, targetPosition: { x: number; y: number; z: number }, options?: CameraRelativeGazeOptions): CameraRelativeGazeOffset;
+export declare function solveScreenSpaceGaze(options: ScreenSpaceGazeOptions): ScreenSpaceGazeSolution;
+export declare function createEmbodyGazeRuntime(
+  profileProvider: Profile | (() => Profile),
+  host?: Pick<PolymerCharacterRuntime, 'getGazeControlState'>
+): EmbodyGazeRuntime;
+export declare function fuzzyNameMatch(objectName: string, targetName: string, suffixPattern?: string): boolean;
+export declare function getMeshNamesForAUProfile(profile: Profile, auId: number): string[];
+export declare function hasLeftRightMorphs(auId: number): boolean;
+export declare function hasLeftRightMorphs(profile: Profile, auId: number): boolean;
+export declare function isMixedAU(auId: number): boolean;
+export declare function isMixedAU(profile: Profile, auId: number): boolean;
+export declare function resolveBoneNames(names: string[] | undefined, profile?: BoneResolutionProfile): string[];
+/** All 55 VRM 1.0 roles, including required flags and optional-parent rules. */
+export declare function getHumanoidSpecification(): HumanoidSpecification;
+/** Assign an actual model bone or clear a role; returns a new authoritative profile. */
+export declare function setHumanoidRoleBinding(profile: Profile, role: VRMHumanoidRole, boneName: string | null): Profile;
+/** Replace one action side's targets, preserving other actions sharing those morphs. */
+export declare function setAUMorphTargets(profile: Profile, auId: number, side: 'left' | 'right' | 'center', targets: Array<string | number>): Profile;
+export declare function resolveHumanoidCharacterization(profile: Profile): HumanoidCharacterizationResolution;
+/** With a model, reports missing bone/morph targets against the actual scene. */
+export declare function getBodyControls(profile: Profile, model?: Object3D): BodyControlDescriptor[];
+export declare function resolveCharacterGazeOrigin(model: Object3D, profile?: Profile | null): Vector3 | null;
+export declare const CC4_BONES: Record<string, string>;
+export declare const VISEME_KEYS: string[];
+export declare const HAIR_COLOR_PRESETS: Record<string, HairColorAppearance>;
+export declare const DEFAULT_HAIR_COLOR_APPEARANCE: HairColorAppearance;
+export declare function normalizeHairColorAppearance(value: HairColorAppearance | string, fallback?: HairColorAppearance): HairColorAppearance;
+export declare const HUMANOID_SKELETON_TEMPLATES: readonly HumanoidSkeletonTemplate[];
+export declare const CC4_HUMANOID_SKELETON_TEMPLATE: HumanoidSkeletonTemplate;
+export declare function getHumanoidSkeletonTemplate(id: string): HumanoidSkeletonTemplate | null;
+export declare function getHumanoidSkeletonTemplateBoneNames(template?: HumanoidSkeletonTemplate): string[];
+export declare function createValidationSkeletonFromHumanoidTemplate(template?: HumanoidSkeletonTemplate): { bones: Array<{ name: string }> };
+export declare function computeHumanoidSkeletonTemplateRestBounds(template: HumanoidSkeletonTemplate): HumanoidSkeletonTemplateBounds;
+export declare function extractHumanoidSkeletonTemplateFromModel(model: Object3D, options: { id: string; sourceCharacterId: string; sourceAsset?: string; sourceSkinName?: string }): HumanoidSkeletonTemplate;
+export declare function createCharacterHost(options: CharacterHostOptions): Promise<CharacterHost>;
+export declare function createDefaultCharacterScene(container: HTMLElement, options?: DefaultCharacterSceneOptions): DefaultCharacterScene;
+export declare function createDefaultCharacterSceneAsync(container: HTMLElement, options?: DefaultCharacterSceneAsyncOptions): Promise<ReadyDefaultCharacterScene>;
+export declare function createDefaultCharacterSceneRuntime(container: HTMLElement, options?: DefaultCharacterSceneRuntimeOptions): DefaultCharacterSceneRuntime;
+export declare function createDefaultCharacterLighting(scene: Scene, renderer: WebGLRenderer, settings?: Partial<DefaultCharacterLightingSettings>): DefaultCharacterLightingController;
+export declare function createShadowPlane(scene: Scene, options?: { size?: number; opacity?: number; yPosition?: number }): Mesh;
+export declare function loadCharacterModel(url: string, options?: CharacterModelLoadOptions): Promise<CharacterModelLoadResult>;
+export declare function parseCharacterModel(data: ArrayBuffer, resourcePath?: string, options?: CharacterModelLoadOptions): Promise<CharacterModelLoadResult>;
+export declare function applyCharacterModelTransform(model: Object3D, value?: CharacterModelTransform): void;
+export declare function disposeCharacterModel(scene: Scene | null, model: Object3D): void;
+export declare const DEFAULT_CHARACTER_LIGHTING_PRESET_ID: DefaultCharacterLightingPresetId;
+export declare const DEFAULT_CHARACTER_LIGHTING_PRESET_IDS: readonly DefaultCharacterLightingPresetId[];
+export declare const DEFAULT_CHARACTER_LIGHTING_PRESETS: Record<DefaultCharacterLightingPresetId, { id: DefaultCharacterLightingPresetId; label: string; settings: DefaultCharacterLightingSettings }>;
+export declare const DEFAULT_CHARACTER_LIGHTING_SETTINGS: DefaultCharacterLightingSettings;
+export declare function normalizeDefaultCharacterLightingSettings(value: unknown): DefaultCharacterLightingSettings | null;
+export declare const CHARACTER_SCENE_TYPES: Record<CharacterSceneTypeId, CharacterSceneTypeDefinition>;
+export declare const CHARACTER_SCENE_TYPE_IDS: readonly CharacterSceneTypeId[];
+export declare const DEFAULT_CHARACTER_SCENE_TYPE_ID: CharacterSceneTypeId;
 
 export interface BlinkState {
   agency: 'blink';
@@ -474,21 +990,176 @@ export interface GazeTarget {
   z?: number;
 }
 
+export interface GazeControlState {
+  headSeedLimited?: boolean;
+  eyeSeedLimited?: boolean;
+  target?: Required<GazeTarget>;
+  eyeTarget: Required<GazeTarget>;
+  headTarget: Required<GazeTarget>;
+  headRoll: number;
+}
+
+export interface GazeFocusRequest {
+  worldTarget: PolymerVector3;
+  target: Required<GazeTarget>;
+  headTarget?: Required<GazeTarget>;
+  eyesEnabled: boolean;
+  headEnabled: boolean;
+  /** Tracking contribution in [0, 1]; older values above 1 normalize to 1. Live changes use scheduled motion. */
+  eyeIntensity?: number;
+  /** Tracking contribution in [0, 1], composed over authored head motion. Live changes use scheduled motion. */
+  headIntensity?: number;
+  initialState?: GazeControlState;
+}
+
+export interface GazeFocusDiagnostics {
+  target: PolymerVector3;
+  eyes: Array<{ name: string; origin: PolymerVector3; direction: PolymerVector3; errorDegrees: number; limited: boolean }>;
+  headLimited: boolean;
+  missingHead: boolean;
+  missingEyes: boolean;
+}
+
+export interface GazeObservation {
+  sampleSequence: number;
+  observedAt: number;
+  bindingGeneration: number;
+  requestId: string | null;
+  diagnostics: GazeFocusDiagnostics;
+}
+
+export interface GazeAttentionOutcome {
+  status: 'moving' | 'settled' | 'unavailable' | 'failed';
+  reason: string;
+  angularErrorDeg?: number;
+  sampleSequence?: number;
+  observedAt?: number;
+  bindingGeneration?: number;
+}
+export interface GazeRetainedCandidate {
+  id: string;
+  source: string;
+  provenance: 'synthetic' | 'peer';
+  target: GazeTarget;
+  targetSpace: string;
+  confidence: number;
+  salience: number;
+  influence: number;
+  /** Actual accepted Society credit for peers, null for synthetic fixtures. */
+  routeCredit: number | null;
+  edgeId: string | null;
+  score: number;
+  observedAt: number;
+  expiresAt: number;
+  eligible: boolean;
+  reason: string;
+  lastOutcome?: GazeAttentionOutcome;
+}
+export interface GazeAttentionState {
+  /** The POC accepts static Conversation facts; live perception arbitration is deferred. */
+  lastRejectedInput?: { source: string; reason: 'moving-peer-arbitration-deferred' };
+  active: boolean;
+  sessionId: string | null;
+  scenario: GazeAttentionScenario | null;
+  phase: 'inactive' | 'waiting' | 'moving' | 'settled' | 'unavailable' | 'failed';
+  reason: string;
+  selectedId: string | null;
+  requestId: string | null;
+  configurationRevision: number;
+  candidates: GazeRetainedCandidate[];
+  feedback: GazeAttentionOutcome | null;
+  decisionCount: number;
+  updatedAt?: number;
+}
+export type GazeAttentionScenario = 'competition' | 'equal-score' | 'expiry' | 'unreachable';
+
+export interface ScreenSpaceGazeSolution {
+  kind: 'gaze.screen-space' | 'gaze.viewer-space';
+  focus?: GazeFocusRequest;
+  target: Required<GazeTarget>;
+  eyeTarget: Required<GazeTarget>;
+  headTarget: Required<GazeTarget>;
+  angles: {
+    yawDegrees: number;
+    pitchDegrees: number;
+    cameraYawDegrees: number;
+    cameraPitchDegrees: number;
+  };
+  /** World-space distance from the character's binocular eye origin to the render camera. */
+  distance: number;
+  viewerTarget: PolymerVector3;
+  screenTarget: Required<GazeTarget>;
+}
+
+export interface ScreenSpaceGazeOptions {
+  profile?: Profile;
+  screenTarget: GazeTarget;
+  cameraPosition: PolymerVector3;
+  cameraQuaternion: PolymerQuaternion;
+  gazeOrigin: PolymerVector3;
+  modelQuaternion: PolymerQuaternion;
+  verticalFovDegrees: number;
+  aspect: number;
+  eyesEnabled?: boolean;
+  headEnabled?: boolean;
+  /** Defaults to 1: full target bearing, bounded by the profile's head AU limits. */
+  headFollowFraction?: number;
+}
+
+export interface CameraGazeGeometry {
+  cameraPosition: PolymerVector3;
+  cameraQuaternion: PolymerQuaternion;
+  gazeOrigin: PolymerVector3;
+  modelQuaternion: PolymerQuaternion;
+  verticalFovDegrees: number;
+  aspect: number;
+  gazeGeometryComplete: boolean;
+  worldUnitsPerMeter?: number;
+}
+
+export interface EmbodyGazeRuntime {
+  solveTarget(
+    screenTarget: GazeTarget,
+    cameraFact: CameraGazeGeometry & Record<string, unknown>,
+    options: GazeApplyOptions & { eyesEnabled: boolean; headEnabled: boolean; headFollowEyes: boolean; headIntensity?: number }
+  ): ScreenSpaceGazeSolution;
+}
+
 export interface GazeConfig {
+  /** Explicitly synthetic lab:A and lab:B receiver influences, not graph-edge weights. */
+  attentionInfluenceA?: number;
+  attentionInfluenceB?: number;
+  attentionDwellMs?: number;
+  attentionSwitchMargin?: number;
+  attentionToleranceDeg?: number;
+  attentionTimeoutMs?: number;
   enabled?: boolean;
   eyesEnabled?: boolean;
   headEnabled?: boolean;
+  /** Default true: follow the full target turn from reference neutral within head AU limits. False prefers neutral, with eye-limit overflow assistance. */
   headFollowEyes?: boolean;
+  headFollowDelay?: number;
   mirrored?: boolean;
   smoothFactor?: number;
+  predictionEnabled?: boolean;
+  predictionFactor?: number;
+  maxPredictionDelta?: number;
   minDelta?: number;
   transitionDurationMs?: number;
+  /** Tracking contribution in [0, 1]; older values above 1 normalize to 1. With geometry-backed focus, live changes move directly toward the latest value without angular reversal braking. */
   eyeIntensity?: number;
+  /** Tracking contribution in [0, 1], composed over authored head motion. With geometry-backed focus, live changes move directly toward the latest value without angular reversal braking. */
   headIntensity?: number;
+  trackingSpeed?: number;
+  /** Braking interval for angular direction changes; geometry-backed strength changes bypass it. */
+  courseChangeDurationMs?: number;
   coalesceMs?: number;
 }
 
 export interface GazeState {
+  attention: GazeAttentionState;
+  configuration: AgencyConfigurationState;
+  lastDecision: GazeDecision | null;
   agency: 'gaze';
   status: string;
   mode: string;
@@ -496,8 +1167,12 @@ export interface GazeState {
   rawTarget: Required<GazeTarget>;
   target: Required<GazeTarget>;
   baseTarget: Required<GazeTarget>;
+  baseOptions: GazeApplyOptions;
+  cameraInvalidated: boolean;
+  sourceAvailable: boolean;
   cameraRelativeOffset: Required<GazeTarget>;
   lastCameraFact: null | Record<string, unknown>;
+  lastGazeSolution: ScreenSpaceGazeSolution | null;
   lastRequestedTarget: Required<GazeTarget>;
   pendingRequest: GazeLookRequest | null;
   lastRequest: GazeLookRequest | GazeResetRequest | null;
@@ -517,11 +1192,22 @@ export interface GazeApplyOptions {
   eyeEnabled?: boolean;
   headEnabled?: boolean;
   headFollowEyes?: boolean;
+  headFollowDelay?: number;
+  /** Fraction of total target bearing assigned to the head from reference neutral. Defaults to 1; head AU limits still apply. */
+  headFollowFraction?: number;
+  viewerTarget?: PolymerVector3;
+  viewerTargetSpace?: 'webcam.viewer';
+  viewerVerticalFovDegrees?: number;
+  viewerAspect?: number;
+  rawViewerTarget?: PolymerVector3;
+  /** Default false. True explicitly prefers the camera bearing instead of reference-neutral target following. */
+  lockHeadToCamera?: boolean;
   force?: boolean;
 }
 
 export interface GazeAttentionCandidate {
   target?: GazeTarget;
+  screenTarget?: GazeTarget;
   gazeTarget?: GazeTarget;
   lookTarget?: GazeTarget;
   x?: number;
@@ -536,19 +1222,25 @@ export interface GazeAttentionCandidate {
 }
 
 export type GazeDispatch =
+  | { type: 'attention.start' | 'attention.stop'; sessionId: string }
+  | { type: 'attention.scenario'; sessionId: string; scenario: GazeAttentionScenario }
   | { type: 'configure'; config: GazeConfig }
   | { type: 'setMode' | 'set-mode'; mode: string }
   | { type: 'setActive' | 'set-active'; active: boolean }
   | { type: 'enable' }
   | { type: 'disable' }
   | { type: 'setTarget' | 'set-target' | 'focusTarget'; target: GazeTarget; options?: GazeApplyOptions }
-  | { type: 'attention.fact'; targets?: GazeAttentionCandidate[]; target?: GazeTarget; source?: string }
-  | { type: 'camera.fact'; relativeOffset: GazeTarget; source?: string }
+  | { type: 'attention.fact'; targets?: GazeAttentionCandidate[]; target?: GazeTarget; screenTarget?: GazeTarget; targetSpace?: string; source?: string }
+  | ({ type: 'camera.fact'; relativeOffset: GazeTarget; source?: string } & Partial<CameraGazeGeometry>)
   | { type: 'camera.stale' | 'clearCameraOffset'; reason?: string; source?: string }
+  | Extract<PolymerDomainEvent, { type: 'userPerception.faceLost' | 'userPerception.status' }>
   | { type: 'reset'; durationMs?: number; eyes?: boolean; head?: boolean }
   | { type: 'cancel'; reason?: string };
 
 export interface GazeLookRequest {
+  attentionFeedback?: { sessionId: string; requestId: string; worldTarget: PolymerVector3 | null; timeoutMs: number; toleranceDeg: number } | null;
+  configurationRevision?: number;
+  coalesceMs?: number;
   type: 'eyeHeadTracking.requestGaze';
   agency: 'gaze';
   targetAgency: 'eyeHeadTracking';
@@ -557,7 +1249,12 @@ export interface GazeLookRequest {
   label?: string;
   mode: string;
   target: Required<GazeTarget>;
+  eyeTarget: Required<GazeTarget>;
+  headTarget: Required<GazeTarget>;
+  gazeSolution?: ScreenSpaceGazeSolution;
   rawTarget: Required<GazeTarget>;
+  predictedTarget: Required<GazeTarget>;
+  predictive: boolean;
   previousTarget: Required<GazeTarget>;
   eyeEnabled: boolean;
   headEnabled: boolean;
@@ -605,9 +1302,14 @@ export interface EyeHeadTrackingConfig {
   lookAtSpeaker?: boolean;
   idleVariation?: boolean;
   idleVariationInterval?: number;
+  /** Tracking contribution in [0, 1]; older values above 1 normalize to 1. With geometry-backed focus, live changes move toward the latest value without angular reversal braking. */
   eyeIntensity?: number;
   eyeBlendWeight?: number;
+  /** Tracking contribution in [0, 1], composed over authored head motion. With geometry-backed focus, live changes move toward the latest value without angular reversal braking. */
   headIntensity?: number;
+  trackingSpeed?: number;
+  /** Angular braking interval; geometry-backed strength changes bypass it. */
+  courseChangeDurationMs?: number;
   headBlendWeight?: number;
   headRoll?: number;
   eyePriority?: number;
@@ -656,12 +1358,19 @@ export interface EyeHeadGazeRequest {
   sourceAgency?: string;
   requestId: string;
   target: Required<GazeTarget>;
+  eyeTarget?: Required<GazeTarget>;
+  headTarget?: Required<GazeTarget>;
+  gazeSolution?: ScreenSpaceGazeSolution;
+  gazeFocus?: GazeFocusRequest;
   rawTarget?: Required<GazeTarget>;
   mode?: string;
   eyeEnabled?: boolean;
   headEnabled?: boolean;
   headFollowEyes?: boolean;
+  headFollowDelay?: number;
+  /** Tracking contribution in [0, 1]; older values above 1 normalize to 1. Live changes use scheduled motion. */
   eyeIntensity?: number;
+  /** Tracking contribution in [0, 1], composed over authored head motion. Live changes use scheduled motion. */
   headIntensity?: number;
   headRoll?: number;
   eyeDurationMs?: number;
@@ -709,11 +1418,37 @@ export interface AnimationScheduledSnippet {
   snippetCategory?: string;
   snippetPriority?: number;
   maxTime?: number;
+  cleanupMaxTime?: number;
   loop: boolean;
   autoPlay: boolean;
   requestedAt: number;
 }
 
+export interface AnimationBakedClipInfo {
+  name: string;
+  duration: number;
+  channels: unknown[];
+}
+
+export interface AnimationBakedUIState {
+  name: string;
+  source: 'baked';
+  time: number;
+  currentTime: number;
+  duration: number;
+  speed: number;
+  playbackRate: number;
+  intensityScale: number;
+  isPlaying: boolean;
+  isPaused: boolean;
+  loop: boolean;
+  loopMode: string;
+  reverse: boolean;
+  category: 'baked';
+  channels: unknown[];
+  [key: string]: unknown;
+}
+
 export interface AnimationState {
   agency: 'animation';
   scheduled: Record<string, AnimationScheduledSnippet>;
@@ -722,18 +1457,30 @@ export interface AnimationState {
   seekCount: number;
   updatedCount: number;
   removedCount: number;
+  bakedClips: AnimationBakedClipInfo[];
+  bakedByName: Record<string, AnimationBakedUIState>;
+  bakedPlaying: AnimationBakedUIState[];
   lastEvent: null | {
     type:
       | 'animationSnippetScheduled'
       | 'animationSnippetStarted'
       | 'animationSnippetSeeked'
       | 'animationSnippetUpdated'
-      | 'animationSnippetRemoved';
-    name: string;
-    sourceAgency: string;
+      | 'animationSnippetRemoved'
+      | 'animationBakedClipsLoaded'
+      | 'animationBakedStarted'
+      | 'animationBakedStopped'
+      | 'animationBakedPaused'
+      | 'animationBakedResumed'
+      | 'animationBakedSeeked'
+      | 'animationBakedUpdated';
+    name?: string;
+    clipName?: string;
+    sourceAgency?: string;
     reason?: string;
     offsetSec?: number;
     params?: Record<string, unknown>;
+    count?: number;
     at: number;
   };
 }
@@ -754,7 +1501,15 @@ export type AnimationDispatch =
   | { type: 'seekSnippet'; sourceAgency?: string; name: string; offsetSec: number }
   | { type: 'updateSnippet'; sourceAgency?: string; name: string; params: Record<string, unknown> }
   | { type: 'removeSnippet'; sourceAgency?: string; name: string }
-  | { type: 'clear'; sourceAgency?: string };
+  | { type: 'clear'; sourceAgency?: string }
+  | { type: 'loadBakedClips'; sourceAgency?: string; clips?: AnimationBakedClipInfo[] }
+  | { type: 'playBaked'; sourceAgency?: string; name: string; options?: Record<string, unknown> }
+  | { type: 'stopBaked'; sourceAgency?: string; name: string }
+  | { type: 'pauseBaked'; sourceAgency?: string; name: string }
+  | { type: 'resumeBaked'; sourceAgency?: string; name: string }
+  | { type: 'seekBaked'; sourceAgency?: string; name: string; offsetSec: number }
+  | { type: 'updateBakedParams'; sourceAgency?: string; name: string; params: Record<string, unknown> }
+  | { type: 'stopAllBaked'; sourceAgency?: string };
 
 export interface PolymerSnippetKeyframe {
   time: number;
@@ -792,6 +1547,8 @@ export interface PolymerAnimationHandle {
 }
 
 export interface PolymerAnimationRuntime {
+  /** Optional capability. Unsupported engines never produce confirmed Gaze alignment. */
+  getGazeObservation?: () => GazeObservation | null;
   buildClip?: (
     name: string,
     curves: Record<string, PolymerSnippetKeyframe[]>,
@@ -825,27 +1582,60 @@ export interface PolymerAnimationSnippet {
   curves?: Record<string, PolymerSnippetKeyframe[]>;
   channels?: PolymerSnippetChannel[];
   maxTime: number;
+  /** Optional visual curve end used for cleanup when it outlives the sync clock. */
+  cleanupMaxTime?: number;
   loop: boolean;
   snippetCategory?: string;
   snippetPriority: number;
   snippetPlaybackRate: number;
   snippetIntensityScale: number;
+  snippetBlendMode?: 'replace' | 'additive';
+  /** Neutral reference sample for converting a clip to additive rotation. */
+  additiveReferenceTimeSec?: number;
+  /** Stable order for zero-fade, once-only additive controls, even after other clips are removed. */
+  additiveCompositionOrder?: number;
   snippetJawScale?: number;
   autoVisemeJaw?: boolean;
   metadata?: Record<string, unknown>;
 }
 
 export interface LipSyncConfig {
+  /**
+   * Resolve from the active runtime profile once per profile change. Explicitly configuring
+   * this field rebuilds an active clip even when equal (setProfile may clear runtime actions).
+   * Null retains legacy canonical routing. Never configure it every frame.
+   */
+  visemeProfile?: ResolvedVisemeProfile | null;
   intensity?: number;
   speechRate?: number;
   jawScale?: number;
   /** Scale for independently planned tongue AU curves. Set 0 to disable tongue motion. */
   tongueScale?: number;
-  rampMs?: number;
-  holdMs?: number;
   priority?: number;
+  /**
+   * Scales the shared viseme-to-viseme handoff window. Higher values produce a
+   * longer pose blend without returning the mouth to neutral. Default 1.75.
+   */
+  envelopeTimeScale?: number;
   visualLeadMs?: number;
+  /** Mixer fade-in for the scheduled utterance clip (seconds). Default 0.15. */
+  fadeInSec?: number;
+  /** Mixer fade-out when the utterance is stopped or replaced (seconds). Default 0.12. */
+  fadeOutSec?: number;
+  /** Mixer blend mode: "replace" (default) or "additive". */
+  blendMode?: 'replace' | 'additive' | string;
+  /**
+   * Keyframe easing applied by the Embody host when densifying scalar tracks.
+   * Default "easeInOutCubic".
+   */
+  easing?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'easeInOutCubic' | string;
+  webSpeechDriftThresholdSec?: number;
+  azureDriftThresholdSec?: number;
   wordDriftThresholdSec?: number;
+  /** Per-viseme jaw opening amounts, usually from the character profile. */
+  visemeJawAmounts?: number[];
+  /** Per-viseme tongue AU targets, supplied by the resolved character preset/profile. */
+  visemeTongueTargets?: VisemeTongueTarget[];
 }
 
 export interface LipSyncRuntime {
@@ -858,13 +1648,11 @@ export interface LipSyncRuntime {
 }
 
 export interface LipSyncVisemeEvent {
+  /** Canonical articulation ID, independent of the destination model slot. */
   visemeId: number;
-  /**
-   * Optional independent jaw-axis activation for this event. When omitted,
-   * Polymer derives a default from the canonical viseme slot. Set to 0 for a
-   * lip-only viseme, or scale with LipSyncConfig.jawScale for JALI-style control.
-   */
-  jawActivation?: number;
+  /** Optional explicit provider identity; unknown/ambiguous routes remain neutral. */
+  provider?: string;
+  providerId?: string | number;
   phoneme?: string;
   /**
    * Primary visual-speech class for planner rules, e.g. vowel, bilabial,
@@ -908,6 +1696,14 @@ export interface LipSyncTimeline {
   durationSec?: number;
 }
 
+/** Voice facts TTS relays with an utterance. Only speechRate is acted on today. */
+export interface LipSyncVoiceFacts {
+  speechRate?: number;
+  volume?: number;
+  pitch?: number;
+  style?: string;
+}
+
 export interface LipSyncState {
   agency: 'lipSync';
   speaking: boolean;
@@ -916,6 +1712,7 @@ export interface LipSyncState {
   snippetName: string | null;
   source: string | null;
   text: string | null;
+  voice: LipSyncVoiceFacts | null;
   startTime: number | null;
   audioStartedAt: number | null;
   audioTimeSec: number | null;
@@ -925,7 +1722,12 @@ export interface LipSyncState {
   scheduledCount: number;
   stoppedCount: number;
   syncCorrectionCount: number;
-  config: Required<LipSyncConfig>;
+  rebuildCount: number;
+  config: Required<Omit<LipSyncConfig, 'visemeJawAmounts' | 'visemeTongueTargets' | 'visemeProfile'>> & {
+    visemeProfile: ResolvedVisemeProfile | null;
+    visemeJawAmounts: number[] | null;
+    visemeTongueTargets: VisemeTongueTarget[] | null;
+  };
   lastEvent: null | Record<string, unknown>;
 }
 
@@ -939,6 +1741,10 @@ export type LipSyncDispatch =
       wordTimings?: LipSyncWordTiming[];
       durationSec?: number;
       totalDurationMs?: number;
+      speechRate?: number;
+      volume?: number;
+      pitch?: number;
+      style?: string;
     }
   | { type: 'startTimeline'; timeline: LipSyncTimeline }
   | {
@@ -949,6 +1755,10 @@ export type LipSyncDispatch =
       text?: string;
       source?: string;
       wordTimings?: LipSyncWordTiming[];
+      speechRate?: number;
+      volume?: number;
+      pitch?: number;
+      style?: string;
       options?: { wordTimings?: LipSyncWordTiming[]; visualLeadMs?: number; [key: string]: unknown };
     }
   | { type: 'wordBoundary'; word: string; wordIndex?: number; observedElapsedSec?: number; hostElapsedSec?: number }
@@ -965,6 +1775,8 @@ export interface TTSVoice {
   lang?: string;
   gender?: string;
   styles?: string[];
+  /** False for Google/network Web Speech voices that omit onboundary events. */
+  localService?: boolean;
   provider?: 'webSpeech' | 'azure' | string;
 }
 
@@ -975,16 +1787,10 @@ export interface TTSConfig {
   azureVoiceName?: string;
   azureStyle?: string;
   azureStyleDegree?: string | number | null;
+  /** Voice facts. Relayed to LipSync on each utterance; rate is live today. */
   rate?: number;
   pitch?: number;
   volume?: number;
-  visualLeadMs?: number;
-  lipsyncIntensity?: number;
-  jawScale?: number;
-  /** Scale for LipSync tongue AU planning forwarded by TTS before each speech session. */
-  tongueScale?: number;
-  webSpeechDriftThresholdSec?: number;
-  azureDriftThresholdSec?: number;
   azureCacheLimit?: number;
   debug?: boolean;
   /** Experimental Web Speech barge-in reference: none | displayMedia */
@@ -1018,6 +1824,9 @@ export type TTSDispatch =
   | {
       type: 'speak';
       text: string;
+      turnId?: string;
+      requestId?: string;
+      speechId?: string;
       engine?: 'webSpeech' | 'azure' | 'livekit' | string;
       name?: string;
       backendUrl?: string;
@@ -1026,17 +1835,161 @@ export type TTSDispatch =
       rate?: number;
       pitch?: number;
       volume?: number;
-      visualLeadMs?: number;
     }
-  | { type: 'stop' }
+  | { type: 'releasePlaybackReference' }
+  | { type: 'stop'; reason?: string; turnId?: string; requestId?: string; speechId?: string }
   | { type: 'reset' };
 
+export type ProsodicProfileSnippet = Record<string, unknown> & {
+  name: string;
+};
+
+export type ProsodicProfileSnippetInput =
+  | ProsodicProfileSnippet
+  | ({ snippet: ProsodicProfileSnippet } & Record<string, unknown>);
+
 export interface ProsodicConfig {
   enabled?: boolean;
   intensity?: number;
   priority?: number;
   speechGestureEvery?: number;
+  browPulseEvery?: number;
+  headPulseEvery?: number;
+  browIntensity?: number;
+  headIntensity?: number;
+  openingMovement?: boolean;
   blinkFastCooldownMs?: number;
+  /** Saved speaking brow snippet selected by the active character profile. */
+  browSnippet?: ProsodicProfileSnippetInput;
+  /** Saved speaking head snippet selected by the active character profile. */
+  headSnippet?: ProsodicProfileSnippetInput;
+}
+
+/** Supported portable live settings; asset bodies and private clocks are not authored here. */
+export type ProsodicEditableConfiguration = Pick<ProsodicConfig,
+  'headIntensity' | 'browIntensity' | 'headPulseEvery' | 'browPulseEvery' | 'openingMovement'>;
+
+/** Scalar policy fields supported by an agency's revisioned apply API. */
+export interface AgencyParameter<Key extends string = string> {
+  key: Key;
+  label: string;
+  type: 'number' | 'boolean';
+  default: number | boolean;
+  minimum?: number;
+  maximum?: number;
+  step?: number;
+  unit?: string;
+  description: string;
+  applyBoundary: 'next-decision';
+}
+
+export interface AgencyConfigurationReceipt {
+  status: 'applied' | 'rejected';
+  requestedRevision: number;
+  appliedRevision: number;
+  reason?: string;
+}
+
+export interface AgencyConfigurationState {
+  appliedRevision: number;
+  applyBoundary: 'next-decision';
+}
+
+export interface ProsodicParameter extends AgencyParameter<keyof ProsodicEditableConfiguration> {}
+
+export type GestureEditableConfiguration = Pick<GestureConfig,
+  'intensity' | 'priority' | 'defaultDurationMs' | 'cooldownMs' | 'rampRatio'
+  | 'holdRatio' | 'returnToBase' | 'replaceActive' | 'maxActive'>;
+export type GazeEditableConfiguration = Pick<GazeConfig,
+  'headFollowDelay' | 'predictionEnabled' | 'trackingSpeed' | 'coalesceMs'
+  | 'attentionInfluenceA' | 'attentionInfluenceB' | 'attentionDwellMs'
+  | 'attentionSwitchMargin' | 'attentionToleranceDeg' | 'attentionTimeoutMs'>;
+export type CameraContextEditableConfiguration = Pick<CameraContextConfig,
+  'coalesceMs' | 'staleAfterMs' | 'yawWeight' | 'pitchWeight'>;
+
+export interface GestureDefinition {
+  id: 'gesture';
+  family: 'action';
+  definitionVersion: 1;
+  parameters: AgencyParameter<keyof GestureEditableConfiguration>[];
+}
+export interface GazeDefinition {
+  id: 'gaze';
+  family: 'cognition';
+  definitionVersion: 2;
+  parameters: AgencyParameter<keyof GazeEditableConfiguration>[];
+}
+export interface CameraContextDefinition {
+  id: 'cameraContext';
+  family: 'perception';
+  definitionVersion: 1;
+  parameters: AgencyParameter<keyof CameraContextEditableConfiguration>[];
+}
+
+/** Safe decision projection, not an execution receipt or replay record. */
+export interface GazeDecision {
+  trigger: string;
+  configurationRevision: number;
+  source: string;
+  mode: string;
+  predictive: boolean;
+  outcome: 'requested' | 'reset-requested' | 'cancel-requested' | 'ignored' | 'rejected' | 'state-updated';
+  reason: string | null;
+  confirmation: 'unobserved';
+  at: number;
+}
+
+export interface GestureDecision {
+  sequence: number;
+  trigger: string;
+  configurationRevision: number;
+  at: number;
+  status: 'requested' | 'not-requested';
+  reason: string | null;
+  activeRequestCount: number;
+}
+
+export interface CameraContextDecision {
+  sequence: number;
+  configurationRevision: number;
+  outcome: 'requested' | 'published';
+  observedAt: number;
+  publishedAt?: number;
+  gazeGeometryComplete: boolean;
+}
+
+export interface ProsodicDefinition {
+  id: 'prosodic';
+  family: 'action';
+  definitionVersion: 1;
+  parameters: ProsodicParameter[];
+}
+
+export interface ProsodicOptions extends ProsodicConfig {
+  /** Private constructor-only millisecond clock for synthetic fixtures. Never serialized. */
+  now?: () => number;
+}
+
+export interface ProsodicConfigurationReceipt extends AgencyConfigurationReceipt {}
+
+/** A compact inspection projection, not a complete captured-session replay record. */
+export interface ProsodicDecision {
+  sequence: number;
+  trigger: string;
+  configurationRevision: number;
+  at: number;
+  outcomes: Array<
+    | {
+        status: 'selected';
+        gesture: string;
+        name: string;
+        effectivePeak: number;
+        /** Request emitted, not a rendered-frame acknowledgment. */
+        outcome: 'requested';
+      }
+    | { status: 'missing-asset'; gesture: string; reason: string }
+    | { status: 'suppressed'; reason: string }
+  >;
 }
 
 export interface ProsodicState {
@@ -1049,7 +2002,23 @@ export interface ProsodicState {
   removedCount: number;
   lastGesture: string | null;
   lastBlinkFastCueAt: number;
-  config: Required<ProsodicConfig>;
+  loadedSnippetNames: string[];
+  config: Required<Omit<ProsodicConfig, 'browSnippet' | 'headSnippet'>>;
+  configuration: { appliedRevision: number; applyBoundary: 'next-decision' };
+  lifecycle: 'active' | 'quiescing' | 'disabled' | 'disposed';
+  routingEnabled: boolean;
+  cleanup: {
+    status: 'not-requested' | 'requested';
+    requestedNames: string[];
+    requestedAt?: number;
+    reason?: string;
+    /** Prosodic does not receive runtime cleanup acknowledgments in this pilot. */
+    confirmation: 'unobserved';
+  };
+  scheduler: { retained: number; limit: number; nextSequence: number; dropped: number };
+  lastDecision: ProsodicDecision | null;
+  rejectedCommandCount: number;
+  lastCommandRejection: { commandType: string; reason: string } | null;
   lastEvent: null | Record<string, unknown>;
 }
 
@@ -1073,19 +2042,67 @@ export interface ConversationConfig {
   autoRespond?: boolean;
   maxHistory?: number;
   responseSource?: string;
+  /** Text replies complete when accepted. Speech (default) waits for TTS playout. */
+  responseDelivery?: 'speech' | 'text';
   ttsAgency?: string;
   interruptionMode?: string;
+  /** Snapshot of module speech settings applied to each utterance. */
+  speechConfig?: TTSConfig;
+  transcriptionConfig?: TranscriptionConfig;
   autoListen?: boolean;
   detectInterruptions?: boolean;
+  /** Minimum playback time for transcript fallback; sustained audio is accepted immediately. */
   minSpeakTime?: number;
   allowTranscriptInterruptionFallback?: boolean;
   eyeHeadTracking?: EyeHeadTrackingService | unknown;
   prosodicService?: unknown;
 }
 
+/** Context identities are scoped to one Conversation instance. Revisions strictly
+ * increase for replacement and removal. Reset clears the bounded registry. */
+export interface ConversationContextRef {
+  namespace: string;
+  sourceId: string;
+  revision: number;
+}
+export interface ConversationContext extends ConversationContextRef {
+  schemaVersion: 1;
+  /** Plain JSON, depth <= 8 and serialized length <= 8192 UTF-16 code units. */
+  content: unknown;
+}
+export type ConversationTurnPurpose = 'explain' | 'ask' | 'clarify' | 'feedback';
+export interface ConversationRequestedTurn {
+  /** Unique per session; duplicate requests are ignored, including after outcome. */
+  requestId: string;
+  purpose: ConversationTurnPurpose;
+  objective: string;
+}
+export interface ConversationSpeechIdentity {
+  turnId: string;
+  requestId?: string;
+  speechId: string;
+}
+export interface ConversationTurnOutcome {
+  type: 'conversation.turnOutcome';
+  agency: 'conversation';
+  requestId: string;
+  turnId: string;
+  purpose: ConversationTurnPurpose;
+  contextRefs: ConversationContextRef[];
+  outcome: 'completed' | 'interrupted' | 'cancelled' | 'failed';
+  /** True when playout began; only completed guarantees the whole text played. */
+  spoken: boolean;
+  reason: string;
+  at: number;
+}
+
 export interface ConversationProviderRequest {
   requestId: string;
-  text: string;
+  /** Null for agency-requested dialogue; never fabricated as a user utterance. */
+  text: string | null;
+  requestedTurn?: ConversationRequestedTurn | null;
+  contextRefs?: ConversationContextRef[];
+  contexts?: ConversationContext[];
   source: string;
   turnId?: string;
   history: Array<Record<string, unknown>>;
@@ -1124,6 +2141,9 @@ export interface ConversationHistoryEntry {
   source?: string;
   at?: number;
   turnId?: string | null;
+  requestId?: string | null;
+  contextRefs?: ConversationContextRef[];
+  deliveryStatus?: 'requested' | 'pending' | 'speaking' | 'delivered' | 'interrupted' | 'cancelled' | 'failed';
 }
 
 export interface ConversationState {
@@ -1133,7 +2153,15 @@ export interface ConversationState {
   turnId: string | null;
   history: ConversationHistoryEntry[];
   context: Record<string, unknown>;
+  contexts: Record<string, ConversationContext>;
+  contextVersions: Record<string, number>;
+  activeTurn: (Partial<ConversationRequestedTurn> & { turnId: string; contextRefs: ConversationContextRef[]; speechId?: string; responseDelivery: 'speech' | 'text'; spoken: boolean }) | null;
+  seenRequests: string[];
   pendingResponse: Record<string, unknown> | null;
+  activeSpeechId: string | null;
+  /** Conversation has requested speech resources that still require release. */
+  speechResourcesRequested: boolean;
+  playbackStartedAt: number | null;
   lastProviderError: string | null;
   lastUserText: string | null;
   lastAgentText: string | null;
@@ -1154,10 +2182,20 @@ export type ConversationDispatch =
   | { type: 'start' }
   | { type: 'stop'; reason?: string }
   | { type: 'reset' }
-  | { type: 'cancel' | 'interrupt'; reason?: string }
+  | { type: 'cancel' | 'interrupt'; reason?: string; requestId?: string }
+  | ({ type: 'context.upsert' } & ConversationContext)
+  | ({ type: 'context.remove' } & ConversationContextRef)
+  | ({ type: 'requestTurn'; contextRefs: ConversationContextRef[] } & ConversationRequestedTurn)
+  | ({ type: 'ttsSpeechStarted' | 'ttsSpeechStopped' | 'ttsSpeechEnded' | 'ttsSpeechFailed'; reason?: string; message?: string } & ConversationSpeechIdentity)
   | { type: 'transcript.final' | 'transcriptFinal' | 'userUtterance'; text?: string; transcript?: string; utterance?: string; responseText?: string; agentText?: string; source?: string }
   | { type: 'agentUtterance' | 'responseReady'; text?: string; utterance?: string; responseText?: string; agentText?: string; requestId?: string; turnId?: string; source?: string }
   | { type: 'providerError'; requestId?: string; turnId?: string; message?: string }
+  | { type: 'listen' | 'pauseListening' | 'flowStart' }
+  | { type: 'audioInterruption' | 'transcriptInterruption'; event?: InterruptionEvent; text?: string }
+  | { type: 'transcript.partial'; text: string }
+  | { type: 'ttsSpeechStarted' | 'ttsSpeechStopped' | 'ttsSpeechEnded'; name?: string }
+  | { type: 'transcriptionStatus'; status: string; reason?: string }
+  | { type: 'ttsError'; message: string }
   | { type: 'tts.status'; status?: string };
 
 export interface TranscriptionConfig {
@@ -1207,6 +2245,7 @@ export interface TranscriptionState {
 export type TranscriptionDispatch =
   | { type: 'configure'; config: TranscriptionConfig }
   | { type: 'start' }
+  | { type: 'release' }
   | { type: 'stop' | 'cancel'; reason?: string }
   | { type: 'reset' }
   | { type: 'providerPartial' | 'partialTranscript' | 'providerFinal' | 'finalTranscript'; text?: string; transcript?: string; confidence?: number; source?: string; speaker?: string }
@@ -1217,6 +2256,7 @@ export type TranscriptionDispatch =
 
 export interface CameraContextConfig {
   coalesceMs?: number;
+  /** Expiry for streaming owners; defaults to 0 (valid until explicitly invalidated). */
   staleAfterMs?: number;
   epsilon?: number;
   yawWeight?: number;
@@ -1237,11 +2277,22 @@ export interface PolymerQuaternion {
 }
 
 export interface CameraContextState {
+  configuration: AgencyConfigurationState;
+  family: 'perception';
+  lastDecision: CameraContextDecision | null;
+  /** Safe bounded inspection projection; full operational snapshots are not redacted. */
+  summary: Pick<CameraContextState,
+    'status' | 'stale' | 'updateCount' | 'publishedCount' | 'lastUpdatedAt' | 'lastPublishedAt' | 'lastDecision'>;
   agency: 'cameraContext';
   status: string;
   cameraPosition: PolymerVector3 | null;
+  cameraQuaternion: PolymerQuaternion;
   targetPosition: PolymerVector3 | null;
+  gazeOrigin: PolymerVector3 | null;
   modelQuaternion: PolymerQuaternion;
+  verticalFovDegrees: number;
+  aspect: number;
+  gazeGeometryComplete: boolean;
   relativeOffset: Required<GazeTarget>;
   lastUpdatedAt: number | null;
   lastPublishedAt: number | null;
@@ -1261,14 +2312,145 @@ export type CameraContextDispatch =
       type: 'updateCamera';
       facts?: Record<string, unknown>;
       cameraPosition?: PolymerVector3;
+      cameraQuaternion?: PolymerQuaternion;
       targetPosition?: PolymerVector3;
+      gazeOrigin?: PolymerVector3;
+      characterEyePosition?: PolymerVector3;
       modelQuaternion?: PolymerQuaternion;
+      verticalFovDegrees?: number;
+      aspect?: number;
       source?: string;
     }
   | { type: 'publishCameraFacts' }
   | { type: 'invalidateStale'; reason?: string }
   | { type: 'reset' };
 
+export interface UserPerceptionConfig {
+  enabled?: boolean;
+  /** Package asset by default; may be replaced by a host-controlled URL. */
+  modelAssetPath?: string;
+  /** Package MediaPipe WASM directory by default; may be replaced by a URL. */
+  wasmRoot?: string;
+  /** Package inference worker by default; may be replaced by a worker URL. */
+  workerUrl?: string;
+  delegate?: 'CPU' | 'GPU';
+  maxFaces?: number;
+  maxInferenceFps?: number;
+  minDetectionConfidence?: number;
+  minTrackingConfidence?: number;
+  minPresenceConfidence?: number;
+  /** Retained history over 50ms, from 0 (immediate) through 0.95. Applied to eye-midpoint XY using elapsed time. */
+  smoothing?: number;
+  /** Whether inference pixels are already mirrored. Default false reflects raw webcam X into display-right NDC; a CSS preview does not affect this. */
+  mirrored?: boolean;
+  /** Default true: use the first accepted face as this session's eye-contact origin. False retains absolute webcam-centered coordinates. */
+  centerOnFirstFace?: boolean;
+  faceLossGraceMs?: number;
+  maxRetries?: number;
+  retryBackoffMs?: number;
+  candidatePriority?: number;
+  diagnosticIntervalMs?: number;
+  videoWidth?: number;
+  videoHeight?: number;
+  /** Assumed/calibrated webcam vertical field of view. Default 50 degrees. */
+  viewerVerticalFovDegrees?: number;
+  /** Physical eye-center spacing used only for diagnostic depth estimation. Default 0.063m. */
+  viewerInterpupillaryDistanceMeters?: number;
+  /** Fixed projection depth shared by webcam and mouse tracking. Default 0.8m. */
+  viewerFallbackDepthMeters?: number;
+  /** Lower bound for diagnostic depth only. */
+  viewerMinDepthMeters?: number;
+  /** Upper bound for diagnostic depth only. */
+  viewerMaxDepthMeters?: number;
+}
+
+export interface UserPerceptionCameraMetadata {
+  width: number;
+  height: number;
+}
+
+export interface UserPerceptionFaceObservation {
+  id: string;
+  confidence?: number;
+  score?: number;
+  bounds: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+    area: number;
+    center: PolymerVector3;
+  };
+  /** Binocular midpoint of the anatomical eye-corner centers, independent of pupil motion. */
+  eyeMidpoint: PolymerVector3;
+  /** Compact separation; z uses MediaPipe's approximate normalized-X depth scale. */
+  interocularDistance?: { x: number; y: number; z?: number; normalized?: number };
+  /** Observational iris offset, not calibrated gaze direction. */
+  irisDirection?: { x: number; y: number } | null;
+  headPose: { yaw: number; pitch: number; roll: number };
+}
+
+export interface UserPerceptionState {
+  agency: 'userPerception';
+  status: 'idle' | 'requestingPermission' | 'loadingModel' | 'ready' | 'observing' | 'faceLost' | 'backingOff' | 'stopped' | 'error' | string;
+  active: boolean;
+  visible: boolean;
+  permission: 'unknown' | 'prompt' | 'granted' | 'denied' | string;
+  cameraStatus: string;
+  /** Negotiated/captured dimensions, retained after stop until reset or acquisition. */
+  cameraMetadata: UserPerceptionCameraMetadata | null;
+  modelStatus: string;
+  faceDetected: boolean;
+  selectedFaceConfidence: number | null;
+  target: Required<GazeTarget>;
+  /** Fixed display-right/up normalized eye-midpoint offset for this activation; never persisted across sessions. */
+  eyeContactReference: { x: number; y: number } | null;
+  lastObservationAt: number | null;
+  lastAcceptedAt: number | null;
+  lastDiagnosticAt: number | null;
+  lastCameraFact: Record<string, unknown> | null;
+  lastObservation: Record<string, unknown> | null;
+  lastError: { message: string; phase: string; retrying: boolean; at: number } | null;
+  lastPlan: Record<string, unknown> | null;
+  lastEvent: Record<string, unknown> | null;
+  retryCount: number;
+  capturedFrameCount: number;
+  inferenceCount: number;
+  acceptedCount: number;
+  rejectedCount: number;
+  droppedFrameCount: number;
+  faceLostCount: number;
+  config: Required<UserPerceptionConfig>;
+}
+
+export type UserPerceptionDispatch =
+  | { type: 'configure' | 'userPerception.configure'; config: UserPerceptionConfig }
+  | { type: 'start' | 'userPerception.start' }
+  | { type: 'stop' | 'userPerception.stop'; reason?: string }
+  | { type: 'reset' | 'userPerception.reset' }
+  | { type: 'recenter' | 'userPerception.recenter' }
+  | Extract<PolymerDomainEvent, { type: 'camera.fact' | 'camera.stale' }>;
+
+/** Injectable browser boundary for deterministic tests and alternate hosts. */
+export interface UserPerceptionRuntime {
+  acquireCamera?(config: Required<UserPerceptionConfig>): unknown | Promise<unknown>;
+  releaseCamera?(handle: unknown): void;
+  createWorker?(url: string): Worker;
+  loadModel?(config: Required<UserPerceptionConfig>): unknown | Promise<unknown>;
+  observe?(config: Required<UserPerceptionConfig>, observedAt: number, requestId: string): {
+    observedAt: number;
+    faces: UserPerceptionFaceObservation[];
+    cameraMetadata?: UserPerceptionCameraMetadata;
+  } | Promise<{
+    observedAt: number;
+    faces: UserPerceptionFaceObservation[];
+    cameraMetadata?: UserPerceptionCameraMetadata;
+  }>;
+  isDocumentVisible?(): boolean;
+}
+
 export type LipSyncSchedulerQueueEntry =
   | {
       type: 'scheduleAnimation';
@@ -1328,7 +2510,7 @@ export type ProsodicSchedulerQueueEntry =
 
 export type TTSSchedulerQueueEntry =
   | {
-      type: 'webSpeechStartFallback';
+      type: 'webSpeechStartFallback' | 'webSpeechBoundaryWatchdog' | 'ttsCompletionWatchdog';
       agency: 'tts';
       sessionId: number;
       delayMs: number;
@@ -1428,6 +2610,11 @@ export interface GestureConfig {
   gestureEmojiMappings?: Record<string, string>;
 }
 
+export interface GestureOptions extends GestureConfig {
+  /** Private constructor-only clock; never authored in society data. */
+  now?: () => number;
+}
+
 export interface GestureGoal {
   gestureId?: string;
   id?: string;
@@ -1468,6 +2655,10 @@ export interface GestureActiveSnippet {
 }
 
 export interface GestureState {
+  configuration: AgencyConfigurationState;
+  lastDecision: GestureDecision | null;
+  lifecycle: 'active' | 'disposed';
+  rejectedCommandCount: number;
   agency: 'gesture';
   gestures: string[];
   gestureCount: number;
@@ -1506,6 +2697,14 @@ export interface PolymerInputStream<TCommand> extends PolymerStream<{ type: 'com
 
 
 export type PolymerDomainEvent =
+  | { type: 'gaze.attention'; agency: 'gaze'; attention: GazeAttentionState }
+  | { type: 'animation.requestObserveGaze'; agency: 'eyeHeadTracking'; requestId: string; sessionId: string; worldTarget: PolymerVector3 | null; timeoutMs: number; toleranceDeg: number }
+  | { type: 'animation.requestCancelGazeObservation'; agency: 'eyeHeadTracking'; requestId: string | null }
+  | { type: 'animation.gazeFeedback'; agency: 'animation'; requestId: string; status: 'observed' | 'unavailable'; reason: string; angularErrorDeg?: number; sampleSequence?: number; observedAt?: number; bindingGeneration?: number }
+  | { type: 'gaze.configurationChanged'; agency: 'gaze'; configuration: AgencyConfigurationState; configure: GazeEditableConfiguration }
+  | { type: 'gaze.decision'; agency: 'gaze'; decision: GazeDecision }
+  | { type: 'gestureDecision'; agency: 'gesture'; decision: GestureDecision }
+  | { type: 'gestureCommandRejected'; agency: 'gesture'; commandType: string; reason: 'revision-exhausted' }
   | {
       /** Diagnostic telemetry emitted after a graph route dispatch succeeds. */
       type: 'society.routeActivated';
@@ -1623,18 +2822,24 @@ export type PolymerDomainEvent =
   | GazeLookRequest
   | GazeResetRequest
   | GazeCancelRequest
-  | { type: 'camera.status'; agency: 'cameraContext'; status: string; stale: boolean; reason?: string; at: number }
+  | { type: 'camera.status'; agency: 'cameraContext'; status: string; stale: boolean; reason?: string; at: number; configurationRevision: number }
   | {
       type: 'camera.fact';
       agency: 'cameraContext';
+      configurationRevision: number;
       kind: 'camera.relative';
       sequence: number;
       source: string;
       observedAt: number;
       publishedAt: number;
       cameraPosition: Record<string, number>;
+      cameraQuaternion: Record<string, number>;
       targetPosition: Record<string, number>;
+      gazeOrigin: Record<string, number>;
       modelQuaternion: Record<string, number>;
+      verticalFovDegrees: number;
+      aspect: number;
+      gazeGeometryComplete: boolean;
       relativeOffset: Required<GazeTarget>;
       stale: false;
     }
@@ -1648,6 +2853,55 @@ export type PolymerDomainEvent =
       lastObservedAt?: number;
       lastRelativeOffset?: Required<GazeTarget>;
     }
+  | {
+      type: 'userPerception.status';
+      agency: 'userPerception';
+      status: string;
+      active: boolean;
+      visible: boolean;
+      permission: string;
+      cameraStatus: string;
+      cameraMetadata?: UserPerceptionCameraMetadata | null;
+      modelStatus: string;
+      faceDetected: boolean;
+      reason?: string;
+      at: number;
+    }
+  | {
+      type: 'attention.fact';
+      agency: 'userPerception';
+      targetAgency: 'gaze';
+      source: 'userPerception';
+      label: string;
+      observedAt: number;
+      confidence?: number | null;
+      priority: number;
+      target: Required<GazeTarget>;
+      screenTarget: Required<GazeTarget>;
+      targetSpace: 'screen.ndc';
+      viewerTarget: Required<GazeTarget>;
+      viewerTargetSpace: 'webcam.viewer';
+      viewerVerticalFovDegrees: number;
+      viewerAspect: number;
+      cameraMetadata?: UserPerceptionCameraMetadata | null;
+      rawViewerTarget: Required<GazeTarget>;
+      options?: GazeApplyOptions;
+      rawTarget: Required<GazeTarget>;
+      face: Pick<UserPerceptionFaceObservation, 'id' | 'bounds' | 'eyeMidpoint' | 'interocularDistance' | 'headPose' | 'irisDirection'>;
+    }
+  | {
+      type: 'userPerception.observation';
+      agency: 'userPerception';
+      observedAt: number;
+      confidence?: number | null;
+      target: Required<GazeTarget>;
+      viewerTarget: Required<GazeTarget>;
+      cameraMetadata?: UserPerceptionCameraMetadata | null;
+      face: Record<string, unknown>;
+      at: number;
+    }
+  | { type: 'userPerception.faceLost'; agency: 'userPerception'; reason: string; lastSeenAt?: number; at: number }
+  | { type: 'userPerception.ignored'; agency: 'userPerception'; reason: string; commandType?: string; at: number }
   | {
       type: 'eyeHeadTracking.status';
       agency: 'eyeHeadTracking';
@@ -1711,9 +2965,10 @@ export type PolymerDomainEvent =
       status?: 'checking' | 'ready' | 'error' | string;
       message?: string;
     }
-  | { type: 'ttsSpeechStarted'; agency: 'tts'; engine: string; name: string; startedAt: number }
-  | { type: 'ttsSpeechStopped'; agency: 'tts'; reason: string; stoppedAt: number }
-  | { type: 'ttsSpeechEnded'; agency: 'tts'; endedAt: number }
+  | ({ type: 'ttsSpeechStarted'; agency: 'tts'; engine: string; name: string; text?: string; startedAt: number } & Partial<ConversationSpeechIdentity>)
+  | ({ type: 'ttsSpeechStopped'; agency: 'tts'; reason: string; name?: string | null; stoppedAt: number } & Partial<ConversationSpeechIdentity>)
+  | ({ type: 'ttsSpeechEnded'; agency: 'tts'; name?: string | null; endedAt: number } & Partial<ConversationSpeechIdentity>)
+  | ({ type: 'ttsSpeechFailed'; agency: 'tts'; name?: string | null; message: string } & Partial<ConversationSpeechIdentity>)
   | { type: 'ttsPlaybackReferenceChanged'; agency: 'tts'; available: boolean; at: number }
   | {
       type: 'ttsWordBoundary';
@@ -1724,11 +2979,17 @@ export type PolymerDomainEvent =
       hostElapsedSec?: number;
     }
   | { type: 'lipSync.command'; agency: 'tts'; command: LipSyncDispatch }
+  | { type: 'conversation.ttsReleaseReferenceRequested'; agency: 'conversation'; command: TTSDispatch }
+  | { type: 'conversation.ttsConfigureRequested'; agency: 'conversation'; command: TTSDispatch }
+  | { type: 'conversation.transcriptionRequested'; agency: 'conversation'; command: TranscriptionDispatch }
+  | { type: 'conversation.transcript'; agency: 'conversation'; text: string; isFinal: boolean; isInterruption: boolean; at: number }
   | { type: 'conversation.status'; agency: 'conversation'; status: string; turnId?: string; reason?: string; at: number }
   | { type: 'conversation.userUtterance'; agency: 'conversation'; text: string; source: string; turnId?: string; at: number }
-  | { type: 'conversation.requestResponse'; agency: 'conversation'; targetAgency: string; requestId: string; text: string; source: string; turnId?: string; history: Array<Record<string, unknown>>; requestedAt: number }
+  | ({ type: 'conversation.requestResponse'; agency: 'conversation'; targetAgency: string } & ConversationProviderRequest)
+  | ({ type: 'conversation.turnRequested'; agency: 'conversation'; turnId: string; contextRefs: ConversationContextRef[]; spoken: false; at: number } & ConversationRequestedTurn)
+  | ConversationTurnOutcome
   | { type: 'conversation.providerError'; agency: 'conversation'; requestId: string; turnId?: string; message: string; at: number }
-  | { type: 'conversation.agentUtterance'; agency: 'conversation'; text: string; at: number }
+  | { type: 'conversation.agentUtterance'; agency: 'conversation'; text: string; source: string; turnId: string; at: number }
   | { type: 'conversation.cancelRequested'; agency: 'conversation'; targetAgency: string; reason: string; turnId?: string; at: number }
   | { type: 'conversation.ignored'; agency: 'conversation'; reason: string; requestId?: string; turnId?: string; at: number }
   | { type: 'tts.requestSpeak'; agency: 'conversation'; targetAgency: string; requestId: string; text: string; source: string; turnId?: string; command: TTSDispatch; requestedAt: number }
@@ -1758,6 +3019,8 @@ export type PolymerDomainEvent =
   | { type: 'gestureRemoved'; agency: 'gesture'; name: string; reason: string; removedAt: number }
   | { type: 'prosodicPlanCreated'; agency: 'prosodic'; plan: Record<string, unknown> }
   | { type: 'prosodicConfigChanged'; agency: 'prosodic'; state: ProsodicState }
+  | { type: 'prosodicDecision'; agency: 'prosodic'; decision: ProsodicDecision }
+  | { type: 'prosodicCommandRejected'; agency: 'prosodic'; rejection: { commandType: string; reason: string } }
   | { type: 'prosodicSpeechStarted'; agency: 'prosodic'; name?: string; startedAt: number }
   | { type: 'prosodicWordBoundary'; agency: 'prosodic'; word?: string; wordIndex: number; observedAt: number }
   | {
@@ -1770,7 +3033,7 @@ export type PolymerDomainEvent =
       scheduledAt: number;
     }
   | { type: 'prosodicStopped'; agency: 'prosodic'; reason: string; stoppedAt: number }
-  | { type: string; agency: 'conversation' | 'transcription' | 'cameraContext'; [key: string]: unknown }
+  | { type: string; agency: 'conversation' | 'transcription' | 'cameraContext' | 'userPerception'; [key: string]: unknown }
   | {
       type: 'ready';
       agency:
@@ -1785,7 +3048,8 @@ export type PolymerDomainEvent =
         | 'prosodic'
         | 'conversation'
         | 'transcription'
-        | 'cameraContext';
+        | 'cameraContext'
+        | 'userPerception';
     }
   | { type: 'error'; agency: string; message: string };
 
@@ -1838,6 +3102,8 @@ export interface AnimationAgency {
 }
 
 export interface GazeAgency {
+  /** Applies between decisions; pending requests retain their accepted policy. */
+  applyConfiguration(update: { revision: number; configure: GazeEditableConfiguration }): AgencyConfigurationReceipt;
   input: PolymerInputStream<GazeDispatch>;
   events: PolymerStream<PolymerDomainEvent>;
   dispatch(command: GazeDispatch): void;
@@ -1934,6 +3200,8 @@ export interface TTSAgency {
 }
 
 export interface GestureAgency {
+  /** Applies between decisions; already scheduled snippets are unchanged. */
+  applyConfiguration(update: { revision: number; configure: GestureEditableConfiguration }): AgencyConfigurationReceipt;
   input: PolymerInputStream<GestureDispatch>;
   events: PolymerStream<PolymerDomainEvent>;
   dispatch(command: GestureDispatch): void;
@@ -1969,6 +3237,14 @@ export interface ProsodicAgency {
   /** Compatibility alias for events. Prefer subscribeEvents. */
   subscribeStatus(listener: (event: PolymerStatusEvent) => void): () => void;
   configure(config: ProsodicConfig): void;
+  /** Atomic between decisions. Invalid/stale updates do not consume a revision.
+   * Existing scheduled work retains its original policy. Reentrant calls during
+   * a decision or configuration notification are rejected; retry at a boundary.
+   */
+  applyConfiguration(update: {
+    revision: number;
+    configure: ProsodicEditableConfiguration;
+  }): ProsodicConfigurationReceipt;
   speechStarted(name?: string): void;
   wordBoundary(word: string, wordIndex?: number): void;
   blinkFast(): void;
@@ -1986,6 +3262,7 @@ export interface ConversationAgency {
   subscribeEvents(listener: (event: PolymerDomainEvent) => void): () => void;
   subscribe(listener: (event: PolymerStatusEvent) => void): () => void;
   subscribeStatus(listener: (event: PolymerStatusEvent) => void): () => void;
+  startFlow(factory: (context: ConversationFlowContext) => ConversationFlow): void;
   start(): void;
   stop(): void;
   reset(): void;
@@ -2013,6 +3290,8 @@ export interface TranscriptionAgency {
 }
 
 export interface CameraContextAgency {
+  /** Applies to new observations; already pending facts retain their policy. */
+  applyConfiguration(update: { revision: number; configure: CameraContextEditableConfiguration }): AgencyConfigurationReceipt;
   input: PolymerInputStream<CameraContextDispatch>;
   events: PolymerStream<PolymerDomainEvent>;
   dispatch(command: CameraContextDispatch): void;
@@ -2028,12 +3307,32 @@ export interface CameraContextAgency {
   dispose(): void;
 }
 
+export interface UserPerceptionAgency {
+  input: PolymerInputStream<UserPerceptionDispatch>;
+  events: PolymerStream<PolymerDomainEvent>;
+  dispatch(command: UserPerceptionDispatch): void;
+  snapshot(): UserPerceptionState;
+  subscribeInput(listener: (event: { type: 'command'; agency: 'userPerception'; command: UserPerceptionDispatch }) => void): () => void;
+  subscribeEvents(listener: (event: PolymerDomainEvent) => void): () => void;
+  subscribe(listener: (event: PolymerStatusEvent) => void): () => void;
+  subscribeStatus(listener: (event: PolymerStatusEvent) => void): () => void;
+  configure(config: UserPerceptionConfig): void;
+  start(): void;
+  stop(): void;
+  /** Reset eye contact to the current face, or the next accepted face if none is visible. */
+  recenter(): void;
+  reset(): void;
+  queue(): Array<Record<string, unknown>>;
+  dispose(): void;
+}
+
 export interface CharacterAgencySnapshot {
   blink: BlinkState;
   gaze: GazeState;
   eyeHeadTracking: EyeHeadTrackingState;
   gesture: GestureState;
   cameraContext: CameraContextState;
+  userPerception: UserPerceptionState;
   transcription: TranscriptionState;
   conversation: ConversationState;
   tts: TTSState;
@@ -2049,6 +3348,7 @@ export type CharacterAgencyDispatch =
   | { agency: 'eyeHeadTracking'; command: EyeHeadTrackingDispatch }
   | { agency: 'gesture'; command: GestureDispatch }
   | { agency: 'cameraContext'; command: CameraContextDispatch }
+  | { agency: 'userPerception'; command: UserPerceptionDispatch }
   | { agency: 'transcription'; command: TranscriptionDispatch }
   | { agency: 'conversation'; command: ConversationDispatch }
   | { agency: 'tts'; command: TTSDispatch }
@@ -2062,7 +3362,10 @@ export interface CharacterAgencies {
   readonly agencySociety: AgencySociety;
   dispatch(message: CharacterAgencyDispatch): void;
   snapshot(): CharacterAgencySnapshot;
-  /** Replace live route admission settings without recreating agency-local state. */
+  /** Replace route admission; Prosodic quiesces before disabling. Nested updates
+   * or re-enable during cleanup return the current society without applying.
+   * Does not overwrite agency-local configure/priors values.
+   */
   updateSocietyRouting(society: AgencySociety): AgencySociety;
   agency(name: 'animation'): AnimationAgency;
   agency(name: 'blink'): BlinkAgency | null;
@@ -2070,6 +3373,7 @@ export interface CharacterAgencies {
   agency(name: 'eyeHeadTracking'): EyeHeadTrackingAgency | null;
   agency(name: 'gesture'): GestureAgency | null;
   agency(name: 'cameraContext'): CameraContextAgency | null;
+  agency(name: 'userPerception'): UserPerceptionAgency | null;
   agency(name: 'transcription'): TranscriptionAgency;
   agency(name: 'conversation'): ConversationAgency;
   agency(name: 'tts'): TTSAgency;
@@ -2123,6 +3427,7 @@ export interface AIExpressionSnippetMetadata {
 }
 
 export interface Snippet {
+  semanticAnimation?: SemanticAnimation;
   name?: string;
   au?: Array<{ id: string | number; t?: number; v?: number; time?: number; intensity?: number; inherit?: boolean }>;
   viseme?: Array<{ key: string | number; t?: number; v?: number; time?: number; intensity?: number; inherit?: boolean }>;
@@ -2131,12 +3436,17 @@ export interface Snippet {
   isPlaying?: boolean;
   loop?: boolean;
   maxTime?: number;
+  cleanupMaxTime?: number;
   duration?: number;
   snippetCategory?: 'auSnippet' | 'visemeSnippet' | 'eyeHeadTracking' | 'combined' | 'default' | string;
   snippetPriority?: number;
   snippetPlaybackRate?: number;
   snippetIntensityScale?: number;
   snippetBlendMode?: 'replace' | 'additive';
+  /** Neutral reference sample for converting a clip to additive rotation. */
+  additiveReferenceTimeSec?: number;
+  /** Stable order for zero-fade, once-only additive controls, even after other clips are removed. */
+  additiveCompositionOrder?: number;
   snippetJawScale?: number;
   autoVisemeJaw?: boolean;
   snippetBalance?: number;
@@ -2202,10 +3512,10 @@ export interface SnippetUIState {
 }
 
 export interface BakedClipChannelInfo {
-  channel: string;
+  channel: BakedClipChannel;
   trackCount: number;
   playable: boolean;
-  blendMode?: 'replace' | 'additive';
+  blendMode?: AnimationBlendMode;
 }
 
 export interface BakedClipInfo {
@@ -2222,7 +3532,6 @@ export interface BakedAnimationUIState {
   duration: number;
   speed: number;
   playbackRate: number;
-  weight: number;
   intensityScale: number;
   isPlaying: boolean;
   isPaused: boolean;
@@ -2319,7 +3628,7 @@ export interface AnimationService {
   bakedAnimationState$(clipName: string): AnimationObservable<BakedAnimationUIState | null>;
   loadFromJSON(data: Snippet | NormalizedSnippet): string;
   updateSnippet(data: Snippet | NormalizedSnippet): string;
-  schedule(data: Snippet | NormalizedSnippet, opts?: { startInSec?: number; startAtSec?: number; offsetSec?: number; priority?: number; autoPlay?: boolean }): string;
+  schedule(data: Snippet | NormalizedSnippet, opts?: { startInSec?: number; startAtSec?: number; offsetSec?: number; priority?: number; autoPlay?: boolean; loop?: boolean; loopMode?: MixerLoopMode }): string;
   remove(name: string): void;
   play(): void;
   pause(): void;
@@ -2357,6 +3666,8 @@ export interface AnimationService {
   pauseBakedAnimation(clipName: string): void;
   resumeBakedAnimation(clipName: string): void;
   setBakedAnimationSpeed(clipName: string, speed: number): void;
+  setBakedAnimationIntensity(clipName: string, intensity: number): void;
+  /** @deprecated Use setBakedAnimationIntensity. */
   setBakedAnimationWeight(clipName: string, weight: number): void;
   setBakedAnimationLoop(clipName: string, loop: boolean): void;
   setBakedAnimationLoopMode(clipName: string, mode: MixerLoopMode): void;
@@ -2499,9 +3810,17 @@ export interface ConversationCallbacks {
 }
 
 export type ConversationFlow = Generator<string | Promise<string>, string | void, string>;
+export interface ConversationFlowContext {
+  /** Current request signal. Capture before async work and check before applying results. */
+  readonly signal: AbortSignal;
+}
 
 export interface ConversationService {
-  start(flowGenerator: () => ConversationFlow): void;
+  start(flowGenerator: (context: ConversationFlowContext) => ConversationFlow): void;
+  listen(): void;
+  pauseListening(): void;
+  interrupt(reason?: string): void;
+  updateConfig(config: Partial<ConversationConfig>): void;
   stop(): void;
   getState(): {
     state: ConversationStateName;
@@ -2542,9 +3861,14 @@ export const playingBakedAnimations$: AnimationObservable<BakedAnimationUIState[
 export const bakedAnimationProgress$: AnimationObservable<AnimationEvent>;
 /** @deprecated Use AnimationService.bakedAnimationState$. */
 export function bakedAnimationState$(clipName: string): AnimationObservable<BakedAnimationUIState | null>;
-export function createAnimationService(engine: Embody | EmbodyRuntime): AnimationService;
+export function createAnimationService(
+  engine: Embody | EmbodyRuntime,
+  options?: { agency?: AnimationAgency },
+): AnimationService;
 export function createEyeHeadTrackingService(config?: EyeHeadTrackingConfig, callbacks?: EyeHeadTrackingCallbacks): EyeHeadTrackingService;
 export function createTranscriptionService(config?: TranscriptionConfig, callbacks?: TranscriptionCallbacks): TranscriptionService;
+export function createCharacterConversationService(agencies: CharacterAgencies, config?: ConversationConfig, callbacks?: ConversationCallbacks): ConversationService;
+/** @deprecated Character hosts should use createCharacterConversationService. */
 export function createConversationService(tts: { speak(text: string): Promise<unknown>; stop(): void }, transcription: TranscriptionService, config?: ConversationConfig, callbacks?: ConversationCallbacks): ConversationService;
 export const DEFAULT_HAIR_PHYSICS_ENABLED: boolean;
 export const DEFAULT_AGENCY_SOCIETY: AgencySociety;
@@ -2575,6 +3899,8 @@ export interface AgencySocietyEdge {
   enabled?: boolean;
   credit?: number;
   match?: Record<string, unknown>;
+  /** Installed cleanup metadata. Setting this on a custom edge grants no bypass. */
+  delivery?: 'cleanup';
 }
 
 export interface AgencySocietyKLine {
@@ -2602,30 +3928,405 @@ export interface AgencySociety {
 
 export function createBlinkAgency(config?: BlinkAgencyConfig): BlinkAgency;
 export function createAnimationAgency(config?: AnimationAgencyConfig): AnimationAgency;
-export function createGazeAgency(config?: GazeConfig): GazeAgency;
+export function createGazeAgency(config?: GazeConfig, runtime?: EmbodyGazeRuntime): GazeAgency;
 export function createEyeHeadTrackingAgency(config?: EyeHeadTrackingConfig): EyeHeadTrackingAgency;
 export function createLipSyncAgency(config?: LipSyncConfig, runtime?: LipSyncRuntime): LipSyncAgency;
 export function createTTSAgency(config?: TTSConfig): TTSAgency;
-export function createGestureAgency(config?: GestureConfig): GestureAgency;
-export function createProsodicAgency(config?: ProsodicConfig): ProsodicAgency;
+export function createGestureAgency(config?: GestureOptions): GestureAgency;
+export function getProsodicDefinition(): ProsodicDefinition;
+export function getGestureDefinition(): GestureDefinition;
+export function getGazeDefinition(): GazeDefinition;
+export function getCameraContextDefinition(): CameraContextDefinition;
+export function createProsodicAgency(config?: ProsodicOptions): ProsodicAgency;
 export function createConversationAgency(config?: ConversationAgencyConfig): ConversationAgency;
 export function createTranscriptionAgency(config?: TranscriptionConfig): TranscriptionAgency;
 export function createCameraContextAgency(config?: CameraContextConfig): CameraContextAgency;
+export function createUserPerceptionAgency(config?: UserPerceptionConfig, runtime?: UserPerceptionRuntime): UserPerceptionAgency;
 export function createCharacterAgencies(config?: {
   blink?: BlinkAgencyConfig;
   gaze?: GazeConfig;
+  gazeRuntime?: EmbodyGazeRuntime;
   eyeHeadTracking?: EyeHeadTrackingConfig;
-  gesture?: GestureConfig;
+  gesture?: GestureOptions;
   cameraContext?: CameraContextConfig;
+  userPerception?: UserPerceptionConfig;
+  userPerceptionRuntime?: UserPerceptionRuntime;
   transcription?: TranscriptionConfig;
   conversation?: ConversationAgencyConfig;
   tts?: TTSConfig;
   lipSync?: LipSyncConfig;
   lipSyncRuntime?: LipSyncRuntime;
-  prosodic?: ProsodicConfig;
+  prosodic?: ProsodicOptions;
   animation?: AnimationAgencyConfig;
   /** Compatibility injection point passed into Conversation's private effector. */
   conversationProvider?: ConversationProvider;
   /** Optional society wiring / priors seed (see AgencySociety). */
   agencySociety?: AgencySociety;
 }): CharacterAgencies;
+
+// Versioned module definitions are pure JSON authoring data, not live agencies.
+export type ModuleType = 'aiChat' | 'frenchQuiz' | 'slideshow' | 'questionnaire';
+export interface ModuleVoiceOverride {
+  engine: 'azure' | 'webSpeech';
+  voiceName: string;
+  rate: number;
+  pitch: number;
+  volume: number;
+}
+export interface ModuleCommonSettings {
+  language?: string;
+  instructions?: string;
+  greeting?: string;
+  inputMode?: 'voice' | 'text' | 'voiceAndText';
+  interruptionMode?: 'cancel-agent' | 'ignore';
+  /** null inherits voice from the character profile referenced by characterBinding. */
+  voiceOverride?: ModuleVoiceOverride | null;
+}
+export interface ModuleUISettings {
+  layout?: 'conversation' | 'stage' | 'backdrop' | 'contentFocus';
+  panels?: Array<'agent' | 'transcript' | 'content' | 'input' | 'progress' | 'feedback'>;
+  actions?: Array<'answer' | 'continue' | 'back' | 'skip' | 'exit' | 'discuss'>;
+}
+export interface ModuleTypeSettings {
+  aiChat: { autoEmotion?: boolean; emotionIntensity?: number };
+  frenchQuiz: { autoPlay?: boolean; showInstructions?: boolean };
+  slideshow: { autoAdvance?: boolean; allowBrowse?: boolean; followPresenter?: boolean; initialSlide?: number };
+  questionnaire: { mode?: 'quiz' | 'diagnostic' | 'unscored'; feedbackTiming?: 'immediate' | 'end' | 'none'; allowBack?: boolean; maxAttempts?: number };
+}
+export interface ModuleSettings<T extends ModuleType = ModuleType> {
+  common?: ModuleCommonSettings;
+  type?: ModuleTypeSettings[T];
+  ui?: ModuleUISettings;
+}
+export interface ModuleContentReference {
+  contentId: string;
+  contentType: 'htmlDeck' | 'workbook' | 'questionnaire';
+  /** Positive immutable content revision. */
+  revision: number;
+}
+export interface ModuleCharacterBinding {
+  characterId: string;
+  /** Positive profile revision; profile data is not copied into the definition. */
+  profileRevision: number;
+}
+export type ModuleDefinition<T extends ModuleType = ModuleType> = T extends ModuleType ? {
+  schemaVersion: 1;
+  moduleId: string;
+  moduleType: T;
+  /** 0 is an unsaved draft; saved definitions use positive revisions. */
+  revision: number;
+  name: string;
+  description: string;
+  characterBinding: ModuleCharacterBinding | null;
+  contentRefs: ModuleContentReference[];
+  settings: ModuleSettingsPatch<ModuleSettings<T>>;
+} : never;
+export type ResolvedModuleDefinition<T extends ModuleType = ModuleType> = T extends ModuleType
+  ? Omit<ModuleDefinition<T>, 'settings'> & { settings: ModuleSettings<T> } : never;
+export interface ModuleValidationError { path: string; code: string; message: string }
+export interface ModuleValidationResult { valid: boolean; errors: ModuleValidationError[] }
+export interface ModuleSettingDescriptor {
+  key: string;
+  control: 'text' | 'textarea' | 'toggle' | 'number' | 'select' | 'multiSelect' | 'editor';
+  label: string;
+  help: string;
+  default: unknown;
+  group: 'common' | 'type' | 'ui';
+  requiredCapabilities: string[];
+  authorVisible: boolean;
+  /** Editor visibility hint, not an authorization rule for participant data. */
+  participantVisible: boolean;
+  applyTiming: 'liveUi' | 'nextRun';
+  options?: Array<{ value: string; label: string }>;
+  min?: number;
+  max?: number;
+  maxLength?: number;
+  editorSlot?: 'voiceOverride';
+}
+export interface ModuleTypeDescriptor {
+  moduleType: ModuleType;
+  label: string;
+  available: boolean;
+  unavailableReason: string | null;
+  fields: ModuleSettingDescriptor[];
+  editorSlots: Array<{ key: 'contentRefs'; editorSlot: 'deck' | 'questionnaire'; label: string; applyTiming: 'nextRun' }>;
+}
+export type ModuleReset = { $reset: true };
+/** Reset removes layered customization by restoring the built-in type default. */
+export type ModuleSettingsPatch<T> = T extends readonly unknown[] ? T | ModuleReset
+  : T extends object ? { [K in keyof T]?: ModuleSettingsPatch<T[K]> } | ModuleReset
+  : T | ModuleReset;
+export interface ModuleResolutionOptions {
+  userDefaults?: ModuleSettingsPatch<ModuleSettings>;
+  sessionOverrides?: ModuleSettingsPatch<ModuleSettings>;
+}
+export interface ModuleLaunchOptions extends ModuleResolutionOptions { sessionId: string; launchedAt: string }
+export interface ModuleLaunchSnapshot {
+  schemaVersion: 1;
+  sessionId: string;
+  launchedAt: string;
+  definitionIdentity: { moduleId: string; moduleType: ModuleType; schemaVersion: 1; revision: number };
+  definition: ResolvedModuleDefinition;
+}
+export function getModuleTypeDescriptors(): ModuleTypeDescriptor[];
+export function getModuleDefinitionSchema(): Record<string, unknown>;
+export function getModuleSettingsDefaults<T extends ModuleType>(moduleType: T): ModuleSettings<T>;
+export function validateModuleDefinition(definition: unknown): ModuleValidationResult;
+/** Throws on unknown/invalid fields or versions; never mutates supplied data. */
+export function resolveModuleDefinition<T extends ModuleType>(definition: ModuleDefinition<T>, options?: ModuleResolutionOptions): ResolvedModuleDefinition<T>;
+/** coveredKeys must enumerate both rendered editors and effective runtime consumers. */
+export function validateModuleCapabilityCoverage(moduleType: ModuleType, coveredKeys: string[]): ModuleValidationResult;
+/** Detached JSON snapshot; unavailable type registrations cannot launch. */
+export function createModuleLaunchSnapshot(definition: ModuleDefinition, options: ModuleLaunchOptions): ModuleLaunchSnapshot;
+
+/** Immutable authored content. This first version supports unscored questions only. */
+export interface QuestionnaireQuestionBase {
+  /** Stable ASCII identifier, 1–120 characters; compatible with InteractionItemRef. */
+  questionId: string;
+  prompt: string;
+  required: boolean;
+  /** Private editorial notes, excluded from participant/Conversation projections. */
+  authorNotes?: string;
+}
+export interface QuestionnaireChoiceQuestion extends QuestionnaireQuestionBase {
+  kind: 'singleChoice';
+  options: Array<{ optionId: string; label: string }>;
+}
+export interface QuestionnaireTextQuestion extends QuestionnaireQuestionBase {
+  kind: 'text';
+  /** Unicode codepoints after ECMAScript whitespace trimming; 0–16000. */
+  minLength: number;
+  /** 1–16000; no smaller than minLength. Optional empty answers bypass length bounds. */
+  maxLength: number;
+}
+export type QuestionnaireQuestion = QuestionnaireChoiceQuestion | QuestionnaireTextQuestion;
+export interface QuestionnaireContent {
+  schemaVersion: 1;
+  contentId: string;
+  contentType: 'questionnaire';
+  /** Positive immutable revision. Draft revision zero is unsupported here. */
+  revision: number;
+  mode: 'unscored';
+  locale: string;
+  instructions: string;
+  order: 'authored';
+  questions: QuestionnaireQuestion[];
+  completionMessage: string;
+  authorNotes?: string;
+}
+export type QuestionnaireParticipantQuestion = Omit<QuestionnaireChoiceQuestion, 'authorNotes'>
+  | Omit<QuestionnaireTextQuestion, 'authorNotes'>;
+export type QuestionnaireParticipantContent = Omit<QuestionnaireContent, 'authorNotes' | 'questions'>
+  & { questions: QuestionnaireParticipantQuestion[] };
+/** Validation data only; this does not commit an answer or advance a run. */
+export interface QuestionnaireAnswer {
+  questionId: string;
+  /** Stable option ID, trimmed text, or explicit null for an optional empty answer. */
+  value: string | null;
+}
+export type QuestionnaireAnswerValidationResult =
+  | { valid: true; errors: []; answer: QuestionnaireAnswer }
+  | { valid: false; errors: ModuleValidationError[]; answer: null };
+export interface QuestionnaireEditorDescriptor {
+  schemaVersion: 1;
+  editorSlot: 'questionnaire';
+  contentType: 'questionnaire';
+  contentSchemaId: string;
+  supportedModes: ['unscored'];
+  questionKinds: ['singleChoice', 'text'];
+  order: 'authored';
+  runtimeAvailable: false;
+  fields: Array<{
+    /** Canonical content path; [] denotes an authored list item. */
+    key: string;
+    control: 'identity' | 'text' | 'textarea' | 'toggle' | 'number' | 'select' | 'questionList' | 'optionList';
+    label: string;
+    help: string;
+    participantVisible: boolean;
+    applyTiming: 'nextRun';
+    options?: string[];
+  }>;
+}
+/** Structural JSON Schema; duplicate IDs, nonblank text, bounds ordering and total size also need semantic validation. */
+export function getQuestionnaireContentSchema(): Record<string, unknown>;
+export function getQuestionnaireEditorDescriptor(): QuestionnaireEditorDescriptor;
+export function validateQuestionnaireContent(content: unknown): ModuleValidationResult;
+/** Validates and returns detached allowlisted content. Throws on malformed/unsupported authored data. */
+export function projectQuestionnaireContent(content: QuestionnaireContent): QuestionnaireParticipantContent;
+/** No coercion, correctness, attempt counting or state mutation. Required blanks fail; optional blanks normalize to null. */
+export function validateQuestionnaireAnswer(content: unknown, questionId: string, value: unknown): QuestionnaireAnswerValidationResult;
+/** Pass the resolved launch definition. Checks unscored mode and one exact pinned bank; does not authorize or launch it. */
+export function validateQuestionnaireBinding(definition: unknown, content: unknown): ModuleValidationResult;
+
+/** Shared data contracts. Each feature agency owns its state and scheduling. */
+export interface InteractionIdentity {
+  schemaVersion: 1;
+  /** Fresh for every mount/account generation, 1–64 ASCII characters. Never reuse. */
+  instanceId: string;
+  /** Pinned run identity; an account change requires a new session as well. */
+  sessionId: string;
+  definition: ModuleLaunchSnapshot['definitionIdentity'];
+  contentRefs: ModuleContentReference[];
+}
+export interface InteractionItemRef { itemId: string; revision: number }
+export type InteractionPhase = 'configured' | 'running' | 'paused' | 'completed' | 'ended';
+export type InteractionTarget = 'session' | 'active' | 'viewed';
+export interface InteractionState {
+  identity: InteractionIdentity;
+  phase: InteractionPhase;
+  lifecycleRevision: number;
+  active: { item: InteractionItemRef | null; revision: number };
+  viewed: { item: InteractionItemRef | null; revision: number };
+}
+/** Confirmed feature-planner decisions, not unvalidated host navigation requests. */
+export type InteractionConfirmation =
+  | { type: 'lifecycle'; phase: InteractionPhase }
+  | { type: 'active' | 'viewed'; item: InteractionItemRef | null };
+export type InteractionJSON = null | boolean | number | string | InteractionJSON[] | { [key: string]: InteractionJSON };
+export interface InteractionCheckpoint<T extends InteractionJSON = InteractionJSON> {
+  schemaVersion: 1;
+  identity: InteractionIdentity;
+  activeItem: InteractionItemRef | null;
+  viewedItem: InteractionItemRef | null;
+  /** Feature-owned, versioned domain data. This API does not persist it. */
+  payload: T;
+}
+export interface InteractionCorrelation {
+  schemaVersion: 1;
+  identity: InteractionIdentity;
+  lifecycleRevision: number;
+  target: InteractionTarget;
+  contextRevision: number;
+  item: InteractionItemRef | null;
+  /** Instance-qualified ID. Send this returned value to Conversation/adapters. */
+  requestId: string;
+}
+/** IDs describe edge-adapter resources; DOM/Embody handles never enter snapshots. */
+export interface InteractionViewDescriptor {
+  layout: NonNullable<ModuleUISettings['layout']>;
+  panels: NonNullable<ModuleUISettings['panels']>;
+  /** Visible controls; feature policy separately determines allowed intents. */
+  actions: NonNullable<ModuleUISettings['actions']>;
+  availableActions: NonNullable<ModuleUISettings['actions']>;
+  contentSurfaceId: string | null;
+}
+export interface InteractionSnapshot<T extends InteractionJSON = InteractionJSON> {
+  interaction: InteractionState;
+  view: InteractionViewDescriptor;
+  /** Participant-safe projection selected by the owning feature. */
+  domain: T;
+}
+export interface InteractionCapabilities {
+  moduleType: ModuleType;
+  available: boolean;
+  unavailableReason: string | null;
+  layouts: Array<NonNullable<ModuleUISettings['layout']>>;
+  actions: NonNullable<ModuleUISettings['actions']>;
+  contentSurface: boolean;
+}
+/** Contract implemented by feature composition inside Polymer. No generic
+ * mutable session manager is supplied. Peers route internally; hosts send
+ * external intents and render snapshots. configure/mount must validate before
+ * changing state; later configuration applies to a new pinned run. dispose is
+ * idempotent and releases only owned work/subscriptions/edge resources. */
+export interface InteractionModule<TIntent extends InteractionJSON, TDomain extends InteractionJSON> {
+  configure(definition: ResolvedModuleDefinition): void;
+  mount(launch: ModuleLaunchSnapshot, instanceId: string): void;
+  dispatch(intent: TIntent): void;
+  snapshot(): InteractionSnapshot<TDomain>;
+  events: PolymerStream<{ type: 'interaction.snapshot'; snapshot: InteractionSnapshot<TDomain> }>;
+  capabilities(): InteractionCapabilities;
+  dispose(): void;
+}
+/** Throws on unsupported identities/versions or non-JSON data; returns detached data. */
+export function createInteractionState(identity: InteractionIdentity): InteractionState;
+export function confirmInteractionTransition(state: InteractionState, confirmation: InteractionConfirmation): InteractionState;
+export function captureInteractionCheckpoint<T extends InteractionJSON>(state: InteractionState, payload: T): InteractionCheckpoint<T>;
+/** Caller validates/restores the feature payload. An ended instance cannot resume. */
+export function restoreInteractionCheckpoint(state: InteractionState, checkpoint: InteractionCheckpoint): InteractionState;
+/** Local key: 1–56 Conversation-compatible ASCII characters, unique per mount. */
+export function createInteractionCorrelation(state: InteractionState, localRequestKey: string, target: InteractionTarget): InteractionCorrelation;
+/** Use the feature's current pending request; pass null after retirement. Accepts
+ * correlated admission errors as well as outcomes. Event-type policy is local. */
+export function matchesInteractionOutcome(state: InteractionState, pending: InteractionCorrelation | null, outcome: { requestId?: string }): boolean;
+
+/** Embody owns the complete Three camera/annotation runtime and lifecycle. */
+export {
+  DPthree,
+  DPthreeCameraController,
+  DPthree3DMarkers,
+  DPthreeHTMLMarkers,
+  DPthreeMarkers,
+  CameraDOMControls,
+  CameraController,
+  Markers3D,
+  MarkersHTML,
+  Controls,
+  RUNTIME_ANNOTATION_REGION_PREFIX,
+  filterCameraViewRegions,
+  isRuntimeAnnotationRegionName,
+  resolveMarkerAnchorRegion,
+  shouldProjectMarkerAnchorToSurface,
+  shouldUseFaceCenterForMarkerAnchor,
+  createMarkerVisibilityLifecycle,
+  createMarkerLifecycleRevealOptions,
+  DEFAULT_MARKER_AUTO_HIDE_MS,
+  boneResolutionProfile,
+  createRuntimeAnnotationPreviewLifecycle,
+  buildRegionDisplayOptions,
+  getRuntimeAnnotationSide,
+  getRuntimeAUMorphAnchorPoint,
+  getRuntimeAUMeshSideOffset,
+  DEFAULT_PREVIEW_AUTO_CLEAR_MS,
+  inferRuntimeAnnotationPreviewSide,
+  pickContinuumAnnotationAuId,
+  resolveAnnotationCharacterConfig,
+  RustAnnotationCameraCore,
+  createRustAnnotationCameraCore,
+  getDefaultAnnotationLaterality,
+  getSemanticHorizontalSignForSide,
+  getSemanticHorizontalSign,
+  resolveRegionCameraAngle,
+  resolveRegionVisibilityCameraAngle,
+  toWorldDirection,
+  getWorldDirectionForCameraAngle,
+  getModelLocalOrbitAngle,
+  passesMarkerCameraAngleGate,
+  resolveFaceCenter,
+  detectAnnotationLaterality,
+} from '@lovelace_lol/embody/three';
+export type {
+  DPthreeConfig,
+  CharacterValidationResult,
+  ValidationCategory,
+  ValidationItem,
+  AnnotationCharacterConfig,
+  AnnotationAnchorPoint,
+  AnnotationMarkerAnchor,
+  AnnotationMarkerAnchorType,
+  AnnotationFocusTarget,
+  AnnotationAnchoredRegion,
+  RuntimeAnnotationMetadata,
+  RuntimeAnnotationOptions,
+  RuntimeAnnotationRegionSummary,
+  RuntimeAnnotationSide,
+  RuntimeAnnotationTargetType,
+  CameraState,
+  FocusPosition,
+  DPthreeCameraControllerConfig,
+  RegionChangeCallback,
+  CharacterChangeCallback,
+  DPthreeRegion,
+  DPthreeCharacterConfig,
+  DPthreeRegistry,
+  DPthreeRegionChangeCallback,
+  DPthreeCharacterChangeCallback,
+  MarkerAnchorProjectionMode,
+  ResolvedMarkerAnchorRegion,
+  MarkerLifecycleRevealOptions,
+  MarkerLifecycleRevealSource,
+  DOMControlRegion,
+  DOMControlsConfig,
+  MarkerStateSnapshot,
+  RuntimeAnnotationPreviewLifecycleOptions,
+} from '@lovelace_lol/embody/three';