@vgai/engine 0.5.4 → 0.5.6

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

@@ -0,0 +1,349 @@
+import * as THREE from 'three';
+import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
+import { evaluateBlendTree } from './blend-node';
+import { clipNamesOf, collectMachineAnimationMeta, isBlendTreeAnimationMeta, } from './xstate-animation-meta';
+/** A binding-time problem such as a missing clip, bone, or ambiguous layer. */
+export class AnimationBindingError extends Error {
+    stateId;
+    constructor(message, stateId) {
+        super(message);
+        this.stateId = stateId;
+        this.name = 'AnimationBindingError';
+    }
+}
+/** The state machine behind a bound actor, from whichever half of the actor
+ *  shape carries it. Throws rather than silently binding nothing when the
+ *  actor is not a state-machine actor (a promise/callback actor has no
+ *  `meta.animation` to collect). */
+export function machineOfXStateActor(actor) {
+    const logic = actor.logic;
+    if (logic?.root)
+        return logic;
+    const snapshot = actor.getSnapshot();
+    if (snapshot?.machine?.root)
+        return snapshot.machine;
+    throw new AnimationBindingError('[bindXStateAnimation] the actor exposes no state machine — only a state-machine ' +
+        'actor carries the `meta.animation` this binder reads');
+}
+let inspectionVersion = 0;
+const inspectionListeners = new Set();
+/** React/useSyncExternalStore-compatible lifecycle signal for live editor inspection. */
+export function subscribeXStateAnimationBindings(listener) {
+    inspectionListeners.add(listener);
+    return () => inspectionListeners.delete(listener);
+}
+/** Monotonic snapshot changed whenever a binding is attached or disposed. */
+export function getXStateAnimationBindingsVersion() {
+    return inspectionVersion;
+}
+function notifyInspectionLifecycle() {
+    inspectionVersion++;
+    for (const listener of inspectionListeners)
+        listener();
+}
+const layerOf = (meta) => meta.layer ?? 'base';
+const layerWeightOf = (meta) => meta.weight ?? 1;
+const blendModeOf = (meta) => meta.blendMode ?? 'override';
+function targetNameOf(track) {
+    try {
+        return THREE.PropertyBinding.parseTrackName(track.name).nodeName ?? '';
+    }
+    catch {
+        const dot = track.name.indexOf('.');
+        return dot < 0 ? track.name : track.name.slice(0, dot);
+    }
+}
+function subtreeNames(root, requested, trackNames) {
+    const names = new Set();
+    const missing = [];
+    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, mask, root, stateId) {
+    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) {
+    return weights.reduce((a, b) => (b.weight > a.weight ? b : a), weights[0]);
+}
+/**
+ * Bind a native XState actor to native Three actions.
+ *
+ * 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, mixer, clips, options = {}) {
+    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 = machineOfXStateActor(actor).root;
+    const entries = collectMachineAnimationMeta(machineRoot);
+    const metaByStateId = new Map(entries.map((entry) => [entry.stateId, entry.meta]));
+    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);
+            }
+        }
+    }
+    // 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();
+    function actionKey(stateId, meta, clipName) {
+        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}`;
+            }
+            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();
+    function ensureAction(key, loop, speed, weight) {
+        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();
+            cached = { action, clip };
+            actionCache.set(key, cached);
+        }
+        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) {
+        const raw = options.selectParameters
+            ? options.selectParameters(context)
+            : context;
+        return new Map(Object.entries(raw ?? {}));
+    }
+    function weightsOf(stateId, meta, context) {
+        const weights = isBlendTreeAnimationMeta(meta)
+            ? evaluateBlendTree(meta.blendTree, readParameters(context))
+            : [{ clip: meta.clip, weight: 1 }];
+        return weights.map(({ clip, weight }) => ({
+            clip,
+            weight,
+            actionKey: actionKey(stateId, meta, clip),
+        }));
+    }
+    const activeLayers = new Map();
+    let disposed = false;
+    function silence(weights, except, duration) {
+        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);
+        }
+    }
+    function applyLiveBlendWeights(state, context) {
+        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);
+        }
+    }
+    function enterState(stateId, meta, context) {
+        const layer = layerOf(meta);
+        const outgoing = activeLayers.get(layer) ?? null;
+        const weights = weightsOf(stateId, meta, context);
+        const dominant = dominantOf(weights);
+        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 duration = meta.crossfade?.duration ?? 0;
+        const warp = meta.crossfade?.warp ?? false;
+        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);
+            }
+        }
+        const active = {
+            layer,
+            stateId,
+            meta,
+            natural: weights,
+            dominantActionKey: dominant.actionKey,
+            crossfadeRemaining: duration,
+        };
+        activeLayers.set(layer, active);
+        if (isBlendTreeAnimationMeta(meta) && duration <= 0)
+            applyLiveBlendWeights(active, context);
+    }
+    function activeStateIds(snapshot) {
+        return Object.keys(snapshot.getMeta()).filter((id) => metaByStateId.has(id));
+    }
+    function reconcile(snapshot) {
+        const nextByLayer = new Map();
+        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);
+        }
+        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)
+            reconcile(snapshot);
+    });
+    function tick(dt) {
+        if (disposed)
+            return;
+        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);
+            }
+        }
+        mixer.update(dt);
+    }
+    const binding = {
+        tick,
+        actor,
+        getActiveLayers: () => [...activeLayers.values()].map((active) => ({
+            layer: active.layer,
+            stateId: active.stateId,
+            clips: active.natural.map((weighted) => weighted.clip),
+            clipWeights: active.natural.map((weighted) => ({
+                clip: weighted.clip,
+                weight: actionCache.get(weighted.actionKey)?.action.getEffectiveWeight() ?? 0,
+            })),
+            weight: layerWeightOf(active.meta),
+            blendMode: blendModeOf(active.meta),
+            ...(active.meta.boneMask ? { boneMask: active.meta.boneMask } : {}),
+        })),
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            options.systems?.remove('animation', tick);
+            subscription.unsubscribe();
+            for (const { action, clip } of actionCache.values()) {
+                action.stop();
+                mixer.uncacheAction(clip, action.getRoot());
+            }
+            actionCache.clear();
+            activeLayers.clear();
+            if (getUserData(owner, '_xstateAnimation') === binding) {
+                deleteUserData(owner, '_xstateAnimation');
+                notifyInspectionLifecycle();
+            }
+        },
+    };
+    setUserData(owner, '_xstateAnimation', binding);
+    notifyInspectionLifecycle();
+    options.systems?.add('animation', tick);
+    return binding;
+}

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

@@ -0,0 +1,266 @@
+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").
+ *
+ * ## Native layered composition
+ *
+ * Parallel XState regions may drive independent named layers. Each layer can
+ * filter a clip to selected bone subtrees, scale its weight, and use normal
+ * override or Three's native additive blend mode. XState still owns all
+ * state/transition semantics; these fields only describe how the active
+ * state's native `AnimationAction`s are composed by the binding.
+ *
+ * ## 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 AnimationBoneMaskSchema: z.ZodObject<{
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type AnimationBoneMask = z.infer<typeof AnimationBoneMaskSchema>;
+declare const ClipAnimationMetaSchema: z.ZodObject<{
+    layer: z.ZodOptional<z.ZodString>;
+    weight: z.ZodOptional<z.ZodNumber>;
+    blendMode: z.ZodOptional<z.ZodEnum<{
+        override: "override";
+        additive: "additive";
+    }>>;
+    boneMask: z.ZodOptional<z.ZodObject<{
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    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<{
+    layer: z.ZodOptional<z.ZodString>;
+    weight: z.ZodOptional<z.ZodNumber>;
+    blendMode: z.ZodOptional<z.ZodEnum<{
+        override: "override";
+        additive: "additive";
+    }>>;
+    boneMask: z.ZodOptional<z.ZodObject<{
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    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<{
+    layer: z.ZodOptional<z.ZodString>;
+    weight: z.ZodOptional<z.ZodNumber>;
+    blendMode: z.ZodOptional<z.ZodEnum<{
+        override: "override";
+        additive: "additive";
+    }>>;
+    boneMask: z.ZodOptional<z.ZodObject<{
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    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<{
+    layer: z.ZodOptional<z.ZodString>;
+    weight: z.ZodOptional<z.ZodNumber>;
+    blendMode: z.ZodOptional<z.ZodEnum<{
+        override: "override";
+        additive: "additive";
+    }>>;
+    boneMask: z.ZodOptional<z.ZodObject<{
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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;AAElF,QAAA,MAAM,uBAAuB;;;kBAiB0C,CAAC;AAExE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AA2BxE,QAAA,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;kBAiBlB,CAAC;AAEZ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,QAAA,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQvB,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"}