@vgai/engine 0.2.0 → 0.3.0

package/dist/animation/xstate-animation-binding.js

@@ -0,0 +1,307 @@
+import * as THREE from 'three';
+import { evaluateBlendTree } from './blend-node';
+import { clipNamesOf, collectMachineAnimationMeta, isBlendTreeAnimationMeta, } 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 {
+    stateId;
+    constructor(message, stateId) {
+        super(message);
+        this.stateId = stateId;
+        this.name = 'AnimationBindingError';
+    }
+}
+function dominantOf(weights) {
+    return weights.reduce((a, b) => (b.weight > a.weight ? b : a), weights[0]);
+}
+function naturalWeightsOf(meta) {
+    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, mixer, clips, options = {}) {
+    const root = actor.logic.root;
+    const entries = 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();
+    function ensureAction(clipName, loop, speed) {
+        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) {
+        const raw = options.selectParameters
+            ? options.selectParameters(context)
+            : context;
+        return new Map(Object.entries(raw ?? {}));
+    }
+    let active = 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, except, duration) {
+        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, dominantClip, loop, speed) {
+        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, outgoing, duration, warp) {
+        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, meta, context) {
+        const isBlend = isBlendTreeAnimationMeta(meta);
+        const weights = isBlend
+            ? evaluateBlendTree(meta.blendTree, 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, context) {
+        if (!isBlendTreeAnimationMeta(state.meta))
+            return;
+        const params = readParameters(context);
+        const weights = evaluateBlendTree(state.meta.blendTree, 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) {
+        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() {
+            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, metaByStateId) {
+    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/dist/animation/xstate-animation-meta.d.ts

@@ -0,0 +1,228 @@
+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.
+ */
+declare const AnimationBlendChildSchema: z.ZodObject<{
+    clip: z.ZodString;
+    threshold: z.ZodNumber;
+    thresholdY: z.ZodOptional<z.ZodNumber>;
+    weight: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type AnimationBlendChild = z.infer<typeof AnimationBlendChildSchema>;
+export declare const AnimationBlendTreeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"1D">;
+    parameter: z.ZodString;
+    children: z.ZodArray<z.ZodObject<{
+        clip: z.ZodString;
+        threshold: z.ZodNumber;
+        thresholdY: z.ZodOptional<z.ZodNumber>;
+        weight: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"2D">;
+    parameter: z.ZodString;
+    parameterY: z.ZodString;
+    children: z.ZodArray<z.ZodObject<{
+        clip: z.ZodString;
+        threshold: z.ZodNumber;
+        weight: z.ZodOptional<z.ZodNumber>;
+        thresholdY: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"direct">;
+    parameter: z.ZodDefault<z.ZodString>;
+    children: z.ZodArray<z.ZodObject<{
+        clip: z.ZodString;
+        threshold: z.ZodNumber;
+        thresholdY: z.ZodOptional<z.ZodNumber>;
+        weight: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "type">;
+export type AnimationBlendTree = z.infer<typeof AnimationBlendTreeSchema>;
+declare const AnimationCrossfadeMetaSchema: z.ZodObject<{
+    duration: z.ZodDefault<z.ZodNumber>;
+    warp: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type AnimationCrossfadeMeta = z.infer<typeof AnimationCrossfadeMetaSchema>;
+declare const ClipAnimationMetaSchema: z.ZodObject<{
+    clip: z.ZodString;
+    loop: z.ZodDefault<z.ZodBoolean>;
+    speed: z.ZodDefault<z.ZodNumber>;
+    crossfade: z.ZodOptional<z.ZodObject<{
+        duration: z.ZodDefault<z.ZodNumber>;
+        warp: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ClipAnimationMeta = z.infer<typeof ClipAnimationMetaSchema>;
+declare const BlendTreeAnimationMetaSchema: z.ZodObject<{
+    blendTree: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"1D">;
+        parameter: z.ZodString;
+        children: z.ZodArray<z.ZodObject<{
+            clip: z.ZodString;
+            threshold: z.ZodNumber;
+            thresholdY: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"2D">;
+        parameter: z.ZodString;
+        parameterY: z.ZodString;
+        children: z.ZodArray<z.ZodObject<{
+            clip: z.ZodString;
+            threshold: z.ZodNumber;
+            weight: z.ZodOptional<z.ZodNumber>;
+            thresholdY: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"direct">;
+        parameter: z.ZodDefault<z.ZodString>;
+        children: z.ZodArray<z.ZodObject<{
+            clip: z.ZodString;
+            threshold: z.ZodNumber;
+            thresholdY: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>], "type">;
+    crossfade: z.ZodOptional<z.ZodObject<{
+        duration: z.ZodDefault<z.ZodNumber>;
+        warp: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$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 declare const StateAnimationMetaSchema: z.ZodUnion<readonly [z.ZodObject<{
+    clip: z.ZodString;
+    loop: z.ZodDefault<z.ZodBoolean>;
+    speed: z.ZodDefault<z.ZodNumber>;
+    crossfade: z.ZodOptional<z.ZodObject<{
+        duration: z.ZodDefault<z.ZodNumber>;
+        warp: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    blendTree: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"1D">;
+        parameter: z.ZodString;
+        children: z.ZodArray<z.ZodObject<{
+            clip: z.ZodString;
+            threshold: z.ZodNumber;
+            thresholdY: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"2D">;
+        parameter: z.ZodString;
+        parameterY: z.ZodString;
+        children: z.ZodArray<z.ZodObject<{
+            clip: z.ZodString;
+            threshold: z.ZodNumber;
+            weight: z.ZodOptional<z.ZodNumber>;
+            thresholdY: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"direct">;
+        parameter: z.ZodDefault<z.ZodString>;
+        children: z.ZodArray<z.ZodObject<{
+            clip: z.ZodString;
+            threshold: z.ZodNumber;
+            thresholdY: z.ZodOptional<z.ZodNumber>;
+            weight: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>], "type">;
+    crossfade: z.ZodOptional<z.ZodObject<{
+        duration: z.ZodDefault<z.ZodNumber>;
+        warp: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>;
+export type StateAnimationMeta = z.infer<typeof StateAnimationMetaSchema>;
+/** True iff a validated meta declares a single clip rather than a blend tree. */
+export declare function isClipAnimationMeta(meta: StateAnimationMeta): meta is ClipAnimationMeta;
+/** True iff a validated meta declares a blend tree rather than a single clip. */
+export declare function isBlendTreeAnimationMeta(meta: StateAnimationMeta): meta is BlendTreeAnimationMeta;
+/** Thrown by `parseStateAnimationMeta` — always names the offending state id. */
+export declare class AnimationMetaValidationError extends Error {
+    readonly stateId: string;
+    readonly issues: z.ZodIssue[];
+    constructor(message: string, stateId: string, issues: z.ZodIssue[]);
+}
+/**
+ * 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 declare function parseStateAnimationMeta(stateId: string, raw: unknown): StateAnimationMeta;
+/** 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 declare function collectMachineAnimationMeta(root: AnimationMetaStateNodeLike): MachineAnimationMetaEntry[];
+/** Every clip name referenced anywhere in a validated meta (1 for clip states, N for blend trees). */
+export declare function clipNamesOf(meta: StateAnimationMeta): string[];
+export {};
+//# sourceMappingURL=xstate-animation-meta.d.ts.map

package/dist/animation/xstate-animation-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xstate-animation-meta.d.ts","sourceRoot":"","sources":["../../src/animation/xstate-animation-meta.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAMH,QAAA,MAAM,yBAAyB;;;;;kBAcpB,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAwC5E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAInC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAM1E,QAAA,MAAM,4BAA4B;;;kBAmBkC,CAAC;AAErE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAMlF,QAAA,MAAM,uBAAuB;;;;;;;;kBAgBlB,CAAC;AAEZ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,QAAA,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAOvB,CAAC;AAEZ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBAGnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,IAAI,iBAAiB,CAEvF;AAED,iFAAiF;AACjF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,IAAI,sBAAsB,CAEjG;AAMD,iFAAiF;AACjF,qBAAa,4BAA6B,SAAQ,KAAK;IAGnD,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;gBAF7B,OAAO,EAAE,MAAM,EACN,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAKhC;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,kBAAkB,CAazF;AAMD,4EAA4E;AAC5E,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,kBAAkB,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,0BAA0B,GAC/B,yBAAyB,EAAE,CAU7B;AAED,sGAAsG;AACtG,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAE9D"}