@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/src/animation/xstate-animation-binding.ts

@@ -1,8 +1,11 @@
 import * as THREE from 'three';
 import type { Actor, AnyActor, AnyStateMachine } from 'xstate';
+import type { createSystemRunner } from '../core/system-runner';
+import { deleteUserData, getUserData, setUserData } from '../scene/user-data';
 import type { BlendTreeDef } from './anim-graph-types';
 import { evaluateBlendTree } from './blend-node';
 import {
+  type AnimationBoneMask,
   type AnimationMetaStateNodeLike,
   clipNamesOf,
   collectMachineAnimationMeta,
@@ -11,69 +14,7 @@ import {
   type StateAnimationMeta,
 } from './xstate-animation-meta';
 
-/**
- * E2 — bind a native XState actor to a native `THREE.AnimationMixer` (spec
- * §11 E2, §5.6, §3.3).
- *
- * A native XState actor drives native `THREE.AnimationAction`s: entering a
- * state activates its `meta.animation` clip(s); leaving it deactivates them.
- * There is no VGAI-specific trigger vocabulary — callers drive the machine
- * with ordinary `actor.send(event)` (or the actor is externally owned and
- * this binding merely observes it); XState alone decides which state is
- * active.
- *
- * ## How enter/exit crossfades use NATIVE Three primitives (not a
- * hand-rolled weight scheduler)
- *
- * The former `AnimGraph` runtime (removed by E5) pre-played every action at
- * weight 0 and re-set every action's weight explicitly every frame,
- * BYPASSING `AnimationAction.fadeIn`/`fadeOut`/`crossFadeTo` (to dodge
- * multi-layer weight-summing bugs it hit historically).
- * E2 deliberately does the opposite, per the spec AC ("use
- * AnimationAction.crossFadeTo / fadeIn / fadeOut per the metadata"): the
- * ENTER/EXIT edge of an XState state transition is represented by one real
- * Three fade call, and `mixer.update(dt)` — the same call that advances clip
- * time — is what advances the fade too. No parallel elapsed-time clock
- * drives "is the fade done" for a plain (non-blend-tree) state; Three's own
- * scheduler is authoritative end to end.
- *
- * A **blend-tree** state is, at the instant of entry, represented by ONE
- * clip — its heaviest-weighted child at that instant (the same "representative"
- * duration/action heuristic the removed `AnimGraph.LayerRuntime` used) — which
- * receives the native crossFadeTo/fadeIn. Sibling
- * children stay silent (weight 0) until the crossfade window elapses, at
- * which point the FULL live blend-tree distribution (`evaluateBlendTree`,
- * reused verbatim from `blend-node.ts` — no reimplementation) takes over via
- * `setEffectiveWeight` every tick, recomputed from the actor's live
- * context/selector value. This is a documented simplification (Three's
- * `crossFadeTo` is strictly 1-to-1; there is no native N-ary blend-tree
- * crossfade), the same spirit as `blend-node.ts`'s own documented 2D
- * "smooth approximation, not Delaunay/barycentric" caveat. The crossfade
- * window itself is tracked as a small elapsed-seconds counter, decremented
- * by the SAME `dt` passed to `mixer.update(dt)` — it never drifts from
- * Three's own fade schedule because both are driven by the identical `dt`
- * stream, so it is bookkeeping for "when to hand off from native fade to
- * live blend", not a second competing scheduler.
- *
- * ## Mixer advancement uses the canonical engine ANIMATION phase
- *
- * `tick(dt)` has exactly the engine's `SystemFn` shape (`core/types.ts`:
- * `(dt: number) => void`) — a caller registers this binding on the engine's
- * one real fixed-step scheduler at the ANIMATION phase, exactly as any other
- * per-frame system: `ctx.systems.add(SystemPhase.ANIMATION, binding.tick)`
- * (or, when the binding is owned by a `GameComponent` that also owns the
- * actor — the §5.6 pattern the examples use — the component simply calls
- * `binding.tick(dt)` from its own `update(dt)`). Either way mixer advancement
- * rides that one scheduler; no second scheduler is invented here. (This is
- * the same ANIMATION-phase slot the removed `AnimGraph` runtime's global
- * `animationSystem` occupied before E5 — see
- * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.3/§11 E5. The D1
- * `AnimationClock` — `animation-clock.ts` — is a distinct, sibling concern: a
- * per-cinematic/Theatre-timeline seek clock for scrubbing/export, not wired
- * into ordinary gameplay ticking today.)
- */
-
-/** Thrown for a binding-time problem: a missing clip, or a target-less bind. */
+/** A binding-time problem such as a missing clip, bone, or ambiguous layer. */
 export class AnimationBindingError extends Error {
   constructor(
     message: string,
@@ -85,77 +26,161 @@ export class AnimationBindingError extends Error {
 }
 
 export interface XStateAnimationBindingOptions {
+  /** Select live numeric/boolean blend-tree parameters from actor context. */
+  selectParameters?: (context: unknown) => Record<string, number | boolean>;
+  /** Root whose named Bone/Object3D hierarchy is used by `boneMask`. Defaults to mixer root. */
+  root?: THREE.Object3D;
+  /** Entity that exposes this binding to editor/runtime inspection. Defaults to `root`. */
+  owner?: THREE.Object3D;
   /**
-   * Reads the blend-tree parameter map from the actor's live context.
-   * Defaults to treating `context` itself as `Record<string, number | boolean>`
-   * (matches the §5.6 example: `context: { speed: number; grounded: boolean }`
-   * fed straight into a blend tree keyed by `parameter: 'speed'`). Override
-   * when a machine's blend-tree parameters need deriving from context via a
-   * selector rather than reading top-level fields directly.
+   * Engine runner used to register `tick` in the canonical animation phase.
+   * Pass `ctx.systems`; disposal removes the callback automatically. When
+   * omitted, the caller owns ticking (useful for standalone Three tests).
    */
-  selectParameters?: (context: unknown) => Record<string, number | boolean>;
+  systems?: Pick<ReturnType<typeof createSystemRunner>, 'add' | 'remove'>;
+}
+
+export interface XStateAnimationLayerState {
+  readonly layer: string;
+  readonly stateId: string;
+  readonly clips: readonly string[];
+  readonly weight: number;
+  readonly blendMode: 'override' | 'additive';
+  readonly boneMask?: AnimationBoneMask;
 }
 
 export interface XStateAnimationBinding {
-  /**
-   * Advance the bound mixer (and any live blend-tree weights) by `dt`
-   * seconds. Register on the engine's `'animation'` phase — see the module
-   * doc above. A no-op after `dispose()`.
-   */
+  /** Advance native actions/mixer. Register this in the engine animation phase. */
   tick: (dt: number) => void;
-  /** The bound actor, for convenience (`binding.actor.send({...})`). */
   readonly actor: AnyActor;
-  /**
-   * Stops observing the actor (does NOT stop the actor itself — the actor's
-   * lifecycle is the caller's, this binding only ever subscribed to it) and
-   * uncaches every `AnimationAction` this binding created from the mixer, so
-   * a dispose+rebind cycle (e.g. hot-reload, despawn/respawn) does not leak
-   * mixer-cached actions. Idempotent; `tick()` is a no-op after this.
-   */
+  /** Current native composition, useful to the editor and game diagnostics. */
+  getActiveLayers: () => readonly XStateAnimationLayerState[];
+  /** Unsubscribe, stop/uncache actions, and remove owner inspection data. Idempotent. */
   dispose: () => void;
 }
 
+let inspectionVersion = 0;
+const inspectionListeners = new Set<() => void>();
+
+/** React/useSyncExternalStore-compatible lifecycle signal for live editor inspection. */
+export function subscribeXStateAnimationBindings(listener: () => void): () => void {
+  inspectionListeners.add(listener);
+  return () => inspectionListeners.delete(listener);
+}
+
+/** Monotonic snapshot changed whenever a binding is attached or disposed. */
+export function getXStateAnimationBindingsVersion(): number {
+  return inspectionVersion;
+}
+
+function notifyInspectionLifecycle(): void {
+  inspectionVersion++;
+  for (const listener of inspectionListeners) listener();
+}
+
 interface WeightedClip {
   clip: string;
+  actionKey: string;
   weight: number;
 }
 
 interface ActiveState {
+  layer: string;
   stateId: string;
   meta: StateAnimationMeta;
-  /** The action(s) this state's `meta` refers to, one weighted entry per clip. */
   natural: WeightedClip[];
-  /** The single clip carrying the native crossFadeTo/fadeIn schedule. */
-  dominantClip: string;
-  /** Seconds remaining in the enter crossfade; 0 once settled (or if duration was 0). */
+  dominantActionKey: string;
   crossfadeRemaining: number;
 }
 
-function dominantOf(weights: WeightedClip[]): WeightedClip {
-  return weights.reduce((a, b) => (b.weight > a.weight ? b : a), weights[0]!);
+interface CachedAction {
+  action: THREE.AnimationAction;
+  clip: THREE.AnimationClip;
 }
 
-function naturalWeightsOf(meta: StateAnimationMeta): WeightedClip[] {
-  if (isBlendTreeAnimationMeta(meta)) {
-    // AnimationBlendTree (xstate-animation-meta.ts) is structurally
-    // identical to BlendTreeDef (anim-graph-types.ts) by design — reuse
-    // evaluateBlendTree verbatim, no conversion/reimplementation.
-    return [];
+const layerOf = (meta: StateAnimationMeta): string => meta.layer ?? 'base';
+const layerWeightOf = (meta: StateAnimationMeta): number => meta.weight ?? 1;
+const blendModeOf = (meta: StateAnimationMeta): 'override' | 'additive' =>
+  meta.blendMode ?? 'override';
+
+function targetNameOf(track: THREE.KeyframeTrack): string {
+  try {
+    return THREE.PropertyBinding.parseTrackName(track.name).nodeName ?? '';
+  } catch {
+    const dot = track.name.indexOf('.');
+    return dot < 0 ? track.name : track.name.slice(0, dot);
   }
-  return [{ clip: meta.clip, weight: 1 }];
+}
+
+function subtreeNames(root: THREE.Object3D, requested: readonly string[], trackNames: Set<string>) {
+  const names = new Set<string>();
+  const missing: string[] = [];
+  for (const requestedName of requested) {
+    let found = false;
+    root.traverse((object) => {
+      if (object.name !== requestedName) return;
+      found = true;
+      object.traverse((descendant) => {
+        if (descendant.name) names.add(descendant.name);
+      });
+    });
+    // Some exporters target a named node not retained as a discoverable Bone.
+    // Exact track-target matches remain useful, but cannot imply descendants.
+    if (trackNames.has(requestedName)) {
+      found = true;
+      names.add(requestedName);
+    }
+    if (!found) missing.push(requestedName);
+  }
+  return { names, missing };
+}
+
+function maskedClip(
+  source: THREE.AnimationClip,
+  mask: AnimationBoneMask,
+  root: THREE.Object3D,
+  stateId: string,
+): THREE.AnimationClip {
+  const trackNames = new Set(source.tracks.map(targetNameOf));
+  const included = mask.include ? subtreeNames(root, mask.include, trackNames) : undefined;
+  const excluded = mask.exclude ? subtreeNames(root, mask.exclude, trackNames) : undefined;
+  const missing = [...(included?.missing ?? []), ...(excluded?.missing ?? [])];
+  if (missing.length) {
+    throw new AnimationBindingError(
+      `[bindXStateAnimation] state "${stateId}" boneMask names unknown bones/objects: ${missing.join(', ')}`,
+      stateId,
+    );
+  }
+  const tracks = source.tracks.filter((track) => {
+    const name = targetNameOf(track);
+    return (!included || included.names.has(name)) && !excluded?.names.has(name);
+  });
+  if (tracks.length === 0) {
+    throw new AnimationBindingError(
+      `[bindXStateAnimation] state "${stateId}" boneMask removes every track from clip "${source.name}"`,
+      stateId,
+    );
+  }
+  return new THREE.AnimationClip(
+    source.name,
+    source.duration,
+    tracks.map((track) => track.clone()),
+  );
+}
+
+function dominantOf(weights: WeightedClip[]): WeightedClip {
+  return weights.reduce((a, b) => (b.weight > a.weight ? b : a), weights[0]!);
 }
 
 /**
- * Bind an XState actor to a `THREE.AnimationMixer`.
- *
- * Validates EVERY state's `meta.animation` (via `collectMachineAnimationMeta`,
- * E1) and resolves every referenced clip name against `clips` up front, at
- * bind time — before the actor enters any of those states — so an agent
- * authoring a machine with a typo'd clip name gets an actionable error
- * immediately, not only once gameplay happens to reach that state.
+ * Bind a native XState actor to native Three actions.
  *
- * @throws {AnimationBindingError} if a state's meta references a clip name
- *   not present in `clips`, naming both the state and the clip.
+ * One active animated state is allowed per named layer. Parallel XState
+ * regions therefore compose lower-body locomotion, upper-body weapon states,
+ * facial animation, and other independent layers without introducing a
+ * second transition language. Bone masks clone/filter native clip tracks;
+ * additive layers use `AnimationUtils.makeClipAdditive` and Three's additive
+ * blend mode. Single unlayered machines retain the original clip/action path.
  */
 export function bindXStateAnimation(
   actor: Actor<AnyStateMachine>,
@@ -163,12 +188,18 @@ export function bindXStateAnimation(
   clips: Map<string, THREE.AnimationClip>,
   options: XStateAnimationBindingOptions = {},
 ): XStateAnimationBinding {
-  const root = actor.logic.root as unknown as AnimationMetaStateNodeLike;
-  const entries: MachineAnimationMetaEntry[] = collectMachineAnimationMeta(root);
-  const metaByStateId = new Map(entries.map((e) => [e.stateId, e.meta]));
+  const mixerRoot = mixer.getRoot();
+  const root = options.root ?? (mixerRoot instanceof THREE.Object3D ? mixerRoot : undefined);
+  if (!root) {
+    throw new AnimationBindingError(
+      '[bindXStateAnimation] a THREE.Object3D `root` option is required when the mixer uses AnimationObjectGroup',
+    );
+  }
+  const owner = options.owner ?? root;
+  const machineRoot = actor.logic.root as unknown as AnimationMetaStateNodeLike;
+  const entries: MachineAnimationMetaEntry[] = collectMachineAnimationMeta(machineRoot);
+  const metaByStateId = new Map(entries.map((entry) => [entry.stateId, entry.meta]));
 
-  // Resolve every referenced clip up front — actionable, named errors before
-  // any state is ever entered.
   for (const entry of entries) {
     for (const clipName of clipNamesOf(entry.meta)) {
       if (!clips.has(clipName)) {
@@ -181,25 +212,58 @@ export function bindXStateAnimation(
     }
   }
 
-  const actionCache = new Map<string, THREE.AnimationAction>();
-  function ensureAction(clipName: string, loop: boolean, speed: number): THREE.AnimationAction {
-    let action = actionCache.get(clipName);
-    if (!action) {
-      const clip = clips.get(clipName);
-      if (!clip) {
-        // Unreachable given the up-front resolution above; kept as a named,
-        // defensive error rather than a silent `mixer.clipAction(undefined)`.
-        throw new AnimationBindingError(`[bindXStateAnimation] clip "${clipName}" not found`);
+  // Different layers need distinct AnimationActions even when they use the
+  // same source clip. A plain base state keeps the original clip identity for
+  // backwards-compatible mixer.existingAction(sourceClip) behavior.
+  const preparedClips = new Map<string, THREE.AnimationClip>();
+  function actionKey(stateId: string, meta: StateAnimationMeta, clipName: string): string {
+    const transformed =
+      layerOf(meta) !== 'base' || Boolean(meta.boneMask) || blendModeOf(meta) === 'additive';
+    return transformed ? `${stateId}\u0000${clipName}` : clipName;
+  }
+  for (const { stateId, meta } of entries) {
+    for (const clipName of clipNamesOf(meta)) {
+      const key = actionKey(stateId, meta, clipName);
+      if (preparedClips.has(key)) continue;
+      const source = clips.get(clipName)!;
+      let prepared = meta.boneMask ? maskedClip(source, meta.boneMask, root, stateId) : source;
+      if (prepared !== source || key !== clipName) {
+        if (prepared === source) prepared = source.clone();
+        prepared.name = `${source.name}@${layerOf(meta)}:${stateId}`;
       }
-      action = mixer.clipAction(clip);
+      if (blendModeOf(meta) === 'additive') {
+        THREE.AnimationUtils.makeClipAdditive(prepared);
+        prepared.blendMode = THREE.AdditiveAnimationBlendMode;
+      } else {
+        prepared.blendMode = THREE.NormalAnimationBlendMode;
+      }
+      preparedClips.set(key, prepared);
+    }
+  }
+
+  const actionCache = new Map<string, CachedAction>();
+  function ensureAction(
+    key: string,
+    loop: boolean,
+    speed: number,
+    weight: number,
+  ): THREE.AnimationAction {
+    let cached = actionCache.get(key);
+    if (!cached) {
+      const clip = preparedClips.get(key);
+      if (!clip)
+        throw new AnimationBindingError(`[bindXStateAnimation] prepared clip "${key}" not found`);
+      const action = mixer.clipAction(clip);
       action.setEffectiveWeight(0);
-      action.play(); // must be "active" for mixer.update() to tick it at all (Three only advances active actions)
-      actionCache.set(clipName, action);
+      action.play();
+      cached = { action, clip };
+      actionCache.set(key, cached);
     }
-    action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, Infinity);
-    action.clampWhenFinished = !loop;
-    action.timeScale = speed;
-    return action;
+    cached.action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, Infinity);
+    cached.action.clampWhenFinished = !loop;
+    cached.action.timeScale = speed;
+    cached.action.weight = weight;
+    return cached.action;
   }
 
   function readParameters(context: unknown): Map<string, number | boolean> {
@@ -209,190 +273,164 @@ export function bindXStateAnimation(
     return new Map(Object.entries(raw ?? {}));
   }
 
-  let active: ActiveState | null = null;
+  function weightsOf(stateId: string, meta: StateAnimationMeta, context: unknown): WeightedClip[] {
+    const weights = isBlendTreeAnimationMeta(meta)
+      ? evaluateBlendTree(meta.blendTree as unknown as BlendTreeDef, readParameters(context))
+      : [{ clip: meta.clip, weight: 1 }];
+    return weights.map(({ clip, weight }) => ({
+      clip,
+      weight,
+      actionKey: actionKey(stateId, meta, clip),
+    }));
+  }
+
+  const activeLayers = new Map<string, ActiveState>();
   let disposed = false;
 
-  // Known limitation (shared with plain Three.js `crossFadeTo` usage generally):
-  // `AnimationAction.fadeOut(duration)` always schedules a fixed 1→0 ramp, not
-  // "current weight → 0" — interrupting an action that is itself still
-  // mid-fade-in (e.g. a state transitions again before its own crossfade
-  // settles) can produce a brief visible pop back toward full weight before
-  // fading out. This is a native Three scheduling property, not something
-  // this binding's bookkeeping can smooth over without re-implementing
-  // Three's own weight scheduler; same accepted-approximation spirit as
-  // `blend-node.ts`'s documented 2D IDW caveat.
   function silence(weights: WeightedClip[], except: string | undefined, duration: number): void {
-    for (const { clip: clipName } of weights) {
-      if (clipName === except) continue;
-      const action = actionCache.get(clipName);
+    for (const weighted of weights) {
+      if (weighted.actionKey === except) continue;
+      const action = actionCache.get(weighted.actionKey)?.action;
       if (!action) continue;
       if (duration > 0) action.fadeOut(duration);
       else action.setEffectiveWeight(0);
     }
   }
 
-  /** Ensure every clip in `weights` has an action; reset the dominant one to weight 1 (base
-   *  multiplier for the fade schedule about to be applied) and every sibling to silent (0). */
-  function prepareStateActions(
-    weights: WeightedClip[],
-    dominantClip: string,
-    loop: boolean,
-    speed: number,
-  ): THREE.AnimationAction {
-    for (const { clip: clipName } of weights) ensureAction(clipName, loop, speed);
-
-    const dominantAction = actionCache.get(dominantClip)!;
-    dominantAction.reset();
-    // `setEffectiveWeight(1)` (not just `.reset()`) is required here: reset() does not touch the
-    // base `.weight` multiplier a scheduled fade scales against, and this action may previously
-    // have been a silenced blend-tree sibling left at `.weight === 0` — left alone, that would mute
-    // the crossFadeTo/fadeIn schedule applied below to a permanent 0.
-    dominantAction.setEffectiveWeight(1);
-
-    // Non-dominant children of THIS state start silent; they pick up their
-    // live share once the crossfade window elapses (see `tick`).
-    for (const { clip: clipName } of weights) {
-      if (clipName === dominantClip) continue;
-      const action = actionCache.get(clipName)!;
-      action.reset();
-      action.setEffectiveWeight(0);
-    }
-    return dominantAction;
-  }
-
-  /** Apply the enter-transition schedule: native crossFadeTo (from a previous dominant), a plain
-   *  fadeIn (first-ever activation with a duration), or an immediate hard cut (duration 0). */
-  function activateTransition(
-    dominantAction: THREE.AnimationAction,
-    outgoing: ActiveState | null,
-    duration: number,
-    warp: boolean,
-  ): void {
-    if (!outgoing) {
-      if (duration > 0) dominantAction.fadeIn(duration);
-      else dominantAction.setEffectiveWeight(1);
-      return;
-    }
-    // Fade out every non-dominant sibling of the OUTGOING state — a plain
-    // (non-blend) outgoing state has none.
-    silence(outgoing.natural, outgoing.dominantClip, duration);
-    const previousDominant = actionCache.get(outgoing.dominantClip);
-    if (previousDominant && duration > 0) {
-      previousDominant.crossFadeTo(dominantAction, duration, warp);
-      return;
+  function applyLiveBlendWeights(state: ActiveState, context: unknown): void {
+    if (!isBlendTreeAnimationMeta(state.meta)) return;
+    state.natural = weightsOf(state.stateId, state.meta, context);
+    const layerWeight = layerWeightOf(state.meta);
+    for (const weighted of state.natural) {
+      actionCache.get(weighted.actionKey)?.action.setEffectiveWeight(weighted.weight * layerWeight);
     }
-    previousDominant?.setEffectiveWeight(0);
-    dominantAction.setEffectiveWeight(1);
   }
 
   function enterState(stateId: string, meta: StateAnimationMeta, context: unknown): void {
-    const isBlend = isBlendTreeAnimationMeta(meta);
-    const weights = isBlend
-      ? evaluateBlendTree(meta.blendTree as unknown as BlendTreeDef, readParameters(context))
-      : naturalWeightsOf(meta);
+    const layer = layerOf(meta);
+    const outgoing = activeLayers.get(layer) ?? null;
+    const weights = weightsOf(stateId, meta, context);
     const dominant = dominantOf(weights);
-    const loop = isBlend ? true : meta.loop;
-    const speed = isBlend ? 1 : meta.speed;
+    const loop = isBlendTreeAnimationMeta(meta) ? true : meta.loop;
+    const speed = isBlendTreeAnimationMeta(meta) ? 1 : meta.speed;
+    const layerWeight = layerWeightOf(meta);
+
+    for (const weighted of weights) ensureAction(weighted.actionKey, loop, speed, layerWeight);
+    const dominantAction = actionCache.get(dominant.actionKey)!.action;
+    dominantAction.reset().setEffectiveWeight(layerWeight);
+    for (const weighted of weights) {
+      if (weighted.actionKey === dominant.actionKey) continue;
+      actionCache.get(weighted.actionKey)!.action.reset().setEffectiveWeight(0);
+    }
 
-    const dominantAction = prepareStateActions(weights, dominant.clip, loop, speed);
     const duration = meta.crossfade?.duration ?? 0;
     const warp = meta.crossfade?.warp ?? false;
-    activateTransition(dominantAction, active, duration, warp);
+    if (!outgoing) {
+      if (duration > 0) dominantAction.fadeIn(duration);
+    } else {
+      silence(outgoing.natural, outgoing.dominantActionKey, duration);
+      const previous = actionCache.get(outgoing.dominantActionKey)?.action;
+      if (previous && duration > 0) previous.crossFadeTo(dominantAction, duration, warp);
+      else {
+        previous?.setEffectiveWeight(0);
+        dominantAction.setEffectiveWeight(layerWeight);
+      }
+    }
 
-    active = {
+    const active: ActiveState = {
+      layer,
       stateId,
       meta,
       natural: weights,
-      dominantClip: dominant.clip,
+      dominantActionKey: dominant.actionKey,
       crossfadeRemaining: duration,
     };
+    activeLayers.set(layer, active);
+    if (isBlendTreeAnimationMeta(meta) && duration <= 0) applyLiveBlendWeights(active, context);
+  }
 
-    // Zero-duration blend-tree entry: no crossfade window to wait out —
-    // apply the full live distribution immediately instead of leaving
-    // siblings silent for one extra tick.
-    if (isBlend && duration <= 0) {
-      applyLiveBlendWeights(active, context);
-    }
+  function activeStateIds(snapshot: { getMeta: () => Record<string, unknown> }): string[] {
+    return Object.keys(snapshot.getMeta()).filter((id) => metaByStateId.has(id));
   }
 
-  function applyLiveBlendWeights(state: ActiveState, context: unknown): void {
-    if (!isBlendTreeAnimationMeta(state.meta)) return;
-    const params = readParameters(context);
-    const weights = evaluateBlendTree(state.meta.blendTree as unknown as BlendTreeDef, params);
-    state.natural = weights;
-    for (const { clip: clipName, weight } of weights) {
-      actionCache.get(clipName)?.setEffectiveWeight(weight);
+  function reconcile(snapshot: { getMeta: () => Record<string, unknown>; context: unknown }): void {
+    const nextByLayer = new Map<string, string>();
+    for (const stateId of activeStateIds(snapshot)) {
+      const meta = metaByStateId.get(stateId)!;
+      const layer = layerOf(meta);
+      const previous = nextByLayer.get(layer);
+      if (previous) {
+        throw new AnimationBindingError(
+          `[bindXStateAnimation] animated states "${previous}" and "${stateId}" are both active ` +
+            `on layer "${layer}". Give parallel regions distinct meta.animation.layer names.`,
+          stateId,
+        );
+      }
+      nextByLayer.set(layer, stateId);
     }
-  }
 
-  const initialSnapshot = actor.getSnapshot();
-  const initialStateId = leafStateIdOf(initialSnapshot, metaByStateId);
-  if (initialStateId) {
-    enterState(initialStateId, metaByStateId.get(initialStateId)!, initialSnapshot.context);
+    for (const [layer, active] of activeLayers) {
+      if (nextByLayer.has(layer)) continue;
+      silence(active.natural, undefined, 0);
+      activeLayers.delete(layer);
+    }
+    for (const [layer, stateId] of nextByLayer) {
+      if (activeLayers.get(layer)?.stateId === stateId) continue;
+      enterState(stateId, metaByStateId.get(stateId)!, snapshot.context);
+    }
   }
 
+  const initialSnapshot = actor.getSnapshot();
+  reconcile(initialSnapshot);
   const subscription = actor.subscribe((snapshot) => {
-    if (disposed) return;
-    const stateId = leafStateIdOf(snapshot, metaByStateId);
-    const meta = stateId ? metaByStateId.get(stateId) : undefined;
-    if (meta && stateId && stateId !== active?.stateId) {
-      enterState(stateId, meta, snapshot.context);
-    }
+    if (!disposed) reconcile(snapshot);
   });
 
   function tick(dt: number): void {
     if (disposed) return;
-    if (active && active.crossfadeRemaining > 0) {
-      active.crossfadeRemaining = Math.max(0, active.crossfadeRemaining - dt);
-      if (active.crossfadeRemaining <= 0 && isBlendTreeAnimationMeta(active.meta)) {
-        applyLiveBlendWeights(active, actor.getSnapshot().context);
+    const context = actor.getSnapshot().context;
+    for (const active of activeLayers.values()) {
+      if (active.crossfadeRemaining > 0) {
+        active.crossfadeRemaining = Math.max(0, active.crossfadeRemaining - dt);
+        if (active.crossfadeRemaining <= 0) applyLiveBlendWeights(active, context);
+      } else {
+        applyLiveBlendWeights(active, context);
       }
-    } else if (active && isBlendTreeAnimationMeta(active.meta)) {
-      applyLiveBlendWeights(active, actor.getSnapshot().context);
     }
     mixer.update(dt);
   }
 
-  return {
+  const binding: XStateAnimationBinding = {
     tick,
     actor,
+    getActiveLayers: () =>
+      [...activeLayers.values()].map((active) => ({
+        layer: active.layer,
+        stateId: active.stateId,
+        clips: active.natural.map((weighted) => weighted.clip),
+        weight: layerWeightOf(active.meta),
+        blendMode: blendModeOf(active.meta),
+        ...(active.meta.boneMask ? { boneMask: active.meta.boneMask } : {}),
+      })),
     dispose(): void {
       if (disposed) return;
       disposed = true;
+      options.systems?.remove('animation', tick);
       subscription.unsubscribe();
-      for (const [clipName, action] of actionCache) {
+      for (const { action, clip } of actionCache.values()) {
         action.stop();
-        mixer.uncacheAction(action.getClip(), action.getRoot());
-        actionCache.delete(clipName);
+        mixer.uncacheAction(clip, action.getRoot());
+      }
+      actionCache.clear();
+      activeLayers.clear();
+      if (getUserData(owner, '_xstateAnimation') === binding) {
+        deleteUserData(owner, '_xstateAnimation');
+        notifyInspectionLifecycle();
       }
-      active = null;
     },
   };
-}
-
-/**
- * The full state id (e.g. `"character-animation.locomotion"`) of the single
- * currently-active leaf that declares `meta.animation`, per `snapshot.value`.
- * XState's `snapshot.getMeta()` is keyed by EVERY active state node's id
- * (including ancestors with no meta of their own); this narrows to whichever
- * one is actually described in `metaByStateId`. Machines with more than one
- * simultaneously-active animated leaf (parallel regions each declaring
- * `meta.animation`) are out of scope for this binding — v1 assumes exactly
- * one active animation-bearing state at a time, matching the single-mixer
- * §5.6 example; a machine that violates this throws rather than silently
- * picking one.
- */
-function leafStateIdOf(
-  snapshot: { getMeta: () => Record<string, unknown> },
-  metaByStateId: Map<string, StateAnimationMeta>,
-): string | undefined {
-  const activeIds = Object.keys(snapshot.getMeta()).filter((id) => metaByStateId.has(id));
-  if (activeIds.length > 1) {
-    throw new AnimationBindingError(
-      `[bindXStateAnimation] more than one animated state is simultaneously active ` +
-        `(${activeIds.join(', ')}) — parallel-region animation composition is not supported by this ` +
-        'binding; exactly one active meta.animation state is required.',
-    );
-  }
-  return activeIds[0];
+  setUserData(owner, '_xstateAnimation', binding);
+  notifyInspectionLifecycle();
+  options.systems?.add('animation', tick);
+  return binding;
 }