@aura3d/engine 1.0.3 → 1.0.5

package/dist/engine/agent-api/AnimationController.js

@@ -0,0 +1,2192 @@
+import { animationClipEventKey, sampleClipEvents } from "../../animation/index.js";
+const defaultLayerName = "base";
+export const auraAnimationRetargetDocumentedConstraints = [
+    {
+        code: "explicit-humanoid-bone-map",
+        severity: "error",
+        message: "Retargeting requires explicit humanoid bone-map metadata; Aura3D does not infer arbitrary external rigs."
+    },
+    {
+        code: "matching-rest-pose",
+        severity: "warning",
+        message: "Retargeting metadata must document source and target rest-pose assumptions such as T-pose, A-pose, or bind pose."
+    },
+    {
+        code: "uniform-scale",
+        severity: "warning",
+        message: "Retargeting supports source-level uniform scale metadata only; runtime proportion warping is not implied."
+    },
+    {
+        code: "root-motion-policy",
+        severity: "warning",
+        message: "Retargeting metadata must state whether root motion is preserved or suppressed by gameplay."
+    },
+    {
+        code: "no-runtime-ik",
+        severity: "info",
+        message: "Aura3D source retarget metadata does not claim runtime IK solving."
+    },
+    {
+        code: "no-automatic-proportion-warp",
+        severity: "info",
+        message: "Aura3D source retarget metadata does not claim automatic humanoid proportion correction."
+    }
+];
+export class AnimationController {
+    id;
+    clips = new Map();
+    listeners = new Map();
+    states = new Map();
+    requiredClips;
+    requiredBones;
+    layerWeights = new Map();
+    layerMetadata = new Map();
+    runtimeNodeBindings = new Map();
+    defaultLayer;
+    embeddedGLB;
+    skeleton;
+    retarget;
+    externalHumanoidLibrary;
+    rootMotion;
+    poseBakedFallback;
+    poseBakedFallbackMetadata;
+    suppressRootMotion;
+    clockTime = 0;
+    nextRegistryIndex = 0;
+    nextPlaybackIndex = 0;
+    pendingCrossFades = [];
+    constructor(options = {}) {
+        this.id = options.id;
+        this.defaultLayer = options.defaultLayer ?? defaultLayerName;
+        this.requiredClips = [...(options.requiredClips ?? [])];
+        this.requiredBones = [...(options.requiredBones ?? [])];
+        this.skeleton = options.skeleton;
+        this.retarget = normalizeRetargetBinding(options.retarget, options.externalHumanoidLibrary);
+        this.externalHumanoidLibrary = options.externalHumanoidLibrary;
+        this.rootMotion = options.rootMotion;
+        this.poseBakedFallback = clonePose(options.poseBakedFallback);
+        this.poseBakedFallbackMetadata = options.poseBakedFallback
+            ? {
+                enabled: true,
+                source: "controller-options",
+                fallbackKind: "registry-pose"
+            }
+            : undefined;
+        this.suppressRootMotion = options.suppressRootMotion ?? options.rootMotion?.suppress ?? false;
+        this.layerWeights.set(this.defaultLayer, 1);
+        this.registerLayerMetadata(inferLayerMetadata(this.defaultLayer));
+        for (const layer of options.layers ?? []) {
+            this.registerLayerMetadata(layer);
+        }
+        if (options.clipRegistry) {
+            this.registerEmbeddedGLBClips(options.clipRegistry);
+        }
+        if (options.clips) {
+            this.registerClips(options.clips);
+        }
+    }
+    on(type, listener) {
+        const listeners = this.listeners.get(type) ?? new Set();
+        listeners.add(listener);
+        this.listeners.set(type, listeners);
+        return () => {
+            const current = this.listeners.get(type);
+            if (!current)
+                return;
+            current.delete(listener);
+            if (current.size === 0)
+                this.listeners.delete(type);
+        };
+    }
+    once(type, listener) {
+        const unsubscribe = this.on(type, (payload) => {
+            unsubscribe();
+            listener(payload);
+        });
+        return unsubscribe;
+    }
+    onEvent(filterOrListener, maybeListener) {
+        if (typeof filterOrListener === "function") {
+            return this.on("event", filterOrListener);
+        }
+        const filter = filterOrListener;
+        const listener = maybeListener;
+        if (!listener) {
+            throw new Error("onEvent(filter, listener) requires a listener.");
+        }
+        return this.on("event", (invocation) => {
+            const event = invocation.event;
+            if (event.name === filter || event.type === filter || event.tags?.includes(filter)) {
+                listener(invocation);
+            }
+        });
+    }
+    registerClip(definition) {
+        const registered = this.createRegisteredClip(definition);
+        this.clips.set(registered.id, registered);
+        return registered;
+    }
+    registerClips(definitions) {
+        return definitions.map((definition) => this.registerClip(definition));
+    }
+    registerLayerMetadata(layer) {
+        const normalized = cloneLayerMetadata(layer);
+        this.layerMetadata.set(normalized.id, normalized);
+        if (!this.layerWeights.has(normalized.id)) {
+            this.layerWeights.set(normalized.id, 1);
+        }
+        return normalized;
+    }
+    getLayerMetadata(layer) {
+        return this.layerMetadata.get(layer);
+    }
+    listLayerMetadata() {
+        return [...this.layerMetadata.values()];
+    }
+    bindRuntimeNode(node, options = {}) {
+        const id = options.id ?? `${node.id}:animation`;
+        const binding = {
+            id,
+            node,
+            options: {
+                applyOnUpdate: true,
+                applyPose: true,
+                applyMorphTargets: true,
+                syncCaptureTime: true,
+                syncLoop: true,
+                syncSpeed: true,
+                ...options,
+                id
+            }
+        };
+        this.runtimeNodeBindings.set(id, binding);
+        binding.snapshot = this.applyRuntimeNodeBinding(binding);
+        return {
+            id,
+            nodeId: node.id,
+            node,
+            update: () => this.applyRuntimeNodeBinding(binding),
+            snapshot: () => binding.snapshot ?? this.createRuntimeNodeBindingSnapshot(binding),
+            dispose: () => {
+                this.runtimeNodeBindings.delete(id);
+                if (typeof node.setAnimationBinding === "function") {
+                    node.setAnimationBinding(undefined);
+                }
+                if (typeof node.setAnimationPose === "function") {
+                    node.setAnimationPose(undefined);
+                }
+                if (typeof node.setMorphTargets === "function") {
+                    node.setMorphTargets({});
+                }
+            }
+        };
+    }
+    unbindRuntimeNode(idOrNode) {
+        const id = typeof idOrNode === "string" ? idOrNode : `${idOrNode.id}:animation`;
+        const binding = this.runtimeNodeBindings.get(id);
+        if (binding && typeof binding.node.setAnimationBinding === "function") {
+            binding.node.setAnimationBinding(undefined);
+        }
+        if (binding && typeof binding.node.setAnimationPose === "function") {
+            binding.node.setAnimationPose(undefined);
+        }
+        if (binding && typeof binding.node.setMorphTargets === "function") {
+            binding.node.setMorphTargets({});
+        }
+        this.runtimeNodeBindings.delete(id);
+    }
+    runtimeNodeBindingSnapshots() {
+        return [...this.runtimeNodeBindings.values()].map((binding) => binding.snapshot ?? this.createRuntimeNodeBindingSnapshot(binding));
+    }
+    registerEmbeddedGLBClips(source) {
+        const registry = createEmbeddedGLBAnimationClipRegistryMetadata(source);
+        this.embeddedGLB = registry;
+        this.skeleton = registry.skeleton ?? this.skeleton;
+        for (const layer of registry.layers ?? []) {
+            this.registerLayerMetadata(layer);
+        }
+        this.externalHumanoidLibrary = registry.externalHumanoidLibrary ?? this.externalHumanoidLibrary;
+        this.retarget = normalizeRetargetBinding(registry.retarget ?? this.retarget, registry.externalHumanoidLibrary ?? this.externalHumanoidLibrary);
+        this.rootMotion = registry.rootMotion ?? this.rootMotion;
+        this.suppressRootMotion = registry.suppressRootMotion ?? registry.rootMotion?.suppress ?? this.suppressRootMotion;
+        this.poseBakedFallback = clonePose(extractPoseBakedFallback(registry.poseBakedFallback)) ?? this.poseBakedFallback ?? createIdentityPose(this.skeleton);
+        this.poseBakedFallbackMetadata = extractPoseBakedFallbackRuntimeMetadata(registry.poseBakedFallback, {
+            enabled: Boolean(this.poseBakedFallback),
+            source: "embedded-glb-registry",
+            sourceAssetId: registry.assetId,
+            sourceAssetName: registry.assetName,
+            fallbackKind: "registry-pose"
+        }) ?? this.poseBakedFallbackMetadata;
+        const clips = registry.clips ?? registry.animations ?? [];
+        return clips.map((clipInput) => {
+            const definition = embeddedClipToDefinition(clipInput, registry, this.defaultLayer);
+            return this.registerClip(definition);
+        });
+    }
+    play(clipId, options = {}) {
+        const resolvedClipId = this.clips.has(clipId) ? clipId : options.fallbackClipId;
+        if (!resolvedClipId || !this.clips.has(resolvedClipId)) {
+            const diagnostic = createDiagnostic("error", "ANIMATION_CLIP_MISSING", `Animation clip "${clipId}" is not registered.`, clipId);
+            this.emit("diagnostic", diagnostic);
+            throw new Error(diagnostic.message);
+        }
+        const clip = this.requireClip(resolvedClipId);
+        const restartFromFrameZero = shouldRestartFromFrameZero(clip, options, this.layerMetadata);
+        const shouldRestart = options.restart === true || restartFromFrameZero;
+        const playOptions = restartFromFrameZero
+            ? {
+                ...options,
+                restart: true,
+                startTime: 0,
+                metadata: {
+                    ...options.metadata,
+                    restartFromFrameZero: true
+                }
+            }
+            : options;
+        const existing = this.findStateByClip(resolvedClipId);
+        if (existing && !shouldRestart) {
+            existing.status = options.paused ? "paused" : "playing";
+            existing.speed = sanitizeSpeed(options.speed ?? existing.speed);
+            existing.targetWeight = sanitizeWeight(options.weight ?? existing.targetWeight);
+            existing.weight = existing.fade ? existing.weight : existing.targetWeight;
+            existing.layer = options.layer ?? existing.layer;
+            existing.layerMetadata = this.layerMetadata.get(existing.layer) ?? inferLayerMetadata(existing.layer);
+            existing.layerWeight = this.layerWeight(existing.layer);
+            existing.inputDirection = options.direction ?? existing.inputDirection;
+            existing.rootMotionSuppressed = shouldSuppressRootMotion(options, existing.clip, this.suppressRootMotion);
+            existing.eventSource = options.eventSource ?? existing.clip.eventSource;
+            existing.metadata = options.metadata ?? existing.metadata;
+            this.applyRuntimeNodeBindings();
+            this.emitStateChanged();
+            return cloneState(existing);
+        }
+        if (existing && shouldRestart) {
+            this.states.delete(existing.id);
+            this.endState(existing, "stopped");
+        }
+        if (options.exclusive ?? true) {
+            for (const state of this.getInternalStates()) {
+                this.endState(state, "stopped");
+            }
+            this.states.clear();
+        }
+        const playback = this.createPlaybackState(clip, playOptions);
+        this.states.set(playback.id, playback);
+        this.emit("start", cloneState(playback));
+        this.applyRuntimeNodeBindings();
+        this.emitStateChanged();
+        return cloneState(playback);
+    }
+    pause(clipId) {
+        for (const state of this.selectStates(clipId)) {
+            if (state.status === "playing")
+                state.status = "paused";
+        }
+        this.applyRuntimeNodeBindings();
+        this.emitStateChanged();
+    }
+    resume(clipId) {
+        for (const state of this.selectStates(clipId)) {
+            if (state.status === "paused")
+                state.status = "playing";
+        }
+        this.applyRuntimeNodeBindings();
+        this.emitStateChanged();
+    }
+    restart(clipId, options = {}) {
+        const resolvedClipId = clipId ?? this.activeClipId();
+        if (!resolvedClipId) {
+            throw new Error("Cannot restart animation without an active clip or clipId.");
+        }
+        return this.play(resolvedClipId, {
+            ...options,
+            restart: true
+        });
+    }
+    stop(clipId, options = {}) {
+        const targets = this.selectStates(clipId);
+        const fadeOut = sanitizeDuration(options.fadeOut ?? 0);
+        for (const state of targets) {
+            if (fadeOut > 0) {
+                state.fade = {
+                    kind: "out",
+                    elapsed: 0,
+                    duration: fadeOut,
+                    fromWeight: state.weight,
+                    toWeight: 0
+                };
+                state.targetWeight = 0;
+            }
+            else {
+                this.states.delete(state.id);
+                this.endState(state, "stopped");
+            }
+        }
+        this.applyRuntimeNodeBindings();
+        this.emitStateChanged();
+    }
+    crossFade(toClipId, duration, options = {}) {
+        const fadeDuration = sanitizeDuration(duration);
+        const fromStates = this.selectCrossFadeSources(options);
+        const fromClipIds = fromStates.map((state) => state.clipId);
+        const layer = options.layer ?? options.fromLayer ?? fromStates[0]?.layer;
+        const event = {
+            fromClipIds,
+            toClipId,
+            duration: fadeDuration,
+            layer
+        };
+        this.emit("crossFadeStart", event);
+        this.emit("crossfadeStart", event);
+        this.pendingCrossFades.push(event);
+        for (const state of fromStates) {
+            state.fade = {
+                kind: "out",
+                elapsed: 0,
+                duration: fadeDuration,
+                fromWeight: state.weight,
+                toWeight: 0
+            };
+            state.targetWeight = 0;
+        }
+        const next = this.play(toClipId, {
+            ...options,
+            exclusive: false,
+            restart: true,
+            fadeIn: fadeDuration,
+            weight: options.weight ?? 1,
+            layer: options.layer ?? layer
+        });
+        if (fadeDuration === 0) {
+            this.finishCrossFade(event);
+        }
+        return next;
+    }
+    crossfade(toClipId, duration, options = {}) {
+        return this.crossFade(toClipId, duration, options);
+    }
+    setLayerWeight(layer, weight) {
+        const cleanLayer = layer.trim() || this.defaultLayer;
+        const cleanWeight = sanitizeWeight(weight);
+        this.layerWeights.set(cleanLayer, cleanWeight);
+        for (const state of this.getInternalStates()) {
+            if (state.layer === cleanLayer) {
+                state.layerWeight = cleanWeight;
+            }
+        }
+        this.applyRuntimeNodeBindings();
+        this.emitStateChanged();
+        return this;
+    }
+    setWeight(weight, layer = this.defaultLayer) {
+        return this.setLayerWeight(layer, weight);
+    }
+    update(dt) {
+        if (!Number.isFinite(dt) || dt === 0) {
+            return this.snapshot();
+        }
+        this.clockTime += dt;
+        const endedStates = [];
+        for (const state of this.getInternalStates()) {
+            this.updateFade(state, Math.abs(dt));
+            if (state.status !== "playing") {
+                continue;
+            }
+            const advance = advanceState(state, dt);
+            this.emitSampledEvents(state);
+            if (advance.loopsPassed > 0) {
+                this.emit("loop", {
+                    clipId: state.clipId,
+                    playbackId: state.id,
+                    loopCount: state.loopCount,
+                    loopsPassed: advance.loopsPassed
+                });
+            }
+            if (advance.completed) {
+                state.status = "completed";
+                state.completed = true;
+                endedStates.push(state);
+            }
+        }
+        for (const state of endedStates) {
+            this.endState(state, "completed");
+        }
+        this.removeFinishedFadeOuts();
+        this.finishCrossFadesIfReady();
+        this.applyRuntimeNodeBindings();
+        this.emitStateChanged();
+        return this.snapshot();
+    }
+    scrub(clipOrTime, timeOrOptions = {}, maybeOptions = {}) {
+        const hasClipId = typeof clipOrTime === "string";
+        const time = hasClipId ? Number(timeOrOptions) : clipOrTime;
+        const options = hasClipId ? maybeOptions : timeOrOptions;
+        const clipId = hasClipId ? clipOrTime : options.clipId ?? this.activeClipId();
+        if (!clipId) {
+            throw new Error("Cannot scrub without an active clip or clipId.");
+        }
+        let state = this.findStateByClip(clipId);
+        if (!state) {
+            if (options.createIfMissing === false) {
+                throw new Error(`Cannot scrub inactive animation clip "${clipId}".`);
+            }
+            this.play(clipId, {
+                startTime: time,
+                paused: true,
+                restart: true,
+                layer: options.layer,
+                suppressRootMotion: options.suppressRootMotion
+            });
+            state = this.findStateByClip(clipId);
+        }
+        if (!state) {
+            throw new Error(`Cannot scrub animation clip "${clipId}".`);
+        }
+        const previousTime = state.localTime;
+        state.previousLocalTime = previousTime;
+        state.localTime = normalizeStateTime(time, state.duration, state.loopMode);
+        state.playhead = state.localTime;
+        state.normalizedTime = state.duration > 0 ? state.localTime / state.duration : 0;
+        state.completed = false;
+        state.status = options.play ? "playing" : "paused";
+        if (options.emitEvents) {
+            this.emitSampledEvents(state);
+        }
+        this.emit("scrub", {
+            clipId,
+            playbackId: state.id,
+            fromTime: previousTime,
+            toTime: state.localTime
+        });
+        this.applyRuntimeNodeBindings();
+        this.emitStateChanged();
+        return this.capturePose({
+            clipId,
+            emitEvent: false,
+            suppressRootMotion: options.suppressRootMotion
+        });
+    }
+    capturePose(options = {}) {
+        const states = options.clipId
+            ? this.selectStates(options.clipId)
+            : this.getInternalStates().filter((state) => effectiveWeight(state) > 0);
+        const pose = options.time !== undefined && options.clipId
+            ? this.sampleSinglePose(this.requireClip(options.clipId), options.time, undefined, options.suppressRootMotion)
+            : this.blendStates(states, options.suppressRootMotion);
+        const diagnostics = this.diagnostics();
+        const snapshot = {
+            time: this.clockTime,
+            pose,
+            clips: states.map(cloneState),
+            diagnostics
+        };
+        if (options.emitEvent ?? true) {
+            this.emit("poseCaptured", snapshot);
+        }
+        return snapshot;
+    }
+    state(clipId) {
+        const state = clipId ? this.findStateByClip(clipId) : this.primaryState();
+        return state ? cloneState(state) : undefined;
+    }
+    snapshot() {
+        return {
+            time: this.clockTime,
+            id: this.id,
+            activeClipId: this.activeClipId(),
+            clips: this.getInternalStates().map(cloneState),
+            layers: Object.fromEntries(this.layerWeights.entries()),
+            layerMetadata: Object.fromEntries([...this.layerMetadata.entries()].map(([id, metadata]) => [id, cloneLayerMetadata(metadata)])),
+            diagnostics: this.diagnostics(),
+            rootMotionSuppressed: this.suppressRootMotion,
+            runtimeNodeBindings: this.runtimeNodeBindingSnapshots(),
+            retarget: this.retargetSnapshot(),
+            embeddedGLB: this.embeddedGLB
+                ? {
+                    assetId: this.embeddedGLB.assetId,
+                    assetName: this.embeddedGLB.assetName,
+                    clipCount: (this.embeddedGLB.clips ?? this.embeddedGLB.animations ?? []).length,
+                    skeletonBones: skeletonBoneNames(this.skeleton).size,
+                    poseBakedFallback: Boolean(this.poseBakedFallback)
+                }
+                : undefined
+        };
+    }
+    diagnostics(options = {}) {
+        const diagnostics = [];
+        const clips = this.listClips();
+        const requiredClips = [...this.requiredClips, ...(options.requiredClips ?? [])];
+        const requiredBones = [...this.requiredBones, ...(options.requiredBones ?? [])];
+        const skeletonBones = skeletonBoneNames(this.skeleton);
+        const hasSkeleton = skeletonBones.size > 0;
+        const requiresSkeleton = options.requireSkeleton === true || requiredBones.length > 0 || clips.some((clip) => clip.requiredBones.length > 0);
+        if (clips.length === 0) {
+            diagnostics.push(createDiagnostic("error", "ANIMATION_CLIPS_MISSING", "No animation clips are registered."));
+        }
+        if (requiresSkeleton && !hasSkeleton) {
+            diagnostics.push(createDiagnostic("error", "ANIMATION_SKELETON_MISSING", "Animation controller is missing skeleton metadata."));
+        }
+        for (const requiredClip of requiredClips) {
+            if (!this.clips.has(requiredClip)) {
+                diagnostics.push(createDiagnostic("error", "ANIMATION_REQUIRED_CLIP_MISSING", `Required animation clip "${requiredClip}" is missing.`, requiredClip));
+            }
+        }
+        for (const requiredBone of requiredBones) {
+            if (hasSkeleton && !skeletonBones.has(requiredBone)) {
+                diagnostics.push(createDiagnostic("error", "ANIMATION_REQUIRED_BONE_MISSING", `Required bone "${requiredBone}" is missing.`, undefined, requiredBone));
+            }
+        }
+        diagnostics.push(...this.retargetDiagnostics(options));
+        for (const clip of clips) {
+            if (clip.tracks.length === 0) {
+                diagnostics.push(createDiagnostic(clip.sample ? "info" : "warning", "ANIMATION_CLIP_EMPTY_TRACKS", `Animation clip "${clip.id}" has no tracks${clip.sample ? " and will use a sampler or pose-baked fallback." : "."}`, clip.id));
+            }
+            for (const requiredBone of clip.requiredBones) {
+                if (hasSkeleton && !skeletonBones.has(requiredBone)) {
+                    diagnostics.push(createDiagnostic("error", "ANIMATION_BONE_MISSING", `Animation clip "${clip.id}" requires missing bone "${requiredBone}".`, clip.id, requiredBone));
+                }
+            }
+            for (const track of clip.tracks) {
+                if (!track.keyframes || track.keyframes.length === 0) {
+                    diagnostics.push(createDiagnostic("warning", "ANIMATION_TRACK_EMPTY", `Animation clip "${clip.id}" has an empty track "${track.id ?? track.target}".`, clip.id, undefined, track.id ?? track.target));
+                }
+                const bone = boneNameFromTrackTarget(track.target);
+                if (bone && hasSkeleton && !skeletonBones.has(bone)) {
+                    diagnostics.push(createDiagnostic("error", "ANIMATION_BONE_MISSING", `Animation clip "${clip.id}" targets missing bone "${bone}".`, clip.id, bone, track.id ?? track.target));
+                }
+            }
+        }
+        for (const binding of this.runtimeNodeBindings.values()) {
+            if (typeof binding.node.play !== "function" && typeof binding.node.setAnimation !== "function") {
+                diagnostics.push(createDiagnostic("warning", "ANIMATION_RUNTIME_NODE_BINDING_UNSUPPORTED", `Runtime node "${binding.node.id}" is bound to an AnimationController but does not expose play() or setAnimation().`));
+            }
+            if (binding.options.applyPose !== false && typeof binding.node.setAnimationPose !== "function") {
+                diagnostics.push(createDiagnostic("warning", "ANIMATION_RUNTIME_NODE_POSE_BINDING_UNSUPPORTED", `Runtime node "${binding.node.id}" is bound to an AnimationController but does not expose setAnimationPose().`));
+            }
+            if (binding.options.applyMorphTargets !== false && typeof binding.node.setMorphTargets !== "function") {
+                diagnostics.push(createDiagnostic("warning", "ANIMATION_RUNTIME_NODE_MORPH_BINDING_UNSUPPORTED", `Runtime node "${binding.node.id}" is bound to an AnimationController but does not expose setMorphTargets().`));
+            }
+            if (binding.options.layer && !this.layerWeights.has(binding.options.layer)) {
+                diagnostics.push(createDiagnostic("warning", "ANIMATION_RUNTIME_NODE_BINDING_LAYER_MISSING", `Runtime node binding "${binding.id}" targets unknown animation layer "${binding.options.layer}".`));
+            }
+        }
+        return diagnostics;
+    }
+    retargetDiagnostics(options = {}) {
+        return this.createRetargetDiagnostics(options);
+    }
+    diagnose(options) {
+        return this.diagnostics(options);
+    }
+    clipIds() {
+        return this.listClips().map((clip) => clip.id);
+    }
+    listClips() {
+        return [...this.clips.values()].sort((a, b) => a.registryIndex - b.registryIndex);
+    }
+    getClip(clipId) {
+        return this.clips.get(clipId);
+    }
+    requireClip(clipId) {
+        const clip = this.getClip(clipId);
+        if (!clip) {
+            throw new Error(`Animation clip "${clipId}" is not registered.`);
+        }
+        return clip;
+    }
+    embeddedGLBClipRegistryMetadata() {
+        return this.embeddedGLB;
+    }
+    dispose() {
+        this.states.clear();
+        this.listeners.clear();
+        for (const binding of this.runtimeNodeBindings.values()) {
+            if (typeof binding.node.setAnimationBinding === "function") {
+                binding.node.setAnimationBinding(undefined);
+            }
+            if (typeof binding.node.setAnimationPose === "function") {
+                binding.node.setAnimationPose(undefined);
+            }
+            if (typeof binding.node.setMorphTargets === "function") {
+                binding.node.setMorphTargets({});
+            }
+        }
+        this.runtimeNodeBindings.clear();
+        this.pendingCrossFades = [];
+    }
+    createRegisteredClip(definition) {
+        if (!definition.id) {
+            throw new Error("Animation clips must have a stable id.");
+        }
+        if (!Number.isFinite(definition.duration) || definition.duration < 0) {
+            throw new Error(`Animation clip "${definition.id}" has an invalid duration.`);
+        }
+        const fallbackPose = clonePose(definition.pose) ??
+            clonePose(definition.fallbackPose) ??
+            clonePose(extractPoseBakedFallback(definition.metadata?.poseBakedFallback)) ??
+            clonePose(this.poseBakedFallback) ??
+            createIdentityPose(this.skeleton);
+        const tracks = [...(definition.tracks ?? [])];
+        const layer = definition.layer ?? definition.metadata?.layer?.id ?? this.defaultLayer;
+        const layerMetadata = cloneLayerMetadata(definition.layerMetadata ?? definition.metadata?.layer ?? this.layerMetadata.get(layer) ?? inferLayerMetadata(layer));
+        this.registerLayerMetadata(layerMetadata);
+        const externalHumanoidLibrary = definition.externalHumanoidLibrary ?? definition.metadata?.externalHumanoidLibrary ?? this.externalHumanoidLibrary;
+        const retarget = normalizeRetargetBinding(definition.retarget ?? definition.metadata?.retarget ?? this.retarget, externalHumanoidLibrary);
+        const eventSource = definition.eventSource ?? definition.metadata?.eventSource ?? (retarget ? "retargeted-source-clip" : "source-clip");
+        const restartFromFrameZero = Boolean(definition.restartFromFrameZero ??
+            definition.metadata?.restartFromFrameZero ??
+            definition.attack ??
+            definition.metadata?.attack ??
+            layerMetadata.restartFromFrameZero ??
+            definition.tags?.includes("attack"));
+        const poseBakedFallbackMetadata = createPoseBakedFallbackRuntimeMetadata(definition.id, definition, this.embeddedGLB, this.poseBakedFallbackMetadata, Boolean(fallbackPose) && !definition.sample);
+        const sample = definition.sample ?? createFallbackSampler(definition.id, tracks, fallbackPose, poseBakedFallbackMetadata);
+        const metadata = {
+            ...definition.metadata,
+            layer: layerMetadata,
+            eventSource,
+            restartFromFrameZero,
+            attack: definition.attack ?? definition.metadata?.attack,
+            retarget,
+            externalHumanoidLibrary,
+            rootMotion: definition.rootMotion ?? definition.metadata?.rootMotion,
+            suppressRootMotion: definition.suppressRootMotion ?? definition.metadata?.suppressRootMotion,
+            poseBakedFallback: Boolean(fallbackPose) && !definition.sample,
+            poseBakedFallbackMetadata
+        };
+        const registered = {
+            ...definition,
+            metadata,
+            duration: sanitizeDuration(definition.duration),
+            loop: definition.loop ?? true,
+            tags: [...(definition.tags ?? [])],
+            tracks,
+            events: [...(definition.events ?? [])].sort((a, b) => a.time - b.time || a.name.localeCompare(b.name)),
+            registryIndex: this.nextRegistryIndex,
+            layer,
+            layerMetadata,
+            requiredBones: [...(definition.requiredBones ?? [])],
+            bones: [...(definition.bones ?? [])],
+            rootMotion: definition.rootMotion ?? definition.metadata?.rootMotion,
+            suppressRootMotion: definition.suppressRootMotion ?? definition.metadata?.suppressRootMotion ?? false,
+            restartFromFrameZero,
+            eventSource,
+            retarget,
+            externalHumanoidLibrary,
+            fallbackPose,
+            poseBakedFallback: poseBakedFallbackMetadata,
+            sample
+        };
+        this.nextRegistryIndex += 1;
+        if (!this.layerWeights.has(registered.layer)) {
+            this.layerWeights.set(registered.layer, 1);
+        }
+        return registered;
+    }
+    createPlaybackState(clip, options) {
+        const targetWeight = sanitizeWeight(options.weight ?? 1);
+        const fadeIn = sanitizeDuration(options.fadeIn ?? 0);
+        const loopMode = normalizeLoopMode(options.loop, clip.loop);
+        const localTime = normalizeStateTime(options.startTime ?? 0, clip.duration, loopMode);
+        const layer = options.layer ?? clip.layer ?? this.defaultLayer;
+        const layerMetadata = this.layerMetadata.get(layer) ?? clip.layerMetadata ?? inferLayerMetadata(layer);
+        const id = options.id ?? `${clip.id}:${this.nextPlaybackIndex}`;
+        this.nextPlaybackIndex += 1;
+        return {
+            id,
+            clip,
+            clipId: clip.id,
+            status: options.paused ? "paused" : "playing",
+            localTime,
+            previousLocalTime: localTime,
+            normalizedTime: clip.duration > 0 ? localTime / clip.duration : 0,
+            duration: clip.duration,
+            speed: sanitizeSpeed(options.speed ?? 1),
+            weight: fadeIn > 0 ? 0 : targetWeight,
+            targetWeight,
+            effectiveWeight: 0,
+            layer,
+            layerMetadata,
+            layerWeight: this.layerWeight(layer),
+            loopMode,
+            loopCount: 0,
+            direction: options.direction ?? 1,
+            inputDirection: options.direction ?? 1,
+            completed: false,
+            playhead: localTime,
+            rootMotionSuppressed: shouldSuppressRootMotion(options, clip, this.suppressRootMotion),
+            restartFromFrameZero: Boolean(options.restartFromFrameZero ?? clip.restartFromFrameZero),
+            eventSource: options.eventSource ?? clip.eventSource,
+            poseBakedFallback: clip.poseBakedFallback,
+            onceEvents: new Set(),
+            metadata: options.metadata,
+            fade: fadeIn > 0
+                ? {
+                    kind: "in",
+                    elapsed: 0,
+                    duration: fadeIn,
+                    fromWeight: 0,
+                    toWeight: targetWeight
+                }
+                : undefined
+        };
+    }
+    emitSampledEvents(state) {
+        const invocations = sampleClipEvents({
+            id: state.clipId,
+            duration: state.duration,
+            events: state.clip.events
+        }, {
+            from: state.previousLocalTime,
+            to: state.localTime,
+            duration: state.duration,
+            loop: state.loopMode !== "once",
+            direction: state.direction,
+            loopCount: state.loopCount,
+            playbackTime: this.clockTime
+        });
+        for (const invocation of invocations) {
+            if (invocation.event.once) {
+                const key = animationClipEventKey(invocation.clipId, invocation.event);
+                if (state.onceEvents.has(key))
+                    continue;
+                state.onceEvents.add(key);
+            }
+            this.emit("event", {
+                ...invocation,
+                source: createClipEventSourceMetadata(state, this.clockTime, this.embeddedGLB)
+            });
+        }
+    }
+    updateFade(state, dt) {
+        if (!state.fade)
+            return;
+        if (state.fade.duration === 0) {
+            state.weight = state.fade.toWeight;
+            state.fade = undefined;
+            return;
+        }
+        const elapsed = Math.min(state.fade.duration, state.fade.elapsed + dt);
+        const alpha = elapsed / state.fade.duration;
+        state.weight = lerp(state.fade.fromWeight, state.fade.toWeight, alpha);
+        state.fade = elapsed >= state.fade.duration
+            ? undefined
+            : {
+                ...state.fade,
+                elapsed
+            };
+    }
+    removeFinishedFadeOuts() {
+        for (const state of this.getInternalStates()) {
+            if (state.fade || state.weight > 0 || state.targetWeight > 0)
+                continue;
+            this.states.delete(state.id);
+            this.endState(state, "stopped");
+        }
+    }
+    finishCrossFadesIfReady() {
+        if (this.pendingCrossFades.length === 0)
+            return;
+        const hasActiveFade = this.getInternalStates().some((state) => state.fade);
+        if (hasActiveFade)
+            return;
+        for (const event of [...this.pendingCrossFades]) {
+            this.finishCrossFade(event);
+        }
+    }
+    finishCrossFade(event) {
+        this.pendingCrossFades = this.pendingCrossFades.filter((pending) => pending !== event);
+        this.emit("crossFadeEnd", event);
+        this.emit("crossfadeEnd", event);
+    }
+    blendStates(states, suppressRootMotion) {
+        const weightedStates = states.filter((state) => effectiveWeight(state) > 0);
+        if (weightedStates.length === 0) {
+            const fallback = clonePose(this.poseBakedFallback) ?? createIdentityPose(this.skeleton);
+            if (fallback) {
+                return {
+                    ...fallback,
+                    metadata: {
+                        ...fallback.metadata,
+                        poseBakedFallback: true,
+                        poseBakedFallbackMetadata: this.poseBakedFallbackMetadata
+                    }
+                };
+            }
+            return emptyPose({ poseBakedFallback: true, poseBakedFallbackMetadata: this.poseBakedFallbackMetadata });
+        }
+        const accumulators = new Map();
+        const morphTargets = {};
+        const rootMotionAccumulator = createBoneAccumulator();
+        let hasRootMotion = false;
+        let totalWeight = 0;
+        let rootMotionSuppressed = false;
+        let poseBakedFallback = false;
+        let poseBakedFallbackMetadata;
+        for (const state of weightedStates) {
+            const pose = this.sampleSinglePose(state.clip, state.localTime, state, suppressRootMotion);
+            const weight = effectiveWeight(state);
+            totalWeight += weight;
+            rootMotionSuppressed = rootMotionSuppressed || Boolean(pose.metadata?.rootMotionSuppressed);
+            poseBakedFallback = poseBakedFallback || Boolean(pose.metadata?.poseBakedFallback);
+            poseBakedFallbackMetadata =
+                poseBakedFallbackMetadata ??
+                    pose.metadata?.poseBakedFallbackMetadata ??
+                    state.poseBakedFallback;
+            for (const [boneName, transform] of Object.entries(pose.bones)) {
+                const accumulator = accumulators.get(boneName) ?? createBoneAccumulator();
+                accumulateTransform(accumulator, transform, weight);
+                accumulators.set(boneName, accumulator);
+            }
+            for (const [name, value] of Object.entries(pose.morphTargets ?? {})) {
+                morphTargets[name] = (morphTargets[name] ?? 0) + value * weight;
+            }
+            if (pose.rootMotion) {
+                hasRootMotion = true;
+                accumulateTransform(rootMotionAccumulator, {
+                    position: pose.rootMotion.translation,
+                    rotation: pose.rootMotion.rotation
+                }, weight);
+            }
+        }
+        const bones = {};
+        for (const [boneName, accumulator] of accumulators) {
+            bones[boneName] = resolveAccumulator(accumulator);
+        }
+        if (totalWeight > 0) {
+            for (const name of Object.keys(morphTargets)) {
+                morphTargets[name] /= totalWeight;
+            }
+        }
+        const rootMotionTransform = hasRootMotion ? resolveAccumulator(rootMotionAccumulator) : undefined;
+        return {
+            bones,
+            morphTargets,
+            rootMotion: rootMotionTransform
+                ? {
+                    translation: rootMotionTransform.position,
+                    rotation: rootMotionTransform.rotation
+                }
+                : undefined,
+            metadata: {
+                poseBakedFallback,
+                poseBakedFallbackMetadata,
+                rootMotionSuppressed
+            }
+        };
+    }
+    sampleSinglePose(clip, time, state, suppressRootMotion) {
+        const localTime = normalizeStateTime(time, clip.duration, clip.loop ? "loop" : "once");
+        const sampled = clip.sample?.({
+            clip,
+            time: localTime,
+            normalizedTime: clip.duration > 0 ? localTime / clip.duration : 0,
+            playbackState: state ? cloneState(state) : undefined
+        });
+        const pose = isAnimationPose(sampled) ? sampled : clonePose(clip.fallbackPose) ?? emptyPose({ poseBakedFallback: true });
+        const shouldSuppress = suppressRootMotion ?? state?.rootMotionSuppressed ?? clip.suppressRootMotion ?? this.suppressRootMotion;
+        return shouldSuppress ? suppressPoseRootMotion(pose, clip.rootMotion ?? this.rootMotion) : clonePose(pose) ?? emptyPose();
+    }
+    applyRuntimeNodeBindings() {
+        for (const binding of this.runtimeNodeBindings.values()) {
+            if (binding.options.applyOnUpdate === false)
+                continue;
+            this.applyRuntimeNodeBinding(binding);
+        }
+    }
+    applyRuntimeNodeBinding(binding) {
+        let snapshot = this.createRuntimeNodeBindingSnapshot(binding);
+        const animation = createRuntimeNodeAnimationSpec(snapshot, binding.options);
+        if (snapshot.appliedClipId) {
+            if (typeof binding.node.play === "function") {
+                const options = { ...animation };
+                delete options.clip;
+                binding.node.play(String(snapshot.appliedClipId), options);
+            }
+            else if (typeof binding.node.setAnimation === "function") {
+                binding.node.setAnimation(animation);
+            }
+        }
+        if (typeof binding.node.setAnimationBinding === "function") {
+            binding.node.setAnimationBinding(createRuntimeNodeAnimationBindingMetadata(snapshot));
+        }
+        if (binding.options.applyPose !== false && snapshot.pose && typeof binding.node.setAnimationPose === "function") {
+            binding.node.setAnimationPose(snapshot.pose, createRuntimeNodeAnimationPoseBindingMetadata(snapshot));
+        }
+        if (binding.options.applyMorphTargets !== false && snapshot.morphTargets && typeof binding.node.setMorphTargets === "function") {
+            binding.node.setMorphTargets(snapshot.morphTargets);
+        }
+        if (binding.options.importedRuntime && binding.options.applyImportedRuntime !== false && snapshot.clipSamples.length > 0) {
+            snapshot = {
+                ...snapshot,
+                importedRuntime: applyImportedAnimationRuntime(binding.options.importedRuntime, snapshot.clipSamples)
+            };
+        }
+        binding.snapshot = snapshot;
+        return snapshot;
+    }
+    createRuntimeNodeBindingSnapshot(binding) {
+        const states = this.selectRuntimeNodeBindingStates(binding.options);
+        const state = states[0];
+        const appliedClipId = state?.clipId ?? binding.options.defaultClipId ?? binding.options.fallbackClipId;
+        const clip = appliedClipId ? this.clips.get(appliedClipId) : undefined;
+        const layer = state?.layer ?? binding.options.layer ?? clip?.layer;
+        const layerMetadata = layer ? this.layerMetadata.get(layer) ?? clip?.layerMetadata ?? inferLayerMetadata(layer) : undefined;
+        const pose = this.captureRuntimeNodeBindingPose(binding.options, states, state, clip);
+        const morphTargets = pose?.morphTargets ? { ...pose.morphTargets } : undefined;
+        const clipSamples = createRuntimeNodeClipSamples(states);
+        const poseBakedFallback = Boolean(state?.poseBakedFallback?.enabled ?? clip?.poseBakedFallback?.enabled);
+        const retargeted = Boolean(state?.clip.retarget ?? clip?.retarget ?? this.retarget);
+        return {
+            id: binding.id,
+            nodeId: binding.node.id,
+            source: "animation-controller",
+            controllerId: this.id,
+            activeClipId: state?.clipId,
+            appliedClipId,
+            playbackId: state?.id,
+            layer,
+            layerMetadata: layerMetadata ? cloneLayerMetadata(layerMetadata) : undefined,
+            localTime: state?.localTime,
+            captureTime: state?.localTime ?? (appliedClipId ? 0 : undefined),
+            loop: state ? state.loopMode !== "once" : clip?.loop,
+            speed: state?.speed,
+            pose,
+            morphTargets,
+            boneCount: Object.keys(pose?.bones ?? {}).length,
+            morphTargetCount: Object.keys(morphTargets ?? {}).length,
+            clipSamples,
+            poseBakedFallback,
+            retargeted,
+            sourceAssetId: clip?.metadata?.assetId ?? this.embeddedGLB?.assetId,
+            sourceAssetName: clip?.metadata?.assetName ?? this.embeddedGLB?.assetName,
+            metadata: {
+                ...binding.options.metadata,
+                eventSource: state?.eventSource ?? clip?.eventSource,
+                restartFromFrameZero: state?.restartFromFrameZero ?? clip?.restartFromFrameZero
+            }
+        };
+    }
+    captureRuntimeNodeBindingPose(options, states, state, clip) {
+        if (options.applyPose === false && options.applyMorphTargets === false)
+            return undefined;
+        if (states.length > 0)
+            return clonePose(this.blendStates(states));
+        if (state)
+            return clonePose(this.sampleSinglePose(state.clip, state.localTime, state, undefined));
+        if (clip)
+            return clonePose(this.sampleSinglePose(clip, 0, undefined, undefined));
+        return undefined;
+    }
+    selectRuntimeNodeBindingStates(options) {
+        const candidates = options.layer
+            ? this.getInternalStates().filter((state) => state.layer === options.layer)
+            : this.getInternalStates();
+        return candidates
+            .filter((state) => state.status === "playing" || state.status === "paused")
+            .filter((state) => effectiveWeight(state) > 0)
+            .sort((a, b) => effectiveWeight(b) - effectiveWeight(a));
+    }
+    selectRuntimeNodeBindingState(options) {
+        return this.selectRuntimeNodeBindingStates(options)[0];
+    }
+    retargetSnapshot() {
+        const bindings = this.collectRetargetBindings();
+        if (bindings.length === 0 && !this.externalHumanoidLibrary)
+            return undefined;
+        const primary = bindings[0]?.retarget ?? normalizeRetargetBinding(undefined, this.externalHumanoidLibrary);
+        const external = primary?.externalLibrary ?? this.externalHumanoidLibrary;
+        const constraints = normalizeRetargetConstraints(primary?.constraints ?? external?.constraints ?? auraAnimationRetargetDocumentedConstraints);
+        return {
+            enabled: true,
+            externalLibrary: external?.library,
+            sourceAssetId: external?.sourceAssetId ?? this.embeddedGLB?.assetId,
+            sourceAssetName: external?.sourceAssetName ?? this.embeddedGLB?.assetName,
+            sourceClipIds: bindings.map((binding) => binding.clipId).filter((clipId) => Boolean(clipId)),
+            constraints,
+            diagnostics: this.createRetargetDiagnostics({})
+        };
+    }
+    collectRetargetBindings() {
+        const bindings = [];
+        if (this.retarget)
+            bindings.push({ retarget: this.retarget });
+        for (const clip of this.listClips()) {
+            const retarget = normalizeRetargetBinding(clip.retarget ?? clip.metadata?.retarget, clip.externalHumanoidLibrary ?? clip.metadata?.externalHumanoidLibrary);
+            if (retarget)
+                bindings.push({ retarget, clipId: clip.id });
+        }
+        return bindings;
+    }
+    createRetargetDiagnostics(options) {
+        const diagnostics = [];
+        const bindings = this.collectRetargetBindings();
+        if (bindings.length === 0)
+            return diagnostics;
+        for (const { retarget, clipId } of bindings) {
+            const external = retarget.externalLibrary ?? this.externalHumanoidLibrary;
+            const constraints = normalizeRetargetConstraints(retarget.constraints ?? external?.constraints ?? []);
+            if (constraints.length === 0) {
+                diagnostics.push(createDiagnostic("warning", "ANIMATION_RETARGET_CONSTRAINTS_UNDOCUMENTED", `Retarget metadata${clipId ? ` for clip "${clipId}"` : ""} should document constraints: explicit humanoid bone map, rest pose, uniform scale, root-motion policy, no runtime IK, and no automatic proportion warp.`, clipId));
+            }
+            else {
+                for (const constraint of constraints) {
+                    diagnostics.push(createDiagnostic(constraint.severity ?? "info", `ANIMATION_RETARGET_CONSTRAINT_${diagnosticCodeSuffix(constraint.code)}`, constraint.message ?? `Retarget constraint documented: ${constraint.code}.`, clipId));
+                }
+            }
+            const mappings = normalizeHumanoidBoneMap(retarget.boneMap ?? external?.boneMap);
+            if (mappings.length === 0) {
+                diagnostics.push(createDiagnostic("error", "ANIMATION_RETARGET_BONE_MAP_MISSING", `Retarget metadata${clipId ? ` for clip "${clipId}"` : ""} is missing an explicit humanoid bone map.`, clipId));
+            }
+            const targetSkeletonBones = skeletonBoneNames(retarget.targetSkeleton ?? this.skeleton);
+            const sourceSkeletonBones = skeletonBoneNames(retarget.sourceSkeleton ?? external?.skeleton);
+            for (const mapping of mappings) {
+                if (mapping.required !== false && targetSkeletonBones.size > 0 && !targetSkeletonBones.has(mapping.target)) {
+                    diagnostics.push(createDiagnostic("error", "ANIMATION_RETARGET_TARGET_BONE_MISSING", `Retarget mapping "${mapping.source}" -> "${mapping.target}" targets a missing skeleton bone.`, clipId, mapping.target));
+                }
+                if (mapping.required !== false && sourceSkeletonBones.size > 0 && !sourceSkeletonBones.has(mapping.source)) {
+                    diagnostics.push(createDiagnostic("warning", "ANIMATION_RETARGET_SOURCE_BONE_UNVERIFIED", `Retarget mapping source bone "${mapping.source}" is not present in source skeleton metadata.`, clipId, mapping.source));
+                }
+            }
+            if (!retarget.restPose && !external?.restPose) {
+                diagnostics.push(createDiagnostic("warning", "ANIMATION_RETARGET_REST_POSE_UNDOCUMENTED", `Retarget metadata${clipId ? ` for clip "${clipId}"` : ""} should document source/target rest-pose assumptions.`, clipId));
+            }
+            if (!retarget.scale) {
+                diagnostics.push(createDiagnostic("warning", "ANIMATION_RETARGET_SCALE_UNDOCUMENTED", `Retarget metadata${clipId ? ` for clip "${clipId}"` : ""} should document uniform scale or unit conversion assumptions.`, clipId));
+            }
+            for (const requiredBone of options.requiredBones ?? []) {
+                if (targetSkeletonBones.size > 0 && !targetSkeletonBones.has(requiredBone)) {
+                    diagnostics.push(createDiagnostic("error", "ANIMATION_RETARGET_REQUIRED_TARGET_BONE_MISSING", `Retarget target skeleton is missing required bone "${requiredBone}".`, clipId, requiredBone));
+                }
+            }
+        }
+        return diagnostics;
+    }
+    selectStates(clipId) {
+        const states = this.getInternalStates();
+        if (!clipId)
+            return states;
+        return states.filter((state) => state.clipId === clipId);
+    }
+    selectCrossFadeSources(options) {
+        if (options.fromClipId)
+            return this.selectStates(options.fromClipId);
+        if (options.fromLayer)
+            return this.getInternalStates().filter((state) => state.layer === options.fromLayer);
+        return this.getInternalStates();
+    }
+    getInternalStates() {
+        return [...this.states.values()];
+    }
+    findStateByClip(clipId) {
+        return this.getInternalStates().find((state) => state.clipId === clipId);
+    }
+    primaryState() {
+        return this.getInternalStates()
+            .filter((state) => state.status === "playing" || state.status === "paused")
+            .sort((a, b) => effectiveWeight(b) - effectiveWeight(a))[0];
+    }
+    activeClipId() {
+        return this.primaryState()?.clipId;
+    }
+    layerWeight(layer) {
+        return this.layerWeights.get(layer) ?? 1;
+    }
+    endState(state, status) {
+        state.status = status;
+        this.emit("end", cloneState(state));
+    }
+    emitStateChanged() {
+        this.emit("stateChanged", this.snapshot());
+    }
+    emit(type, payload) {
+        const listeners = this.listeners.get(type);
+        if (!listeners)
+            return;
+        for (const listener of [...listeners]) {
+            listener(payload);
+        }
+    }
+}
+export function createAnimationController(options = {}) {
+    return new AnimationController(options);
+}
+export const auraAnimationRuntimeMitigationContract = {
+    embeddedClipPlaybackFirst: true,
+    externalHumanoidRetargeting: "diagnostics-gated",
+    retargetingRequiresDocumentedConstraints: true,
+    constraints: auraAnimationRetargetDocumentedConstraints
+};
+export function createSourceTestGLBAnimationSwitchHarness(options = {}) {
+    const clipRegistry = options.clipRegistry ?? createDefaultSourceTestGLBClipRegistry();
+    const controller = new AnimationController({
+        id: "source-test-glb-animation-switch",
+        clipRegistry,
+        requiredClips: ["idle", "walk", "lightPunch"],
+        requiredBones: ["hips", "spine", "head", "leftArm", "rightArm", "leftLeg", "rightLeg"],
+        suppressRootMotion: true
+    });
+    const fade = options.crossFadeDuration ?? 0.08;
+    const dt = options.dt ?? 1 / 30;
+    const sequence = [];
+    const capture = (expectedClipId, transition) => {
+        const snapshot = controller.snapshot();
+        const active = snapshot.clips.filter((clip) => clip.status === "playing" || clip.status === "completed");
+        sequence.push({
+            expectedClipId,
+            transition,
+            activeClipId: snapshot.activeClipId,
+            activeClipIds: active.map((clip) => clip.clipId),
+            localTime: controller.state(expectedClipId)?.localTime,
+            rootMotionSuppressed: snapshot.rootMotionSuppressed,
+            poseBakedFallback: Boolean(controller.state(expectedClipId)?.poseBakedFallback)
+        });
+    };
+    controller.play("idle", { restart: true, loop: "loop" });
+    controller.update(dt);
+    capture("idle", "play");
+    controller.crossFade("walk", fade, { restart: true, loop: "loop" });
+    controller.update(fade);
+    capture("walk", "crossFade");
+    controller.crossFade("lightPunch", fade, { restart: true, loop: false, layer: "upper-body", attack: true });
+    controller.update(fade);
+    capture("lightPunch", "crossFade");
+    controller.crossFade("idle", fade, { restart: true, loop: "loop" });
+    controller.update(fade);
+    capture("idle", "crossFade");
+    const diagnostics = controller.diagnostics({
+        requireSkeleton: true,
+        requiredClips: ["idle", "walk", "lightPunch"],
+        requiredBones: ["hips", "spine", "head", "leftArm", "rightArm", "leftLeg", "rightLeg"]
+    });
+    const expectedSequence = ["idle", "walk", "lightPunch", "idle"];
+    return {
+        ok: sequence.map((step) => step.activeClipId).every((clipId, index) => clipId === expectedSequence[index]) &&
+            diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+        source: "source-test-glb-clip-registry",
+        assetId: clipRegistry.assetId,
+        sequence,
+        diagnostics,
+        mitigation: auraAnimationRuntimeMitigationContract
+    };
+}
+function createDefaultSourceTestGLBClipRegistry() {
+    const skeleton = {
+        rootBone: "hips",
+        bones: ["hips", "spine", "head", "leftArm", "rightArm", "leftLeg", "rightLeg"]
+    };
+    return {
+        kind: "aura3d-embedded-glb-animation-registry",
+        assetId: "source-test-fighter-glb",
+        assetName: "Source Test Fighter GLB",
+        skeleton,
+        suppressRootMotion: true,
+        clips: [
+            {
+                id: "idle",
+                duration: 1,
+                loop: true,
+                requiredBones: skeleton.bones,
+                tracks: [
+                    {
+                        id: "idle-hips",
+                        target: "hips.position",
+                        property: "translation",
+                        keyframes: [
+                            { time: 0, value: { x: 0, y: 0, z: 0 } },
+                            { time: 1, value: { x: 0, y: 0.02, z: 0 } }
+                        ]
+                    }
+                ]
+            },
+            {
+                id: "walk",
+                duration: 1,
+                loop: true,
+                requiredBones: skeleton.bones,
+                rootMotion: { track: "walk-root", bone: "hips", suppress: true, reason: "gameplay kinematic body owns locomotion" },
+                tracks: [
+                    {
+                        id: "walk-root",
+                        target: "hips.position",
+                        property: "translation",
+                        keyframes: [
+                            { time: 0, value: { x: 0, y: 0, z: 0 } },
+                            { time: 1, value: { x: 0, y: 0, z: 0.35 } }
+                        ]
+                    },
+                    {
+                        id: "walk-left-leg",
+                        target: "leftLeg.rotation",
+                        property: "rotation",
+                        keyframes: [
+                            { time: 0, value: { x: 0, y: 0, z: -0.12, w: 0.99 } },
+                            { time: 0.5, value: { x: 0, y: 0, z: 0.12, w: 0.99 } },
+                            { time: 1, value: { x: 0, y: 0, z: -0.12, w: 0.99 } }
+                        ]
+                    }
+                ]
+            },
+            {
+                id: "lightPunch",
+                duration: 0.45,
+                loop: false,
+                attack: true,
+                restartFromFrameZero: true,
+                layer: "upper-body",
+                requiredBones: ["spine", "head", "leftArm", "rightArm"],
+                events: [{ name: "active", type: "hitbox", time: 0.12, once: true, payload: { volume: "light-punch" } }],
+                tracks: [
+                    {
+                        id: "light-punch-right-arm",
+                        target: "rightArm.rotation",
+                        property: "rotation",
+                        keyframes: [
+                            { time: 0, value: { x: 0, y: 0, z: 0, w: 1 } },
+                            { time: 0.12, value: { x: 0.25, y: 0, z: -0.15, w: 0.96 } },
+                            { time: 0.45, value: { x: 0, y: 0, z: 0, w: 1 } }
+                        ]
+                    }
+                ]
+            }
+        ]
+    };
+}
+function createRuntimeNodeAnimationSpec(snapshot, options) {
+    return compactObject({
+        clip: snapshot.appliedClipId ? String(snapshot.appliedClipId) : undefined,
+        loop: options.syncLoop === false ? undefined : snapshot.loop,
+        speed: options.syncSpeed === false ? undefined : snapshot.speed,
+        startTime: snapshot.metadata?.restartFromFrameZero ? 0 : undefined,
+        duration: undefined,
+        captureTime: options.syncCaptureTime === false ? undefined : snapshot.captureTime,
+        metadata: compactObject({
+            controllerId: snapshot.controllerId,
+            bindingId: snapshot.id,
+            playbackId: snapshot.playbackId,
+            layer: snapshot.layer,
+            layerRole: snapshot.layerMetadata?.role,
+            bodyMask: snapshot.layerMetadata?.bodyMask,
+            poseBakedFallback: snapshot.poseBakedFallback,
+            retargeted: snapshot.retargeted,
+            sourceAssetId: snapshot.sourceAssetId,
+            sourceAssetName: snapshot.sourceAssetName,
+            eventSource: snapshot.metadata?.eventSource,
+            restartFromFrameZero: snapshot.metadata?.restartFromFrameZero
+        })
+    });
+}
+function createRuntimeNodeAnimationBindingMetadata(snapshot) {
+    return compactObject({
+        kind: "aura-runtime-node-animation-binding",
+        controllerId: snapshot.controllerId,
+        bindingId: snapshot.id,
+        activeClipId: snapshot.activeClipId ? String(snapshot.activeClipId) : undefined,
+        playbackId: snapshot.playbackId,
+        layer: snapshot.layer,
+        layerRole: snapshot.layerMetadata?.role,
+        bodyMask: snapshot.layerMetadata?.bodyMask,
+        localTime: snapshot.localTime,
+        captureTime: snapshot.captureTime,
+        loop: snapshot.loop,
+        speed: snapshot.speed,
+        eventSource: typeof snapshot.metadata?.eventSource === "string" ? snapshot.metadata.eventSource : undefined,
+        retargeted: snapshot.retargeted,
+        poseBakedFallback: snapshot.poseBakedFallback,
+        sourceAssetId: snapshot.sourceAssetId,
+        sourceAssetName: snapshot.sourceAssetName,
+        metadata: snapshot.metadata
+    });
+}
+function createRuntimeNodeAnimationPoseBindingMetadata(snapshot) {
+    return compactObject({
+        kind: "aura-runtime-node-animation-pose",
+        controllerId: snapshot.controllerId,
+        bindingId: snapshot.id,
+        activeClipId: snapshot.activeClipId ? String(snapshot.activeClipId) : undefined,
+        playbackId: snapshot.playbackId,
+        localTime: snapshot.localTime,
+        captureTime: snapshot.captureTime,
+        boneCount: snapshot.boneCount,
+        morphTargetCount: snapshot.morphTargetCount,
+        sourceAssetId: snapshot.sourceAssetId,
+        sourceAssetName: snapshot.sourceAssetName,
+        metadata: compactObject({
+            layer: snapshot.layer,
+            layerRole: snapshot.layerMetadata?.role,
+            bodyMask: snapshot.layerMetadata?.bodyMask,
+            poseBakedFallback: snapshot.poseBakedFallback,
+            retargeted: snapshot.retargeted,
+            eventSource: snapshot.metadata?.eventSource,
+            restartFromFrameZero: snapshot.metadata?.restartFromFrameZero
+        })
+    });
+}
+function createRuntimeNodeClipSamples(states) {
+    return states.map((state) => {
+        const additive = Boolean(state.layerMetadata?.additive ?? state.clip.layerMetadata?.additive);
+        return compactObject({
+            clipId: state.clipId,
+            clipName: runtimeClipNameForState(state),
+            localTime: state.localTime,
+            weight: effectiveWeight(state),
+            layer: state.layer,
+            additive: additive ? true : undefined
+        });
+    });
+}
+function applyImportedAnimationRuntime(runtime, samples) {
+    const importedSamples = samples.map((sample) => compactObject({
+        clipName: sample.clipName,
+        time: sample.localTime,
+        weight: sample.weight,
+        additive: sample.additive
+    }));
+    const blended = importedSamples.length > 1;
+    const applyResult = blended && typeof runtime.blendClips === "function"
+        ? runtime.blendClips(importedSamples)
+        : blended && typeof runtime.applyClips === "function"
+            ? runtime.applyClips(importedSamples)
+            : applySingleImportedClip(runtime, highestWeightRuntimeClipSample(importedSamples));
+    return compactObject({
+        applied: true,
+        blended,
+        sampleCount: importedSamples.length,
+        applyResult,
+        runtimeSnapshot: typeof runtime.snapshot === "function" ? runtime.snapshot() : undefined
+    });
+}
+function applySingleImportedClip(runtime, sample) {
+    if (typeof runtime.applyClip === "function")
+        return runtime.applyClip(sample.clipName, sample.time);
+    if (typeof runtime.applyClipByName === "function")
+        return runtime.applyClipByName(sample.clipName, sample.time);
+    if (typeof runtime.applyClips === "function")
+        return runtime.applyClips([sample]);
+    if (typeof runtime.blendClips === "function")
+        return runtime.blendClips([sample]);
+    throw new Error("Imported animation runtime must expose applyClip(), applyClipByName(), applyClips(), or blendClips().");
+}
+function highestWeightRuntimeClipSample(samples) {
+    const [first] = samples;
+    if (!first) {
+        throw new Error("Cannot apply imported animation runtime without an active clip sample.");
+    }
+    return samples.reduce((best, sample) => (sample.weight ?? 1) > (best.weight ?? 1) ? sample : best, first);
+}
+function runtimeClipNameForState(state) {
+    return (stringMetadata(state.clip.metadata, "runtimeClipName") ??
+        stringMetadata(state.clip.metadata, "sourceClipName") ??
+        stringMetadata(state.clip.metadata, "sourceClipId") ??
+        stringMetadata(state.clip.metadata, "clipName") ??
+        state.clip.name ??
+        String(state.clipId));
+}
+function stringMetadata(metadata, key) {
+    const value = metadata?.[key];
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function createClipEventSourceMetadata(state, controllerTime, registry) {
+    const poseBakedFallback = Boolean(state.poseBakedFallback?.enabled ?? state.clip.poseBakedFallback?.enabled);
+    const retargeted = Boolean(state.clip.retarget);
+    return {
+        kind: poseBakedFallback ? "pose-baked-fallback" : state.eventSource,
+        semantics: "clip-local-time",
+        clipId: state.clipId,
+        playbackId: state.id,
+        layer: state.layer,
+        localTime: state.localTime,
+        previousLocalTime: state.previousLocalTime,
+        normalizedTime: state.normalizedTime,
+        controllerTime,
+        loopCount: state.loopCount,
+        retargeted,
+        poseBakedFallback,
+        sourceAssetId: state.clip.metadata?.assetId ?? registry?.assetId,
+        sourceAssetName: state.clip.metadata?.assetName ?? registry?.assetName,
+        sourceClipId: state.clip.metadata?.sourceClipId,
+        metadata: {
+            rule: "Clip events are sampled from source clip local time before runtime-node binding or renderer skinning.",
+            layerRole: state.layerMetadata?.role,
+            bodyMask: state.layerMetadata?.bodyMask
+        }
+    };
+}
+function shouldRestartFromFrameZero(clip, options, layers) {
+    if (options.restartFromFrameZero === true || options.attack === true)
+        return true;
+    const layer = options.layer ?? clip.layer;
+    const layerMetadata = layers.get(layer) ?? clip.layerMetadata;
+    return Boolean(clip.restartFromFrameZero ||
+        clip.metadata?.restartFromFrameZero ||
+        clip.metadata?.attack ||
+        clip.tags.includes("attack") ||
+        layerMetadata?.restartFromFrameZero);
+}
+function cloneLayerMetadata(layer) {
+    return {
+        ...layer,
+        bones: layer.bones ? [...layer.bones] : undefined,
+        excludedBones: layer.excludedBones ? [...layer.excludedBones] : undefined,
+        metadata: layer.metadata ? { ...layer.metadata } : undefined
+    };
+}
+function inferLayerMetadata(layer) {
+    const normalized = layer.trim() || defaultLayerName;
+    if (normalized === "upper-body") {
+        return {
+            id: normalized,
+            role: "upper-body",
+            bodyMask: "upper-body",
+            bones: ["Spine", "Chest", "UpperChest", "Neck", "Head", "LeftShoulder", "LeftUpperArm", "LeftLowerArm", "LeftHand", "RightShoulder", "RightUpperArm", "RightLowerArm", "RightHand"],
+            restartFromFrameZero: true,
+            description: "Upper-body overlay layer for attacks, gestures, aim offsets, and hit reactions."
+        };
+    }
+    if (normalized === "lower-body") {
+        return {
+            id: normalized,
+            role: "lower-body",
+            bodyMask: "lower-body",
+            bones: ["Hips", "LeftUpperLeg", "LeftLowerLeg", "LeftFoot", "LeftToeBase", "RightUpperLeg", "RightLowerLeg", "RightFoot", "RightToeBase"],
+            description: "Lower-body locomotion layer for feet, hips, and grounded movement."
+        };
+    }
+    return {
+        id: normalized,
+        role: normalized === defaultLayerName ? "base" : "custom",
+        bodyMask: "full-body",
+        description: normalized === defaultLayerName ? "Full-body base animation layer." : "Custom animation layer metadata."
+    };
+}
+function normalizeRetargetBinding(retarget, externalLibrary) {
+    if (!retarget && !externalLibrary)
+        return undefined;
+    return {
+        ...retarget,
+        kind: retarget?.kind ?? "aura-animation-retarget-binding",
+        source: retarget?.source ?? (externalLibrary ? "external-humanoid-library" : undefined),
+        boneMap: retarget?.boneMap ?? externalLibrary?.boneMap,
+        sourceSkeleton: retarget?.sourceSkeleton ?? externalLibrary?.skeleton,
+        constraints: retarget?.constraints ?? externalLibrary?.constraints,
+        externalLibrary: retarget?.externalLibrary ?? externalLibrary
+    };
+}
+function normalizeRetargetConstraints(constraints = []) {
+    return constraints.map((constraint) => {
+        if (typeof constraint === "string") {
+            return documentedRetargetConstraint(constraint);
+        }
+        return {
+            ...documentedRetargetConstraint(constraint.code),
+            ...constraint
+        };
+    });
+}
+function documentedRetargetConstraint(code) {
+    return auraAnimationRetargetDocumentedConstraints.find((constraint) => constraint.code === code) ?? {
+        code,
+        severity: "info",
+        message: `Retarget constraint documented: ${code}.`
+    };
+}
+function normalizeHumanoidBoneMap(map) {
+    if (!map)
+        return [];
+    if (Array.isArray(map)) {
+        return map
+            .filter((binding) => Boolean(binding.source && binding.target))
+            .map((binding) => ({ ...binding }));
+    }
+    return Object.entries(map)
+        .filter(([source, target]) => Boolean(source && target))
+        .map(([source, target]) => ({ source, target, required: true }));
+}
+function diagnosticCodeSuffix(value) {
+    return value.trim().toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "DOCUMENTED";
+}
+function compactObject(value) {
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry !== undefined)
+            result[key] = entry;
+    }
+    return result;
+}
+export function createEmbeddedGLBAnimationClipRegistryMetadata(source) {
+    const asset = isAnimationAssetLike(source) ? source : undefined;
+    const metadata = asset?.metadata;
+    const nested = metadata?.animation;
+    const registry = (nested ?? source);
+    const clips = registry.clips ?? registry.animations ?? metadata?.animationClips ?? metadata?.animations ?? [];
+    const bones = registry.bones ?? metadata?.bones;
+    const skeleton = registry.skeleton ?? metadata?.skeleton ?? (bones ? { bones } : undefined);
+    const layers = registry.layers ?? metadata?.layers;
+    const externalHumanoidLibrary = registry.externalHumanoidLibrary ?? metadata?.externalHumanoidLibrary;
+    return {
+        kind: registry.kind ?? "aura3d-embedded-glb-animation-registry",
+        assetId: registry.assetId ?? asset?.id,
+        assetName: registry.assetName ?? asset?.name,
+        clips,
+        skeleton,
+        bones,
+        layers,
+        retarget: registry.retarget ?? metadata?.retarget,
+        externalHumanoidLibrary,
+        rootMotion: registry.rootMotion ?? metadata?.rootMotion,
+        suppressRootMotion: registry.suppressRootMotion ?? metadata?.suppressRootMotion,
+        poseBakedFallback: registry.poseBakedFallback ?? metadata?.poseBakedFallback,
+        metadata: {
+            ...registry.metadata,
+            url: asset?.url,
+            hash: asset?.hash
+        }
+    };
+}
+function embeddedClipToDefinition(input, registry, defaultLayer) {
+    if (typeof input === "string") {
+        const retarget = normalizeRetargetBinding(registry.retarget, registry.externalHumanoidLibrary);
+        return {
+            id: input,
+            name: input,
+            duration: 1,
+            loop: true,
+            layer: defaultLayer,
+            layerMetadata: registry.layers?.find((layer) => layer.id === defaultLayer),
+            eventSource: retarget ? "retargeted-source-clip" : "source-clip",
+            retarget,
+            externalHumanoidLibrary: registry.externalHumanoidLibrary,
+            metadata: {
+                embeddedGLB: true,
+                assetId: registry.assetId,
+                assetName: registry.assetName,
+                source: "embedded-glb-animation-name",
+                durationSource: "defaulted"
+            },
+            fallbackPose: extractPoseBakedFallback(registry.poseBakedFallback)
+        };
+    }
+    const id = input.id ?? input.name;
+    if (!id) {
+        throw new Error("Embedded GLB animation clips require id or name metadata.");
+    }
+    return {
+        id,
+        name: input.name ?? id,
+        duration: input.duration ?? 1,
+        frameRate: input.frameRate,
+        loop: input.loop ?? true,
+        tags: input.tags,
+        tracks: input.tracks,
+        events: input.events,
+        layer: input.layer ?? defaultLayer,
+        layerMetadata: input.layerMetadata ?? registry.layers?.find((layer) => layer.id === (input.layer ?? defaultLayer)),
+        bones: input.bones,
+        requiredBones: input.requiredBones,
+        rootMotion: input.rootMotion ?? registry.rootMotion,
+        suppressRootMotion: input.suppressRootMotion ?? registry.suppressRootMotion,
+        restartFromFrameZero: input.restartFromFrameZero,
+        attack: input.attack,
+        eventSource: input.eventSource,
+        retarget: input.retarget ?? registry.retarget,
+        externalHumanoidLibrary: input.externalHumanoidLibrary ?? registry.externalHumanoidLibrary,
+        pose: input.pose,
+        fallbackPose: input.fallbackPose ?? extractPoseBakedFallback(registry.poseBakedFallback),
+        metadata: {
+            ...input.metadata,
+            embeddedGLB: true,
+            assetId: registry.assetId,
+            assetName: registry.assetName,
+            source: "embedded-glb-clip-registry",
+            durationSource: input.duration === undefined ? "defaulted" : "metadata"
+        }
+    };
+}
+function isAnimationAssetLike(value) {
+    return isObject(value) && "metadata" in value;
+}
+function createFallbackSampler(clipId, tracks, fallbackPose, poseBakedFallback) {
+    if (tracks.length > 0) {
+        return (context) => samplePoseFromTracks(tracks, context.time, context.clip.duration, fallbackPose, clipId);
+    }
+    if (fallbackPose) {
+        return () => {
+            const pose = clonePose(fallbackPose) ?? emptyPose();
+            return {
+                ...pose,
+                bones: pose.bones,
+                metadata: {
+                    ...fallbackPose.metadata,
+                    poseBakedFallback: true,
+                    poseBakedFallbackMetadata: poseBakedFallback,
+                    sourceClipId: clipId
+                }
+            };
+        };
+    }
+    return () => emptyPose({ poseBakedFallback: true, poseBakedFallbackMetadata: poseBakedFallback, emptyTracks: true, sourceClipId: clipId });
+}
+function samplePoseFromTracks(tracks, time, duration, fallbackPose, clipId) {
+    const pose = clonePose(fallbackPose) ?? emptyPose();
+    const bones = { ...pose.bones };
+    const morphTargets = { ...(pose.morphTargets ?? {}) };
+    let sampledTracks = 0;
+    for (const track of tracks) {
+        const keyframes = [...(track.keyframes ?? [])].sort((a, b) => a.time - b.time);
+        if (keyframes.length === 0)
+            continue;
+        const value = sampleKeyframes(keyframes, normalizeStateTime(time, duration, "loop"));
+        const property = trackProperty(track);
+        const boneName = boneNameFromTrackTarget(track.target) ?? track.target;
+        if (property === "morph") {
+            const numberValue = toFiniteNumber(value);
+            if (numberValue !== undefined) {
+                morphTargets[track.target] = numberValue;
+                sampledTracks += 1;
+            }
+            continue;
+        }
+        const current = bones[boneName] ?? {};
+        if (property === "translation" || property === "position") {
+            const vector = toVector3(value);
+            if (vector) {
+                bones[boneName] = { ...current, position: vector };
+                sampledTracks += 1;
+            }
+        }
+        else if (property === "rotation") {
+            const quaternion = toQuaternion(value);
+            if (quaternion) {
+                bones[boneName] = { ...current, rotation: quaternion };
+                sampledTracks += 1;
+            }
+        }
+        else if (property === "scale") {
+            const vector = toVector3(value);
+            if (vector) {
+                bones[boneName] = { ...current, scale: vector };
+                sampledTracks += 1;
+            }
+        }
+    }
+    return {
+        bones,
+        morphTargets,
+        metadata: {
+            ...pose.metadata,
+            poseBakedFallback: sampledTracks === 0,
+            sampledTracks,
+            sourceClipId: clipId
+        }
+    };
+}
+function sampleKeyframes(keyframes, time) {
+    if (keyframes.length === 0)
+        return undefined;
+    if (time <= keyframes[0].time)
+        return keyframes[0].value;
+    const last = keyframes[keyframes.length - 1];
+    if (time >= last.time)
+        return last.value;
+    for (let index = 0; index < keyframes.length - 1; index += 1) {
+        const from = keyframes[index];
+        const to = keyframes[index + 1];
+        if (time < from.time || time > to.time)
+            continue;
+        const span = Math.max(0.000001, to.time - from.time);
+        const alpha = (time - from.time) / span;
+        return interpolateValue(from.value, to.value, alpha);
+    }
+    return last.value;
+}
+function interpolateValue(from, to, alpha) {
+    const fromNumber = toFiniteNumber(from);
+    const toNumber = toFiniteNumber(to);
+    if (fromNumber !== undefined && toNumber !== undefined)
+        return lerp(fromNumber, toNumber, alpha);
+    const fromVector = toVector3(from);
+    const toVector = toVector3(to);
+    if (fromVector && toVector) {
+        return {
+            x: lerp(fromVector.x, toVector.x, alpha),
+            y: lerp(fromVector.y, toVector.y, alpha),
+            z: lerp(fromVector.z, toVector.z, alpha)
+        };
+    }
+    const fromQuaternion = toQuaternion(from);
+    const toQuaternionValue = toQuaternion(to);
+    if (fromQuaternion && toQuaternionValue) {
+        return normalizeQuaternion({
+            x: lerp(fromQuaternion.x, toQuaternionValue.x, alpha),
+            y: lerp(fromQuaternion.y, toQuaternionValue.y, alpha),
+            z: lerp(fromQuaternion.z, toQuaternionValue.z, alpha),
+            w: lerp(fromQuaternion.w, toQuaternionValue.w, alpha)
+        });
+    }
+    return alpha < 0.5 ? from : to;
+}
+function advanceState(state, dt) {
+    state.previousLocalTime = state.localTime;
+    if (state.duration <= 0) {
+        state.localTime = 0;
+        state.normalizedTime = 0;
+        return {
+            loopsPassed: 0,
+            completed: state.loopMode === "once"
+        };
+    }
+    const delta = dt * state.speed * state.inputDirection;
+    state.direction = delta >= 0 ? 1 : -1;
+    if (state.loopMode === "once") {
+        const nextTime = clamp(state.localTime + delta, 0, state.duration);
+        state.localTime = nextTime;
+        state.playhead = nextTime;
+        state.normalizedTime = state.duration > 0 ? state.localTime / state.duration : 0;
+        return {
+            loopsPassed: 0,
+            completed: delta >= 0 ? nextTime >= state.duration : nextTime <= 0
+        };
+    }
+    const previousPlayhead = state.playhead;
+    state.playhead += delta;
+    const loopsPassed = Math.abs(loopIndex(state.playhead, state.duration) - loopIndex(previousPlayhead, state.duration));
+    if (state.loopMode === "pingpong") {
+        const cycle = loopIndex(state.playhead, state.duration);
+        const local = positiveModulo(state.playhead, state.duration);
+        state.localTime = cycle % 2 === 0 ? local : state.duration - local;
+        state.direction = cycle % 2 === 0 ? state.direction : (state.direction === 1 ? -1 : 1);
+    }
+    else {
+        state.localTime = positiveModulo(state.playhead, state.duration);
+    }
+    state.loopCount += loopsPassed;
+    state.normalizedTime = state.duration > 0 ? state.localTime / state.duration : 0;
+    return {
+        loopsPassed,
+        completed: false
+    };
+}
+function normalizeLoopMode(loop, clipLoop) {
+    if (loop === true)
+        return "loop";
+    if (loop === false)
+        return "once";
+    return loop ?? (clipLoop ? "loop" : "once");
+}
+function normalizeStateTime(time, duration, loopMode) {
+    if (!Number.isFinite(time) || duration <= 0)
+        return 0;
+    if (loopMode === "once")
+        return clamp(time, 0, duration);
+    return positiveModulo(time, duration);
+}
+function positiveModulo(value, modulus) {
+    if (modulus <= 0)
+        return 0;
+    return ((value % modulus) + modulus) % modulus;
+}
+function loopIndex(value, duration) {
+    if (duration <= 0)
+        return 0;
+    return Math.floor(value / duration);
+}
+function sanitizeDuration(duration) {
+    if (!Number.isFinite(duration) || duration < 0)
+        return 0;
+    return duration;
+}
+function sanitizeSpeed(speed) {
+    if (!Number.isFinite(speed))
+        return 1;
+    return speed;
+}
+function sanitizeWeight(weight) {
+    if (!Number.isFinite(weight))
+        return 1;
+    return clamp(weight, 0, 1);
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function lerp(from, to, alpha) {
+    return from + (to - from) * alpha;
+}
+function cloneState(state) {
+    const layerWeight = state.layerWeight;
+    return {
+        id: state.id,
+        clipId: state.clipId,
+        status: state.status,
+        localTime: state.localTime,
+        previousLocalTime: state.previousLocalTime,
+        normalizedTime: state.normalizedTime,
+        duration: state.duration,
+        speed: state.speed,
+        weight: state.weight,
+        targetWeight: state.targetWeight,
+        effectiveWeight: state.weight * layerWeight,
+        layer: state.layer,
+        layerMetadata: state.layerMetadata ? cloneLayerMetadata(state.layerMetadata) : undefined,
+        layerWeight,
+        loopMode: state.loopMode,
+        loopCount: state.loopCount,
+        direction: state.direction,
+        completed: state.completed,
+        rootMotionSuppressed: state.rootMotionSuppressed,
+        restartFromFrameZero: state.restartFromFrameZero,
+        eventSource: state.eventSource,
+        poseBakedFallback: state.poseBakedFallback ? { ...state.poseBakedFallback } : undefined,
+        metadata: state.metadata ? { ...state.metadata } : undefined,
+        fade: state.fade ? { ...state.fade } : undefined
+    };
+}
+function effectiveWeight(state) {
+    return state.weight * state.layerWeight;
+}
+function shouldSuppressRootMotion(options, clip, controllerSuppressRootMotion) {
+    return options.suppressRootMotion ?? clip.suppressRootMotion ?? clip.rootMotion?.suppress ?? controllerSuppressRootMotion;
+}
+function suppressPoseRootMotion(pose, metadata) {
+    const cloned = clonePose(pose) ?? emptyPose();
+    return {
+        ...cloned,
+        rootMotion: undefined,
+        metadata: {
+            ...cloned.metadata,
+            rootMotionSuppressed: true,
+            rootMotionPolicy: "suppressed",
+            rootMotionTrack: metadata?.track,
+            rootMotionBone: metadata?.bone,
+            rootMotionReason: metadata?.reason
+        }
+    };
+}
+function isAnimationPose(value) {
+    return isObject(value) && isObject(value.bones);
+}
+function emptyPose(metadata = {}) {
+    return {
+        bones: {},
+        morphTargets: {},
+        metadata
+    };
+}
+function createIdentityPose(skeleton) {
+    const bones = skeletonBoneNames(skeleton);
+    if (bones.size === 0)
+        return undefined;
+    const poseBones = {};
+    for (const bone of bones) {
+        poseBones[bone] = {
+            position: { x: 0, y: 0, z: 0 },
+            rotation: { x: 0, y: 0, z: 0, w: 1 },
+            scale: { x: 1, y: 1, z: 1 }
+        };
+    }
+    return {
+        bones: poseBones,
+        morphTargets: {},
+        metadata: {
+            poseBakedFallback: true,
+            source: "skeleton-bind-pose"
+        }
+    };
+}
+function clonePose(pose) {
+    if (!pose)
+        return undefined;
+    const bones = {};
+    for (const [name, transform] of Object.entries(pose.bones ?? {})) {
+        bones[name] = {
+            position: transform.position ? { ...transform.position } : undefined,
+            rotation: transform.rotation ? { ...transform.rotation } : undefined,
+            scale: transform.scale ? { ...transform.scale } : undefined
+        };
+    }
+    return {
+        bones,
+        morphTargets: pose.morphTargets ? { ...pose.morphTargets } : undefined,
+        rootMotion: pose.rootMotion
+            ? {
+                translation: pose.rootMotion.translation ? { ...pose.rootMotion.translation } : undefined,
+                rotation: pose.rootMotion.rotation ? { ...pose.rootMotion.rotation } : undefined
+            }
+            : undefined,
+        metadata: pose.metadata ? { ...pose.metadata } : undefined
+    };
+}
+function extractPoseBakedFallback(value) {
+    if (!value || value === true)
+        return undefined;
+    if (isAnimationPose(value))
+        return value;
+    if (isObject(value) && isAnimationPose(value.pose)) {
+        const pose = clonePose(value.pose);
+        return pose
+            ? {
+                ...pose,
+                metadata: {
+                    ...pose.metadata,
+                    poseBakedFallback: true,
+                    poseBakedFallbackSource: value.source,
+                    poseBakedFallbackReason: value.reason
+                }
+            }
+            : undefined;
+    }
+    return undefined;
+}
+function extractPoseBakedFallbackRuntimeMetadata(value, fallback) {
+    if (!value)
+        return undefined;
+    if (value === true || isAnimationPose(value))
+        return fallback;
+    if (isObject(value)) {
+        const metadata = value;
+        return {
+            ...fallback,
+            source: metadata.source ?? fallback.source,
+            reason: metadata.reason ?? fallback.reason
+        };
+    }
+    return fallback;
+}
+function createPoseBakedFallbackRuntimeMetadata(clipId, definition, registry, controllerFallback, enabled) {
+    if (!enabled)
+        return undefined;
+    const explicit = extractPoseBakedFallbackRuntimeMetadata(definition.metadata?.poseBakedFallback, {
+        enabled: true,
+        source: "clip-metadata",
+        sourceClipId: clipId,
+        sourceAssetId: registry?.assetId,
+        sourceAssetName: registry?.assetName,
+        fallbackKind: "clip-metadata"
+    });
+    if (explicit)
+        return explicit;
+    if (definition.pose) {
+        return {
+            enabled: true,
+            source: "clip-pose",
+            sourceClipId: clipId,
+            sourceAssetId: registry?.assetId,
+            sourceAssetName: registry?.assetName,
+            fallbackKind: "clip-pose"
+        };
+    }
+    if (definition.fallbackPose) {
+        return {
+            enabled: true,
+            source: "clip-fallback-pose",
+            sourceClipId: clipId,
+            sourceAssetId: registry?.assetId,
+            sourceAssetName: registry?.assetName,
+            fallbackKind: "clip-fallback-pose"
+        };
+    }
+    if (controllerFallback) {
+        return {
+            ...controllerFallback,
+            enabled: true,
+            sourceClipId: clipId,
+            sourceAssetId: controllerFallback.sourceAssetId ?? registry?.assetId,
+            sourceAssetName: controllerFallback.sourceAssetName ?? registry?.assetName
+        };
+    }
+    return {
+        enabled: true,
+        source: "skeleton-bind-pose",
+        sourceClipId: clipId,
+        sourceAssetId: registry?.assetId,
+        sourceAssetName: registry?.assetName,
+        fallbackKind: "skeleton-bind-pose"
+    };
+}
+function skeletonBoneNames(skeleton) {
+    const names = new Set();
+    for (const bone of skeleton?.bones ?? []) {
+        if (typeof bone === "string" && bone.trim())
+            names.add(bone);
+        if (isObject(bone) && typeof bone.name === "string" && bone.name.trim())
+            names.add(bone.name);
+    }
+    if (skeleton?.rootBone)
+        names.add(skeleton.rootBone);
+    return names;
+}
+function boneNameFromTrackTarget(target) {
+    if (!target.trim())
+        return undefined;
+    const normalized = target.replace(/^\//, "").replace(/\//g, ".");
+    const parts = normalized.split(".").filter(Boolean);
+    if (parts.length === 0)
+        return undefined;
+    if (parts[0] === "materials" || parts[0] === "material" || parts[0] === "morphTargets" || parts[0] === "weights")
+        return undefined;
+    if (parts.length === 1) {
+        return isKnownTransformProperty(parts[0]) ? undefined : parts[0];
+    }
+    if (parts[0] === "bones" || parts[0] === "nodes")
+        return parts[1];
+    const last = parts[parts.length - 1];
+    if (isKnownTransformProperty(last))
+        return parts.slice(0, -1).join(".");
+    return parts[0];
+}
+function trackProperty(track) {
+    switch (track.property) {
+        case "translation":
+            return "translation";
+        case "rotation":
+            return "rotation";
+        case "scale":
+            return "scale";
+        case "morph":
+            return "morph";
+    }
+    const target = track.target.toLowerCase();
+    if (target.endsWith(".position"))
+        return "position";
+    if (target.endsWith(".translation"))
+        return "translation";
+    if (target.endsWith(".rotation") || target.endsWith(".quaternion"))
+        return "rotation";
+    if (target.endsWith(".scale"))
+        return "scale";
+    if (target.includes("morph") || target.includes("weights"))
+        return "morph";
+    return "unknown";
+}
+function isKnownTransformProperty(value) {
+    return [
+        "translation",
+        "position",
+        "rotation",
+        "quaternion",
+        "scale",
+        "weights",
+        "morph",
+        "visibility",
+        "material"
+    ].includes(value);
+}
+function createBoneAccumulator() {
+    return {
+        positionWeight: 0,
+        rotationWeight: 0,
+        scaleWeight: 0
+    };
+}
+function accumulateTransform(accumulator, transform, weight) {
+    if (weight <= 0)
+        return;
+    if (transform.position) {
+        accumulator.position = accumulator.position ?? { x: 0, y: 0, z: 0 };
+        accumulator.position.x += transform.position.x * weight;
+        accumulator.position.y += transform.position.y * weight;
+        accumulator.position.z += transform.position.z * weight;
+        accumulator.positionWeight += weight;
+    }
+    if (transform.rotation) {
+        accumulator.rotation = accumulator.rotation ?? { x: 0, y: 0, z: 0, w: 0 };
+        accumulator.rotation.x += transform.rotation.x * weight;
+        accumulator.rotation.y += transform.rotation.y * weight;
+        accumulator.rotation.z += transform.rotation.z * weight;
+        accumulator.rotation.w += transform.rotation.w * weight;
+        accumulator.rotationWeight += weight;
+    }
+    if (transform.scale) {
+        accumulator.scale = accumulator.scale ?? { x: 0, y: 0, z: 0 };
+        accumulator.scale.x += transform.scale.x * weight;
+        accumulator.scale.y += transform.scale.y * weight;
+        accumulator.scale.z += transform.scale.z * weight;
+        accumulator.scaleWeight += weight;
+    }
+}
+function resolveAccumulator(accumulator) {
+    return {
+        position: accumulator.position && accumulator.positionWeight > 0
+            ? {
+                x: accumulator.position.x / accumulator.positionWeight,
+                y: accumulator.position.y / accumulator.positionWeight,
+                z: accumulator.position.z / accumulator.positionWeight
+            }
+            : undefined,
+        rotation: accumulator.rotation && accumulator.rotationWeight > 0
+            ? normalizeQuaternion({
+                x: accumulator.rotation.x / accumulator.rotationWeight,
+                y: accumulator.rotation.y / accumulator.rotationWeight,
+                z: accumulator.rotation.z / accumulator.rotationWeight,
+                w: accumulator.rotation.w / accumulator.rotationWeight
+            })
+            : undefined,
+        scale: accumulator.scale && accumulator.scaleWeight > 0
+            ? {
+                x: accumulator.scale.x / accumulator.scaleWeight,
+                y: accumulator.scale.y / accumulator.scaleWeight,
+                z: accumulator.scale.z / accumulator.scaleWeight
+            }
+            : undefined
+    };
+}
+function toVector3(value) {
+    if (Array.isArray(value) && value.length >= 3) {
+        const [x, y, z] = value.map(Number);
+        if ([x, y, z].every(Number.isFinite))
+            return { x, y, z };
+    }
+    if (isObject(value)) {
+        const x = Number(value.x);
+        const y = Number(value.y);
+        const z = Number(value.z);
+        if ([x, y, z].every(Number.isFinite))
+            return { x, y, z };
+    }
+    return undefined;
+}
+function toQuaternion(value) {
+    if (Array.isArray(value) && value.length >= 4) {
+        const [x, y, z, w] = value.map(Number);
+        if ([x, y, z, w].every(Number.isFinite))
+            return normalizeQuaternion({ x, y, z, w });
+    }
+    if (isObject(value)) {
+        const x = Number(value.x);
+        const y = Number(value.y);
+        const z = Number(value.z);
+        const w = Number(value.w);
+        if ([x, y, z, w].every(Number.isFinite))
+            return normalizeQuaternion({ x, y, z, w });
+    }
+    return undefined;
+}
+function normalizeQuaternion(quaternion) {
+    const length = Math.hypot(quaternion.x, quaternion.y, quaternion.z, quaternion.w);
+    if (length <= 0.000001)
+        return { x: 0, y: 0, z: 0, w: 1 };
+    return {
+        x: quaternion.x / length,
+        y: quaternion.y / length,
+        z: quaternion.z / length,
+        w: quaternion.w / length
+    };
+}
+function toFiniteNumber(value) {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}
+function createDiagnostic(severity, code, message, clipId, bone, trackId) {
+    return {
+        severity,
+        code,
+        message,
+        clipId,
+        bone,
+        trackId
+    };
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=AnimationController.js.map