motion 12.39.0 → 12.40.0

package/dist/motion.dev.js

@@ -2161,8 +2161,15 @@
     ];
     /**
      * A quick lookup for transform props.
+     *
+     * `pathRotation` is a transform for routing purposes (skipped from raw
+     * style application, wired to the transform composite, flags transform
+     * dirty) but is intentionally NOT in `transformPropOrder` — it is
+     * composed onto `rotate` at the build sites, not serialized in its own
+     * slot, and must stay out of the order-array consumers (parse-transform,
+     * unit-conversion, keys-position).
      */
-    const transformProps = /*@__PURE__*/ (() => new Set(transformPropOrder))();
+    const transformProps = /*@__PURE__*/ (() => new Set([...transformPropOrder, "pathRotation"]))();
 
     const isNumOrPxType = (v) => v === number || v === px;
     const transformKeys = new Set(["x", "y", "z"]);
@@ -3175,271 +3182,6 @@
                 : maxStaggerDuration - index * staggerChildren;
     }
 
-    /**
-     * Parse Framer's special CSS variable format into a CSS token and a fallback.
-     *
-     * ```
-     * `var(--foo, #fff)` => [`--foo`, '#fff']
-     * ```
-     *
-     * @param current
-     */
-    const splitCSSVariableRegex = 
-    // eslint-disable-next-line redos-detector/no-unsafe-regex -- false positive, as it can match a lot of words
-    /^var\(--(?:([\w-]+)|([\w-]+), ?([a-zA-Z\d ()%#.,-]+))\)/u;
-    function parseCSSVariable(current) {
-        const match = splitCSSVariableRegex.exec(current);
-        if (!match)
-            return [,];
-        const [, token1, token2, fallback] = match;
-        return [`--${token1 ?? token2}`, fallback];
-    }
-    const maxDepth = 4;
-    function getVariableValue(current, element, depth = 1) {
-        exports.invariant(depth <= maxDepth, `Max CSS variable fallback depth detected in property "${current}". This may indicate a circular fallback dependency.`, "max-css-var-depth");
-        const [token, fallback] = parseCSSVariable(current);
-        // No CSS variable detected
-        if (!token)
-            return;
-        // Attempt to read this CSS variable off the element
-        const resolved = window.getComputedStyle(element).getPropertyValue(token);
-        if (resolved) {
-            const trimmed = resolved.trim();
-            return isNumericalString(trimmed) ? parseFloat(trimmed) : trimmed;
-        }
-        return isCSSVariableToken(fallback)
-            ? getVariableValue(fallback, element, depth + 1)
-            : fallback;
-    }
-
-    const underDampedSpring = {
-        type: "spring",
-        stiffness: 500,
-        damping: 25,
-        restSpeed: 10,
-    };
-    const criticallyDampedSpring = (target) => ({
-        type: "spring",
-        stiffness: 550,
-        damping: target === 0 ? 2 * Math.sqrt(550) : 30,
-        restSpeed: 10,
-    });
-    const keyframesTransition = {
-        type: "keyframes",
-        duration: 0.8,
-    };
-    /**
-     * Default easing curve is a slightly shallower version of
-     * the default browser easing curve.
-     */
-    const ease = {
-        type: "keyframes",
-        ease: [0.25, 0.1, 0.35, 1],
-        duration: 0.3,
-    };
-    const getDefaultTransition = (valueKey, { keyframes }) => {
-        if (keyframes.length > 2) {
-            return keyframesTransition;
-        }
-        else if (transformProps.has(valueKey)) {
-            return valueKey.startsWith("scale")
-                ? criticallyDampedSpring(keyframes[1])
-                : underDampedSpring;
-        }
-        return ease;
-    };
-
-    /**
-     * If `transition` has `inherit: true`, shallow-merge it with
-     * `parentTransition` (child keys win) and strip the `inherit` key.
-     * Otherwise return `transition` unchanged.
-     */
-    function resolveTransition(transition, parentTransition) {
-        if (transition?.inherit && parentTransition) {
-            const { inherit: _, ...rest } = transition;
-            return { ...parentTransition, ...rest };
-        }
-        return transition;
-    }
-
-    function getValueTransition$1(transition, key) {
-        const valueTransition = transition?.[key] ??
-            transition?.["default"] ??
-            transition;
-        if (valueTransition !== transition) {
-            return resolveTransition(valueTransition, transition);
-        }
-        return valueTransition;
-    }
-
-    const orchestrationKeys = new Set([
-        "when",
-        "delay",
-        "delayChildren",
-        "staggerChildren",
-        "staggerDirection",
-        "repeat",
-        "repeatType",
-        "repeatDelay",
-        "from",
-        "elapsed",
-    ]);
-    /**
-     * Decide whether a transition is defined on a given Transition.
-     * This filters out orchestration options and returns true
-     * if any options are left.
-     */
-    function isTransitionDefined(transition) {
-        for (const key in transition) {
-            if (!orchestrationKeys.has(key))
-                return true;
-        }
-        return false;
-    }
-
-    const animateMotionValue = (name, value, target, transition = {}, element, isHandoff) => (onComplete) => {
-        const valueTransition = getValueTransition$1(transition, name) || {};
-        /**
-         * Most transition values are currently completely overwritten by value-specific
-         * transitions. In the future it'd be nicer to blend these transitions. But for now
-         * delay actually does inherit from the root transition if not value-specific.
-         */
-        const delay = valueTransition.delay || transition.delay || 0;
-        /**
-         * Elapsed isn't a public transition option but can be passed through from
-         * optimized appear effects in milliseconds.
-         */
-        let { elapsed = 0 } = transition;
-        elapsed = elapsed - secondsToMilliseconds(delay);
-        const options = {
-            keyframes: Array.isArray(target) ? target : [null, target],
-            ease: "easeOut",
-            velocity: value.getVelocity(),
-            ...valueTransition,
-            delay: -elapsed,
-            onUpdate: (v) => {
-                value.set(v);
-                valueTransition.onUpdate && valueTransition.onUpdate(v);
-            },
-            onComplete: () => {
-                onComplete();
-                valueTransition.onComplete && valueTransition.onComplete();
-            },
-            name,
-            motionValue: value,
-            element: isHandoff ? undefined : element,
-        };
-        /**
-         * If there's no transition defined for this value, we can generate
-         * unique transition settings for this value.
-         */
-        if (!isTransitionDefined(valueTransition)) {
-            Object.assign(options, getDefaultTransition(name, options));
-        }
-        /**
-         * Both WAAPI and our internal animation functions use durations
-         * as defined by milliseconds, while our external API defines them
-         * as seconds.
-         */
-        options.duration && (options.duration = secondsToMilliseconds(options.duration));
-        options.repeatDelay && (options.repeatDelay = secondsToMilliseconds(options.repeatDelay));
-        /**
-         * Support deprecated way to set initial value. Prefer keyframe syntax.
-         */
-        if (options.from !== undefined) {
-            options.keyframes[0] = options.from;
-        }
-        let shouldSkip = false;
-        if (options.type === false ||
-            (options.duration === 0 && !options.repeatDelay)) {
-            makeAnimationInstant(options);
-            if (options.delay === 0) {
-                shouldSkip = true;
-            }
-        }
-        if (MotionGlobalConfig.instantAnimations ||
-            MotionGlobalConfig.skipAnimations ||
-            element?.shouldSkipAnimations ||
-            valueTransition.skipAnimations) {
-            shouldSkip = true;
-            makeAnimationInstant(options);
-            options.delay = 0;
-        }
-        /**
-         * If the transition type or easing has been explicitly set by the user
-         * then we don't want to allow flattening the animation.
-         */
-        options.allowFlatten = !valueTransition.type && !valueTransition.ease;
-        /**
-         * If we can or must skip creating the animation, and apply only
-         * the final keyframe, do so. We also check once keyframes are resolved but
-         * this early check prevents the need to create an animation at all.
-         */
-        if (shouldSkip && !isHandoff && value.get() !== undefined) {
-            const finalKeyframe = getFinalKeyframe(options.keyframes, valueTransition);
-            if (finalKeyframe !== undefined) {
-                frame.update(() => {
-                    options.onUpdate(finalKeyframe);
-                    options.onComplete();
-                });
-                return;
-            }
-        }
-        return valueTransition.isSync
-            ? new JSAnimation(options)
-            : new AsyncMotionValueAnimation(options);
-    };
-
-    function getValueState(visualElement) {
-        const state = [{}, {}];
-        visualElement?.values.forEach((value, key) => {
-            state[0][key] = value.get();
-            state[1][key] = value.getVelocity();
-        });
-        return state;
-    }
-    function resolveVariantFromProps(props, definition, custom, visualElement) {
-        /**
-         * If the variant definition is a function, resolve.
-         */
-        if (typeof definition === "function") {
-            const [current, velocity] = getValueState(visualElement);
-            definition = definition(custom !== undefined ? custom : props.custom, current, velocity);
-        }
-        /**
-         * If the variant definition is a variant label, or
-         * the function returned a variant label, resolve.
-         */
-        if (typeof definition === "string") {
-            definition = props.variants && props.variants[definition];
-        }
-        /**
-         * At this point we've resolved both functions and variant labels,
-         * but the resolved variant label might itself have been a function.
-         * If so, resolve. This can only have returned a valid target object.
-         */
-        if (typeof definition === "function") {
-            const [current, velocity] = getValueState(visualElement);
-            definition = definition(custom !== undefined ? custom : props.custom, current, velocity);
-        }
-        return definition;
-    }
-
-    function resolveVariant(visualElement, definition, custom) {
-        const props = visualElement.getProps();
-        return resolveVariantFromProps(props, definition, custom !== undefined ? custom : props.custom, visualElement);
-    }
-
-    const positionalKeys = new Set([
-        "width",
-        "height",
-        "top",
-        "left",
-        "right",
-        "bottom",
-        ...transformPropOrder,
-    ]);
-
     /**
      * Maximum time between the value of two frames, beyond which we
      * assume the velocity has since been 0.
@@ -3648,116 +3390,562 @@
             }
         }
         /**
-         * Returns the latest state of `MotionValue`
-         *
-         * @returns - The latest state of `MotionValue`
-         *
-         * @public
+         * Returns the latest state of `MotionValue`
+         *
+         * @returns - The latest state of `MotionValue`
+         *
+         * @public
+         */
+        get() {
+            if (collectMotionValues.current) {
+                collectMotionValues.current.push(this);
+            }
+            return this.current;
+        }
+        /**
+         * @public
+         */
+        getPrevious() {
+            return this.prev;
+        }
+        /**
+         * Returns the latest velocity of `MotionValue`
+         *
+         * @returns - The latest velocity of `MotionValue`. Returns `0` if the state is non-numerical.
+         *
+         * @public
+         */
+        getVelocity() {
+            const currentTime = time.now();
+            if (!this.canTrackVelocity ||
+                this.prevFrameValue === undefined ||
+                currentTime - this.updatedAt > MAX_VELOCITY_DELTA) {
+                return 0;
+            }
+            const delta = Math.min(this.updatedAt - this.prevUpdatedAt, MAX_VELOCITY_DELTA);
+            // Casts because of parseFloat's poor typing
+            return velocityPerSecond(parseFloat(this.current) -
+                parseFloat(this.prevFrameValue), delta);
+        }
+        /**
+         * Registers a new animation to control this `MotionValue`. Only one
+         * animation can drive a `MotionValue` at one time.
+         *
+         * ```jsx
+         * value.start()
+         * ```
+         *
+         * @param animation - A function that starts the provided animation
+         */
+        start(startAnimation) {
+            this.stop();
+            return new Promise((resolve) => {
+                this.hasAnimated = true;
+                this.animation = startAnimation(resolve);
+                if (this.events.animationStart) {
+                    this.events.animationStart.notify();
+                }
+            }).then(() => {
+                if (this.events.animationComplete) {
+                    this.events.animationComplete.notify();
+                }
+                this.clearAnimation();
+            });
+        }
+        /**
+         * Stop the currently active animation.
+         *
+         * @public
+         */
+        stop() {
+            if (this.animation) {
+                this.animation.stop();
+                if (this.events.animationCancel) {
+                    this.events.animationCancel.notify();
+                }
+            }
+            this.clearAnimation();
+        }
+        /**
+         * Returns `true` if this value is currently animating.
+         *
+         * @public
+         */
+        isAnimating() {
+            return !!this.animation;
+        }
+        clearAnimation() {
+            delete this.animation;
+        }
+        /**
+         * Destroy and clean up subscribers to this `MotionValue`.
+         *
+         * The `MotionValue` hooks like `useMotionValue` and `useTransform` automatically
+         * handle the lifecycle of the returned `MotionValue`, so this method is only necessary if you've manually
+         * created a `MotionValue` via the `motionValue` function.
+         *
+         * @public
+         */
+        destroy() {
+            this.dependents?.clear();
+            this.events.destroy?.notify();
+            this.clearListeners();
+            this.stop();
+            if (this.stopPassiveEffect) {
+                this.stopPassiveEffect();
+            }
+        }
+    }
+    function motionValue(init, options) {
+        return new MotionValue(init, options);
+    }
+
+    /**
+     * If `transition` has `inherit: true`, shallow-merge it with
+     * `parentTransition` (child keys win) and strip the `inherit` key.
+     * Otherwise return `transition` unchanged.
+     */
+    function resolveTransition(transition, parentTransition) {
+        if (transition?.inherit && parentTransition) {
+            const { inherit: _, ...rest } = transition;
+            return { ...parentTransition, ...rest };
+        }
+        return transition;
+    }
+
+    function getValueTransition$1(transition, key) {
+        const valueTransition = transition?.[key] ??
+            transition?.["default"] ??
+            transition;
+        if (valueTransition !== transition) {
+            return resolveTransition(valueTransition, transition);
+        }
+        return valueTransition;
+    }
+
+    const underDampedSpring = {
+        type: "spring",
+        stiffness: 500,
+        damping: 25,
+        restSpeed: 10,
+    };
+    const criticallyDampedSpring = (target) => ({
+        type: "spring",
+        stiffness: 550,
+        damping: target === 0 ? 2 * Math.sqrt(550) : 30,
+        restSpeed: 10,
+    });
+    const keyframesTransition = {
+        type: "keyframes",
+        duration: 0.8,
+    };
+    /**
+     * Default easing curve is a slightly shallower version of
+     * the default browser easing curve.
+     */
+    const ease = {
+        type: "keyframes",
+        ease: [0.25, 0.1, 0.35, 1],
+        duration: 0.3,
+    };
+    const getDefaultTransition = (valueKey, { keyframes }) => {
+        if (keyframes.length > 2) {
+            return keyframesTransition;
+        }
+        else if (transformProps.has(valueKey)) {
+            return valueKey.startsWith("scale")
+                ? criticallyDampedSpring(keyframes[1])
+                : underDampedSpring;
+        }
+        return ease;
+    };
+
+    const orchestrationKeys = new Set([
+        "when",
+        "delay",
+        "delayChildren",
+        "staggerChildren",
+        "staggerDirection",
+        "repeat",
+        "repeatType",
+        "repeatDelay",
+        "from",
+        "elapsed",
+    ]);
+    /**
+     * Decide whether a transition is defined on a given Transition.
+     * This filters out orchestration options and returns true
+     * if any options are left.
+     */
+    function isTransitionDefined(transition) {
+        for (const key in transition) {
+            if (!orchestrationKeys.has(key))
+                return true;
+        }
+        return false;
+    }
+
+    const animateMotionValue = (name, value, target, transition = {}, element, isHandoff) => (onComplete) => {
+        const valueTransition = getValueTransition$1(transition, name) || {};
+        /**
+         * Most transition values are currently completely overwritten by value-specific
+         * transitions. In the future it'd be nicer to blend these transitions. But for now
+         * delay actually does inherit from the root transition if not value-specific.
+         */
+        const delay = valueTransition.delay || transition.delay || 0;
+        /**
+         * Elapsed isn't a public transition option but can be passed through from
+         * optimized appear effects in milliseconds.
+         */
+        let { elapsed = 0 } = transition;
+        elapsed = elapsed - secondsToMilliseconds(delay);
+        const options = {
+            keyframes: Array.isArray(target) ? target : [null, target],
+            ease: "easeOut",
+            velocity: value.getVelocity(),
+            ...valueTransition,
+            delay: -elapsed,
+            onUpdate: (v) => {
+                value.set(v);
+                valueTransition.onUpdate && valueTransition.onUpdate(v);
+            },
+            onComplete: () => {
+                onComplete();
+                valueTransition.onComplete && valueTransition.onComplete();
+            },
+            name,
+            motionValue: value,
+            element: isHandoff ? undefined : element,
+        };
+        /**
+         * If there's no transition defined for this value, we can generate
+         * unique transition settings for this value.
          */
-        get() {
-            if (collectMotionValues.current) {
-                collectMotionValues.current.push(this);
-            }
-            return this.current;
+        if (!isTransitionDefined(valueTransition)) {
+            Object.assign(options, getDefaultTransition(name, options));
         }
         /**
-         * @public
+         * Both WAAPI and our internal animation functions use durations
+         * as defined by milliseconds, while our external API defines them
+         * as seconds.
          */
-        getPrevious() {
-            return this.prev;
-        }
+        options.duration && (options.duration = secondsToMilliseconds(options.duration));
+        options.repeatDelay && (options.repeatDelay = secondsToMilliseconds(options.repeatDelay));
         /**
-         * Returns the latest velocity of `MotionValue`
-         *
-         * @returns - The latest velocity of `MotionValue`. Returns `0` if the state is non-numerical.
-         *
-         * @public
+         * Support deprecated way to set initial value. Prefer keyframe syntax.
          */
-        getVelocity() {
-            const currentTime = time.now();
-            if (!this.canTrackVelocity ||
-                this.prevFrameValue === undefined ||
-                currentTime - this.updatedAt > MAX_VELOCITY_DELTA) {
-                return 0;
+        if (options.from !== undefined) {
+            options.keyframes[0] = options.from;
+        }
+        let shouldSkip = false;
+        if (options.type === false ||
+            (options.duration === 0 && !options.repeatDelay)) {
+            makeAnimationInstant(options);
+            if (options.delay === 0) {
+                shouldSkip = true;
             }
-            const delta = Math.min(this.updatedAt - this.prevUpdatedAt, MAX_VELOCITY_DELTA);
-            // Casts because of parseFloat's poor typing
-            return velocityPerSecond(parseFloat(this.current) -
-                parseFloat(this.prevFrameValue), delta);
+        }
+        if (MotionGlobalConfig.instantAnimations ||
+            MotionGlobalConfig.skipAnimations ||
+            element?.shouldSkipAnimations ||
+            valueTransition.skipAnimations) {
+            shouldSkip = true;
+            makeAnimationInstant(options);
+            options.delay = 0;
         }
         /**
-         * Registers a new animation to control this `MotionValue`. Only one
-         * animation can drive a `MotionValue` at one time.
-         *
-         * ```jsx
-         * value.start()
-         * ```
-         *
-         * @param animation - A function that starts the provided animation
+         * If the transition type or easing has been explicitly set by the user
+         * then we don't want to allow flattening the animation.
          */
-        start(startAnimation) {
-            this.stop();
-            return new Promise((resolve) => {
-                this.hasAnimated = true;
-                this.animation = startAnimation(resolve);
-                if (this.events.animationStart) {
-                    this.events.animationStart.notify();
+        options.allowFlatten = !valueTransition.type && !valueTransition.ease;
+        /**
+         * If we can or must skip creating the animation, and apply only
+         * the final keyframe, do so. We also check once keyframes are resolved but
+         * this early check prevents the need to create an animation at all.
+         */
+        if (shouldSkip && !isHandoff && value.get() !== undefined) {
+            const finalKeyframe = getFinalKeyframe(options.keyframes, valueTransition);
+            if (finalKeyframe !== undefined) {
+                frame.update(() => {
+                    options.onUpdate(finalKeyframe);
+                    options.onComplete();
+                });
+                return;
+            }
+        }
+        return valueTransition.isSync
+            ? new JSAnimation(options)
+            : new AsyncMotionValueAnimation(options);
+    };
+
+    const MIN_LAYOUT_DISTANCE = 20;
+    function bezierPoint(t, origin, control, target) {
+        const inv = 1 - t;
+        return inv * inv * origin + 2 * inv * t * control + t * t * target;
+    }
+    function bezierTangentAngle(t, originX, controlX, targetX, originY, controlY, targetY) {
+        const dx = 2 * (1 - t) * (controlX - originX) + 2 * t * (targetX - controlX);
+        const dy = 2 * (1 - t) * (controlY - originY) + 2 * t * (targetY - controlY);
+        return Math.atan2(dy, dx) * (180 / Math.PI);
+    }
+    function computeArcControlPoint(fromX, fromY, toX, toY, strength, peak) {
+        const deltaX = toX - fromX;
+        const deltaY = toY - fromY;
+        const distance = Math.sqrt(deltaX * deltaX + deltaY * deltaY);
+        if (distance > 0) {
+            const normalPerpX = -deltaY / distance;
+            const normalPerpY = deltaX / distance;
+            const desiredHeight = strength * distance;
+            return {
+                x: fromX + deltaX * peak + normalPerpX * desiredHeight,
+                y: fromY + deltaY * peak + normalPerpY * desiredHeight,
+            };
+        }
+        return { x: fromX, y: fromY };
+    }
+    /**
+     * The pure sampling factory: `(from, to) => (t) => point`. Internal —
+     * used by {@link arc} and the unit tests. Not part of the public surface.
+     */
+    function createArcPath({ strength = 0.5, peak = 0.5, direction, rotate = false, } = {}) {
+        const rotationScale = rotate === true ? 1 : typeof rotate === "number" ? rotate : 0;
+        // Auto-direction only: persists across calls to flip the bulge back
+        // onto the same screen side when the dominant axis changes between
+        // calls. Reuse the factory (module scope / useMemo) to keep this alive.
+        let prevBulgeSign;
+        const createInterpolator = (from, to) => {
+            const dx = to.x - from.x;
+            const dy = to.y - from.y;
+            let signed;
+            if (direction === "cw") {
+                signed = -strength;
+            }
+            else if (direction === "ccw") {
+                signed = strength;
+            }
+            else {
+                const dom = Math.abs(dx) >= Math.abs(dy) ? dx : dy;
+                signed = dom < 0 ? -strength : strength;
+            }
+            let control = computeArcControlPoint(from.x, from.y, to.x, to.y, signed, peak);
+            if (direction === undefined) {
+                const isVertical = Math.abs(dx) < Math.abs(dy);
+                const midX = from.x + dx * peak;
+                const midY = from.y + dy * peak;
+                const bulgeSign = isVertical
+                    ? Math.sign(control.x - midX)
+                    : Math.sign(control.y - midY);
+                if (prevBulgeSign !== undefined &&
+                    bulgeSign !== 0 &&
+                    bulgeSign !== prevBulgeSign) {
+                    signed = -signed;
+                    control = computeArcControlPoint(from.x, from.y, to.x, to.y, signed, peak);
+                }
+                else if (bulgeSign !== 0) {
+                    prevBulgeSign = bulgeSign;
+                }
+            }
+            const tangent0 = rotationScale
+                ? bezierTangentAngle(0, from.x, control.x, to.x, from.y, control.y, to.y)
+                : 0;
+            const tangent1 = rotationScale
+                ? bezierTangentAngle(1, from.x, control.x, to.x, from.y, control.y, to.y)
+                : 0;
+            const tangentDelta = rotationScale
+                ? wrap(-180, 180, tangent1 - tangent0)
+                : 0;
+            return (t) => {
+                const out = {
+                    x: bezierPoint(t, from.x, control.x, to.x),
+                    y: bezierPoint(t, from.y, control.y, to.y),
+                };
+                if (rotationScale) {
+                    const raw = bezierTangentAngle(t, from.x, control.x, to.x, from.y, control.y, to.y);
+                    const baseline = tangent0 + tangentDelta * t;
+                    out.rotate = wrap(-180, 180, raw - baseline) * rotationScale;
                 }
-            }).then(() => {
-                if (this.events.animationComplete) {
-                    this.events.animationComplete.notify();
+                return out;
+            };
+        };
+        return createInterpolator;
+    }
+    /**
+     * Creates a curved path for `transition.path`:
+     *
+     * ```ts
+     * <motion.div animate={{ x: 200, y: 100 }} transition={{ path: arc() }} />
+     * ```
+     *
+     * Reuse the returned value (module scope / useMemo / useRef) so its
+     * continuity closure survives re-renders — a fresh `arc()` has no memory.
+     */
+    function arc(options = {}) {
+        const sample = createArcPath(options);
+        const path = {
+            interpolateProjection(delta) {
+                // `from` is the current translate offset (carries any in-flight
+                // displacement when interrupted); `to` is the new layout origin.
+                // The distance floor avoids visible wobble on tiny shifts.
+                const tx = delta.x.translate;
+                const ty = delta.y.translate;
+                if (Math.sqrt(tx * tx + ty * ty) < MIN_LAYOUT_DISTANCE) {
+                    return undefined;
                 }
-                this.clearAnimation();
-            });
+                return sample({ x: tx, y: ty }, { x: 0, y: 0 });
+            },
+            animateVisualElement(visualElement, target, transition, delay, animations) {
+                if (!("x" in target || "y" in target))
+                    return;
+                const xValue = visualElement.getValue("x", visualElement.latestValues["x"] ?? 0);
+                const yValue = visualElement.getValue("y", visualElement.latestValues["y"] ?? 0);
+                const xRaw = target.x;
+                const yRaw = target.y;
+                const xFrom = (Array.isArray(xRaw) && xRaw[0] != null
+                    ? xRaw[0]
+                    : xValue?.get()) ?? 0;
+                const yFrom = (Array.isArray(yRaw) && yRaw[0] != null
+                    ? yRaw[0]
+                    : yValue?.get()) ?? 0;
+                const xTo = (Array.isArray(xRaw)
+                    ? xRaw[xRaw.length - 1]
+                    : xRaw ?? xFrom);
+                const yTo = (Array.isArray(yRaw)
+                    ? yRaw[yRaw.length - 1]
+                    : yRaw ?? yFrom);
+                // Interruption needs no flag: x/y already hold the displaced
+                // mid-arc position, so xFrom/yFrom carry the continuity geometry.
+                const interpolate = sample({ x: xFrom, y: yFrom }, { x: xTo, y: yTo });
+                // Drive a dedicated `pathRotation` value (composed onto `rotate`
+                // at the build sites) rather than `rotate` itself, so a
+                // concurrent rotate animation composes and nothing accumulates
+                // on interrupt.
+                const pathRotationValue = interpolate(0).rotate !== undefined
+                    ? visualElement.getValue("pathRotation", 0)
+                    : undefined;
+                const pathTransition = {
+                    delay,
+                    ...getValueTransition$1(transition || {}, "x"),
+                };
+                delete pathTransition.path;
+                const progress = motionValue(0);
+                progress.start(animateMotionValue("", progress, [0, 1000], {
+                    ...pathTransition,
+                    isSync: true,
+                    velocity: 0,
+                    onUpdate: (latest) => {
+                        const point = interpolate(latest / 1000);
+                        xValue?.set(point.x);
+                        yValue?.set(point.y);
+                        if (pathRotationValue && point.rotate !== undefined) {
+                            pathRotationValue.set(point.rotate);
+                        }
+                    },
+                    onComplete: () => {
+                        xValue?.set(xTo);
+                        yValue?.set(yTo);
+                        pathRotationValue?.set(0);
+                    },
+                    // Interrupt/cancel must clear our additive contribution
+                    // so it can't linger on top of the user's `rotate`.
+                    onStop: () => pathRotationValue?.set(0),
+                    onCancel: () => pathRotationValue?.set(0),
+                }));
+                if (progress.animation)
+                    animations.push(progress.animation);
+                delete target.x;
+                delete target.y;
+            },
+        };
+        return path;
+    }
+
+    /**
+     * Parse Framer's special CSS variable format into a CSS token and a fallback.
+     *
+     * ```
+     * `var(--foo, #fff)` => [`--foo`, '#fff']
+     * ```
+     *
+     * @param current
+     */
+    const splitCSSVariableRegex = 
+    // eslint-disable-next-line redos-detector/no-unsafe-regex -- false positive, as it can match a lot of words
+    /^var\(--(?:([\w-]+)|([\w-]+), ?([a-zA-Z\d ()%#.,-]+))\)/u;
+    function parseCSSVariable(current) {
+        const match = splitCSSVariableRegex.exec(current);
+        if (!match)
+            return [,];
+        const [, token1, token2, fallback] = match;
+        return [`--${token1 ?? token2}`, fallback];
+    }
+    const maxDepth = 4;
+    function getVariableValue(current, element, depth = 1) {
+        exports.invariant(depth <= maxDepth, `Max CSS variable fallback depth detected in property "${current}". This may indicate a circular fallback dependency.`, "max-css-var-depth");
+        const [token, fallback] = parseCSSVariable(current);
+        // No CSS variable detected
+        if (!token)
+            return;
+        // Attempt to read this CSS variable off the element
+        const resolved = window.getComputedStyle(element).getPropertyValue(token);
+        if (resolved) {
+            const trimmed = resolved.trim();
+            return isNumericalString(trimmed) ? parseFloat(trimmed) : trimmed;
         }
+        return isCSSVariableToken(fallback)
+            ? getVariableValue(fallback, element, depth + 1)
+            : fallback;
+    }
+
+    function getValueState(visualElement) {
+        const state = [{}, {}];
+        visualElement?.values.forEach((value, key) => {
+            state[0][key] = value.get();
+            state[1][key] = value.getVelocity();
+        });
+        return state;
+    }
+    function resolveVariantFromProps(props, definition, custom, visualElement) {
         /**
-         * Stop the currently active animation.
-         *
-         * @public
+         * If the variant definition is a function, resolve.
          */
-        stop() {
-            if (this.animation) {
-                this.animation.stop();
-                if (this.events.animationCancel) {
-                    this.events.animationCancel.notify();
-                }
-            }
-            this.clearAnimation();
+        if (typeof definition === "function") {
+            const [current, velocity] = getValueState(visualElement);
+            definition = definition(custom !== undefined ? custom : props.custom, current, velocity);
         }
         /**
-         * Returns `true` if this value is currently animating.
-         *
-         * @public
+         * If the variant definition is a variant label, or
+         * the function returned a variant label, resolve.
          */
-        isAnimating() {
-            return !!this.animation;
-        }
-        clearAnimation() {
-            delete this.animation;
+        if (typeof definition === "string") {
+            definition = props.variants && props.variants[definition];
         }
         /**
-         * Destroy and clean up subscribers to this `MotionValue`.
-         *
-         * The `MotionValue` hooks like `useMotionValue` and `useTransform` automatically
-         * handle the lifecycle of the returned `MotionValue`, so this method is only necessary if you've manually
-         * created a `MotionValue` via the `motionValue` function.
-         *
-         * @public
+         * At this point we've resolved both functions and variant labels,
+         * but the resolved variant label might itself have been a function.
+         * If so, resolve. This can only have returned a valid target object.
          */
-        destroy() {
-            this.dependents?.clear();
-            this.events.destroy?.notify();
-            this.clearListeners();
-            this.stop();
-            if (this.stopPassiveEffect) {
-                this.stopPassiveEffect();
-            }
+        if (typeof definition === "function") {
+            const [current, velocity] = getValueState(visualElement);
+            definition = definition(custom !== undefined ? custom : props.custom, current, velocity);
         }
+        return definition;
     }
-    function motionValue(init, options) {
-        return new MotionValue(init, options);
+
+    function resolveVariant(visualElement, definition, custom) {
+        const props = visualElement.getProps();
+        return resolveVariantFromProps(props, definition, custom !== undefined ? custom : props.custom, visualElement);
     }
 
+    const positionalKeys = new Set([
+        "width",
+        "height",
+        "top",
+        "left",
+        "right",
+        "bottom",
+        ...transformPropOrder,
+    ]);
+
     const isKeyframesTarget = (v) => {
         return Array.isArray(v);
     };
@@ -3846,6 +4034,11 @@
         const animationTypeState = type &&
             visualElement.animationState &&
             visualElement.animationState.getState()[type];
+        const path = transition?.path;
+        if (path) {
+            // path mutates `target` to claim x/y; loop below skips them.
+            path.animateVisualElement(visualElement, target, transition, delay, animations);
+        }
         for (const key in target) {
             const value = visualElement.getValue(key, visualElement.latestValues[key] ?? null);
             const valueTarget = target[key];
@@ -4064,6 +4257,12 @@
 
     const transformValueTypes = {
         rotate: degrees,
+        /**
+         * Internal channel for `transition.path` orientToPath. Composed onto
+         * `rotate` at the transform-build sites so the user's `rotate` is
+         * never read or overwritten. Not part of `transformPropOrder`.
+         */
+        pathRotation: degrees,
         rotateX: degrees,
         rotateY: degrees,
         rotateZ: degrees,
@@ -4615,6 +4814,15 @@
                 transform += `${transformName}(${value}) `;
             }
         }
+        // See build-transform.ts: additive `rotate()` so user `rotate` isn't
+        // clobbered. Not a `transformPropOrder` slot.
+        const pathRotation = state.latest.pathRotation;
+        if (pathRotation) {
+            transformIsDefault = false;
+            transform += `rotate(${typeof pathRotation === "number"
+            ? `${pathRotation}deg`
+            : pathRotation}) `;
+        }
         return transformIsDefault ? "none" : transform.trim();
     }
 
@@ -6767,6 +6975,14 @@
                 }
             }
         }
+        // `pathRotation` composes onto `rotate` as a separate additive term so
+        // the user's `rotate` is never clobbered. Deliberately not a slot in
+        // `transformPropOrder`.
+        const pathRotation = latestValues.pathRotation;
+        if (pathRotation) {
+            transformIsDefault = false;
+            transformString += `rotate(${getValueAsType(pathRotation, numberValueTypes.pathRotation)}) `;
+        }
         transformString = transformString.trim();
         // If we have a custom `transform` template, pass our transform values and
         // generated transformString to that before returning
@@ -7829,11 +8045,14 @@
             transform += `scale(${1 / treeScale.x}, ${1 / treeScale.y}) `;
         }
         if (latestTransform) {
-            const { transformPerspective, rotate, rotateX, rotateY, skewX, skewY } = latestTransform;
+            const { transformPerspective, rotate, pathRotation, rotateX, rotateY, skewX, skewY, } = latestTransform;
             if (transformPerspective)
                 transform = `perspective(${transformPerspective}px) ${transform}`;
             if (rotate)
                 transform += `rotate(${rotate}deg) `;
+            // Additive `rotate()` so user `rotate` isn't clobbered.
+            if (pathRotation)
+                transform += `rotate(${pathRotation}deg) `;
             if (rotateX)
                 transform += `rotateX(${rotateX}deg) `;
             if (rotateY)
@@ -8388,7 +8607,8 @@
                              * Set animation origin after starting animation to avoid layout jump
                              * caused by stopping previous layout animation
                              */
-                            this.setAnimationOrigin(delta, hasOnlyRelativeTargetChanged);
+                            this.setAnimationOrigin(delta, hasOnlyRelativeTargetChanged, animationOptions
+                                .path);
                         }
                         else {
                             /**
@@ -9104,7 +9324,7 @@
                 this.projectionDelta = createDelta();
                 this.projectionDeltaWithTransform = createDelta();
             }
-            setAnimationOrigin(delta, hasOnlyRelativeTargetChanged = false) {
+            setAnimationOrigin(delta, hasOnlyRelativeTargetChanged = false, pathFn) {
                 const snapshot = this.snapshot;
                 const snapshotLatestValues = snapshot ? snapshot.latestValues : {};
                 const mixedValues = { ...this.latestValues };
@@ -9126,10 +9346,26 @@
                     !this.path.some(hasOpacityCrossfade));
                 this.animationProgress = 0;
                 let prevRelativeTarget;
+                // The path decides whether the layout shift is worth curving
+                // (distance floor) and resolves the interpolator from the delta.
+                const interpolate = pathFn?.interpolateProjection(delta);
                 this.mixTargetDelta = (latest) => {
                     const progress = latest / 1000;
-                    mixAxisDelta(targetDelta.x, delta.x, progress);
-                    mixAxisDelta(targetDelta.y, delta.y, progress);
+                    const point = interpolate?.(progress);
+                    if (point) {
+                        targetDelta.x.translate = point.x;
+                        targetDelta.x.scale = mixNumber$1(delta.x.scale, 1, progress);
+                        targetDelta.x.origin = delta.x.origin;
+                        targetDelta.x.originPoint = delta.x.originPoint;
+                        targetDelta.y.translate = point.y;
+                        targetDelta.y.scale = mixNumber$1(delta.y.scale, 1, progress);
+                        targetDelta.y.origin = delta.y.origin;
+                        targetDelta.y.originPoint = delta.y.originPoint;
+                    }
+                    else {
+                        mixAxisDeltaLinear(targetDelta.x, delta.x, progress);
+                        mixAxisDeltaLinear(targetDelta.y, delta.y, progress);
+                    }
                     this.setTargetDelta(targetDelta);
                     if (this.relativeTarget &&
                         this.relativeTargetOrigin &&
@@ -9154,6 +9390,13 @@
                         this.animationValues = mixedValues;
                         mixValues(mixedValues, snapshotLatestValues, this.latestValues, progress, shouldCrossfadeOpacity, isOnlyMember);
                     }
+                    if (point && point.rotate !== undefined) {
+                        // Dedicated `pathRotation` channel, not `rotate`, so an
+                        // animating `rotate` is composed with, never clobbered.
+                        if (!this.animationValues)
+                            this.animationValues = mixedValues;
+                        this.animationValues.pathRotation = point.rotate;
+                    }
                     this.root.scheduleUpdateProjection();
                     this.scheduleRender();
                     this.animationProgress = progress;
@@ -9674,7 +9917,7 @@
     function removeLeadSnapshots(stack) {
         stack.removeLeadSnapshot();
     }
-    function mixAxisDelta(output, delta, p) {
+    function mixAxisDeltaLinear(output, delta, p) {
         output.translate = mixNumber$1(delta.translate, 0, p);
         output.scale = mixNumber$1(delta.scale, 1, p);
         output.origin = delta.origin;
@@ -11426,6 +11669,7 @@
     exports.applyPointDelta = applyPointDelta;
     exports.applyPxDefaults = applyPxDefaults;
     exports.applyTreeDeltas = applyTreeDeltas;
+    exports.arc = arc;
     exports.aspectRatio = aspectRatio;
     exports.attachFollow = attachFollow;
     exports.attachSpring = attachSpring;