@aura3d/animation 4.7.18 → 5.0.1

package/dist/AnimationAction.js

@@ -1,4 +1,6 @@
-import { eventsBetween } from "./AnimationEvents.js";
+import { AnimationClip } from "./AnimationClip.js";
+import { collectAnimationEvents, DEFAULT_MAX_ANIMATION_EVENTS, MAX_ANIMATION_EVENT_CATCH_UP } from "./AnimationEvents.js";
+import { AnimationTrack } from "./AnimationTrack.js";
 export class AnimationAction {
     clip;
     time = 0;
@@ -25,14 +27,20 @@ export class AnimationAction {
     clampWhenFinished = false;
     playing = false;
     paused = false;
+    /** Maximum marker callbacks produced by one update. Excess is reported in playback signals. */
+    maxEventCatchUp = DEFAULT_MAX_ANIMATION_EVENTS;
+    /** Signed unwrapped clip-time distance actually traveled by the last update. */
+    lastPlaybackDelta = 0;
     pingPongForward = true;
     loopsCompleted = 0;
     signalLoopDelta = 0;
     signalFinishedDirection = 0;
+    signalEventOverflow = 0;
     fadeDuration = 0;
     fadeElapsed = 0;
     fadeStartWeight = 1;
     fadeTargetWeight = 1;
+    warpState = null;
     constructor(clip) {
         this.clip = clip;
     }
@@ -50,6 +58,7 @@ export class AnimationAction {
             this.loopsCompleted = 0;
             this.signalLoopDelta = 0;
             this.signalFinishedDirection = 0;
+            this.signalEventOverflow = 0;
         }
         this.playing = true;
         this.paused = false;
@@ -68,6 +77,12 @@ export class AnimationAction {
         this.time = 0;
         this.pingPongForward = true;
         this.loopsCompleted = 0;
+        this.lastPlaybackDelta = 0;
+        this.signalLoopDelta = 0;
+        this.signalFinishedDirection = 0;
+        this.signalEventOverflow = 0;
+        this.fadeDuration = 0;
+        this.warpState = null;
         return this;
     }
     setWeight(weight) {
@@ -91,6 +106,9 @@ export class AnimationAction {
      * `repeat`/`pingpong` default to `Infinity`.
      */
     setLoop(loopMode, repetitions) {
+        if (loopMode !== "once" && loopMode !== "repeat" && loopMode !== "pingpong") {
+            throw new Error(`AnimationAction.setLoop: unknown loop mode ${String(loopMode)}.`);
+        }
         if (repetitions !== undefined) {
             if (!(repetitions === Infinity) && (!Number.isFinite(repetitions) || repetitions < 0)) {
                 throw new Error(`AnimationAction.setLoop: repetitions must be a non-negative number or Infinity, got ${repetitions}.`);
@@ -107,6 +125,21 @@ export class AnimationAction {
         this.loopsCompleted = 0;
         this.signalLoopDelta = 0;
         this.signalFinishedDirection = 0;
+        this.signalEventOverflow = 0;
+        this.lastPlaybackDelta = 0;
+        return this;
+    }
+    /** Copy the phase and reflected direction of another action, optionally scaling its phase. */
+    synchronizePlayback(other, normalized = false) {
+        if (!(other instanceof AnimationAction))
+            throw new Error("AnimationAction.synchronizePlayback: expected an AnimationAction.");
+        this.time = normalized
+            ? (other.clip.duration > 0 ? other.time / other.clip.duration * this.clip.duration : 0)
+            : Math.min(other.time, this.clip.duration);
+        this.pingPongForward = other.pingPongForward;
+        this.loopsCompleted = other.loopsCompleted;
+        this.timeScale = other.timeScale;
+        this.warpState = null;
         return this;
     }
     seek(time) {
@@ -133,6 +166,25 @@ export class AnimationAction {
         }
         return this;
     }
+    /** Linearly interpolate the signed playback rate over unpaused mixer time. */
+    warp(startTimeScale, endTimeScale, duration) {
+        if (![startTimeScale, endTimeScale, duration].every(Number.isFinite) ||
+            !Number.isFinite(endTimeScale - startTimeScale) || duration < 0) {
+            throw new Error("AnimationAction.warp: rates and duration must be finite, and duration must be non-negative.");
+        }
+        if (duration === 0) {
+            this.warpState = null;
+            this.timeScale = endTimeScale;
+        }
+        else {
+            this.warpState = { duration, elapsed: 0, from: startTimeScale, to: endTimeScale };
+        }
+        return this;
+    }
+    /** @internal Convert travel through a monotonic linear-rate segment to mixer time. */
+    static consumedWarpDuration(segment, travelled) {
+        return consumedWarpDuration(segment, travelled);
+    }
     /**
      * Advances playback by `delta` seconds scaled by `timeScale` (signed — a
      * negative product reverses the playhead) and returns the clip marker events
@@ -152,7 +204,7 @@ export class AnimationAction {
         if (!Number.isFinite(this.timeScale)) {
             throw new Error("AnimationAction.update: timeScale must be finite; call AnimationAction.setTimeScale with a valid value.");
         }
-        if (this.fadeDuration > 0) {
+        if (this.playing && this.fadeDuration > 0) {
             this.fadeElapsed = Math.min(this.fadeDuration, this.fadeElapsed + Math.abs(delta));
             const t = this.fadeElapsed / this.fadeDuration;
             this.weight = this.fadeStartWeight + (this.fadeTargetWeight - this.fadeStartWeight) * t;
@@ -160,92 +212,149 @@ export class AnimationAction {
                 this.fadeDuration = 0;
             }
         }
+        this.lastPlaybackDelta = 0;
         if (!this.playing || this.paused || this.clip.duration === 0) {
             return [];
         }
-        const previous = this.time;
-        const scaledDelta = delta * this.timeScale;
-        const duration = this.clip.duration;
-        let looped = false;
-        let finishedThisUpdate = false;
-        let next;
-        if (this.loopMode === "repeat") {
-            next = previous + scaledDelta;
-            if (next >= duration || next < 0) {
-                const loopDelta = Math.floor(next / duration);
-                next -= duration * loopDelta;
-                this.loopsCompleted += Math.abs(loopDelta);
-                looped = true;
-                if (this.loopsCompleted >= this.repetitions) {
-                    next = scaledDelta >= 0 ? duration : 0;
-                    finishedThisUpdate = true;
-                    this.finish(scaledDelta >= 0 ? 1 : -1);
-                }
-                else {
-                    // three dispatches 'loop' for intermediate wraps but 'finished'
-                    // instead of 'loop' on the wrap that exhausts repetitions.
-                    this.signalLoopDelta += loopDelta;
-                }
-            }
+        if (!Number.isSafeInteger(this.maxEventCatchUp) || this.maxEventCatchUp < 0 || this.maxEventCatchUp > MAX_ANIMATION_EVENT_CATCH_UP)
+            throw new Error(`AnimationAction.update: maxEventCatchUp must be an integer from 0 to ${MAX_ANIMATION_EVENT_CATCH_UP}.`);
+        const warp = this.warpState;
+        if (!warp) {
+            const scaledDelta = delta * this.timeScale;
+            if (!Number.isFinite(scaledDelta))
+                throw new Error("AnimationAction.update: scaled delta must be finite.");
+            return scaledDelta === 0 ? [] : this.advancePlayback(scaledDelta, this.maxEventCatchUp);
         }
-        else if (this.loopMode === "once") {
-            next = previous + scaledDelta;
-            if (scaledDelta !== 0) {
-                if (next >= duration) {
-                    next = duration;
-                    this.finish(1);
-                }
-                else if (next <= 0) {
-                    next = 0;
-                    this.finish(-1);
+        const segments = AnimationAction.warpSegments(delta, warp);
+        const events = [];
+        for (const segment of segments) {
+            if (!this.playing || this.paused)
+                break;
+            const previousDelta = this.lastPlaybackDelta;
+            if (segment.distance !== 0) {
+                for (const event of this.advancePlayback(segment.distance, this.maxEventCatchUp - events.length))
+                    events.push(event);
+            }
+            const finished = !this.playing || this.paused;
+            if (segment.inWarp) {
+                const consumed = finished
+                    ? consumedWarpDuration(segment, Math.abs(this.lastPlaybackDelta - previousDelta))
+                    : segment.duration;
+                warp.elapsed = Math.min(warp.duration, segment.elapsed + consumed);
+                if (warp.elapsed === warp.duration) {
+                    this.timeScale = warp.to;
+                    this.warpState = null;
                 }
             }
+            if (finished)
+                break;
+        }
+        if (this.warpState === null && warp.to === 0 && this.playing)
+            this.paused = true;
+        return events;
+    }
+    /** @internal Integrate monotonic parts separately so a rate reversal retains marker crossings. */
+    static warpSegments(delta, warp) {
+        const amount = Math.abs(delta);
+        const span = Math.min(amount, warp.duration - warp.elapsed);
+        const endElapsed = warp.elapsed + span;
+        const rateAt = (elapsed) => warp.from + (warp.to - warp.from) * (elapsed / warp.duration);
+        const startRate = rateAt(warp.elapsed);
+        const endRate = rateAt(endElapsed);
+        const direction = delta < 0 ? -1 : 1;
+        const segments = [];
+        const add = (elapsed, duration, from, to, inWarp) => {
+            const distance = direction * duration * (from / 2 + to / 2);
+            if (!Number.isFinite(distance))
+                throw new Error("AnimationAction.update: warped playback span must be finite.");
+            segments.push({ elapsed, duration, from, to, inWarp, distance });
+        };
+        if ((startRate < 0 && endRate > 0) || (startRate > 0 && endRate < 0)) {
+            const firstSpan = span * (-startRate / (endRate - startRate));
+            add(warp.elapsed, firstSpan, startRate, 0, true);
+            add(warp.elapsed + firstSpan, span - firstSpan, 0, endRate, true);
         }
         else {
-            // pingpong: clip time bounces between the 0 and duration boundaries; each
-            // reflection counts one repetition (three's loopCount parity).
-            next = this.pingPongForward ? previous + scaledDelta : previous - scaledDelta;
-            let crossings = 0;
-            let exhausted = false;
-            while (!exhausted && (next > duration || next < 0)) {
-                next = next > duration ? 2 * duration - next : -next;
-                this.pingPongForward = !this.pingPongForward;
-                crossings++;
-                if (this.loopsCompleted + crossings >= this.repetitions) {
-                    exhausted = true;
-                }
+            add(warp.elapsed, span, startRate, endRate, true);
+        }
+        if (endElapsed === warp.duration) {
+            add(warp.duration, amount - span, warp.to, warp.to, false);
+        }
+        return segments;
+    }
+    advancePlayback(scaledDelta, maxEvents) {
+        const previous = this.time;
+        const duration = this.clip.duration;
+        if (!Number.isFinite(previous) || previous < 0 || previous > duration)
+            throw new Error("AnimationAction.update: time must be finite and within the clip duration.");
+        if (this.loopMode !== "once" && this.loopMode !== "repeat" && this.loopMode !== "pingpong")
+            throw new Error("AnimationAction.update: unknown loop mode.");
+        if (this.repetitions !== Infinity && (!Number.isFinite(this.repetitions) || this.repetitions < 0))
+            throw new Error("AnimationAction.update: repetitions must be non-negative or Infinity.");
+        const sign = scaledDelta > 0 ? 1 : -1;
+        const direction = this.loopMode === "pingpong" && !this.pingPongForward ? -sign : sign;
+        const phase = this.loopMode === "pingpong" && !this.pingPongForward ? 2 * duration - previous : previous;
+        let distance = Math.abs(scaledDelta);
+        const first = direction > 0 ? duration - previous : previous;
+        // Repeated decimal frame intervals often land one ulp below a boundary.
+        // Normalize only within floating-point rounding error of that boundary.
+        const nearest = first + Math.round((distance - first) / duration) * duration;
+        const tolerance = Math.min(duration * 1e-12, 8 * Number.EPSILON * Math.max(duration, distance, Math.abs(previous), Number.MIN_VALUE));
+        if (nearest >= 0 && Number.isFinite(nearest) && Math.abs(distance - nearest) <= tolerance)
+            distance = nearest;
+        const available = this.loopMode === "once" ? 1 : Math.max(1, Math.ceil(this.repetitions - this.loopsCompleted));
+        let crossings = 0;
+        if (this.loopMode === "repeat" && sign < 0) {
+            // The reverse seam is entered when moving past zero; arriving exactly at
+            // zero leaves that endpoint visible until the next update.
+            if (distance > first)
+                crossings = Math.ceil((distance - first) / duration);
+            // A finite action must nevertheless finish as soon as it reaches its
+            // final boundary. Waiting for seam entry would leave it playing at zero
+            // until a subsequent nonzero update and defer the finished signal.
+            if (available !== Infinity && distance >= first) {
+                const arrivals = 1 + Math.floor((distance - first) / duration);
+                if (arrivals >= available)
+                    crossings = available;
             }
-            if (!exhausted) {
-                // Landing exactly on the boundary the playhead moves toward counts as a
-                // wrap (three counts t === duration as a completed loop).
-                const clipVelocity = this.pingPongForward ? scaledDelta : -scaledDelta;
-                if ((clipVelocity > 0 && next === duration) || (clipVelocity < 0 && next === 0)) {
+        }
+        else if (distance >= first) {
+            crossings = 1 + Math.floor((distance - first) / duration);
+        }
+        const finished = crossings > 0 && crossings >= available;
+        if (finished)
+            crossings = available;
+        if (!Number.isSafeInteger(crossings))
+            throw new Error("AnimationAction.update: playback crosses more than the safe boundary count.");
+        const travelled = finished ? first + (crossings - 1) * duration : distance;
+        if (!Number.isSafeInteger(this.loopsCompleted + crossings) || !Number.isFinite(phase) ||
+            !Number.isFinite(phase + sign * travelled) || (this.loopMode === "pingpong" && !Number.isFinite(2 * duration))) {
+            throw new Error("AnimationAction.update: playback span exceeds the supported numeric range.");
+        }
+        this.lastPlaybackDelta += sign * travelled;
+        let next = previous + direction * travelled;
+        if (crossings > 0) {
+            const tail = finished ? 0 : travelled - first - (crossings - 1) * duration;
+            if (this.loopMode === "pingpong") {
+                const odd = crossings % 2 === 1;
+                const boundary = direction > 0 ? (odd ? duration : 0) : (odd ? 0 : duration);
+                next = boundary + (odd ? -direction : direction) * tail;
+                if (odd && !finished)
                     this.pingPongForward = !this.pingPongForward;
-                    crossings++;
-                    if (this.loopsCompleted + crossings >= this.repetitions) {
-                        exhausted = true;
-                    }
-                }
-            }
-            this.loopsCompleted += crossings;
-            if (crossings > 0 && !exhausted) {
-                this.signalLoopDelta += scaledDelta < 0 ? -crossings : crossings;
-                looped = true;
             }
-            if (exhausted) {
-                // The final parity selects which boundary the clip clamps to (three's
-                // loopCount odd/even → duration/0).
-                next = this.pingPongForward ? duration : 0;
-                this.finish(scaledDelta >= 0 ? 1 : -1);
+            else {
+                const boundary = direction > 0 ? duration : 0;
+                next = finished ? boundary : (direction > 0 ? 0 : duration) + direction * tail;
             }
+            this.signalLoopDelta += sign * (crossings - (finished ? 1 : 0));
+            this.loopsCompleted += crossings;
         }
-        this.time = next;
-        if (this.clip.events.length === 0) {
-            return [];
-        }
-        // A wrap that exhausts `repetitions` clamps the playhead to the boundary —
-        // for marker purposes that is a single un-wrapped span from `previous`.
-        return eventsBetween(this.clip.events, this.clip.name, previous, next, this.clip.duration, looped && !finishedThisUpdate, scaledDelta >= 0);
+        this.time = Math.max(0, Math.min(duration, next));
+        if (finished)
+            this.finish(sign);
+        const traversal = collectAnimationEvents(this.clip.events, this.clip.name, phase, phase + sign * travelled, duration, this.loopMode, this.loopsCompleted - crossings + (this.loopMode === "pingpong" && first === 0 && crossings > 0 && !finished ? 1 : 0), maxEvents, finished);
+        this.signalEventOverflow += traversal.overflow;
+        return traversal.events;
     }
     /**
      * Drains the `loop`/`finished` signals accumulated by the last `update`. The
@@ -256,16 +365,15 @@ export class AnimationAction {
     consumePlaybackSignals() {
         const signals = {
             loopDelta: this.signalLoopDelta,
-            finishedDirection: this.signalFinishedDirection
+            finishedDirection: this.signalFinishedDirection,
+            eventOverflow: this.signalEventOverflow
         };
         this.signalLoopDelta = 0;
         this.signalFinishedDirection = 0;
+        this.signalEventOverflow = 0;
         return signals;
     }
     finish(direction) {
-        if (this.signalFinishedDirection !== 0) {
-            return;
-        }
         this.signalFinishedDirection = direction;
         if (this.clampWhenFinished) {
             this.paused = true;
@@ -283,8 +391,270 @@ export class AnimationAction {
             timeScale: this.timeScale,
             playing: this.playing,
             paused: this.paused,
-            loopMode: this.loopMode
+            loopMode: this.loopMode,
+            state: {
+                version: 1,
+                repetitions: this.repetitions === Infinity ? null : this.repetitions,
+                clampWhenFinished: this.clampWhenFinished,
+                maxEventCatchUp: this.maxEventCatchUp,
+                pingPongForward: this.pingPongForward,
+                loopsCompleted: this.loopsCompleted,
+                fade: this.fadeDuration > 0 ? {
+                    duration: this.fadeDuration, elapsed: this.fadeElapsed,
+                    startWeight: this.fadeStartWeight, targetWeight: this.fadeTargetWeight
+                } : null,
+                warp: this.warpState ? { ...this.warpState } : null,
+                lastPlaybackDelta: this.lastPlaybackDelta,
+                signals: {
+                    loopDelta: this.signalLoopDelta,
+                    finishedDirection: this.signalFinishedDirection,
+                    eventOverflow: this.signalEventOverflow === Infinity ? null : this.signalEventOverflow
+                }
+            }
+        };
+    }
+    /**
+     * Capture a JSON-safe, restorable action state. The identity covers the full
+     * clip, including keyframes, interpolation and event payloads; custom clip
+     * implementations and non-JSON event payloads cannot be silently dropped.
+     */
+    serialize() {
+        const snapshot = this.snapshot();
+        const serialized = {
+            ...snapshot,
+            state: { ...snapshot.state, clipIdentity: animationClipIdentity(this.clip) }
         };
+        parseActionSnapshot(serialized, this.clip);
+        rejectActionNegativeZero(serialized);
+        return serialized;
+    }
+    /**
+     * Restore in place without calling `play()`, emitting events, or applying a
+     * pose. Pre-versioned snapshots retain their fields but start with unlimited
+     * repetitions, forward reflection, no transition and no pending signals.
+     */
+    restore(snapshot) {
+        const parsed = parseActionSnapshot(snapshot, this.clip);
+        this.time = parsed.time;
+        this.weight = parsed.weight;
+        this.timeScale = parsed.timeScale;
+        this.playing = parsed.playing;
+        this.paused = parsed.paused;
+        this.loopMode = parsed.loopMode;
+        this.repetitions = parsed.repetitions;
+        this.clampWhenFinished = parsed.clampWhenFinished;
+        this.maxEventCatchUp = parsed.maxEventCatchUp;
+        this.pingPongForward = parsed.pingPongForward;
+        this.loopsCompleted = parsed.loopsCompleted;
+        this.fadeDuration = parsed.fade?.duration ?? 0;
+        this.fadeElapsed = parsed.fade?.elapsed ?? 0;
+        this.fadeStartWeight = parsed.fade?.startWeight ?? parsed.weight;
+        this.fadeTargetWeight = parsed.fade?.targetWeight ?? parsed.weight;
+        this.warpState = parsed.warp ? { ...parsed.warp } : null;
+        this.lastPlaybackDelta = parsed.lastPlaybackDelta;
+        this.signalLoopDelta = parsed.signals.loopDelta;
+        this.signalFinishedDirection = parsed.signals.finishedDirection;
+        this.signalEventOverflow = parsed.signals.eventOverflow;
+        return this;
+    }
+}
+function rejectActionNegativeZero(value) {
+    if (typeof value === "number" && Object.is(value, -0)) {
+        throw new Error("AnimationAction.serialize: negative zero cannot round-trip through JSON.");
+    }
+    if (value && typeof value === "object") {
+        for (const nested of Object.values(value))
+            rejectActionNegativeZero(nested);
+    }
+}
+/** Invert the integral of a monotonic linear rate on one warp segment. */
+function consumedWarpDuration(segment, travelled) {
+    const total = Math.abs(segment.distance);
+    if (total === 0)
+        return segment.duration;
+    const ratio = Math.min(1, Math.max(0, travelled / total));
+    if (ratio === 0)
+        return 0;
+    if (ratio >= 1 - 8 * Number.EPSILON)
+        return segment.duration;
+    const scale = Math.max(Math.abs(segment.from), Math.abs(segment.to));
+    const from = Math.abs(segment.from) / scale;
+    const to = Math.abs(segment.to) / scale;
+    const area = ratio * (from / 2 + to / 2);
+    const denominator = from + Math.sqrt(Math.max(0, from * from + 2 * (to - from) * area));
+    const fraction = denominator === 0 ? 0 : 2 * area / denominator;
+    return segment.duration * Math.max(0, Math.min(1, fraction));
+}
+function actionRecord(value, label, allowed, required = allowed) {
+    if (!value || typeof value !== "object" || Array.isArray(value) ||
+        (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
+        throw new Error(`AnimationAction.restore: ${label} must be a plain object.`);
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Object.getOwnPropertySymbols(value).length || Object.keys(descriptors).some(key => !allowed.includes(key) || !("value" in descriptors[key]) || !descriptors[key].enumerable)) {
+        throw new Error(`AnimationAction.restore: ${label} contains unsupported fields or callbacks.`);
+    }
+    if (required.some(key => !Object.prototype.hasOwnProperty.call(descriptors, key))) {
+        throw new Error(`AnimationAction.restore: ${label} is missing required fields.`);
+    }
+    return value;
+}
+function actionNumber(value, label, minimum = -Infinity) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < minimum) {
+        throw new Error(`AnimationAction.restore: ${label} must be a finite number${minimum === 0 ? " >= 0" : ""}.`);
+    }
+    return value;
+}
+function actionBoolean(value, label) {
+    if (typeof value !== "boolean")
+        throw new Error(`AnimationAction.restore: ${label} must be boolean.`);
+    return value;
+}
+function parseActionSnapshot(input, clip) {
+    const baseKeys = ["clipName", "duration", "time", "weight", "timeScale", "playing", "paused", "loopMode"];
+    const inputRecord = actionRecord(input, "snapshot", [...baseKeys, "state", "active"], baseKeys);
+    if (inputRecord.clipName !== clip.name || inputRecord.duration !== clip.duration) {
+        throw new Error("AnimationAction.restore: clip name and duration must match.");
+    }
+    const time = actionNumber(inputRecord.time, "time", 0);
+    if (time > clip.duration)
+        throw new Error("AnimationAction.restore: time exceeds clip duration.");
+    const weight = actionNumber(inputRecord.weight, "weight", 0);
+    const timeScale = actionNumber(inputRecord.timeScale, "timeScale");
+    const playing = actionBoolean(inputRecord.playing, "playing");
+    const paused = actionBoolean(inputRecord.paused, "paused");
+    const loopMode = inputRecord.loopMode;
+    if (loopMode !== "once" && loopMode !== "repeat" && loopMode !== "pingpong")
+        throw new Error("AnimationAction.restore: invalid loop mode.");
+    if ("active" in inputRecord && (typeof inputRecord.active !== "boolean" || inputRecord.active !== (playing && !paused && weight > 0))) {
+        throw new Error("AnimationAction.restore: active must agree with playback state.");
+    }
+    const base = {
+        time, weight, timeScale, playing, paused, loopMode, repetitions: Infinity, clampWhenFinished: false,
+        maxEventCatchUp: DEFAULT_MAX_ANIMATION_EVENTS, pingPongForward: true, loopsCompleted: 0,
+        fade: null, warp: null, lastPlaybackDelta: 0,
+        signals: { loopDelta: 0, finishedDirection: 0, eventOverflow: 0 }
+    };
+    if (!("state" in inputRecord))
+        return base;
+    const state = actionRecord(inputRecord.state, "state", [
+        "version", "clipIdentity", "repetitions", "clampWhenFinished", "maxEventCatchUp", "pingPongForward",
+        "loopsCompleted", "fade", "warp", "lastPlaybackDelta", "signals"
+    ]);
+    if (state.version !== 1)
+        throw new Error("AnimationAction.restore: unsupported state version.");
+    if (typeof state.clipIdentity !== "string" || state.clipIdentity !== animationClipIdentity(clip)) {
+        throw new Error("AnimationAction.restore: clip identity does not match; use serialize() for restorable snapshots.");
+    }
+    base.repetitions = state.repetitions === null ? Infinity : actionNumber(state.repetitions, "repetitions", 0);
+    base.clampWhenFinished = actionBoolean(state.clampWhenFinished, "clampWhenFinished");
+    base.pingPongForward = actionBoolean(state.pingPongForward, "pingPongForward");
+    base.maxEventCatchUp = actionNumber(state.maxEventCatchUp, "maxEventCatchUp", 0);
+    if (!Number.isSafeInteger(base.maxEventCatchUp) || base.maxEventCatchUp > MAX_ANIMATION_EVENT_CATCH_UP)
+        throw new Error("AnimationAction.restore: invalid maxEventCatchUp.");
+    base.loopsCompleted = actionNumber(state.loopsCompleted, "loopsCompleted", 0);
+    if (!Number.isSafeInteger(base.loopsCompleted))
+        throw new Error("AnimationAction.restore: invalid loopsCompleted.");
+    base.lastPlaybackDelta = actionNumber(state.lastPlaybackDelta, "lastPlaybackDelta");
+    if (state.fade !== null) {
+        const fade = actionRecord(state.fade, "fade", ["duration", "elapsed", "startWeight", "targetWeight"]);
+        const duration = actionNumber(fade.duration, "fade duration", 0);
+        const elapsed = actionNumber(fade.elapsed, "fade elapsed", 0);
+        if (duration === 0 || elapsed >= duration)
+            throw new Error("AnimationAction.restore: invalid fade interval.");
+        base.fade = { duration, elapsed, startWeight: actionNumber(fade.startWeight, "fade startWeight", 0), targetWeight: actionNumber(fade.targetWeight, "fade targetWeight", 0) };
+    }
+    if (state.warp !== null) {
+        const warp = actionRecord(state.warp, "warp", ["duration", "elapsed", "from", "to"]);
+        const duration = actionNumber(warp.duration, "warp duration", 0);
+        const elapsed = actionNumber(warp.elapsed, "warp elapsed", 0);
+        const from = actionNumber(warp.from, "warp from");
+        const to = actionNumber(warp.to, "warp to");
+        if (duration === 0 || elapsed >= duration || !Number.isFinite(to - from))
+            throw new Error("AnimationAction.restore: invalid warp interval.");
+        base.warp = { duration, elapsed, from, to };
+    }
+    const signals = actionRecord(state.signals, "signals", ["loopDelta", "finishedDirection", "eventOverflow"]);
+    const loopDelta = actionNumber(signals.loopDelta, "loopDelta");
+    const finishedDirection = signals.finishedDirection;
+    const eventOverflow = signals.eventOverflow === null ? Infinity : actionNumber(signals.eventOverflow, "eventOverflow", 0);
+    if (!Number.isSafeInteger(loopDelta) || (finishedDirection !== -1 && finishedDirection !== 0 && finishedDirection !== 1) ||
+        (eventOverflow !== Infinity && !Number.isSafeInteger(eventOverflow)))
+        throw new Error("AnimationAction.restore: invalid playback signals.");
+    base.signals = { loopDelta, finishedDirection, eventOverflow };
+    return base;
+}
+/**
+ * A canonical, collision-free clip identity rather than a name/duration hash.
+ * It deliberately rejects accessors, custom implementations, callbacks and
+ * values that JSON would change or discard.
+ */
+function animationClipIdentity(clip) {
+    if (Object.getPrototypeOf(clip) !== AnimationClip.prototype ||
+        !hasOnlyDataFields(clip, ["name", "tracks", "events", "duration"])) {
+        throw new Error("AnimationAction.serialize: custom clip implementations cannot be serialized.");
+    }
+    assertAnimationArray(clip.tracks);
+    const tracks = clip.tracks.map(track => {
+        if (Object.getPrototypeOf(track) !== AnimationTrack.prototype ||
+            !hasOnlyDataFields(track, ["target", "valueType", "valueSize", "keyframes", "duration"])) {
+            throw new Error("AnimationAction.serialize: custom track implementations cannot be serialized.");
+        }
+        return { target: track.target, valueType: track.valueType, valueSize: track.valueSize, duration: track.duration, keyframes: track.keyframes };
+    });
+    return canonicalAnimationJSON({ name: clip.name, duration: clip.duration, tracks, events: clip.events }, new Set(), 0);
+}
+function hasOnlyDataFields(value, allowed) {
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    return Object.getOwnPropertySymbols(value).length === 0 &&
+        Object.keys(descriptors).every(key => allowed.includes(key) && "value" in descriptors[key] && descriptors[key].enumerable);
+}
+function assertAnimationArray(value) {
+    if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || Object.getOwnPropertySymbols(value).length) {
+        throw new Error("AnimationAction.serialize: clip contains a nonserializable array.");
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const keys = Object.keys(descriptors);
+    if (keys.length !== value.length + 1 || keys.some(key => key !== "length" && (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length))) {
+        throw new Error("AnimationAction.serialize: clip contains a sparse or nonserializable array.");
+    }
+    for (let index = 0; index < value.length; index++) {
+        const item = descriptors[String(index)];
+        if (!item || !("value" in item) || !item.enumerable)
+            throw new Error("AnimationAction.serialize: clip contains a sparse or nonserializable array.");
+    }
+}
+function canonicalAnimationJSON(value, ancestors, depth) {
+    if (value === null)
+        return "null";
+    if (typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "number" && Number.isFinite(value))
+        return Object.is(value, -0) ? "-0" : JSON.stringify(value);
+    if (typeof value !== "object" || depth > 128)
+        throw new Error("AnimationAction.serialize: clip contains a nonserializable value or callback.");
+    if (ancestors.has(value))
+        throw new Error("AnimationAction.serialize: clip contains a cycle.");
+    const array = Array.isArray(value);
+    const prototype = Object.getPrototypeOf(value);
+    if ((array && prototype !== Array.prototype) || (!array && prototype !== Object.prototype && prototype !== null) ||
+        Object.getOwnPropertySymbols(value).length)
+        throw new Error("AnimationAction.serialize: clip contains a nonserializable object.");
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    ancestors.add(value);
+    try {
+        if (array) {
+            assertAnimationArray(value);
+            return `[${value.map((entry) => canonicalAnimationJSON(entry, ancestors, depth + 1)).join(",")}]`;
+        }
+        const keys = Object.keys(descriptors).sort();
+        if (keys.some(key => !("value" in descriptors[key]) || !descriptors[key].enumerable)) {
+            throw new Error("AnimationAction.serialize: clip contains an accessor or nonserializable property.");
+        }
+        return `{${keys.map(key => `${JSON.stringify(key)}:${canonicalAnimationJSON(descriptors[key].value, ancestors, depth + 1)}`).join(",")}}`;
+    }
+    finally {
+        ancestors.delete(value);
     }
 }
 //# sourceMappingURL=AnimationAction.js.map