motion 13.4.5 → 13.5.0

package/dist/motion.dev.js

@@ -40,8 +40,7 @@
 
     exports.warning = () => { };
     exports.invariant = () => { };
-    if (typeof process !== "undefined" &&
-        process.env?.NODE_ENV !== "production") {
+    if (typeof process !== "undefined" && "development" !== "production") {
         exports.warning = (check, message, errorCode) => {
             if (!check && typeof console !== "undefined") {
                 console.warn(formatErrorMessage(message, errorCode));
@@ -310,170 +309,15 @@
         return definition;
     };
 
-    const stepsOrder = [
-        "setup", // Compute
-        "read", // Read
-        "resolveKeyframes", // Write/Read/Write/Read
-        "preUpdate", // Compute
-        "update", // Compute
-        "preRender", // Compute
-        "render", // Write
-        "postRender", // Compute
-    ];
-
-    function createRenderStep(runNextFrame) {
-        /**
-         * We create and reuse two queues, one to queue jobs for the current frame
-         * and one for the next. We reuse to avoid triggering GC after x frames.
-         */
-        let thisFrame = new Set();
-        let nextFrame = new Set();
-        /**
-         * Track whether we're currently processing jobs in this step. This way
-         * we can decide whether to schedule new jobs for this frame or next.
-         */
-        let isProcessing = false;
-        let flushNextFrame = false;
-        /**
-         * A set of processes which were marked keepAlive when scheduled.
-         * A keepAlive process is always also held by a frame queue until
-         * it's cancelled, so a Set has the same lifetime semantics as a
-         * WeakSet here while being considerably faster to query every frame.
-         */
-        const toKeepAlive = new Set();
-        let latestFrameData = {
-            delta: 0.0,
-            timestamp: 0.0,
-            isProcessing: false,
-        };
-        function triggerCallback(callback) {
-            if (toKeepAlive.has(callback)) {
-                nextFrame.add(callback);
-                runNextFrame();
-            }
-            callback(latestFrameData);
-        }
-        const step = {
-            /**
-             * Schedule a process to run on the next frame.
-             */
-            schedule: (callback, keepAlive = false, immediate = false) => {
-                const addToCurrentFrame = immediate && isProcessing;
-                const queue = addToCurrentFrame ? thisFrame : nextFrame;
-                if (keepAlive)
-                    toKeepAlive.add(callback);
-                queue.add(callback);
-                return callback;
-            },
-            /**
-             * Cancel the provided callback from running on the next frame.
-             */
-            cancel: (callback) => {
-                nextFrame.delete(callback);
-                toKeepAlive.delete(callback);
-            },
-            /**
-             * Execute all schedule callbacks.
-             */
-            process: (frameData) => {
-                latestFrameData = frameData;
-                /**
-                 * If we're already processing we've probably been triggered by a flushSync
-                 * inside an existing process. Instead of executing, mark flushNextFrame
-                 * as true and ensure we flush the following frame at the end of this one.
-                 */
-                if (isProcessing) {
-                    flushNextFrame = true;
-                    return;
-                }
-                isProcessing = true;
-                // Swap this frame and the next to avoid GC
-                const prevFrame = thisFrame;
-                thisFrame = nextFrame;
-                nextFrame = prevFrame;
-                // Execute this frame
-                thisFrame.forEach(triggerCallback);
-                // Clear the frame so no callbacks remain. This is to avoid
-                // memory leaks should this render step not run for a while.
-                thisFrame.clear();
-                isProcessing = false;
-                if (flushNextFrame) {
-                    flushNextFrame = false;
-                    step.process(frameData);
-                }
-            },
-        };
-        return step;
-    }
-
-    const maxElapsed$1 = 40;
-    function createRenderBatcher(scheduleNextBatch, allowKeepAlive) {
-        let runNextFrame = false;
-        let useDefaultElapsed = true;
-        const state = {
-            delta: 0.0,
-            timestamp: 0.0,
-            isProcessing: false,
-        };
-        const flagRunNextFrame = () => (runNextFrame = true);
-        const steps = stepsOrder.reduce((acc, key) => {
-            acc[key] = createRenderStep(flagRunNextFrame);
-            return acc;
-        }, {});
-        const { setup, read, resolveKeyframes, preUpdate, update, preRender, render, postRender, } = steps;
-        const processBatch = () => {
-            const useManualTiming = MotionGlobalConfig.useManualTiming;
-            const timestamp = useManualTiming
-                ? state.timestamp
-                : performance.now();
-            runNextFrame = false;
-            if (!useManualTiming) {
-                state.delta = useDefaultElapsed
-                    ? 1000 / 60
-                    : Math.max(Math.min(timestamp - state.timestamp, maxElapsed$1), 1);
-            }
-            state.timestamp = timestamp;
-            state.isProcessing = true;
-            // Unrolled render loop for better per-frame performance
-            setup.process(state);
-            read.process(state);
-            resolveKeyframes.process(state);
-            preUpdate.process(state);
-            update.process(state);
-            preRender.process(state);
-            render.process(state);
-            postRender.process(state);
-            state.isProcessing = false;
-            if (runNextFrame && allowKeepAlive) {
-                useDefaultElapsed = false;
-                scheduleNextBatch(processBatch);
-            }
-        };
-        const wake = () => {
-            runNextFrame = true;
-            useDefaultElapsed = true;
-            if (!state.isProcessing) {
-                scheduleNextBatch(processBatch);
-            }
-        };
-        const schedule = stepsOrder.reduce((acc, key) => {
-            const step = steps[key];
-            acc[key] = (process, keepAlive = false, immediate = false) => {
-                if (!runNextFrame)
-                    wake();
-                return step.schedule(process, keepAlive, immediate);
-            };
-            return acc;
-        }, {});
-        const cancel = (process) => {
-            for (let i = 0; i < stepsOrder.length; i++) {
-                steps[stepsOrder[i]].cancel(process);
-            }
-        };
-        return { schedule, cancel, state, steps };
-    }
-
-    const { schedule: frame, cancel: cancelFrame, state: frameData, steps: frameSteps, } = /* @__PURE__ */ createRenderBatcher(typeof requestAnimationFrame !== "undefined" ? requestAnimationFrame : noop, true);
+    /**
+     * The frameloop's state, kept apart from the frameloop itself so that
+     * reading it doesn't bundle the scheduler.
+     */
+    const frameData = {
+        delta: 0.0,
+        timestamp: 0.0,
+        isProcessing: false,
+    };
 
     let now;
     function clearTime() {
@@ -1057,6 +901,170 @@
         return mixer(from, to);
     }
 
+    const stepsOrder = [
+        "setup", // Compute
+        "read", // Read
+        "resolveKeyframes", // Write/Read/Write/Read
+        "preUpdate", // Compute
+        "update", // Compute
+        "preRender", // Compute
+        "render", // Write
+        "postRender", // Compute
+    ];
+
+    function createRenderStep(runNextFrame) {
+        /**
+         * We create and reuse two queues, one to queue jobs for the current frame
+         * and one for the next. We reuse to avoid triggering GC after x frames.
+         */
+        let thisFrame = new Set();
+        let nextFrame = new Set();
+        /**
+         * Track whether we're currently processing jobs in this step. This way
+         * we can decide whether to schedule new jobs for this frame or next.
+         */
+        let isProcessing = false;
+        let flushNextFrame = false;
+        /**
+         * A set of processes which were marked keepAlive when scheduled.
+         * A keepAlive process is always also held by a frame queue until
+         * it's cancelled, so a Set has the same lifetime semantics as a
+         * WeakSet here while being considerably faster to query every frame.
+         */
+        const toKeepAlive = new Set();
+        let latestFrameData = {
+            delta: 0.0,
+            timestamp: 0.0,
+            isProcessing: false,
+        };
+        function triggerCallback(callback) {
+            if (toKeepAlive.has(callback)) {
+                nextFrame.add(callback);
+                runNextFrame();
+            }
+            callback(latestFrameData);
+        }
+        const step = {
+            /**
+             * Schedule a process to run on the next frame.
+             */
+            schedule: (callback, keepAlive = false, immediate = false) => {
+                const addToCurrentFrame = immediate && isProcessing;
+                const queue = addToCurrentFrame ? thisFrame : nextFrame;
+                if (keepAlive)
+                    toKeepAlive.add(callback);
+                queue.add(callback);
+                return callback;
+            },
+            /**
+             * Cancel the provided callback from running on the next frame.
+             */
+            cancel: (callback) => {
+                nextFrame.delete(callback);
+                toKeepAlive.delete(callback);
+            },
+            /**
+             * Execute all schedule callbacks.
+             */
+            process: (frameData) => {
+                latestFrameData = frameData;
+                /**
+                 * If we're already processing we've probably been triggered by a flushSync
+                 * inside an existing process. Instead of executing, mark flushNextFrame
+                 * as true and ensure we flush the following frame at the end of this one.
+                 */
+                if (isProcessing) {
+                    flushNextFrame = true;
+                    return;
+                }
+                isProcessing = true;
+                // Swap this frame and the next to avoid GC
+                const prevFrame = thisFrame;
+                thisFrame = nextFrame;
+                nextFrame = prevFrame;
+                // Execute this frame
+                thisFrame.forEach(triggerCallback);
+                // Clear the frame so no callbacks remain. This is to avoid
+                // memory leaks should this render step not run for a while.
+                thisFrame.clear();
+                isProcessing = false;
+                if (flushNextFrame) {
+                    flushNextFrame = false;
+                    step.process(frameData);
+                }
+            },
+        };
+        return step;
+    }
+
+    const maxElapsed$1 = 40;
+    function createRenderBatcher(scheduleNextBatch, allowKeepAlive, state = {
+        delta: 0.0,
+        timestamp: 0.0,
+        isProcessing: false,
+    }) {
+        let runNextFrame = false;
+        let useDefaultElapsed = true;
+        const flagRunNextFrame = () => (runNextFrame = true);
+        const steps = stepsOrder.reduce((acc, key) => {
+            acc[key] = createRenderStep(flagRunNextFrame);
+            return acc;
+        }, {});
+        const { setup, read, resolveKeyframes, preUpdate, update, preRender, render, postRender, } = steps;
+        const processBatch = () => {
+            const useManualTiming = MotionGlobalConfig.useManualTiming;
+            const timestamp = useManualTiming
+                ? state.timestamp
+                : performance.now();
+            runNextFrame = false;
+            if (!useManualTiming) {
+                state.delta = useDefaultElapsed
+                    ? 1000 / 60
+                    : Math.max(Math.min(timestamp - state.timestamp, maxElapsed$1), 1);
+            }
+            state.timestamp = timestamp;
+            state.isProcessing = true;
+            // Unrolled render loop for better per-frame performance
+            setup.process(state);
+            read.process(state);
+            resolveKeyframes.process(state);
+            preUpdate.process(state);
+            update.process(state);
+            preRender.process(state);
+            render.process(state);
+            postRender.process(state);
+            state.isProcessing = false;
+            if (runNextFrame && allowKeepAlive) {
+                useDefaultElapsed = false;
+                scheduleNextBatch(processBatch);
+            }
+        };
+        const wake = () => {
+            runNextFrame = true;
+            useDefaultElapsed = true;
+            if (!state.isProcessing) {
+                scheduleNextBatch(processBatch);
+            }
+        };
+        const schedule = stepsOrder.reduce((acc, key) => {
+            const step = steps[key];
+            acc[key] = (process, keepAlive = false, immediate = false) => {
+                if (!runNextFrame)
+                    wake();
+                return step.schedule(process, keepAlive, immediate);
+            };
+            return acc;
+        }, {});
+        const cancel = (process) => {
+            for (let i = 0; i < stepsOrder.length; i++) {
+                steps[stepsOrder[i]].cancel(process);
+            }
+        };
+        return { schedule, cancel, state, steps };
+    }
+
+    const { schedule: frame, cancel: cancelFrame, steps: frameSteps, } = /* @__PURE__ */ createRenderBatcher(typeof requestAnimationFrame !== "undefined" ? requestAnimationFrame : noop, true, frameData);
+
     const frameloopDriver = (update) => {
         const passTimestamp = ({ timestamp }) => update(timestamp);
         return {
@@ -1135,8 +1143,37 @@
         minDuration: 0.01, // in seconds
         maxDuration: 10.0, // in seconds
         minDamping: 0.05,
-        maxDamping: 1,
     };
+    /**
+     * Maps bounce to a damping ratio as SwiftUI does: 0 is critically damped, and
+     * it approaches undamped towards 1 and infinitely overdamped towards -1. Both
+     * ends are limited so the spring still moves and settles.
+     */
+    const bounceToDampingRatio = (bounce) => bounce < 0
+        ? 1 / Math.max(1 + bounce, springDefaults.minDamping)
+        : Math.max(1 - bounce, springDefaults.minDamping);
+    /**
+     * Scales an overdamped spring's undamped frequency so that, at its defining
+     * time, it has as far left to go as the critically damped spring that's
+     * criticalFreqTime radians in by then. A negative bounce then changes the
+     * shape of the curve, not when it arrives. 1 at a damping ratio of 1, so
+     * there's no jump at a bounce of 0.
+     *
+     * Solved by Newton on the remaining distance (times fast - slow), which is
+     * convex from criticalFreqTime onwards. criticalFreqTime is always below the
+     * answer, so it converges from below without overshooting.
+     */
+    function overdampedFreqScale(dampingRatio, criticalFreqTime) {
+        if (!(dampingRatio > 1))
+            return 1;
+        const root = Math.sqrt(dampingRatio * dampingRatio - 1);
+        const slow = dampingRatio - root;
+        const fast = dampingRatio + root;
+        const target = 2 * root * Math.exp(-criticalFreqTime) * (1 + criticalFreqTime);
+        return (approximateRoot((freqTime) => fast * Math.exp(-slow * freqTime) -
+            slow * Math.exp(-fast * freqTime) -
+            target, (freqTime) => Math.exp(-fast * freqTime) - Math.exp(-slow * freqTime), criticalFreqTime) / criticalFreqTime);
+    }
     function calcAngularFreq(undampedFreq, dampingRatio) {
         return undampedFreq * Math.sqrt(1 - dampingRatio * dampingRatio);
     }
@@ -1161,11 +1198,7 @@
         let envelope;
         let derivative;
         exports.warning(duration <= secondsToMilliseconds(springDefaults.maxDuration), "Spring duration must be 10 seconds or less", "spring-duration-limit");
-        let dampingRatio = 1 - bounce;
-        /**
-         * Restrict dampingRatio and duration to within acceptable ranges.
-         */
-        dampingRatio = clamp(springDefaults.minDamping, springDefaults.maxDamping, dampingRatio);
+        const dampingRatio = bounceToDampingRatio(bounce);
         duration = clamp(springDefaults.minDuration, springDefaults.maxDuration, millisecondsToSeconds(duration));
         if (dampingRatio < 1) {
             /**
@@ -1194,7 +1227,8 @@
         }
         else {
             /**
-             * Critically-damped spring
+             * Critically-damped spring. Overdamped springs reuse this root,
+             * scaled below.
              */
             envelope = (undampedFreq) => {
                 const a = Math.exp(-undampedFreq * duration);
@@ -1208,7 +1242,9 @@
             };
         }
         const initialGuess = 5 / duration;
-        const undampedFreq = approximateRoot(envelope, derivative, initialGuess);
+        const criticalFreq = approximateRoot(envelope, derivative, initialGuess);
+        const undampedFreq = criticalFreq *
+            overdampedFreqScale(dampingRatio, criticalFreq * duration);
         const stiffness = undampedFreq * undampedFreq;
         return {
             stiffness,
@@ -1258,12 +1294,12 @@
         };
         if (springOptions.isTimeDefined) {
             if (options.visualDuration) {
-                const root = (2 * Math.PI) / (options.visualDuration * 1.2);
+                const dampingRatio = bounceToDampingRatio(options.bounce || 0);
+                const root = ((2 * Math.PI) / (options.visualDuration * 1.2)) *
+                    overdampedFreqScale(dampingRatio, (2 * Math.PI) / 1.2);
                 springOptions.stiffness = root * root;
                 springOptions.damping =
-                    2 *
-                        clamp(0.05, 1, 1 - (options.bounce || 0)) *
-                        Math.sqrt(springOptions.stiffness);
+                    2 * dampingRatio * Math.sqrt(springOptions.stiffness);
             }
             else {
                 Object.assign(springOptions, findSpring(springOptions));
@@ -1398,31 +1434,32 @@
                 (undampedAngularFreq * c.C * t - s.velocity);
         }
         else {
-            // Overdamped spring
+            /**
+             * Overdamped spring: the sum of a slow and a fast decaying
+             * exponential, so no term can overflow however heavily it's damped.
+             */
             const dampedAngularFreq = undampedAngularFreq * Math.sqrt(dampingRatio * dampingRatio - 1);
-            resolveSpring = (t) => {
-                const envelope = Math.exp(-decay * t);
-                // When performing sinh or cosh values can hit Infinity so we cap them here
-                const freqForT = Math.min(dampedAngularFreq * t, 300);
-                return (s.target -
-                    (envelope *
-                        ((s.velocity + decay * s.delta) * Math.sinh(freqForT) +
-                            dampedAngularFreq * s.delta * Math.cosh(freqForT))) /
-                        dampedAngularFreq);
-            };
-            // Analytical derivative of overdamped spring (px/ms)
-            const c = { P: 0, sinh: 0, cosh: 0 };
+            const slow = decay - dampedAngularFreq;
+            const fast = decay + dampedAngularFreq;
+            /**
+             * Physics-defined springs keep a non-physical limit: once
+             * dampedAngularFreq * t passes 300, both terms decay at the damping
+             * rate. Heavily overdamped drag springs (dragElastic: 0,
+             * dragTransition) rely on this to settle almost at once rather than
+             * creep at stiffness / damping. Negative bounce needs the exact
+             * curve, so time-defined springs are exempt.
+             */
+            const limit = isTimeDefined ? Infinity : 300 / dampedAngularFreq;
+            const decayAt = (rate, t) => Math.exp(t > limit ? -rate * limit - decay * (t - limit) : -rate * t);
+            const c = { S: 0, F: 0 };
             update = () => {
-                c.P = (s.velocity + decay * s.delta) / dampedAngularFreq;
-                c.sinh = decay * c.P - s.delta * dampedAngularFreq;
-                c.cosh = decay * s.delta - c.P * dampedAngularFreq;
-            };
-            resolveVelocity = (t) => {
-                const envelope = Math.exp(-decay * t);
-                const freqForT = Math.min(dampedAngularFreq * t, 300);
-                return (envelope *
-                    (c.sinh * Math.sinh(freqForT) + c.cosh * Math.cosh(freqForT)));
+                const P = (s.velocity + decay * s.delta) / dampedAngularFreq;
+                c.S = (s.delta + P) / 2;
+                c.F = (s.delta - P) / 2;
             };
+            resolveSpring = (t) => s.target - c.S * decayAt(slow, t) - c.F * decayAt(fast, t);
+            // Analytical derivative of overdamped spring (px/ms)
+            resolveVelocity = (t) => slow * c.S * decayAt(slow, t) + fast * c.F * decayAt(fast, t);
         }
         update();
         const calculatedDuration = isResolvedFromDuration ? duration || null : null;
@@ -3000,17 +3037,14 @@
         /**
          * Attaches a timeline to the animation, for instance the `ScrollTimeline`.
          */
-        attachTimeline({ timeline, rangeStart, rangeEnd, observe, }) {
+        attachTimeline({ timeline, onAttach, observe, }) {
             if (this.allowFlatten) {
                 this.animation.effect?.updateTiming({ easing: "linear" });
             }
             this.animation.onfinish = null;
             if (timeline && supportsScrollTimeline()) {
                 this.animation.timeline = timeline;
-                if (rangeStart)
-                    this.animation.rangeStart = rangeStart;
-                if (rangeEnd)
-                    this.animation.rangeEnd = rangeEnd;
+                onAttach?.(this.animation);
                 return noop;
             }
             else {
@@ -6343,21 +6377,6 @@
         return typeof a === "function" ? resizeWindow(a) : resizeElement(a, b);
     }
 
-    function observeTimeline(update, timeline) {
-        let prevProgress;
-        const onFrame = () => {
-            const { currentTime } = timeline;
-            const percentage = currentTime === null ? 0 : currentTime.value;
-            const progress = percentage / 100;
-            if (prevProgress !== progress) {
-                update(progress);
-            }
-            prevProgress = progress;
-        };
-        frame.preUpdate(onFrame, true);
-        return () => cancelFrame(onFrame);
-    }
-
     const statsBuffer = {
         value: null,
         addProjectionMetrics: null,
@@ -6471,8 +6490,7 @@
                 this.options.onStop?.();
             };
             this.options = options;
-            replaceTransitionType(options);
-            this.factory = options.type || keyframes;
+            this.factory = options.type;
             this.generator = this.factory(options);
             const { driver } = options;
             if (driver)
@@ -6573,41 +6591,15 @@
         }
     }
 
+    const asNumber = (v) => typeof v === "number" ? v : parseFloat(v);
+
     /**
-     * Create a `MotionValue` that animates to its latest value using any transition type.
-     * Can either be a value or track another `MotionValue`.
-     *
-     * ```jsx
-     * const x = motionValue(0)
-     * const y = followValue(x, { type: "spring", stiffness: 300 })
-     * // or with tween
-     * const z = followValue(x, { type: "tween", duration: 0.5, ease: "easeOut" })
-     * ```
-     *
-     * @param source - Initial value or MotionValue to track
-     * @param options - Animation transition options
-     * @returns `MotionValue`
-     *
-     * @public
-     */
-    function followValue(source, options) {
-        const initialValue = isMotionValue(source) ? source.get() : source;
-        const value = motionValue(initialValue);
-        attachFollow(value, source, options);
-        return value;
-    }
-    /**
-     * Attach an animation to a MotionValue that will animate whenever the value changes.
-     * Similar to attachSpring but supports any transition type (spring, tween, inertia, etc.)
-     *
-     * @param value - The MotionValue to animate
-     * @param source - Initial value or MotionValue to track
-     * @param options - Animation transition options
-     * @returns Cleanup function
-     *
-     * @public
+     * Animate `value` to its latest value with the generator in
+     * `options.type`, tracking `source` if it's a `MotionValue`. Takes a
+     * generator rather than a type name, so spring-only callers don't
+     * bundle every generator.
      */
-    function attachFollow(value, source, options = {}) {
+    function follow(value, source, options) {
         const initialValue = value.get();
         let activeAnimation = null;
         let set;
@@ -6625,7 +6617,7 @@
         };
         value.attach((v, safeSet) => {
             set = safeSet;
-            const target = asNumber$1(v);
+            const target = asNumber(v);
             if (activeAnimation?.state === "running") {
                 /**
                  * Steer the running animation rather than replacing it. This
@@ -6636,7 +6628,7 @@
                 activeAnimation.setTarget(target, options.velocity);
                 return;
             }
-            const current = asNumber$1(value.get());
+            const current = asNumber(value.get());
             const velocity = activeAnimation
                 ? activeAnimation.getGeneratorVelocity()
                 : value.getVelocity();
@@ -6647,8 +6639,6 @@
             const animationOptions = {
                 keyframes: [current, target],
                 velocity,
-                // Default to spring if no type specified (matches useSpring behavior)
-                type: "spring",
                 restDelta: 0.001,
                 restSpeed: 0.01,
                 ...options,
@@ -6690,8 +6680,47 @@
     function parseValue(v, unit) {
         return unit ? v + unit : v;
     }
-    function asNumber$1(v) {
-        return typeof v === "number" ? v : parseFloat(v);
+
+    /**
+     * Create a `MotionValue` that animates to its latest value using any transition type.
+     * Can either be a value or track another `MotionValue`.
+     *
+     * ```jsx
+     * const x = motionValue(0)
+     * const y = followValue(x, { type: "spring", stiffness: 300 })
+     * // or with tween
+     * const z = followValue(x, { type: "tween", duration: 0.5, ease: "easeOut" })
+     * ```
+     *
+     * @param source - Initial value or MotionValue to track
+     * @param options - Animation transition options
+     * @returns `MotionValue`
+     *
+     * @public
+     */
+    function followValue(source, options) {
+        const initialValue = isMotionValue(source) ? source.get() : source;
+        const value = motionValue(initialValue);
+        attachFollow(value, source, options);
+        return value;
+    }
+    /**
+     * Attach an animation to a MotionValue that will animate whenever the value changes.
+     * Similar to attachSpring but supports any transition type (spring, tween, inertia, etc.)
+     *
+     * @param value - The MotionValue to animate
+     * @param source - Initial value or MotionValue to track
+     * @param options - Animation transition options
+     * @returns Cleanup function
+     *
+     * @public
+     */
+    function attachFollow(value, source, options = {}) {
+        // Default to spring if no type specified (matches useSpring behavior)
+        const transition = { type: "spring", ...options };
+        replaceTransitionType(transition);
+        transition.type = transition.type || keyframes;
+        return follow(value, source, transition);
     }
 
     function subscribeValue(inputValues, outputValue, getLatest) {
@@ -6793,7 +6822,9 @@
      * @public
      */
     function springValue(source, options) {
-        return followValue(source, { type: "spring", ...options });
+        const value = motionValue(isMotionValue(source) ? source.get() : source);
+        attachSpring(value, source, options);
+        return value;
     }
     /**
      * Attach a spring animation to a MotionValue that will animate whenever the value changes.
@@ -6806,7 +6837,7 @@
      * @public
      */
     function attachSpring(value, source, options) {
-        return attachFollow(value, source, { type: "spring", ...options });
+        return follow(value, source, { ...options, type: spring });
     }
 
     /**
@@ -8476,7 +8507,15 @@
                     this.removeValue(key);
                 this.bindToMotionValue(key, value);
                 this.values.set(key, value);
-                this.latestValues[key] = value.get();
+                /**
+                 * An animated value with no base value is undefined until the
+                 * keyframe resolver reads its origin. Rendering it before then
+                 * writes an invalid placeholder (e.g. points="undefined") that
+                 * the resolver can read back from the DOM as the origin.
+                 */
+                const latest = value.get();
+                if (latest !== undefined)
+                    this.latestValues[key] = latest;
             }
         }
         /**
@@ -8504,7 +8543,9 @@
             }
             let value = this.values.get(key);
             if (value === undefined && defaultValue !== undefined) {
-                value = motionValue(defaultValue === null ? undefined : defaultValue, { owner: this });
+                value = motionValue(defaultValue ?? this.getDefaultValue?.(key), {
+                    owner: this,
+                });
                 this.addValue(key, value);
             }
             return value;
@@ -8666,86 +8707,7 @@
         }
     }
 
-    function pixelsToPercent(pixels, axis) {
-        if (axis.max === axis.min)
-            return 0;
-        return (pixels / (axis.max - axis.min)) * 100;
-    }
-    /**
-     * We always correct borderRadius as a percentage rather than pixels to reduce paints.
-     * For example, if you are projecting a box that is 100px wide with a 10px borderRadius
-     * into a box that is 200px wide with a 20px borderRadius, that is actually a 10%
-     * borderRadius in both states. If we animate between the two in pixels that will trigger
-     * a paint each time. If we animate between the two in percentage we'll avoid a paint.
-     */
-    const correctBorderRadius = {
-        correct: (latest, node) => {
-            if (!node.target)
-                return latest;
-            /**
-             * If latest is a string, if it's a percentage we can return immediately as it's
-             * going to be stretched appropriately. Otherwise, if it's a pixel, convert it to a number.
-             */
-            if (typeof latest === "string") {
-                if (px.test(latest)) {
-                    latest = parseFloat(latest);
-                }
-                else {
-                    return latest;
-                }
-            }
-            /**
-             * If latest is a number, it's a pixel value. We use the current viewportBox to calculate that
-             * pixel value as a percentage of each axis
-             */
-            const x = pixelsToPercent(latest, node.target.x);
-            const y = pixelsToPercent(latest, node.target.y);
-            return `${x}% ${y}%`;
-        },
-    };
-
-    const correctBoxShadow = {
-        correct: (latest, { treeScale, projectionDelta }) => {
-            const original = latest;
-            const shadow = complex.parse(latest);
-            // TODO: Doesn't support multiple shadows
-            if (shadow.length > 5)
-                return original;
-            const template = complex.createTransformer(latest);
-            const offset = typeof shadow[0] !== "number" ? 1 : 0;
-            // Calculate the overall context scale
-            const xScale = projectionDelta.x.scale * treeScale.x;
-            const yScale = projectionDelta.y.scale * treeScale.y;
-            shadow[0 + offset] /= xScale;
-            shadow[1 + offset] /= yScale;
-            /**
-             * Ideally we'd correct x and y scales individually, but because blur and
-             * spread apply to both we have to take a scale average and apply that instead.
-             * We could potentially improve the outcome of this by incorporating the ratio between
-             * the two scales.
-             */
-            const averageScale = mixNumber$1(xScale, yScale, 0.5);
-            // Blur
-            if (typeof shadow[2 + offset] === "number")
-                shadow[2 + offset] /= averageScale;
-            // Spread
-            if (typeof shadow[3 + offset] === "number")
-                shadow[3 + offset] /= averageScale;
-            return template(shadow);
-        },
-    };
-
-    const scaleCorrectors = {
-        borderRadius: {
-            ...correctBorderRadius,
-            applyTo: [...cornerRadiusProps],
-        },
-        borderTopLeftRadius: correctBorderRadius,
-        borderTopRightRadius: correctBorderRadius,
-        borderBottomLeftRadius: correctBorderRadius,
-        borderBottomRightRadius: correctBorderRadius,
-        boxShadow: correctBoxShadow,
-    };
+    const scaleCorrectors = {};
     function addScaleCorrector(correctors) {
         for (const key in correctors) {
             scaleCorrectors[key] = correctors[key];
@@ -8919,7 +8881,24 @@
             this.measureInstanceViewportBox = createBox;
         }
         getBaseTargetFromProps(props, key) {
-            return props[key];
+            /**
+             * An independent transform's base is never an attribute of the same
+             * name, e.g. <rect x> is a position, not a translate. Like HTML it
+             * comes from style, falling back to the transform's default.
+             */
+            return transformProps.has(key)
+                ? super.getBaseTargetFromProps(props, key) ??
+                    defaultTransformValue(key)
+                : props[key];
+        }
+        /**
+         * An independent transform's origin is never read from the DOM, so it
+         * starts from its latest or default value and renders on mount.
+         */
+        getDefaultValue(key) {
+            return transformProps.has(key)
+                ? this.latestValues[key] ?? defaultTransformValue(key)
+                : undefined;
         }
         readValueFromInstance(instance, key) {
             if (transformProps.has(key)) {
@@ -9532,6 +9511,75 @@
         return [callback("x"), callback("y")];
     }
 
+    function pixelsToPercent(pixels, axis) {
+        if (axis.max === axis.min)
+            return 0;
+        return (pixels / (axis.max - axis.min)) * 100;
+    }
+    /**
+     * We always correct borderRadius as a percentage rather than pixels to reduce paints.
+     * For example, if you are projecting a box that is 100px wide with a 10px borderRadius
+     * into a box that is 200px wide with a 20px borderRadius, that is actually a 10%
+     * borderRadius in both states. If we animate between the two in pixels that will trigger
+     * a paint each time. If we animate between the two in percentage we'll avoid a paint.
+     */
+    const correctBorderRadius = {
+        correct: (latest, node) => {
+            if (!node.target)
+                return latest;
+            /**
+             * If latest is a string, if it's a percentage we can return immediately as it's
+             * going to be stretched appropriately. Otherwise, if it's a pixel, convert it to a number.
+             */
+            if (typeof latest === "string") {
+                if (px.test(latest)) {
+                    latest = parseFloat(latest);
+                }
+                else {
+                    return latest;
+                }
+            }
+            /**
+             * If latest is a number, it's a pixel value. We use the current viewportBox to calculate that
+             * pixel value as a percentage of each axis
+             */
+            const x = pixelsToPercent(latest, node.target.x);
+            const y = pixelsToPercent(latest, node.target.y);
+            return `${x}% ${y}%`;
+        },
+    };
+
+    const correctBoxShadow = {
+        correct: (latest, { treeScale, projectionDelta }) => {
+            const original = latest;
+            const shadow = complex.parse(latest);
+            // TODO: Doesn't support multiple shadows
+            if (shadow.length > 5)
+                return original;
+            const template = complex.createTransformer(latest);
+            const offset = typeof shadow[0] !== "number" ? 1 : 0;
+            // Calculate the overall context scale
+            const xScale = projectionDelta.x.scale * treeScale.x;
+            const yScale = projectionDelta.y.scale * treeScale.y;
+            shadow[0 + offset] /= xScale;
+            shadow[1 + offset] /= yScale;
+            /**
+             * Ideally we'd correct x and y scales individually, but because blur and
+             * spread apply to both we have to take a scale average and apply that instead.
+             * We could potentially improve the outcome of this by incorporating the ratio between
+             * the two scales.
+             */
+            const averageScale = mixNumber$1(xScale, yScale, 0.5);
+            // Blur
+            if (typeof shadow[2 + offset] === "number")
+                shadow[2 + offset] /= averageScale;
+            // Spread
+            if (typeof shadow[3 + offset] === "number")
+                shadow[3 + offset] /= averageScale;
+            return template(shadow);
+        },
+    };
+
     function buildProjectionTransform(delta, treeScale, latestTransform) {
         let transform = "";
         /**
@@ -9584,7 +9632,6 @@
     }
 
     const numBorders = cornerRadiusProps.length;
-    const asNumber = (value) => typeof value === "string" ? parseFloat(value) : value;
     const isPx = (value) => typeof value === "number" || px.test(value);
     function mixValues(target, follow, lead, progress, shouldCrossfadeOpacity, isOnlyMember) {
         if (shouldCrossfadeOpacity) {
@@ -9783,6 +9830,18 @@
         }
     }
 
+    const defaultScaleCorrectors = {
+        borderRadius: {
+            ...correctBorderRadius,
+            applyTo: [...cornerRadiusProps],
+        },
+        borderTopLeftRadius: correctBorderRadius,
+        borderTopRightRadius: correctBorderRadius,
+        borderBottomLeftRadius: correctBorderRadius,
+        borderBottomRightRadius: correctBorderRadius,
+        boxShadow: correctBoxShadow,
+    };
+
     /**
      * This should only ever be modified on the client otherwise it'll
      * persist through server requests. If we need instanced states we
@@ -9801,6 +9860,14 @@
         hasEverUpdated: false,
     };
 
+    /**
+     * Correctors registered via addScaleCorrector before projection loaded
+     * (e.g. with an async LazyMotion bundle) take precedence over the defaults.
+     */
+    Object.assign(scaleCorrectors, {
+        ...defaultScaleCorrectors,
+        ...scaleCorrectors,
+    });
     const metrics = {
         nodes: 0,
         calculatedTargetDeltas: 0,
@@ -12556,12 +12623,6 @@
     };
     const animateMini = /*@__PURE__*/ createScopedWaapiAnimate();
 
-    function canUseNativeTimeline(target) {
-        if (typeof window === "undefined")
-            return false;
-        return target ? supportsViewTimeline() : supportsScrollTimeline();
-    }
-
     /**
      * A time in milliseconds, beyond which we consider the scroll velocity to be 0.
      */
@@ -12701,18 +12762,6 @@
     }
 
     const ScrollOffset = {
-        Enter: [
-            [0, 1],
-            [1, 1],
-        ],
-        Exit: [
-            [0, 0],
-            [1, 0],
-        ],
-        Any: [
-            [1, 0],
-            [0, 1],
-        ],
         All: [
             [0, 0],
             [1, 1],
@@ -12964,158 +13013,163 @@
         };
     }
 
-    /**
-     * Maps from ProgressIntersection pairs used by Motion's preset offsets to
-     * ViewTimeline named ranges. Returns undefined for unrecognised patterns,
-     * which signals the caller to fall back to JS-based scroll tracking.
-     */
-    const presets = [
-        [ScrollOffset.Enter, "entry"],
-        [ScrollOffset.Exit, "exit"],
-        [ScrollOffset.Any, "cover"],
-        [ScrollOffset.All, "contain"],
-    ];
-    const stringToProgress = {
-        start: 0,
-        end: 1,
-    };
-    function parseStringOffset(s) {
-        const parts = s.trim().split(/\s+/);
-        if (parts.length !== 2)
-            return undefined;
-        const a = stringToProgress[parts[0]];
-        const b = stringToProgress[parts[1]];
-        if (a === undefined || b === undefined)
-            return undefined;
-        return [a, b];
-    }
-    function normaliseOffset(offset) {
-        if (offset.length !== 2)
-            return undefined;
-        const result = [];
-        for (const item of offset) {
-            if (Array.isArray(item)) {
-                result.push(item);
-            }
-            else if (typeof item === "string") {
-                const parsed = parseStringOffset(item);
-                if (!parsed)
-                    return undefined;
-                result.push(parsed);
-            }
-            else {
-                return undefined;
-            }
-        }
-        return result;
-    }
-    function matchesPreset(offset, preset) {
-        const normalised = normaliseOffset(offset);
-        if (!normalised)
+    function canUseNativeTimeline(target) {
+        if (typeof window === "undefined")
             return false;
-        for (let i = 0; i < 2; i++) {
-            const o = normalised[i];
-            const p = preset[i];
-            if (o[0] !== p[0] || o[1] !== p[1])
-                return false;
-        }
-        return true;
-    }
-    function offsetToViewTimelineRange(offset) {
-        if (!offset) {
-            return { rangeStart: "contain 0%", rangeEnd: "contain 100%" };
-        }
-        for (const [preset, name] of presets) {
-            if (matchesPreset(offset, preset)) {
-                return { rangeStart: `${name} 0%`, rangeEnd: `${name} 100%` };
-            }
-        }
-        return undefined;
+        return target ? supportsViewTimeline() : supportsScrollTimeline();
     }
 
     const timelineCache = new Map();
-    function scrollTimelineFallback(options) {
-        const currentTime = { value: 0 };
-        const cancel = scrollInfo((info) => {
-            currentTime.value = info[options.axis].progress * 100;
-        }, options);
-        return { currentTime, cancel };
-    }
-    function getTimeline({ container, ...options }) {
-        const { axis } = options;
+    /**
+     * Native timelines are only attached to WAAPI animations. Offsets are
+     * applied to each animation as a range, so a timeline is shared by every
+     * offset.
+     */
+    function getTimeline({ container, target, axis, }) {
         let containerCache = timelineCache.get(container);
         if (!containerCache) {
             containerCache = new Map();
             timelineCache.set(container, containerCache);
         }
-        const targetKey = options.target ?? "self";
+        const targetKey = target ?? "self";
         let targetCache = containerCache.get(targetKey);
         if (!targetCache) {
             targetCache = {};
             containerCache.set(targetKey, targetCache);
         }
-        const axisKey = axis + (options.offset ?? []).join(",");
-        if (!targetCache[axisKey]) {
-            if (options.target && canUseNativeTimeline(options.target)) {
-                const range = offsetToViewTimelineRange(options.offset);
-                if (range) {
-                    targetCache[axisKey] = new ViewTimeline({
-                        subject: options.target,
-                        axis,
-                    });
-                }
-                else {
-                    targetCache[axisKey] = scrollTimelineFallback({
-                        container,
-                        ...options,
-                    });
-                }
-            }
-            else if (canUseNativeTimeline()) {
-                targetCache[axisKey] = new ScrollTimeline({
-                    source: container,
-                    axis,
-                });
-            }
-            else {
-                targetCache[axisKey] = scrollTimelineFallback({
-                    container,
-                    ...options,
-                });
-            }
+        return (targetCache[axis] || (targetCache[axis] = target
+            ? new ViewTimeline({ subject: target, axis })
+            : new ScrollTimeline({ source: container, axis })));
+    }
+
+    /**
+     * Resolved offsets are linear in the target and container lengths, so
+     * probing them gives [target progress, container progress, pixels].
+     * vw/vh can resolve to 0px, so they're rejected up front.
+     */
+    const toIntersection = (o) => {
+        if (/v/u.test(o))
+            return [];
+        const px = resolveOffset(o, 0, 0, 0);
+        return [resolveOffset(o, 0, 1, 0) - px, px - resolveOffset(o, 1, 0, 0), px];
+    };
+    const toRange = ([t, c, px]) => !px &&
+        (c === 0 || c === 1) &&
+        `${c ? "entry" : "exit"}-crossing ${t * 100}%`;
+    /**
+     * Maps an offset to an equivalent ViewTimeline range. Returns undefined when
+     * there isn't one, which signals the caller to fall back to JS-based scroll
+     * tracking.
+     */
+    function offsetToViewTimelineRange(offset = ScrollOffset.All) {
+        if (offset.length !== 2)
+            return;
+        const [start, end] = offset.map(toIntersection);
+        const points = [toRange(start), toRange(end)];
+        const a = end[0] - start[0];
+        const b = start[1] - end[1];
+        if (points[0] && points[1] && (a || b)) {
+            return {
+                points: points,
+                a,
+                b,
+                cover: !start[0] && a === 1 && b === 1,
+            };
         }
-        return targetCache[axisKey];
     }
 
     function attachToAnimation(animation, options) {
-        const timeline = getTimeline(options);
-        const range = options.target
-            ? offsetToViewTimelineRange(options.offset)
-            : undefined;
+        const { target, container, axis } = options;
+        const range = target && offsetToViewTimelineRange(options.offset);
         /**
          * Use native timeline when:
-         * - No target: ScrollTimeline (existing behaviour)
+         * - No target and no offset: ScrollTimeline
          * - Target with mappable offset: ViewTimeline with named range
-         * - Target with unmappable offset: fall back to JS observe
-         */
-        const useNative = options.target
-            ? canUseNativeTimeline(options.target) && !!range
-            : canUseNativeTimeline();
-        return animation.attachTimeline({
-            timeline: useNative ? timeline : undefined,
-            ...(range &&
-                useNative && {
-                rangeStart: range.rangeStart,
-                rangeEnd: range.rangeEnd,
+         * - Otherwise: fall back to JS observe. A ScrollTimeline has no offset,
+         *   so page offsets are applied by the JS timeline.
+         */
+        const native = canUseNativeTimeline(target) && (target ? !!range : !options.offset);
+        const animations = new Map();
+        const observed = new Set();
+        let stopObserving;
+        let reverse = false;
+        /**
+         * When an offset's second point comes first, its range is swapped and
+         * the animation played backwards. The range is set after the direction,
+         * as that's what realigns a running animation with its timeline. Chrome
+         * skips that realignment when the range changes in the frame the
+         * animation starts, leaving it offset for good, so it's replayed too.
+         */
+        const apply = (direction, waapi) => {
+            const [start, end] = range.points;
+            waapi.effect.updateTiming({
+                direction: reverse
+                    ? direction === "normal"
+                        ? "reverse"
+                        : "alternate-reverse"
+                    : direction,
+            });
+            Object.assign(waapi, {
+                rangeStart: reverse ? end : start,
+                rangeEnd: reverse ? start : end,
+            });
+            waapi.play();
+        };
+        const stops = [
+            animation.attachTimeline({
+                /**
+                 * Read only by WAAPI animations, so values driven from JS don't
+                 * create a native timeline they won't use.
+                 */
+                get timeline() {
+                    return native ? getTimeline(options) : undefined;
+                },
+                onAttach: range &&
+                    ((waapi) => {
+                        const direction = waapi.effect.getTiming().direction;
+                        animations.set(waapi, direction);
+                        apply(direction, waapi);
+                    }),
+                /**
+                 * Values driven from JS all track the offset with scrollInfo,
+                 * which measures once per frame for all of them.
+                 */
+                observe: (valueAnimation) => {
+                    valueAnimation.pause();
+                    observed.add(valueAnimation);
+                    stopObserving || (stopObserving = scrollInfo((info) => {
+                        observed.forEach((observedAnimation) => {
+                            observedAnimation.time =
+                                observedAnimation.iterationDuration *
+                                    info[axis].progress;
+                        });
+                    }, options));
+                    return () => observed.delete(valueAnimation);
+                },
             }),
-            observe: (valueAnimation) => {
-                valueAnimation.pause();
-                return observeTimeline((progress) => {
-                    valueAnimation.time =
-                        valueAnimation.iterationDuration * progress;
-                }, timeline);
-            },
-        });
+        ];
+        if (native && range) {
+            const { a, b } = range;
+            const length = axis === "y" ? "clientHeight" : "clientWidth";
+            /**
+             * Offsets like All only run forwards when the target is longer than
+             * the container, so their direction is remeasured on resize.
+             */
+            const update = () => {
+                if (reverse !==
+                    (reverse = a * target[length] + b * container[length] < 0)) {
+                    animations.forEach(apply);
+                }
+            };
+            update();
+            if (a * b < 0) {
+                stops.push(resize(update), resize([target, container], update));
+            }
+        }
+        return () => {
+            stops.forEach((stop) => stop());
+            stopObserving?.();
+        };
     }
 
     function scroll(onScroll, { axis = "y", source, container = document.scrollingElement, ...options } = {}) {
@@ -13415,7 +13469,6 @@
     exports.noop = noop;
     exports.number = number;
     exports.numberValueTypes = numberValueTypes;
-    exports.observeTimeline = observeTimeline;
     exports.optimizedAppearDataAttribute = optimizedAppearDataAttribute;
     exports.optimizedAppearDataId = optimizedAppearDataId;
     exports.parseAnimateLayoutArgs = parseAnimateLayoutArgs;