framer-motion 8.5.0 → 8.5.2-alpha.1

package/dist/cjs/index.js

@@ -90,7 +90,7 @@ function useVisualElement(Component, visualState, props, createVisualElement) {
      * So if we detect a situtation where optimised appear animations
      * are running, we use useLayoutEffect to trigger animations.
      */
-    const useAnimateChangesEffect = window.MotionAppearAnimations
+    const useAnimateChangesEffect = window.HandoffAppearAnimations
         ? useIsomorphicLayoutEffect
         : React.useEffect;
     useAnimateChangesEffect(() => {
@@ -2105,7 +2105,7 @@ class MotionValue {
          * This will be replaced by the build step with the latest version number.
          * When MotionValues are provided to motion components, warn if versions are mixed.
          */
-        this.version = "8.5.0";
+        this.version = "8.5.2-alpha.1";
         /**
          * Duration, in milliseconds, since last updating frame.
          *
@@ -2799,54 +2799,6 @@ function isWillChangeMotionValue(value) {
     return Boolean(isMotionValue(value) && value.add);
 }
 
-const appearStoreId = (id, value) => `${id}: ${value}`;
-
-function handoffOptimizedAppearAnimation(id, name, value) {
-    const { MotionAppearAnimations } = window;
-    const animationId = appearStoreId(id, transformProps.has(name) ? "transform" : name);
-    const animation = MotionAppearAnimations && MotionAppearAnimations.get(animationId);
-    if (animation) {
-        const sampledTime = performance.now();
-        /**
-         * Resync handoff animation with optimised animation.
-         *
-         * This step would be unnecessary if we triggered animateChanges() in useEffect,
-         * but due to potential hydration errors we currently fire them in useLayoutEffect.
-         *
-         * By the time we're safely ready to cancel the optimised WAAPI animation,
-         * the main thread might have been blocked and desynced the two animations.
-         *
-         * Here, we resync the two animations before the optimised WAAPI animation is cancelled.
-         */
-        sync.update(() => {
-            if (value.animation) {
-                value.animation.currentTime = performance.now() - sampledTime;
-            }
-        });
-        /**
-         * We allow the animation to persist until the next frame:
-         *   1. So it continues to play until Framer Motion is ready to render
-         *      (avoiding a potential flash of the element's original state)
-         *   2. As all independent transforms share a single transform animation, stopping
-         *      it synchronously would prevent subsequent transforms from handing off.
-         */
-        sync.render(() => {
-            MotionAppearAnimations.delete(animationId);
-            /**
-             * Animation.cancel() throws so it needs to be wrapped in a try/catch
-             */
-            try {
-                animation.cancel();
-            }
-            catch (e) { }
-        });
-        return animation.currentTime || 0;
-    }
-    else {
-        return 0;
-    }
-}
-
 const optimizedAppearDataId = "framerAppearId";
 const optimizedAppearDataAttribute = "data-" + camelToDash(optimizedAppearDataId);
 
@@ -3384,7 +3336,7 @@ const velocitySampleDuration = 5;
 /**
  * This is based on the spring implementation of Wobble https://github.com/skevy/wobble
  */
-function spring({ keyframes, restSpeed = 2, restDelta = 0.01, ...options }) {
+function spring({ keyframes, restDelta, restSpeed, ...options }) {
     let origin = keyframes[0];
     let target = keyframes[keyframes.length - 1];
     /**
@@ -3400,12 +3352,15 @@ function spring({ keyframes, restSpeed = 2, restDelta = 0.01, ...options }) {
         const initialDelta = target - origin;
         const undampedAngularFreq = Math.sqrt(stiffness / mass) / 1000;
         /**
-         * If we're working within what looks like a 0-1 range, change the default restDelta
-         * to 0.01
+         * If we're working on a granular scale, use smaller defaults for determining
+         * when the spring is finished.
+         *
+         * These defaults have been selected emprically based on what strikes a good
+         * ratio between feeling good and finishing as soon as changes are imperceptible.
          */
-        if (restDelta === undefined) {
-            restDelta = Math.min(Math.abs(target - origin) / 100, 0.4);
-        }
+        const isGranularScale = Math.abs(initialDelta) < 5;
+        restSpeed || (restSpeed = isGranularScale ? 0.01 : 2);
+        restDelta || (restDelta = isGranularScale ? 0.005 : 0.5);
         if (dampingRatio < 1) {
             const angularFreq = calcAngularFreq(undampedAngularFreq, dampingRatio);
             // Underdamped spring
@@ -4245,10 +4200,10 @@ function animateTarget(visualElement, definition, { delay = 0, transitionOverrid
          * If this is the first time a value is being animated, check
          * to see if we're handling off from an existing animation.
          */
-        if (!value.hasAnimated) {
+        if (!value.hasAnimated && window.HandoffAppearAnimations) {
             const appearId = visualElement.getProps()[optimizedAppearDataAttribute];
             if (appearId) {
-                valueTransition.elapsed = handoffOptimizedAppearAnimation(appearId, key, value);
+                valueTransition.elapsed = window.HandoffAppearAnimations(appearId, key, value, sync);
             }
         }
         let animation = value.start(createMotionValueAnimation(key, value, valueTarget, visualElement.shouldReduceMotion && transformProps.has(key)
@@ -5998,7 +5953,7 @@ function updateMotionValuesFromProps(element, next, prev) {
              * and warn against mismatches.
              */
             if (process.env.NODE_ENV === "development") {
-                warnOnce(nextValue.version === "8.5.0", `Attempting to mix Framer Motion versions ${nextValue.version} with 8.5.0 may not work as expected.`);
+                warnOnce(nextValue.version === "8.5.2-alpha.1", `Attempting to mix Framer Motion versions ${nextValue.version} with 8.5.2-alpha.1 may not work as expected.`);
             }
         }
         else if (isMotionValue(prevValue)) {
@@ -9860,14 +9815,99 @@ function useResetProjection() {
     return reset;
 }
 
-function startOptimizedAppearAnimation(element, name, keyframes, options) {
-    window.MotionAppearAnimations || (window.MotionAppearAnimations = new Map());
+const appearStoreId = (id, value) => `${id}: ${value}`;
+
+const appearAnimationStore = new Map();
+
+function handoffOptimizedAppearAnimation(id, name, value, 
+/**
+ * This function is loaded via window by startOptimisedAnimation.
+ * By accepting `sync` as an argument, rather than using it via
+ * import, it can be kept out of the first-load Framer bundle,
+ * while also allowing this function to not be included in
+ * Framer Motion bundles where it's not needed.
+ */
+sync) {
+    const storeId = appearStoreId(id, transformProps.has(name) ? "transform" : name);
+    const { animation, ready } = appearAnimationStore.get(storeId) || {};
+    if (!animation)
+        return 0;
+    const cancelOptimisedAnimation = () => {
+        appearAnimationStore.delete(storeId);
+        /**
+         * Animation.cancel() throws so it needs to be wrapped in a try/catch
+         */
+        try {
+            animation.cancel();
+        }
+        catch (e) { }
+    };
+    if (ready) {
+        const sampledTime = performance.now();
+        /**
+         * Resync handoff animation with optimised animation.
+         *
+         * This step would be unnecessary if we triggered animateChanges() in useEffect,
+         * but due to potential hydration errors we currently fire them in useLayoutEffect.
+         *
+         * By the time we're safely ready to cancel the optimised WAAPI animation,
+         * the main thread might have been blocked and desynced the two animations.
+         *
+         * Here, we resync the two animations before the optimised WAAPI animation is cancelled.
+         */
+        sync.update(() => {
+            if (value.animation) {
+                value.animation.currentTime = performance.now() - sampledTime;
+            }
+        });
+        /**
+         * We allow the animation to persist until the next frame:
+         *   1. So it continues to play until Framer Motion is ready to render
+         *      (avoiding a potential flash of the element's original state)
+         *   2. As all independent transforms share a single transform animation, stopping
+         *      it synchronously would prevent subsequent transforms from handing off.
+         */
+        sync.render(cancelOptimisedAnimation);
+        console.log("handing off from", animation.currentTime);
+        return animation.currentTime || 0;
+    }
+    else {
+        cancelOptimisedAnimation();
+        return 0;
+    }
+}
+
+function startOptimizedAppearAnimation(element, name, keyframes, options, onReady) {
     const id = element.dataset[optimizedAppearDataId];
-    const animation = animateStyle(element, name, keyframes, options);
-    if (id && animation) {
-        window.MotionAppearAnimations.set(appearStoreId(id, name), animation);
+    if (!id)
+        return;
+    window.HandoffAppearAnimations = handoffOptimizedAppearAnimation;
+    const storeId = appearStoreId(id, name);
+    /**
+     * Use a dummy animation to detect when Chrome is ready to start
+     * painting the page and hold off from triggering the real animation
+     * until then.
+     */
+    const readyAnimation = animateStyle(element, name, [keyframes[0], keyframes[0]], { duration: 1 });
+    appearAnimationStore.set(storeId, {
+        animation: readyAnimation,
+        ready: false,
+    });
+    const startAnimation = () => {
+        const animation = animateStyle(element, name, keyframes, options);
+        appearAnimationStore.set(storeId, { animation, ready: true });
+        if (onReady)
+            onReady(animation);
+    };
+    if (readyAnimation.ready) {
+        readyAnimation.ready.then(() => {
+            readyAnimation.cancel();
+            startAnimation();
+        });
+    }
+    else {
+        startAnimation();
     }
-    return animation;
 }
 
 const createObject = () => ({});

package/dist/es/animation/legacy-popmotion/spring.mjs

@@ -33,7 +33,7 @@ const velocitySampleDuration = 5;
 /**
  * This is based on the spring implementation of Wobble https://github.com/skevy/wobble
  */
-function spring({ keyframes, restSpeed = 2, restDelta = 0.01, ...options }) {
+function spring({ keyframes, restDelta, restSpeed, ...options }) {
     let origin = keyframes[0];
     let target = keyframes[keyframes.length - 1];
     /**
@@ -49,12 +49,15 @@ function spring({ keyframes, restSpeed = 2, restDelta = 0.01, ...options }) {
         const initialDelta = target - origin;
         const undampedAngularFreq = Math.sqrt(stiffness / mass) / 1000;
         /**
-         * If we're working within what looks like a 0-1 range, change the default restDelta
-         * to 0.01
+         * If we're working on a granular scale, use smaller defaults for determining
+         * when the spring is finished.
+         *
+         * These defaults have been selected emprically based on what strikes a good
+         * ratio between feeling good and finishing as soon as changes are imperceptible.
          */
-        if (restDelta === undefined) {
-            restDelta = Math.min(Math.abs(target - origin) / 100, 0.4);
-        }
+        const isGranularScale = Math.abs(initialDelta) < 5;
+        restSpeed || (restSpeed = isGranularScale ? 0.01 : 2);
+        restDelta || (restDelta = isGranularScale ? 0.005 : 0.5);
         if (dampingRatio < 1) {
             const angularFreq = calcAngularFreq(undampedAngularFreq, dampingRatio);
             // Underdamped spring

package/dist/es/animation/optimized-appear/handoff.mjs

@@ -1,12 +1,31 @@
-import { sync } from '../../frameloop/index.mjs';
 import { transformProps } from '../../render/html/utils/transform.mjs';
+import { appearAnimationStore } from './store.mjs';
 import { appearStoreId } from './store-id.mjs';
 
-function handoffOptimizedAppearAnimation(id, name, value) {
-    const { MotionAppearAnimations } = window;
-    const animationId = appearStoreId(id, transformProps.has(name) ? "transform" : name);
-    const animation = MotionAppearAnimations && MotionAppearAnimations.get(animationId);
-    if (animation) {
+function handoffOptimizedAppearAnimation(id, name, value, 
+/**
+ * This function is loaded via window by startOptimisedAnimation.
+ * By accepting `sync` as an argument, rather than using it via
+ * import, it can be kept out of the first-load Framer bundle,
+ * while also allowing this function to not be included in
+ * Framer Motion bundles where it's not needed.
+ */
+sync) {
+    const storeId = appearStoreId(id, transformProps.has(name) ? "transform" : name);
+    const { animation, ready } = appearAnimationStore.get(storeId) || {};
+    if (!animation)
+        return 0;
+    const cancelOptimisedAnimation = () => {
+        appearAnimationStore.delete(storeId);
+        /**
+         * Animation.cancel() throws so it needs to be wrapped in a try/catch
+         */
+        try {
+            animation.cancel();
+        }
+        catch (e) { }
+    };
+    if (ready) {
         const sampledTime = performance.now();
         /**
          * Resync handoff animation with optimised animation.
@@ -31,19 +50,12 @@ function handoffOptimizedAppearAnimation(id, name, value) {
          *   2. As all independent transforms share a single transform animation, stopping
          *      it synchronously would prevent subsequent transforms from handing off.
          */
-        sync.render(() => {
-            MotionAppearAnimations.delete(animationId);
-            /**
-             * Animation.cancel() throws so it needs to be wrapped in a try/catch
-             */
-            try {
-                animation.cancel();
-            }
-            catch (e) { }
-        });
+        sync.render(cancelOptimisedAnimation);
+        console.log("handing off from", animation.currentTime);
         return animation.currentTime || 0;
     }
     else {
+        cancelOptimisedAnimation();
         return 0;
     }
 }

package/dist/es/animation/optimized-appear/start.mjs

@@ -1,15 +1,40 @@
 import { appearStoreId } from './store-id.mjs';
 import { animateStyle } from '../waapi/index.mjs';
 import { optimizedAppearDataId } from './data-id.mjs';
+import { handoffOptimizedAppearAnimation } from './handoff.mjs';
+import { appearAnimationStore } from './store.mjs';
 
-function startOptimizedAppearAnimation(element, name, keyframes, options) {
-    window.MotionAppearAnimations || (window.MotionAppearAnimations = new Map());
+function startOptimizedAppearAnimation(element, name, keyframes, options, onReady) {
     const id = element.dataset[optimizedAppearDataId];
-    const animation = animateStyle(element, name, keyframes, options);
-    if (id && animation) {
-        window.MotionAppearAnimations.set(appearStoreId(id, name), animation);
+    if (!id)
+        return;
+    window.HandoffAppearAnimations = handoffOptimizedAppearAnimation;
+    const storeId = appearStoreId(id, name);
+    /**
+     * Use a dummy animation to detect when Chrome is ready to start
+     * painting the page and hold off from triggering the real animation
+     * until then.
+     */
+    const readyAnimation = animateStyle(element, name, [keyframes[0], keyframes[0]], { duration: 1 });
+    appearAnimationStore.set(storeId, {
+        animation: readyAnimation,
+        ready: false,
+    });
+    const startAnimation = () => {
+        const animation = animateStyle(element, name, keyframes, options);
+        appearAnimationStore.set(storeId, { animation, ready: true });
+        if (onReady)
+            onReady(animation);
+    };
+    if (readyAnimation.ready) {
+        readyAnimation.ready.then(() => {
+            readyAnimation.cancel();
+            startAnimation();
+        });
+    }
+    else {
+        startAnimation();
     }
-    return animation;
 }
 
 export { startOptimizedAppearAnimation };

package/dist/es/animation/optimized-appear/store.mjs

@@ -0,0 +1,3 @@
+const appearAnimationStore = new Map();
+
+export { appearAnimationStore };

package/dist/es/motion/utils/use-visual-element.mjs

@@ -41,7 +41,7 @@ function useVisualElement(Component, visualState, props, createVisualElement) {
      * So if we detect a situtation where optimised appear animations
      * are running, we use useLayoutEffect to trigger animations.
      */
-    const useAnimateChangesEffect = window.MotionAppearAnimations
+    const useAnimateChangesEffect = window.HandoffAppearAnimations
         ? useIsomorphicLayoutEffect
         : useEffect;
     useAnimateChangesEffect(() => {

package/dist/es/render/utils/animation.mjs

@@ -2,9 +2,9 @@ import { setTarget } from './setters.mjs';
 import { resolveVariant } from './resolve-dynamic-variants.mjs';
 import { transformProps } from '../html/utils/transform.mjs';
 import { isWillChangeMotionValue } from '../../value/use-will-change/is.mjs';
-import { handoffOptimizedAppearAnimation } from '../../animation/optimized-appear/handoff.mjs';
 import { optimizedAppearDataAttribute } from '../../animation/optimized-appear/data-id.mjs';
 import { createMotionValueAnimation } from '../../animation/index.mjs';
+import { sync } from '../../frameloop/index.mjs';
 
 function animateVisualElement(visualElement, definition, options = {}) {
     visualElement.notify("AnimationStart", definition);
@@ -88,10 +88,10 @@ function animateTarget(visualElement, definition, { delay = 0, transitionOverrid
          * If this is the first time a value is being animated, check
          * to see if we're handling off from an existing animation.
          */
-        if (!value.hasAnimated) {
+        if (!value.hasAnimated && window.HandoffAppearAnimations) {
             const appearId = visualElement.getProps()[optimizedAppearDataAttribute];
             if (appearId) {
-                valueTransition.elapsed = handoffOptimizedAppearAnimation(appearId, key, value);
+                valueTransition.elapsed = window.HandoffAppearAnimations(appearId, key, value, sync);
             }
         }
         let animation = value.start(createMotionValueAnimation(key, value, valueTarget, visualElement.shouldReduceMotion && transformProps.has(key)

package/dist/es/render/utils/motion-values.mjs

@@ -22,7 +22,7 @@ function updateMotionValuesFromProps(element, next, prev) {
              * and warn against mismatches.
              */
             if (process.env.NODE_ENV === "development") {
-                warnOnce(nextValue.version === "8.5.0", `Attempting to mix Framer Motion versions ${nextValue.version} with 8.5.0 may not work as expected.`);
+                warnOnce(nextValue.version === "8.5.2-alpha.1", `Attempting to mix Framer Motion versions ${nextValue.version} with 8.5.2-alpha.1 may not work as expected.`);
             }
         }
         else if (isMotionValue(prevValue)) {

package/dist/es/value/index.mjs

@@ -25,7 +25,7 @@ class MotionValue {
          * This will be replaced by the build step with the latest version number.
          * When MotionValues are provided to motion components, warn if versions are mixed.
          */
-        this.version = "8.5.0";
+        this.version = "8.5.2-alpha.1";
         /**
          * Duration, in milliseconds, since last updating frame.
          *

package/dist/framer-motion.dev.js

@@ -88,7 +88,7 @@
          * So if we detect a situtation where optimised appear animations
          * are running, we use useLayoutEffect to trigger animations.
          */
-        const useAnimateChangesEffect = window.MotionAppearAnimations
+        const useAnimateChangesEffect = window.HandoffAppearAnimations
             ? useIsomorphicLayoutEffect
             : React.useEffect;
         useAnimateChangesEffect(() => {
@@ -2103,7 +2103,7 @@
              * This will be replaced by the build step with the latest version number.
              * When MotionValues are provided to motion components, warn if versions are mixed.
              */
-            this.version = "8.5.0";
+            this.version = "8.5.2-alpha.1";
             /**
              * Duration, in milliseconds, since last updating frame.
              *
@@ -2797,54 +2797,6 @@
         return Boolean(isMotionValue(value) && value.add);
     }
 
-    const appearStoreId = (id, value) => `${id}: ${value}`;
-
-    function handoffOptimizedAppearAnimation(id, name, value) {
-        const { MotionAppearAnimations } = window;
-        const animationId = appearStoreId(id, transformProps.has(name) ? "transform" : name);
-        const animation = MotionAppearAnimations && MotionAppearAnimations.get(animationId);
-        if (animation) {
-            const sampledTime = performance.now();
-            /**
-             * Resync handoff animation with optimised animation.
-             *
-             * This step would be unnecessary if we triggered animateChanges() in useEffect,
-             * but due to potential hydration errors we currently fire them in useLayoutEffect.
-             *
-             * By the time we're safely ready to cancel the optimised WAAPI animation,
-             * the main thread might have been blocked and desynced the two animations.
-             *
-             * Here, we resync the two animations before the optimised WAAPI animation is cancelled.
-             */
-            sync.update(() => {
-                if (value.animation) {
-                    value.animation.currentTime = performance.now() - sampledTime;
-                }
-            });
-            /**
-             * We allow the animation to persist until the next frame:
-             *   1. So it continues to play until Framer Motion is ready to render
-             *      (avoiding a potential flash of the element's original state)
-             *   2. As all independent transforms share a single transform animation, stopping
-             *      it synchronously would prevent subsequent transforms from handing off.
-             */
-            sync.render(() => {
-                MotionAppearAnimations.delete(animationId);
-                /**
-                 * Animation.cancel() throws so it needs to be wrapped in a try/catch
-                 */
-                try {
-                    animation.cancel();
-                }
-                catch (e) { }
-            });
-            return animation.currentTime || 0;
-        }
-        else {
-            return 0;
-        }
-    }
-
     const optimizedAppearDataId = "framerAppearId";
     const optimizedAppearDataAttribute = "data-" + camelToDash(optimizedAppearDataId);
 
@@ -3397,7 +3349,7 @@
     /**
      * This is based on the spring implementation of Wobble https://github.com/skevy/wobble
      */
-    function spring({ keyframes, restSpeed = 2, restDelta = 0.01, ...options }) {
+    function spring({ keyframes, restDelta, restSpeed, ...options }) {
         let origin = keyframes[0];
         let target = keyframes[keyframes.length - 1];
         /**
@@ -3413,12 +3365,15 @@
             const initialDelta = target - origin;
             const undampedAngularFreq = Math.sqrt(stiffness / mass) / 1000;
             /**
-             * If we're working within what looks like a 0-1 range, change the default restDelta
-             * to 0.01
+             * If we're working on a granular scale, use smaller defaults for determining
+             * when the spring is finished.
+             *
+             * These defaults have been selected emprically based on what strikes a good
+             * ratio between feeling good and finishing as soon as changes are imperceptible.
              */
-            if (restDelta === undefined) {
-                restDelta = Math.min(Math.abs(target - origin) / 100, 0.4);
-            }
+            const isGranularScale = Math.abs(initialDelta) < 5;
+            restSpeed || (restSpeed = isGranularScale ? 0.01 : 2);
+            restDelta || (restDelta = isGranularScale ? 0.005 : 0.5);
             if (dampingRatio < 1) {
                 const angularFreq = calcAngularFreq(undampedAngularFreq, dampingRatio);
                 // Underdamped spring
@@ -4258,10 +4213,10 @@
              * If this is the first time a value is being animated, check
              * to see if we're handling off from an existing animation.
              */
-            if (!value.hasAnimated) {
+            if (!value.hasAnimated && window.HandoffAppearAnimations) {
                 const appearId = visualElement.getProps()[optimizedAppearDataAttribute];
                 if (appearId) {
-                    valueTransition.elapsed = handoffOptimizedAppearAnimation(appearId, key, value);
+                    valueTransition.elapsed = window.HandoffAppearAnimations(appearId, key, value, sync);
                 }
             }
             let animation = value.start(createMotionValueAnimation(key, value, valueTarget, visualElement.shouldReduceMotion && transformProps.has(key)
@@ -6011,7 +5966,7 @@
                  * and warn against mismatches.
                  */
                 {
-                    warnOnce(nextValue.version === "8.5.0", `Attempting to mix Framer Motion versions ${nextValue.version} with 8.5.0 may not work as expected.`);
+                    warnOnce(nextValue.version === "8.5.2-alpha.1", `Attempting to mix Framer Motion versions ${nextValue.version} with 8.5.2-alpha.1 may not work as expected.`);
                 }
             }
             else if (isMotionValue(prevValue)) {
@@ -10479,14 +10434,99 @@
         return reset;
     }
 
-    function startOptimizedAppearAnimation(element, name, keyframes, options) {
-        window.MotionAppearAnimations || (window.MotionAppearAnimations = new Map());
+    const appearStoreId = (id, value) => `${id}: ${value}`;
+
+    const appearAnimationStore = new Map();
+
+    function handoffOptimizedAppearAnimation(id, name, value, 
+    /**
+     * This function is loaded via window by startOptimisedAnimation.
+     * By accepting `sync` as an argument, rather than using it via
+     * import, it can be kept out of the first-load Framer bundle,
+     * while also allowing this function to not be included in
+     * Framer Motion bundles where it's not needed.
+     */
+    sync) {
+        const storeId = appearStoreId(id, transformProps.has(name) ? "transform" : name);
+        const { animation, ready } = appearAnimationStore.get(storeId) || {};
+        if (!animation)
+            return 0;
+        const cancelOptimisedAnimation = () => {
+            appearAnimationStore.delete(storeId);
+            /**
+             * Animation.cancel() throws so it needs to be wrapped in a try/catch
+             */
+            try {
+                animation.cancel();
+            }
+            catch (e) { }
+        };
+        if (ready) {
+            const sampledTime = performance.now();
+            /**
+             * Resync handoff animation with optimised animation.
+             *
+             * This step would be unnecessary if we triggered animateChanges() in useEffect,
+             * but due to potential hydration errors we currently fire them in useLayoutEffect.
+             *
+             * By the time we're safely ready to cancel the optimised WAAPI animation,
+             * the main thread might have been blocked and desynced the two animations.
+             *
+             * Here, we resync the two animations before the optimised WAAPI animation is cancelled.
+             */
+            sync.update(() => {
+                if (value.animation) {
+                    value.animation.currentTime = performance.now() - sampledTime;
+                }
+            });
+            /**
+             * We allow the animation to persist until the next frame:
+             *   1. So it continues to play until Framer Motion is ready to render
+             *      (avoiding a potential flash of the element's original state)
+             *   2. As all independent transforms share a single transform animation, stopping
+             *      it synchronously would prevent subsequent transforms from handing off.
+             */
+            sync.render(cancelOptimisedAnimation);
+            console.log("handing off from", animation.currentTime);
+            return animation.currentTime || 0;
+        }
+        else {
+            cancelOptimisedAnimation();
+            return 0;
+        }
+    }
+
+    function startOptimizedAppearAnimation(element, name, keyframes, options, onReady) {
         const id = element.dataset[optimizedAppearDataId];
-        const animation = animateStyle(element, name, keyframes, options);
-        if (id && animation) {
-            window.MotionAppearAnimations.set(appearStoreId(id, name), animation);
+        if (!id)
+            return;
+        window.HandoffAppearAnimations = handoffOptimizedAppearAnimation;
+        const storeId = appearStoreId(id, name);
+        /**
+         * Use a dummy animation to detect when Chrome is ready to start
+         * painting the page and hold off from triggering the real animation
+         * until then.
+         */
+        const readyAnimation = animateStyle(element, name, [keyframes[0], keyframes[0]], { duration: 1 });
+        appearAnimationStore.set(storeId, {
+            animation: readyAnimation,
+            ready: false,
+        });
+        const startAnimation = () => {
+            const animation = animateStyle(element, name, keyframes, options);
+            appearAnimationStore.set(storeId, { animation, ready: true });
+            if (onReady)
+                onReady(animation);
+        };
+        if (readyAnimation.ready) {
+            readyAnimation.ready.then(() => {
+                readyAnimation.cancel();
+                startAnimation();
+            });
+        }
+        else {
+            startAnimation();
         }
-        return animation;
     }
 
     const createObject = () => ({});