@vgai/engine 0.2.0 → 0.3.0

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

@@ -0,0 +1,398 @@
+import * as THREE from 'three';
+import type { Actor, AnyActor, AnyStateMachine } from 'xstate';
+import type { BlendTreeDef } from './anim-graph-types';
+import { evaluateBlendTree } from './blend-node';
+import {
+  type AnimationMetaStateNodeLike,
+  clipNamesOf,
+  collectMachineAnimationMeta,
+  isBlendTreeAnimationMeta,
+  type MachineAnimationMetaEntry,
+  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. */
+export class AnimationBindingError extends Error {
+  constructor(
+    message: string,
+    readonly stateId?: string,
+  ) {
+    super(message);
+    this.name = 'AnimationBindingError';
+  }
+}
+
+export interface XStateAnimationBindingOptions {
+  /**
+   * 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.
+   */
+  selectParameters?: (context: unknown) => Record<string, number | boolean>;
+}
+
+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()`.
+   */
+  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.
+   */
+  dispose: () => void;
+}
+
+interface WeightedClip {
+  clip: string;
+  weight: number;
+}
+
+interface ActiveState {
+  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). */
+  crossfadeRemaining: number;
+}
+
+function dominantOf(weights: WeightedClip[]): WeightedClip {
+  return weights.reduce((a, b) => (b.weight > a.weight ? b : a), weights[0]!);
+}
+
+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 [];
+  }
+  return [{ clip: meta.clip, weight: 1 }];
+}
+
+/**
+ * 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.
+ *
+ * @throws {AnimationBindingError} if a state's meta references a clip name
+ *   not present in `clips`, naming both the state and the clip.
+ */
+export function bindXStateAnimation(
+  actor: Actor<AnyStateMachine>,
+  mixer: THREE.AnimationMixer,
+  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]));
+
+  // 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)) {
+        throw new AnimationBindingError(
+          `[bindXStateAnimation] state "${entry.stateId}" references clip "${clipName}", which is ` +
+            `not present in the supplied clips map. Known clips: ${[...clips.keys()].join(', ') || '(none)'}`,
+          entry.stateId,
+        );
+      }
+    }
+  }
+
+  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`);
+      }
+      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.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, Infinity);
+    action.clampWhenFinished = !loop;
+    action.timeScale = speed;
+    return action;
+  }
+
+  function readParameters(context: unknown): Map<string, number | boolean> {
+    const raw = options.selectParameters
+      ? options.selectParameters(context)
+      : (context as Record<string, number | boolean> | null | undefined);
+    return new Map(Object.entries(raw ?? {}));
+  }
+
+  let active: ActiveState | null = null;
+  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);
+      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;
+    }
+    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 dominant = dominantOf(weights);
+    const loop = isBlend ? true : meta.loop;
+    const speed = isBlend ? 1 : meta.speed;
+
+    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);
+
+    active = {
+      stateId,
+      meta,
+      natural: weights,
+      dominantClip: dominant.clip,
+      crossfadeRemaining: duration,
+    };
+
+    // 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 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);
+    }
+  }
+
+  const initialSnapshot = actor.getSnapshot();
+  const initialStateId = leafStateIdOf(initialSnapshot, metaByStateId);
+  if (initialStateId) {
+    enterState(initialStateId, metaByStateId.get(initialStateId)!, initialSnapshot.context);
+  }
+
+  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);
+    }
+  });
+
+  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);
+      }
+    } else if (active && isBlendTreeAnimationMeta(active.meta)) {
+      applyLiveBlendWeights(active, actor.getSnapshot().context);
+    }
+    mixer.update(dt);
+  }
+
+  return {
+    tick,
+    actor,
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      subscription.unsubscribe();
+      for (const [clipName, action] of actionCache) {
+        action.stop();
+        mixer.uncacheAction(action.getClip(), action.getRoot());
+        actionCache.delete(clipName);
+      }
+      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];
+}

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

@@ -0,0 +1,282 @@
+import { z } from 'zod';
+
+/**
+ * E1 — Zod/TypeScript metadata attached to XState state `meta.animation`
+ * (spec §11 E1, §5.6, §3.3).
+ *
+ * This module defines ONLY animation data: which clip(s) a state plays, how
+ * they loop/blend/crossfade, and (for locomotion-style states) how a 1D/2D/
+ * direct blend tree distributes weight across several clips from a live
+ * parameter. It intentionally contains **no transition vocabulary** — no
+ * `on`/`target`/`guard`/`always`/`after`/`entry`/`exit`. XState alone owns
+ * states, transitions, events, and guards (§3.3); this metadata is read-only
+ * data a binding (`xstate-animation-binding.ts`, E2) consumes to drive a
+ * `THREE.AnimationMixer` when XState enters/exits a state. Every schema below
+ * is `.strict()` specifically so that smuggling a transition-shaped key into
+ * `meta.animation` is a loud Zod "unrecognized key" error, not a silently
+ * ignored field (E1 AC: "Metadata contains no transition language").
+ *
+ * ## Deliberately out of scope: layers, additive blending, bone masks
+ *
+ * The spec asks for layer/weight/additive metadata "if retained" and bone
+ * masks "if supported by the Three implementation" (§11 E1). Neither is
+ * supported by the current Three-facing animation code: no bone-masking or
+ * blend-compositing across layers exists (the former `AnimGraph` layers, now
+ * removed by E5, never had it either, and rejected `blendMode`/`weight`/
+ * `boneMask` at parse for exactly this reason — those fields had no runtime
+ * reader anywhere in the engine). Per this repo's policy ("Do not author
+ * schema fields that have no runtime reader" — CLAUDE.md), this module does
+ * not declare fields for capabilities nothing reads. A single XState machine
+ * drives one mixer's weight budget; multi-machine/multi-layer composition
+ * (if ever added) is a distinct, future binding concern with its own reader,
+ * not a dead field here.
+ *
+ * ## Blend tree shape
+ *
+ * Deliberately structurally IDENTICAL to `anim-graph-types.ts`'s
+ * `BlendTreeDef` (same `type`/`parameter`/`parameterY`/`children[].clip`/
+ * `.threshold`/`.thresholdY`/`.weight` fields) so the binding can hand a
+ * parsed `AnimationBlendTree` straight to the existing, already-tested
+ * `evaluateBlendTree` (`blend-node.ts`) with zero conversion — E2 reuses that
+ * function verbatim rather than re-implementing 1D/2D/direct blend math.
+ */
+
+// ---------------------------------------------------------------------------
+// Blend tree children
+// ---------------------------------------------------------------------------
+
+const AnimationBlendChildSchema = z
+  .object({
+    clip: z.string().min(1).describe('Animation clip name this child plays'),
+    threshold: z.number().describe('1D/2D blend position on the primary parameter axis'),
+    thresholdY: z
+      .number()
+      .optional()
+      .describe('2D blend position on the secondary parameter axis (2D blend trees only)'),
+    weight: z
+      .number()
+      .min(0)
+      .optional()
+      .describe('Explicit weight for "direct" blend trees (ignored by 1D/2D)'),
+  })
+  .strict();
+
+export type AnimationBlendChild = z.infer<typeof AnimationBlendChildSchema>;
+
+const AnimationBlendTree1DSchema = z
+  .object({
+    type: z.literal('1D').describe('Interpolates linearly between sorted children by threshold'),
+    parameter: z.string().min(1).describe('Context/selector value driving the blend'),
+    children: z
+      .array(AnimationBlendChildSchema)
+      .min(2, '1D blend tree needs at least 2 children to interpolate between'),
+  })
+  .strict();
+
+const AnimationBlendTree2DSchema = z
+  .object({
+    type: z
+      .literal('2D')
+      .describe('Inverse-distance-weights children by (parameter, parameterY) position'),
+    parameter: z.string().min(1).describe('Primary axis context/selector value'),
+    parameterY: z.string().min(1).describe('Secondary axis context/selector value'),
+    children: z
+      .array(AnimationBlendChildSchema.extend({ thresholdY: z.number() }))
+      .min(1, '2D blend tree needs at least 1 child'),
+  })
+  .strict();
+
+const AnimationBlendTreeDirectSchema = z
+  .object({
+    type: z.literal('direct').describe('Each child has an explicit weight, normalized to sum to 1'),
+    // `parameter` is unused by direct blending (evaluateBlendTree never reads
+    // it for `type: 'direct'`) but kept required+defaulted so the parsed
+    // value stays structurally assignable to `BlendTreeDef`
+    // (`anim-graph-types.ts`), which declares `parameter: string` for every
+    // blend mode — the same convention that type already uses.
+    parameter: z.string().default(''),
+    children: z
+      .array(AnimationBlendChildSchema.extend({ weight: z.number().min(0) }))
+      .min(1, 'direct blend tree needs at least 1 child'),
+  })
+  .strict();
+
+export const AnimationBlendTreeSchema = z.discriminatedUnion('type', [
+  AnimationBlendTree1DSchema,
+  AnimationBlendTree2DSchema,
+  AnimationBlendTreeDirectSchema,
+]);
+
+export type AnimationBlendTree = z.infer<typeof AnimationBlendTreeSchema>;
+
+// ---------------------------------------------------------------------------
+// Crossfade / blend-in-out metadata (shared by clip and blend-tree states)
+// ---------------------------------------------------------------------------
+
+const AnimationCrossfadeMetaSchema = z
+  .object({
+    duration: z
+      .number()
+      .min(0)
+      .default(0)
+      .describe(
+        'Seconds to blend from the previously active clip into this state on entry, applied via ' +
+          'native `AnimationAction.crossFadeTo`/`fadeIn` (E2). 0 = instant activation, no fade.',
+      ),
+    warp: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Passed through to AnimationAction.crossFadeTo's `warp` param — linearly warps timeScale " +
+          'across the two clips during the blend so differing clip lengths line up. Default false.',
+      ),
+  })
+  .strict()
+  .describe('Blend-in/out/crossfade timing for entering this state');
+
+export type AnimationCrossfadeMeta = z.infer<typeof AnimationCrossfadeMetaSchema>;
+
+// ---------------------------------------------------------------------------
+// Per-state animation metadata: single clip OR blend tree, plus crossfade
+// ---------------------------------------------------------------------------
+
+const ClipAnimationMetaSchema = z
+  .object({
+    clip: z.string().min(1).describe('Single clip to play while this XState state is active'),
+    loop: z
+      .boolean()
+      .default(true)
+      .describe(
+        'Loop the clip (THREE.LoopRepeat) vs play once (THREE.LoopOnce, clamped on last frame)',
+      ),
+    speed: z
+      .number()
+      .positive()
+      .default(1)
+      .describe('Playback speed multiplier (AnimationAction.timeScale)'),
+    crossfade: AnimationCrossfadeMetaSchema.optional(),
+  })
+  .strict();
+
+export type ClipAnimationMeta = z.infer<typeof ClipAnimationMetaSchema>;
+
+const BlendTreeAnimationMetaSchema = z
+  .object({
+    blendTree: AnimationBlendTreeSchema.describe(
+      'Multiple clips blended by a live context/selector-driven parameter',
+    ),
+    crossfade: AnimationCrossfadeMetaSchema.optional(),
+  })
+  .strict();
+
+export type BlendTreeAnimationMeta = z.infer<typeof BlendTreeAnimationMetaSchema>;
+
+/**
+ * The full shape of `state.meta.animation` for one XState state (spec §5.6):
+ * exactly one of a single clip or a blend tree, plus optional crossfade
+ * timing. `.strict()` on both branches is what makes authoring a transition
+ * keyword (`on`, `target`, `guard`, …) inside `meta.animation` a validation
+ * error instead of a silently-accepted second transition dialect.
+ */
+export const StateAnimationMetaSchema = z.union([
+  ClipAnimationMetaSchema,
+  BlendTreeAnimationMetaSchema,
+]);
+
+export type StateAnimationMeta = z.infer<typeof StateAnimationMetaSchema>;
+
+/** True iff a validated meta declares a single clip rather than a blend tree. */
+export function isClipAnimationMeta(meta: StateAnimationMeta): meta is ClipAnimationMeta {
+  return 'clip' in meta;
+}
+
+/** True iff a validated meta declares a blend tree rather than a single clip. */
+export function isBlendTreeAnimationMeta(meta: StateAnimationMeta): meta is BlendTreeAnimationMeta {
+  return 'blendTree' in meta;
+}
+
+// ---------------------------------------------------------------------------
+// Validation entry point
+// ---------------------------------------------------------------------------
+
+/** Thrown by `parseStateAnimationMeta` — always names the offending state id. */
+export class AnimationMetaValidationError extends Error {
+  constructor(
+    message: string,
+    readonly stateId: string,
+    readonly issues: z.ZodIssue[],
+  ) {
+    super(message);
+    this.name = 'AnimationMetaValidationError';
+  }
+}
+
+/**
+ * Validate one state's `meta.animation` value. Called by the E2 binding for
+ * every state a machine declares (both at bind time, up front, and — for
+ * belt-and-suspenders — again whenever a state is entered).
+ *
+ * @throws {AnimationMetaValidationError} naming the state id and every Zod
+ *   issue (path + message) — e.g. an unrecognized `on`/`target` key, a
+ *   missing `clip`, or a 1D blend tree with only one child.
+ */
+export function parseStateAnimationMeta(stateId: string, raw: unknown): StateAnimationMeta {
+  const result = StateAnimationMetaSchema.safeParse(raw);
+  if (!result.success) {
+    const detail = result.error.issues
+      .map((issue) => `${issue.path.length ? issue.path.join('.') : '(root)'}: ${issue.message}`)
+      .join('; ');
+    throw new AnimationMetaValidationError(
+      `[xstate-animation] invalid meta.animation for state "${stateId}": ${detail}`,
+      stateId,
+      result.error.issues,
+    );
+  }
+  return result.data;
+}
+
+// ---------------------------------------------------------------------------
+// Machine-wide collection (used by E2 to validate + resolve clips up front)
+// ---------------------------------------------------------------------------
+
+/** The minimal shape of an XState `StateNode` this module needs to walk. */
+export interface AnimationMetaStateNodeLike {
+  id: string;
+  meta?: { animation?: unknown } & Record<string, unknown>;
+  states?: Record<string, AnimationMetaStateNodeLike>;
+}
+
+export interface MachineAnimationMetaEntry {
+  stateId: string;
+  meta: StateAnimationMeta;
+}
+
+/**
+ * Walk every state node in a machine (from its root `StateNode`, e.g.
+ * `actor.logic.root`) and validate every `meta.animation` value found.
+ * States with no `meta.animation` are skipped (not every XState state needs
+ * to drive animation). Returns one entry per animated state, in document
+ * order.
+ *
+ * @throws {AnimationMetaValidationError} on the FIRST invalid meta found —
+ *   naming the specific state id, so an agent authoring a machine gets an
+ *   actionable pointer straight to the bad state instead of a generic error.
+ */
+export function collectMachineAnimationMeta(
+  root: AnimationMetaStateNodeLike,
+): MachineAnimationMetaEntry[] {
+  const out: MachineAnimationMetaEntry[] = [];
+  const visit = (node: AnimationMetaStateNodeLike): void => {
+    if (node.meta && 'animation' in node.meta && node.meta.animation !== undefined) {
+      out.push({ stateId: node.id, meta: parseStateAnimationMeta(node.id, node.meta.animation) });
+    }
+    for (const child of Object.values(node.states ?? {})) visit(child);
+  };
+  visit(root);
+  return out;
+}
+
+/** Every clip name referenced anywhere in a validated meta (1 for clip states, N for blend trees). */
+export function clipNamesOf(meta: StateAnimationMeta): string[] {
+  return isClipAnimationMeta(meta) ? [meta.clip] : meta.blendTree.children.map((c) => c.clip);
+}