@lovelace_lol/polymer 0.0.14 → 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
@@ -459,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
@@ -671,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;
@@ -2874,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;