@lovelace_lol/polymer 0.0.13 → 0.0.15

package/README.md

@@ -30,13 +30,10 @@ It retains the renderer lifecycle support and speech AU 103 in
 the existing `JAW.pitch.aus` list in CC4's `compositeRotations`. LipSync can send
 the AU through Animation and use its saved bone and morph outputs.
 
-The CC4 body-control catalog places hip bend, twist and side bend in **Whole
-body**, separate from the waist, spine and chest controls in **Torso**. These
-existing animation controls rotate the hip bone, which carries both torso and
-legs. They differ from import/setup rotation, which rotates the entire model
-object and saves its orientation as `modelRotation`. Hosts using
-`getBodyControls` inherit the catalog labels and sections unless a profile
-explicitly overrides them. Action IDs and bone motion stay unchanged.
+The CC4 hip bend, twist and side-bend AUs rotate the mapped hip bone, carrying
+both torso and legs. Import/setup rotation remains a model transform saved as
+`modelRotation`. `getAUDescriptors()` reads each character's actual AU labels,
+bone and morph bindings and supported outputs; editors use this data directly.
 
 The character host restores `profile.meshes` visibility and material settings
 through Embody when binding a model or applying `setProfile`. Explicit hidden
@@ -282,6 +279,44 @@ The host supplies the gesture library and may observe streams for diagnostics,
 but Gesture's own scheduler is responsible for replacement, cancellation, and
 completion cleanup before Animation owns the runtime side effect.
 
+### Animation API removal
+
+Animation no longer exports `dispatch` or `AnimationDispatch`, and the character
+`dispatch({ agency: "animation", ... })` envelope is rejected. Other agencies
+retain their dispatch APIs. Hosts use the character's existing Animation agency:
+
+```js
+const animation = agencies.agency("animation");
+animation.loadBakedClips();
+animation.playBaked("Walk", { loop: true });
+animation.pauseBaked("Walk");
+animation.resumeBaked("Walk");
+animation.seekBaked("Walk", 0);
+animation.updateBakedParams("Walk", { intensityScale: 0.5 });
+animation.stopBaked("Walk");
+animation.prepareSnippet(snippet); // Forces autoPlay: false.
+animation.resumeSnippet(snippet.name);
+animation.pauseSnippet(snippet.name);
+animation.removeSnippet(snippet.name);
+```
+
+`clearSnippets()` removes all scheduled snippets, including peer speech/gesture
+work, while preserving baked clips. `stopAllBaked()` stops tracked baked handles,
+including held actions, while preserving snippets. These are whole-agency
+controls, not owner-scoped preview cancellation.
+
+Peer messages use `AnimationInput` on `animation.input.write(command)`. Character
+society routing delivers to that port while preserving route admission and
+trusted source attribution. Worker hosts send
+`{ type: "animationInput", id, command }`, without native handles or Three objects.
+Named controls and peer input use the same private planner/scheduler path.
+
+This removes Animation dispatch; it does not complete issue #306. The separate
+AnimationService compatibility API, its catalog/event projections and native
+baked bypass remain migration work. Unified source/instance controls,
+configuration/inspection adoption, account storage and regional priority are
+not delivered by this API removal.
+
 ### Animation snippet looping
 
 Animation snippets default to repeating when no loop preference is supplied.
@@ -421,19 +456,16 @@ action/composite mappings, and continuum pairs, then reconfigure the runtime. Au
 remain authoritative across preset upgrades. Clearing a role makes its semantic
 bone outputs dormant while preserving the rest of the profile.
 
-The CC4 preset supplies a complete role map and controls across torso, head,
-arms, hands/fingers, legs, and feet/toes. Bound UI controls use
-`engine.getBodyControls()` to read descriptors cached from the configured Rust
-profile/model, avoiding scene traversal and repeated profile parsing. The standalone
-`getBodyControls(profile, model)` query remains available for unbound authoring.
-`engine.resetBodyControls()` clears the configured catalog's action values and
-balances in one Rust call and applies one frame, preserving unrelated facial actions
-and morph-strength settings. Head, eye, and jaw controls
-share existing facial actuators; all controls use the existing AU/continuum
-host methods. Applications should show the full role inventory even when a
-model omits optional bones, and allow users to repair its assignments.
-
-Every configured Body action, including each direction of a signed control,
+The CC4 preset supplies anatomical role bindings and AU mappings across torso,
+head, arms, hands/fingers, legs and feet/toes. `engine.getAUDescriptors()` returns
+metadata from the configured Rust profile/model. The standalone
+`getAUDescriptors(profile, model)` query supports unbound authoring. Descriptors
+include numeric AU IDs, directional pairs when configured, bilateral support,
+actual bone/morph bindings, saved morph strength and availability diagnostics.
+Applications use the normal AU setters and getters; clearing a pose means
+releasing its owned AU values, balances and morph-strength overrides.
+
+Every configured AU, including each direction of a signed control,
 can drive authored left/right/center morph mappings. Morph strength scales
 those outputs even when the action has no bone bindings. Persist the action's
 `auToMorphs` and `auMixDefaults`, and retain its mesh category: head, eye, and
@@ -633,31 +665,29 @@ request correlation and opaque checkpoint helpers. See
 composition interface, account/mount identity and scoped cleanup rules. These
 contracts do not enable a feature runtime or persist conversation/run data.
 
-### Semantic pose capture and generated animations
-
-The Rust host exposes `getSemanticPoseCatalog()`, `captureSemanticPose()`,
-`validateSemanticPose(pose)` and `applySemanticPose(pose)`. The catalog follows
-the configured profile and actual model, including independent direction support,
-VRM role names, owned bone/morph names and authored default tissue strengths.
-Captures preserve both opposing directions, bilateral balance and morph strength;
-they represent manual semantic state, not inverse inference of a baked pose.
-Validation is atomic and lives in Embody. Known missing outputs may be saved for
-partial rigs; generation should offer only supported catalog directions.
-
-Normal `AnimationService.schedule` snippets may include `semanticAnimation`:
-`{version:1,durationSeconds,tracks:[{controlId,direction,balance?,morphStrength?,
-keyframes:[{time,intensity}]}]}`. Existing `curves` are non-Body facial AUs.
-Embody compiles both sets together into bone/morph tracks, preserving each tissue
-strength without changing live controls. Service save, pause, resume and cleanup
-use the existing snippet lifecycle. `validateSemanticAnimation(animation, options)`
-compiles without retaining clips. `semanticAnimationToClip(name, animation,
-options)` builds an ordinary playback handle; `options.faceCurves` adds facial
-curves for direct callers. IDs and direction labels come from the catalog, amounts
-are normalized `0..1`, balance is character-relative `-1` left / `+1` right, and
-times are seconds. Unknown controls, unsupported directions and invalid tracks fail.
+### AU pose capture and generated animations
+
+A pose uses numeric AU values, character-relative balances and per-AU morph
+weights. Hosts read `engine.getAUDescriptors()` for actual saved mappings and
+use `getAU`, `getAUBalance` and `getAUMixWeight` to capture values, then their
+corresponding setters to restore them. Host code validates a complete record
+before applying it; Polymer adds no parallel named-control pose format.
+
+`AnimationService.schedule` uses ordinary `curves` keyed by numeric AU ID for
+both facial and body motion. A snippet may add `balanceMap` and `mixWeights`:
+`{curves:{1001:[{time:0,intensity:0},{time:0.2,intensity:0.8}]},
+balanceMap:{1001:-1},mixWeights:{1001:0.25}}`. Balance ranges from character-left
+`-1` to character-right `+1`; morph weight changes tissue deformation without
+attenuating the AU's bone movement. Embody compiles the saved bone/morph
+mappings into native clips without changing live AU settings. Existing save,
+pause/resume, held-final-pose, completion and removal behavior applies.
+
+`LEGACY_BODY_CONTROL_AUS` is an immutable lookup for host loaders decoding old
+persisted names to numeric AUs. It supplies no labels, availability, profile
+configuration or runtime control behavior. New records use AU IDs directly.
 
 Manual `setAU` / `transitionAU` selects one configured continuum direction:
 nonzero input clears its opposite, negative input selects the opposite, and
 zero releases only the named action. `setContinuum` controls both directions
-explicitly. Body and individual AU/morph previews therefore share the same
-live state; separate axes remain independent.
+explicitly. AU and individual morph previews share the same live state;
+separate axes remain independent.

package/dist/index.d.ts

@@ -15,6 +15,7 @@ import type {
 import type { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import type { ThreeModelReferencePose as EmbodyModelReferencePose } from '@lovelace_lol/embody/three';
 export type ThreeModelReferencePose = EmbodyModelReferencePose;
+export type { AUDescriptor } from '@lovelace_lol/embody';
 import type {
   CharacterSceneRenderer,
   CharacterSceneBackend,
@@ -268,67 +269,6 @@ export interface HumanoidCharacterizationResolution {
   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;
@@ -370,8 +310,6 @@ export interface Profile {
   disabledRegions?: string[];
   hairPhysics?: HairPhysicsProfileConfig;
   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> {
@@ -699,16 +637,8 @@ export interface PolymerCharacterRuntime {
   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; the next native mixer frame applies the pose. */
-  resetBodyControls(): void;
+  /** Saved AU metadata resolved against the configured profile and model. */
+  getAUDescriptors(): import('@lovelace_lol/embody').AUDescriptor[];
   setContinuum(negAU: number, posAU: number, value: number, balance?: number): void;
   getContinuum(negAU: number, posAU: number): number;
   /** Mixer-timed live control; defaults to 200 ms. getAU reports its destination immediately. */
@@ -901,7 +831,9 @@ export declare function setHumanoidRoleBinding(profile: Profile, role: VRMHumano
 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 { getAUDescriptors } from '@lovelace_lol/embody';
+/** @deprecated Immutable decoder lookup for historical host records; never a live control catalog. */
+export { LEGACY_BODY_CONTROL_AUS } from '@lovelace_lol/embody';
 export declare const VISEME_KEYS: string[];
 export declare const HAIR_COLOR_PRESETS: Record<string, HairColorAppearance>;
 export declare const DEFAULT_HAIR_COLOR_APPEARANCE: HairColorAppearance;
@@ -1062,7 +994,7 @@ export interface AnimationAgencyConfig {
   runtimeConfig?: Record<string, unknown>;
 }
 
-export type AnimationDispatch =
+export type AnimationInput =
   | {
       type: 'scheduleSnippet';
       sourceAgency?: string;
@@ -1071,6 +1003,8 @@ export type AnimationDispatch =
     }
   | { type: 'seekSnippet'; sourceAgency?: string; name: string; offsetSec: number }
   | { type: 'updateSnippet'; sourceAgency?: string; name: string; params: Record<string, unknown> }
+  | { type: 'pauseSnippet'; sourceAgency?: string; name: string }
+  | { type: 'resumeSnippet'; sourceAgency?: string; name: string; snippet?: PolymerAnimationSnippet; options?: { autoPlay?: boolean; [key: string]: unknown } }
   | { type: 'removeSnippet'; sourceAgency?: string; name: string }
   | { type: 'clear'; sourceAgency?: string }
   | { type: 'loadBakedClips'; sourceAgency?: string; clips?: AnimationBakedClipInfo[] }
@@ -2571,11 +2505,10 @@ export interface BlinkAgency {
 }
 
 export interface AnimationAgency {
-  input: PolymerInputStream<AnimationDispatch>;
+  input: PolymerInputStream<AnimationInput>;
   events: PolymerStream<PolymerDomainEvent>;
-  dispatch(command: AnimationDispatch): void;
   snapshot(): AnimationState;
-  subscribeInput(listener: (event: { type: 'command'; agency: 'animation'; command: AnimationDispatch }) => void): () => void;
+  subscribeInput(listener: (event: { type: 'command'; agency: 'animation'; command: AnimationInput }) => void): () => void;
   subscribeEvents(listener: (event: PolymerDomainEvent) => void): () => void;
   /** Compatibility alias for events. Prefer subscribeEvents. */
   subscribe(listener: (event: PolymerStatusEvent) => void): () => void;
@@ -2585,6 +2518,22 @@ export interface AnimationAgency {
   seekSnippet(name: string, offsetSec: number): void;
   updateSnippet(name: string, params: Record<string, unknown>): void;
   removeSnippet(name: string): void;
+  pauseSnippet(name: string): void;
+  resumeSnippet(name: string, snippet?: PolymerAnimationSnippet, options?: { autoPlay?: boolean; [key: string]: unknown }): void;
+  /** Build a private native handle without playing. Forces autoPlay: false. */
+  prepareSnippet(snippet: PolymerAnimationSnippet, options?: { autoPlay?: boolean; [key: string]: unknown }): void;
+  /** Remove all scheduled snippets in this agency, including peer-owned snippets. Does not stop baked clips. */
+  clearSnippets(): void;
+  /** Refresh the catalog from the runtime when omitted; does not start playback or fetch assets. */
+  loadBakedClips(clips?: AnimationBakedClipInfo[]): void;
+  playBaked(name: string, options?: Record<string, unknown>): void;
+  stopBaked(name: string): void;
+  pauseBaked(name: string): void;
+  resumeBaked(name: string): void;
+  seekBaked(name: string, offsetSec: number): void;
+  updateBakedParams(name: string, params: Record<string, unknown>): void;
+  /** Stop all baked handles tracked by this agency, including held actions. Does not remove snippets. */
+  stopAllBaked(): void;
   dispose(): void;
 }
 
@@ -2787,8 +2736,7 @@ export type CharacterAgencyDispatch =
   | { agency: 'conversation'; command: ConversationDispatch }
   | { agency: 'tts'; command: TTSDispatch }
   | { agency: 'lipSync'; command: LipSyncDispatch }
-  | { agency: 'prosodic'; command: ProsodicDispatch }
-  | { agency: 'animation'; command: AnimationDispatch };
+  | { agency: 'prosodic'; command: ProsodicDispatch };
 
 export interface CharacterAgencies {
   input: PolymerInputStream<CharacterAgencyDispatch>;
@@ -2858,11 +2806,14 @@ 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 }>;
   curves?: Record<string, CurvePoint[]>;
+  /** Per-AU character-relative balance, -1 left to +1 right; canonical clip input. */
+  balanceMap?: Record<string, number>;
+  /** Per-AU morph strength; does not attenuate the AU's bone contribution. */
+  mixWeights?: Record<string, number>;
   channels?: PolymerSnippetChannel[];
   isPlaying?: boolean;
   loop?: boolean;