@tamagui/animations-motion 2.0.0-rc.8 → 2.0.0

package/src/createAnimations.tsx

@@ -9,7 +9,7 @@ import {
   hooks,
   styleToCSS,
   Text,
-  type TransitionProp,
+  TransitionProp,
   type UniversalAnimatedNumber,
   useComposedRefs,
   useIsomorphicLayoutEffect,
@@ -28,19 +28,31 @@ import {
 import React, {
   forwardRef,
   useEffect,
-  useId,
   useLayoutEffect,
   useMemo,
   useRef,
   useState,
 } from 'react'
 
+const isServer = typeof window === 'undefined'
+
+// SSR-safe wrapper: framer-motion's useAnimate imports its own React copy in
+// Vite SSR bundles which causes "Invalid hook call" errors. during SSR we
+// don't need animations so we return a no-op scope/animate pair.
+function useAnimateSSRSafe() {
+  if (isServer) {
+    return [useRef(null), (() => {}) as any] as ReturnType<typeof useAnimate>
+  }
+  return useAnimate()
+}
+
 type MotionAnimatedNumber = MotionValue<number>
 type AnimationConfig = ValueTransition
 
 type MotionAnimatedNumberStyle = {
-  getStyle: (cur: number) => Record<string, unknown>
-  motionValue: MotionValue<number>
+  getStyle: (...args: any[]) => Record<string, unknown>
+  motionValue?: MotionValue<number>
+  motionValues?: MotionValue<number>[]
 }
 
 /**
@@ -54,9 +66,26 @@ type TransitionAnimationOptions = AnimationOptions & {
 
 const MotionValueStrategy = new WeakMap<MotionValue, AnimatedNumberStrategy>()
 
-// regex to detect non-position transform operations (scale, rotate, skew, matrix, perspective)
-// used to identify position-only transforms for the popper animation fix
-const nonPositionTransformRe = /scale|rotate|skew|matrix|perspective/
+// pending setValue onFinish callbacks, keyed by motion value. setValue stores
+// the callback here; the change handler in the animated component's useEffect
+// consumes it by chaining to the DOM-level animate() controls so onFinish
+// fires when the *visible* animation actually completes.
+const PendingMotionOnFinish = new WeakMap<MotionValue, () => void>()
+
+function settlePendingMotionOnFinish(
+  mv: MotionValue,
+  controls: AnimationPlaybackControlsWithThen
+) {
+  const onFinish = PendingMotionOnFinish.get(mv)
+  if (!onFinish) return
+  PendingMotionOnFinish.delete(mv)
+  // chain to the DOM animation's completion. settle on both resolve and
+  // reject — a rejection means the animation was cancelled by a later
+  // setValue, and the caller still needs a completion signal. use the
+  // real Promise interface (.then().catch()) because framer-motion types
+  // the .then() callbacks as VoidFunction with no error arg.
+  controls.then(() => onFinish()).catch(() => onFinish())
+}
 
 type AnimationProps = {
   doAnimate?: Record<string, unknown>
@@ -64,9 +93,23 @@ type AnimationProps = {
   animationOptions?: AnimationOptions
 }
 
-// track if we're still in the initial hydration phase
-// TODO didnt realize claude took the wrong one here - this should uust be isComponentHydrating ideally
-// but this is fine for beta motion driver rc.0 fix in rc.1
+// internal refs consolidated into a single object
+type MotionRefs = {
+  isFirstRender: boolean
+  lastDoAnimate: Record<string, unknown> | null
+  lastDontAnimate: Record<string, unknown> | null
+  controls: AnimationPlaybackControlsWithThen | null
+  lastAnimateAt: number
+  disposed: boolean
+  wasExiting: boolean
+  isExiting: boolean
+  sendExitComplete: (() => void) | null | undefined
+  animationState: 'enter' | 'exit' | 'default'
+  frozenExitTarget: Record<string, unknown> | null
+  exitCompleteScheduled: boolean
+  wasEntering: boolean
+  wasDisabled: boolean
+}
 
 export function createAnimations<A extends Record<string, AnimationConfig>>(
   animations: A
@@ -75,14 +118,11 @@ export function createAnimations<A extends Record<string, AnimationConfig>>(
   const hydratingComponents = new Set<Function>()
 
   return {
-    // this is only used by Sheet basically for now to pass result of useAnimatedStyle to
     View: MotionView,
     Text: MotionText,
     isReactNative: false,
-    supportsCSS: true,
     inputStyle: 'css',
     outputStyle: 'inline',
-    needsWebStyles: true,
     avoidReRenders: true,
     animations,
     usePresence,
@@ -111,58 +151,77 @@ export function createAnimations<A extends Record<string, AnimationConfig>>(
       const isExiting = presence?.[0] === false
       const sendExitComplete = presence?.[1]
 
-      // Track if we just finished entering (transition from entering to not entering)
-      const wasEnteringRef = useRef(isEntering)
-      const justFinishedEntering = wasEnteringRef.current && !isEntering
+      // single consolidated ref with lazy init
+      const refs = useRef<MotionRefs>(null!)
+      if (!refs.current) {
+        refs.current = {
+          isFirstRender: true,
+          lastDoAnimate: null,
+          lastDontAnimate: null,
+          controls: null,
+          lastAnimateAt: 0,
+          disposed: false,
+          wasExiting: false,
+          isExiting: false,
+          sendExitComplete: undefined,
+          animationState: 'default',
+          frozenExitTarget: null,
+          exitCompleteScheduled: false,
+          wasEntering: false,
+          wasDisabled: false,
+        }
+      }
+
+      // track entering state transitions
+      const justFinishedEntering = refs.current.wasEntering && !isEntering
       useEffect(() => {
-        wasEnteringRef.current = isEntering
+        refs.current.wasEntering = isEntering
       })
 
-      // Determine animation state for enter/exit transitions
-      // Use 'enter' if we're mounting OR if we just finished entering
+      // determine animation state for enter/exit transitions
       const animationState: 'enter' | 'exit' | 'default' = isExiting
         ? 'exit'
         : isMounting || justFinishedEntering
           ? 'enter'
           : 'default'
 
-      // Disable animation during hydration AND during mounting (should-enter phase)
-      // This prevents the "flying across the page" effect on initial render
+      // disable animation during hydration and mounting (prevents "flying across the page")
       const disableAnimation = isComponentHydrating || isMounting || !animationKey
 
-      const isFirstRender = useRef(true)
-      const [scope, animate] = useAnimate()
-      const lastDoAnimate = useRef<Record<string, unknown> | null>(null)
-      const controls = useRef<AnimationPlaybackControlsWithThen | null>(null)
-      const styleKey = JSON.stringify(style)
+      const [scope, animate] = useAnimateSSRSafe()
+
+      // sync ref values for reliable access from callbacks
+      refs.current.isExiting = isExiting
+      refs.current.sendExitComplete = sendExitComplete
+      refs.current.animationState = animationState
+
+      // detect transition into exiting state
+      const justStartedExiting = isExiting && !refs.current.wasExiting
+      const justStoppedExiting = !isExiting && refs.current.wasExiting
 
-      // until fully stable allow debugging in prod to help debugging prod issues
-      const shouldDebug =
-        // process.env.NODE_ENV === 'development' &&
-        props['debug'] && props['debug'] !== 'profile'
+      // freeze exit animation target so direction changes don't reverse mid-exit
+      if (justStartedExiting || justStoppedExiting) {
+        refs.current.frozenExitTarget = null
+        refs.current.exitCompleteScheduled = false
+      }
+
+      // track previous exiting state
+      useEffect(() => {
+        refs.current.wasExiting = isExiting
+      })
 
       const {
         dontAnimate = {},
         doAnimate,
         animationOptions,
-      } = useMemo(() => {
-        const motionAnimationState = getMotionAnimatedProps(
-          props as any,
-          style,
-          disableAnimation,
-          animationState
-        )
-        return motionAnimationState
-      }, [isExiting, animationKey, styleKey, animationState, disableAnimation])
+      } = getMotionAnimatedProps(props as any, style, disableAnimation, animationState)
 
-      const id = useId()
-      const debugId = process.env.NODE_ENV === 'development' ? id : ''
-      const lastAnimateAt = useRef(0)
-      const disposed = useRef(false)
       const [firstRenderStyle] = useState(style)
 
       // avoid first render returning wrong styles - always render all, after that we can just mutate
-      const lastDontAnimate = useRef<Record<string, unknown> | null>(firstRenderStyle)
+      if (refs.current.isFirstRender) {
+        refs.current.lastDontAnimate = firstRenderStyle
+      }
       const [isHydrating, setIsHydrating] = useState(isHydratingGlobal)
 
       useLayoutEffect(() => {
@@ -172,46 +231,68 @@ export function createAnimations<A extends Record<string, AnimationConfig>>(
           })
         }
         return () => {
-          disposed.current = true
+          refs.current.disposed = true
         }
       }, [])
 
       const flushAnimation = ({
-        doAnimate = {},
-        animationOptions = {},
+        doAnimate: doAnimateRaw = {},
+        animationOptions: passedOptions = {},
         dontAnimate,
       }: AnimationProps) => {
+        // track whether THIS flush starts a new animation (vs using stale controls)
+        let startedControls: AnimationPlaybackControlsWithThen | null = null
+
+        // read current state from refs (closure variables can be stale)
+        const isCurrentlyExiting = refs.current.isExiting
+        const currentSendExitComplete = refs.current.sendExitComplete
+
+        // freeze exit target: once the first exit animation starts, subsequent
+        // renders (e.g. direction change) should not reverse the exit animation.
+        let doAnimate = doAnimateRaw
+        if (isCurrentlyExiting && refs.current.frozenExitTarget) {
+          doAnimate = refs.current.frozenExitTarget
+        }
+
+        // only recompute animation options for exit animations to avoid stale state.
+        const animationOptions =
+          isCurrentlyExiting && currentSendExitComplete
+            ? getAnimationOptions(props.transition ?? null, 'exit')
+            : passedOptions
+
         try {
           const node = stateRef.current.host
 
           // on first render, reset stale animation refs - they can persist if component
           // instance is reused (e.g. AnimatePresence keepChildrenMounted)
-          if (isFirstRender.current) {
-            lastDontAnimate.current = null
-            lastDoAnimate.current = null
+          if (refs.current.isFirstRender) {
+            refs.current.lastDontAnimate = null
+            refs.current.lastDoAnimate = null
           }
 
-          if (shouldDebug) {
-            console.groupCollapsed(
-              `[motion] ${debugId} 🌊 animate (${JSON.stringify(getDiff(lastDoAnimate.current, doAnimate), null, 2)})`
-            )
-            console.info({
-              props,
-              componentState,
-              doAnimate,
-              dontAnimate,
-              animationOptions,
-              animationProps,
-              lastDoAnimate: { ...lastDoAnimate.current },
-              lastDontAnimate: { ...lastDontAnimate.current },
-              isExiting,
-              style,
-              node,
-            })
-            console.groupCollapsed(`trace >`)
-            console.trace()
-            console.groupEnd()
-            console.groupEnd()
+          if (process.env.NODE_ENV === 'development') {
+            if (props['debug'] && props['debug'] !== 'profile') {
+              console.groupCollapsed(
+                `[motion] animate (${JSON.stringify(getDiff(refs.current.lastDoAnimate, doAnimate), null, 2)})`
+              )
+              console.info({
+                props,
+                componentState,
+                doAnimate,
+                dontAnimate,
+                animationOptions,
+                animationProps,
+                lastDoAnimate: { ...refs.current.lastDoAnimate },
+                lastDontAnimate: { ...refs.current.lastDontAnimate },
+                isExiting,
+                style,
+                node,
+              })
+              console.groupCollapsed(`trace >`)
+              console.trace()
+              console.groupEnd()
+              console.groupEnd()
+            }
           }
 
           if (!(node instanceof HTMLElement)) {
@@ -219,263 +300,233 @@ export function createAnimations<A extends Record<string, AnimationConfig>>(
           }
 
           // handle case where dontAnimate changes
-          // we just set it onto animate + set options to not actually animate
-          const prevDont = lastDontAnimate.current
+          const prevDont = refs.current.lastDontAnimate
           if (dontAnimate) {
             if (prevDont) {
-              // Pass doAnimate as preserve to prevent clearing styles that moved to doAnimate
               removeRemovedStyles(prevDont, dontAnimate, node, doAnimate)
               const changed = getDiff(prevDont, dontAnimate)
               if (changed) {
                 Object.assign(node.style, changed as any)
               }
             } else {
-              // First time - apply directly without diff check
               Object.assign(node.style, dontAnimate as any)
             }
           }
 
           if (doAnimate) {
-            // bugfix: going from non-animated to animated in motion -
-            // motion batches things so the above removal can happen a frame before causing flickering
-            // we see this with tooltips, this is not an ideal solution though, ideally we can remove/update
-            // in the same batch/frame as motion
-            // Also sync motion's internal state for properties moving from dontAnimate to doAnimate
+            // when a property moves from dontAnimate to doAnimate, preserve
+            // the current inline style value so WAAPI starts from the right place
             if (prevDont) {
-              const movedToAnimate: Record<string, unknown> = {}
               for (const key in prevDont) {
                 if (key in doAnimate) {
                   node.style[key] = prevDont[key]
-                  movedToAnimate[key] = prevDont[key]
-                  // Also update lastDoAnimate to include the previous value
-                  // This prevents animating from undefined to the current value
-                  // when a property transitions from dontAnimate to doAnimate
-                  if (lastDoAnimate.current) {
-                    lastDoAnimate.current[key] = prevDont[key]
+                  if (refs.current.lastDoAnimate) {
+                    refs.current.lastDoAnimate[key] = prevDont[key]
                   }
                 }
               }
-              // Sync motion's internal state for moved properties
-              if (Object.keys(movedToAnimate).length > 0) {
-                animate(scope.current, { ...movedToAnimate }, { duration: 0 })
-              }
             }
 
-            const lastAnimated = lastDoAnimate.current
+            const lastAnimated = refs.current.lastDoAnimate
             if (lastAnimated) {
-              // Pass dontAnimate as third arg to prevent clearing styles that moved to dontAnimate
               removeRemovedStyles(lastAnimated, doAnimate, node, dontAnimate)
             }
 
-            const diff = getDiff(lastDoAnimate.current, doAnimate)
+            const diff = getDiff(refs.current.lastDoAnimate, doAnimate)
+
             if (diff) {
-              // FIX: Handle animation interruption for position-only animations
-              // Only apply this fix when:
-              // 1. There's a running animation
-              // 2. The transform change is POSITION-ONLY (just translate, no scale/rotate/skew)
-              // 3. animatePosition is being used (Popper/Tooltip pattern)
-              // This fixes tooltip position jumping without breaking AnimatePresence scale/rotate animations
-              // NOTE: We check for animatePosition to avoid this fix causing jitter
-              // on components like the TAMAGUI logo dot indicator which also use translate-only transforms
-
-              const isRunning =
-                /**
-                 * TypeError: Cannot read properties of undefined (reading 'state')
-                 * at GroupAnimationWithThen.getAll (http://localhost:8081/node_modules/.vite/deps/@tamagui_config_v5-motion.js?v=d717d926:2374:30)
-                 * at get state (http://localhost:8081/node_modules/.vite/deps/@tamagui_config_v5-motion.js?v=d717d926:2403:17)
-                 * at flushAnimation (http://localhost:8081/node_modules/.vite/deps/@tamagui_config_v5-motion.js?v=d717d926:9686:49)
-                 **/
-                // @ts-expect-error it is there, and for some crazy reason in ~/chat pretty often i get errors ^
-                controls.current?.animations?.length === 0
-                  ? false
-                  : controls.current?.state === 'running'
-              const targetTransform =
-                typeof diff.transform === 'string' ? diff.transform : null
-
-              // only apply position fix for translate-only transforms
-              const isPositionOnlyTransform =
-                targetTransform &&
-                targetTransform.includes('translate') &&
-                !nonPositionTransformRe.test(targetTransform)
-
-              // Position fix for Popper/Tooltip elements with animatePosition.
-              // Only apply when:
-              // 1. Animation is actively running
-              // 2. Transform is position-only (translate without scale/rotate/etc)
-              // 3. Element has data-popper-animate-position attribute (set by Popper when
-              //    animatePosition is true)
-              //
-              // The issue: when a Popper animation is interrupted mid-flight, motion's
-              // animate() may start from wrong position causing jumps to origin.
+              // capture frozen exit target on first exit diff
+              if (isCurrentlyExiting && !refs.current.frozenExitTarget) {
+                refs.current.frozenExitTarget = { ...doAnimate }
+              }
+
+              // capture mid-flight values so we can provide explicit [from, to]
+              // keyframes to WAAPI, ensuring smooth interpolation from the
+              // current visual state.
               //
-              // Why check data-popper-animate-position: This attribute is ONLY set on Popper
-              // elements that explicitly use animatePosition. Regular
-              // components like the logo Circle don't have this attribute, so they won't
-              // get this fix applied (which would cause jitter due to getComputedStyle
-              // overhead on rapid updates).
-
-              // check if this is a Popper element with animated position
-              const isPopperElement = node.hasAttribute('data-popper-animate-position')
-
-              // also apply fix for AnimatePresence children that just finished entering
-              // this fixes roving tabs indicator jumping when rapidly switching
-              const isEnteringPresenceChild = presence && justFinishedEntering
-
-              if (
-                isRunning &&
-                controls.current &&
-                isPositionOnlyTransform &&
-                (isPopperElement || isEnteringPresenceChild)
-              ) {
-                const currentTransform = getComputedStyle(node).transform
-
-                if (currentTransform && currentTransform !== 'none') {
-                  const matrixMatch = currentTransform.match(
-                    /matrix\([^,]+,\s*[^,]+,\s*[^,]+,\s*[^,]+,\s*([^,]+),\s*([^)]+)\)/
-                  )
-
-                  if (matrixMatch) {
-                    // stop animation and preserve current position
-                    controls.current.stop()
-                    node.style.transform = currentTransform
-
-                    // animate from current matrix position to target
-                    const currentX = Number.parseFloat(matrixMatch[1])
-                    const currentY = Number.parseFloat(matrixMatch[2])
-                    const keyframeDiff = {
-                      ...diff,
-                      transform: [
-                        `translateX(${currentX}px) translateY(${currentY}px)`,
-                        targetTransform,
-                      ],
+              // only stop() during exit — for non-exit cases, WAAPI
+              // naturally replaces only conflicting property animations,
+              // letting non-conflicting ones (like an in-flight enter
+              // opacity animation) continue to completion.
+              const isPopperPosition = node.hasAttribute('data-popper-animate-position')
+              let midFlightValues: Record<string, string> | null = null
+              if (refs.current.controls) {
+                try {
+                  const computed = getComputedStyle(node)
+                  midFlightValues = {}
+                  for (const key in diff) {
+                    const val = (computed as any)[key]
+                    if (val !== undefined && val !== '') {
+                      midFlightValues[key] = val
                     }
+                  }
+                } catch {
+                  // getComputedStyle can fail on detached nodes
+                }
 
-                    controls.current = animate(
-                      scope.current,
-                      keyframeDiff,
-                      animationOptions
-                    )
-                    lastAnimateAt.current = Date.now()
-                    lastDontAnimate.current = dontAnimate ? { ...dontAnimate } : {}
-                    lastDoAnimate.current = doAnimate ? { ...doAnimate } : {}
-                    return
+                if (isCurrentlyExiting) {
+                  refs.current.controls.stop()
+                }
+
+                // write mid-flight values to inline so the 1-frame gap
+                // (while motion resolves keyframes) shows the correct
+                // position instead of stale inline styles
+                if (midFlightValues) {
+                  for (const key in midFlightValues) {
+                    ;(node.style as any)[key] = midFlightValues[key]
+                  }
+                }
+
+                // for popper position elements, cancel WAAPI animations
+                // directly so motion.dev's internal stop() sees "idle" state
+                // and skips commitStyles. without this, commitStyles writes
+                // a mid-flight transform that's visible for 1 frame before
+                // the new animation starts, causing a flash toward (0,0).
+                if (isPopperPosition) {
+                  const anims = node.getAnimations()
+                  for (const anim of anims) {
+                    anim.cancel()
                   }
                 }
               }
 
-              // IMPORTANT: Spread to create mutable copy - style objects may be frozen
-              // fix transparent colors to use rgba for motion.dev compatibility
-              const fixedDiff = fixTransparentColors({ ...diff }, lastDoAnimate.current)
+              const fixedDiff = fixTransparentColors(
+                diff,
+                refs.current.lastDoAnimate,
+                doAnimate
+              )
 
-              controls.current = animate(scope.current, fixedDiff, animationOptions)
-              lastAnimateAt.current = Date.now()
+              // provide explicit [from, to] keyframe for transforms during
+              // mid-flight interruption so motion starts from the right place
+              if (midFlightValues?.transform && fixedDiff.transform) {
+                fixedDiff.transform = [midFlightValues.transform, fixedDiff.transform]
+              }
+
+              startedControls = animate(scope.current, fixedDiff, animationOptions)
+              refs.current.controls = startedControls
+              refs.current.lastAnimateAt = Date.now()
             }
           }
 
-          // IMPORTANT: Spread to create mutable copies - objects may be frozen
-          lastDontAnimate.current = dontAnimate ? { ...dontAnimate } : {}
-          lastDoAnimate.current = doAnimate ? { ...doAnimate } : {}
+          refs.current.lastDontAnimate = dontAnimate ? { ...dontAnimate } : {}
+          refs.current.lastDoAnimate = doAnimate ? { ...doAnimate } : {}
         } finally {
-          if (isExiting) {
-            if (controls.current) {
-              controls.current.finished.then(() => {
-                sendExitComplete?.()
-              })
-            } else {
-              sendExitComplete?.()
+          // exit completion: notify AnimatePresence when exit animation finishes
+          if (isCurrentlyExiting && currentSendExitComplete) {
+            if (startedControls) {
+              // new animation started — attach completion handler
+              refs.current.exitCompleteScheduled = true
+              startedControls.finished
+                .then(() => {
+                  // guard: only complete if still exiting (prevents stale promise
+                  // from calling sendExitComplete after a re-entry cancels the exit)
+                  if (refs.current.isExiting) {
+                    currentSendExitComplete()
+                  }
+                })
+                .catch(() => {
+                  if (refs.current.isExiting) {
+                    currentSendExitComplete()
+                  }
+                })
+            } else if (!refs.current.exitCompleteScheduled) {
+              // no animation started AND none previously scheduled (e.g. diff=null
+              // on re-render mid-exit because frozenExitTarget matches lastDoAnimate)
+              // — complete immediately only if we've never started an exit animation
+              currentSendExitComplete()
             }
+            // else: exit animation already scheduled via a previous flush,
+            // its .finished promise will call sendExitComplete when done
           }
         }
       }
 
-      useStyleEmitter?.((nextStyle) => {
+      useStyleEmitter?.((nextStyle, effectiveTransition) => {
         const animationProps = getMotionAnimatedProps(
           props as any,
           nextStyle,
           disableAnimation,
-          animationState
+          refs.current.animationState,
+          effectiveTransition
         )
 
         flushAnimation(animationProps)
       })
 
       useIsomorphicLayoutEffect(() => {
-        if (isFirstRender.current) {
-          isFirstRender.current = false
-
-          // during hydration, use full sync logic to prevent flash
-          // doing this - will fix some of the enter (accordion) glitches but breaks animatepresence
-          //  isHydrating || (isMounting && !isEntering)
+        if (refs.current.isFirstRender) {
+          refs.current.isFirstRender = false
+          refs.current.wasDisabled = disableAnimation
+
+          // during hydration, skip inline style writes entirely — SSR CSS
+          // already has the correct values. writing them again as inline
+          // styles triggers browser style recalc that causes visible font
+          // flashes (fontWeight, fontSize, letterSpacing, lineHeight).
+          // we only need to track refs for future animation diffing.
           if (isHydrating) {
-            const node = stateRef.current.host
-
-            if (node instanceof HTMLElement) {
-              // IMPORTANT: On first render, we need to:
-              // 1. Apply dontAnimate styles to the DOM (enterStyle values like scale(0))
-              // 2. Tell motion about these styles so it knows the starting state
-              // This ensures AnimatePresence enter animations work correctly.
-
-              if (dontAnimate) {
-                // Apply initial styles to DOM
-                Object.assign(node.style, dontAnimate as any)
-
-                // Tell motion about the initial state by animating instantly to dontAnimate
-                // This syncs motion's internal state with what's actually on the DOM
-                // IMPORTANT: Spread to create mutable copy - React/Tamagui style objects may be frozen
-                animate(scope.current, { ...dontAnimate }, { duration: 0 })
-              }
-
-              // If there are styles to animate, set them up (but animation is disabled on first render)
-              if (doAnimate && Object.keys(doAnimate).length > 0) {
-                // IMPORTANT: Spread to create mutable copy - objects may be frozen
-                lastDoAnimate.current = { ...doAnimate }
-                animate(scope.current, { ...doAnimate }, { duration: 0 })
-              } else {
-                // doAnimate is empty, so track dontAnimate as the initial animated state
-                // This way on next render, getDiff will detect the change
-                // IMPORTANT: Spread to create mutable copy - objects may be frozen
-                lastDoAnimate.current = dontAnimate ? { ...dontAnimate } : {}
-              }
+            if (doAnimate && Object.keys(doAnimate).length > 0) {
+              refs.current.lastDoAnimate = { ...doAnimate }
+            } else {
+              refs.current.lastDoAnimate = dontAnimate ? { ...dontAnimate } : {}
             }
 
-            // IMPORTANT: Spread to create mutable copy - objects may be frozen
-            lastDontAnimate.current = dontAnimate ? { ...dontAnimate } : {}
-            lastAnimateAt.current = Date.now()
+            refs.current.lastDontAnimate = dontAnimate ? { ...dontAnimate } : {}
+            refs.current.lastAnimateAt = Date.now()
             return
           }
 
           // after hydration, use simpler logic
-          lastDontAnimate.current = dontAnimate ? { ...dontAnimate } : {}
-          lastDoAnimate.current = doAnimate ? { ...doAnimate } : {}
+          refs.current.lastDontAnimate = dontAnimate ? { ...dontAnimate } : {}
+          refs.current.lastDoAnimate = doAnimate ? { ...doAnimate } : {}
           return
         }
 
-        // don't ever queue on a render
-        flushAnimation({
-          doAnimate,
-          dontAnimate,
-          animationOptions,
-        })
-      }, [styleKey, isExiting, disableAnimation])
+        // when animations first turn on after the mount/hydration handoff, the
+        // element is already at its resting position (SSR atomic class, or the
+        // dontAnimate inline styles). animating now would spring from the lost
+        // "from" value — which for a transform reads as 0 and flashes the
+        // element across the screen (e.g. progress bar flashing full, #4011).
+        // jump straight to the resolved styles instead, so it renders at the
+        // right place with no enter animation. only real changes after this
+        // animate. components with an explicit enter animation still animate.
+        const justEnabled = refs.current.wasDisabled && !disableAnimation
+        refs.current.wasDisabled = disableAnimation
+        if (justEnabled && animationState !== 'enter') {
+          const node = stateRef.current.host
+          if (node instanceof HTMLElement) {
+            if (dontAnimate) Object.assign(node.style, dontAnimate)
+            if (doAnimate) Object.assign(node.style, doAnimate)
+          }
+          refs.current.lastDontAnimate = dontAnimate ? { ...dontAnimate } : {}
+          refs.current.lastDoAnimate = doAnimate ? { ...doAnimate } : {}
+          return
+        }
 
-      if (shouldDebug) {
-        console.groupCollapsed(`[motion] 🌊 render`)
-        console.info({
-          style,
+        flushAnimation({
           doAnimate,
           dontAnimate,
-          styleKey,
-          scope,
           animationOptions,
-          isExiting,
-          isFirstRender: isFirstRender.current,
-          animationProps,
         })
-        console.groupEnd()
+      }, [style, isExiting, disableAnimation])
+
+      if (process.env.NODE_ENV === 'development') {
+        if (props['debug'] && props['debug'] !== 'profile') {
+          console.groupCollapsed(`[motion] render`)
+          console.info({
+            style,
+            doAnimate,
+            dontAnimate,
+            scope,
+            animationOptions,
+            isExiting,
+            isFirstRender: refs.current.isFirstRender,
+            animationProps,
+          })
+          console.groupEnd()
+        }
       }
 
       return {
-        // we never change this, after first render on
         style: firstRenderStyle,
         ref: scope,
         render: 'div',
@@ -495,26 +546,44 @@ export function createAnimations<A extends Record<string, AnimationConfig>>(
           },
           setValue(next, config = { type: 'spring' }, onFinish) {
             if (config.type === 'direct') {
-              MotionValueStrategy.set(motionValue, {
-                type: 'direct',
-              })
+              MotionValueStrategy.set(motionValue, { type: 'direct' })
               motionValue.set(next)
               onFinish?.()
-            } else {
-              MotionValueStrategy.set(motionValue, config)
+              return
+            }
 
-              if (onFinish) {
-                const unsubscribe = motionValue.on('change', (value) => {
-                  if (Math.abs(value - next) < 0.01) {
-                    unsubscribe()
-                    onFinish()
-                  }
-                })
+            MotionValueStrategy.set(motionValue, config)
+
+            // we intentionally DO NOT animate the motion value itself here
+            // (via framer-motion's imperative animate(motionValue, next)).
+            // doing so drives the JS value over time, which fires a 'change'
+            // event per frame, and each change event kicks off a new DOM
+            // animate(node, ...) that cancels the previous one — the DOM
+            // never reaches the target (double-animation stall).
+            //
+            // instead we jump the motion value to `next` synchronously. the
+            // animated component's change handler receives a single change
+            // event, computes the final webStyle, and drives the visible
+            // animation via DOM animate(node, webStyle, springConfig). that
+            // DOM animation is the real timing source.
+            //
+            // to make `onFinish` resolve when the VISIBLE animation finishes
+            // (not synchronously on the change event), we stash it in
+            // PendingMotionOnFinish here and the change handler chains it to
+            // the DOM animate() controls.
+            if (onFinish) {
+              // if a previous setValue is still pending on this motion value,
+              // fire it now — the new setValue will cancel the prior DOM
+              // animation, and the caller is still owed a completion signal.
+              const prior = PendingMotionOnFinish.get(motionValue)
+              if (prior) {
+                PendingMotionOnFinish.delete(motionValue)
+                prior()
               }
-
-              motionValue.set(next)
-              // Motion doesn't have a direct onFinish callback, so we simulate it
+              PendingMotionOnFinish.set(motionValue, onFinish)
             }
+
+            motionValue.set(next)
           },
           stop() {
             motionValue.stop()
@@ -536,7 +605,6 @@ export function createAnimations<A extends Record<string, AnimationConfig>>(
       // we need to change useAnimatedNumberStyle to have dep args to be concurrent safe
       getStyleRef.current = getStyleProp
 
-      // never changes
       return useMemo(() => {
         return {
           getStyle: (cur) => {
@@ -546,13 +614,27 @@ export function createAnimations<A extends Record<string, AnimationConfig>>(
         } satisfies MotionAnimatedNumberStyle
       }, [])
     },
+
+    useAnimatedNumbersStyle(vals, getStyleProp) {
+      const motionValues = vals.map((v) => v.getInstance() as MotionValue<number>)
+      const getStyleRef = useRef<typeof getStyleProp>(getStyleProp)
+      getStyleRef.current = getStyleProp
+
+      return useMemo(() => {
+        return {
+          getStyle: (...currentValues: number[]) => getStyleRef.current(...currentValues),
+          motionValues,
+        } satisfies MotionAnimatedNumberStyle
+      }, [])
+    },
   }
 
   function getMotionAnimatedProps(
-    props: { transition: TransitionProp | null; animateOnly?: string[] },
+    props: { transition?: TransitionProp | null; animateOnly?: string[] },
     style: Record<string, unknown>,
     disable: boolean,
-    animationState: 'enter' | 'exit' | 'default' = 'default'
+    animationState: 'enter' | 'exit' | 'default' = 'default',
+    transitionOverride?: TransitionProp | null
   ): AnimationProps {
     if (disable) {
       return {
@@ -560,7 +642,10 @@ export function createAnimations<A extends Record<string, AnimationConfig>>(
       }
     }
 
-    const animationOptions = getAnimationOptions(props.transition, animationState)
+    const animationOptions = getAnimationOptions(
+      transitionOverride ?? props.transition ?? null,
+      animationState
+    )
 
     let dontAnimate: Record<string, unknown> | undefined
     let doAnimate: Record<string, unknown> | undefined
@@ -590,50 +675,54 @@ export function createAnimations<A extends Record<string, AnimationConfig>>(
   ): TransitionAnimationOptions {
     const normalized = normalizeTransition(transitionProp)
 
-    // Get the effective animation key based on enter/exit/default state
-    const effectiveKey = getEffectiveAnimation(normalized, animationState)
+    let effectiveKey = getEffectiveAnimation(normalized, animationState)
+
+    // fallback: if we have enter/exit defined but state is 'default' and no default key,
+    // use enter timing as fallback to avoid empty animation options
+    if (!effectiveKey && animationState === 'default') {
+      effectiveKey = normalized.enter || normalized.exit || null
+    }
+
+    const globalConfigOverride: Record<string, unknown> | undefined = normalized.config
+      ? { ...normalized.config }
+      : undefined
 
-    // If no animation defined, return empty config
-    if (!effectiveKey && Object.keys(normalized.properties).length === 0) {
+    if (
+      !effectiveKey &&
+      Object.keys(normalized.properties).length === 0 &&
+      !globalConfigOverride
+    ) {
       return {}
     }
 
     const defaultConfig = effectiveKey ? withInferredType(animations[effectiveKey]) : null
 
-    // Framer Motion uses seconds, so convert from ms
-    const delay =
-      typeof normalized.delay === 'number' ? normalized.delay / 1000 : undefined
+    const delay = normalized.delay
 
-    // Convert global config overrides from ms to seconds where needed
-    let globalConfigOverride: Record<string, unknown> | undefined
-    if (normalized.config) {
-      globalConfigOverride = { ...normalized.config }
-      if (typeof normalized.config.duration === 'number') {
-        globalConfigOverride.duration = normalized.config.duration / 1000
-      }
-    }
-
-    // Build the animation options
-    // Framer Motion's animate() expects default config at the TOP LEVEL, not nested under 'default'
-    // Per-property configs can be nested under property names like { scale: { duration: 1 } }
+    // framer motion's animate() expects default config at the TOP LEVEL
     const result: TransitionAnimationOptions = {}
 
-    // Apply base config from preset at top level (this is what animate() reads as default)
     if (defaultConfig) {
       Object.assign(result, defaultConfig)
     }
 
-    // Apply global spring config overrides at top level
     if (globalConfigOverride) {
       Object.assign(result, globalConfigOverride)
+      if (
+        result.type === undefined &&
+        result.duration !== undefined &&
+        result.damping === undefined &&
+        result.stiffness === undefined &&
+        result.mass === undefined
+      ) {
+        result.type = 'tween'
+      }
     }
 
-    // Apply delay at top level
     if (delay) {
       result.delay = delay
     }
 
-    // Also set the 'default' key for backwards compatibility with per-property fallback logic
     if (defaultConfig || globalConfigOverride || delay) {
       result.default = {
         ...defaultConfig,
@@ -642,7 +731,6 @@ export function createAnimations<A extends Record<string, AnimationConfig>>(
       }
     }
 
-    // Add property-specific animations
     for (const [propName, animationNameOrConfig] of Object.entries(
       normalized.properties
     )) {
@@ -653,27 +741,30 @@ export function createAnimations<A extends Record<string, AnimationConfig>>(
           ? withInferredType(animations[animationNameOrConfig.type])
           : defaultConfig
 
-        // @ts-expect-error
         result[propName] = {
           ...baseConfig,
           ...animationNameOrConfig,
-        }
+        } as ValueTransition
       }
     }
 
     // we standardize to ms across drivers, motion expects s
-    // apply to default and each per-property config
+    convertMsToS(result as ValueTransition)
     convertMsToS(result.default)
     for (const key in result) {
-      if (key !== 'default') convertMsToS(result[key])
+      if (key !== 'default' && typeof result[key] === 'object') {
+        convertMsToS(result[key])
+      }
     }
 
     return result
   }
 }
 
-// infer type from config shape if not explicitly set, always returns a copy
-function withInferredType(config: AnimationConfig): AnimationConfig {
+function withInferredType(config: AnimationConfig | undefined): AnimationConfig {
+  if (!config) {
+    return { type: 'spring' }
+  }
   const isTimingBased =
     config.duration !== undefined &&
     config.damping === undefined &&
@@ -682,11 +773,20 @@ function withInferredType(config: AnimationConfig): AnimationConfig {
   return { type: isTimingBased ? 'tween' : 'spring', ...config }
 }
 
-// convert tween duration/delay from ms to s (motion expects seconds)
 function convertMsToS(config: ValueTransition | undefined) {
-  if (!config || config.type !== 'tween') return
-  if (typeof config.duration === 'number') config.duration = config.duration / 1000
+  if (!config) return
   if (typeof config.delay === 'number') config.delay = config.delay / 1000
+  if (typeof config.duration === 'number') {
+    const isTimingBased =
+      config.type === 'tween' ||
+      (config.type === undefined &&
+        config.damping === undefined &&
+        config.stiffness === undefined &&
+        config.mass === undefined)
+    if (isTimingBased) {
+      config.duration = config.duration / 1000
+    }
+  }
 }
 
 function removeRemovedStyles(
@@ -697,7 +797,6 @@ function removeRemovedStyles(
 ) {
   for (const key in prev) {
     if (!(key in next)) {
-      // Don't clear if the style is now in dontAnimate (moved from animated to non-animated)
       if (dontClearIfIn && key in dontClearIfIn) {
         continue
       }
@@ -706,56 +805,37 @@ function removeRemovedStyles(
   }
 }
 
-// sort of temporary
-const disableAnimationProps = new Set<string>([
+// truly non-animatable CSS properties (discrete, keyword-based, no interpolation)
+// properties like margin, maxHeight, zIndex, etc are animatable and intentionally excluded
+export const disableAnimationProps: Set<string> = new Set<string>([
   'alignContent',
   'alignItems',
-  'aspectRatio',
-  'backdropFilter',
   'boxSizing',
   'contain',
   'containerType',
   'display',
   'flexBasis',
   'flexDirection',
-  'flexGrow',
-  'flexShrink',
   'fontFamily',
   'justifyContent',
-  'marginBottom',
-  'marginLeft',
-  'marginRight',
-  'marginTop',
-  'maxHeight',
-  'maxWidth',
-  'minHeight',
-  'minWidth',
   'overflow',
   'overflowX',
   'overflowY',
   'pointerEvents',
   'position',
   'textWrap',
-  'transformOrigin',
   'userSelect',
-  'WebkitBackdropFilter',
-  'zIndex',
 ])
 
 const MotionView = createMotionView('div')
 const MotionText = createMotionView('span')
 
 function createMotionView(defaultTag: string) {
-  // return forwardRef((props: any, ref) => {
-  //   console.info('rendering?', props)
-  //   const Element = motion[props.render || defaultTag]
-  //   return <Element ref={ref} {...props} />
-  // })
   const isText = defaultTag === 'span'
 
   const Component = forwardRef((propsIn: any, ref) => {
     const { forwardedRef, animation, render = defaultTag, style, ...propsRest } = propsIn
-    const [scope, animate] = useAnimate()
+    const [scope, animate] = useAnimateSSRSafe()
     const hostRef = useRef<HTMLElement>(null)
     const composedRefs = useComposedRefs(forwardedRef, ref, hostRef, scope)
 
@@ -772,12 +852,17 @@ function createMotionView(defaultTag: string) {
 
     const styles = Array.isArray(style) ? style : [style]
 
-    // we can assume just one animatedStyle max for now
     const [animatedStyle, nonAnimatedStyles] = (() => {
-      return [
-        styles.find((x) => x.getStyle) as MotionAnimatedNumberStyle | undefined,
-        styles.filter((x) => !x.getStyle),
-      ] as const
+      let animatedStyle: MotionAnimatedNumberStyle | undefined
+      const nonAnimatedStyles: typeof styles = []
+      for (const style of styles) {
+        if (style.getStyle) {
+          animatedStyle = style as MotionAnimatedNumberStyle
+        } else {
+          nonAnimatedStyles.push(style)
+        }
+      }
+      return [animatedStyle, nonAnimatedStyles] as const
     })()
 
     function getProps(props: any) {
@@ -792,7 +877,6 @@ function createMotionView(defaultTag: string) {
         {
           isAnimated: false,
           noClass: true,
-          // noMergeStyle: true,
           resolveValues: 'auto',
         }
       )
@@ -801,7 +885,6 @@ function createMotionView(defaultTag: string) {
         return {}
       }
 
-      // we can definitely get rid of this here
       if (out.viewProps.style) {
         fixStyles(out.viewProps.style)
         styleToCSS(out.viewProps.style)
@@ -817,9 +900,40 @@ function createMotionView(defaultTag: string) {
     useEffect(() => {
       if (!animatedStyle) return
 
+      // multi-value path: subscribe to all motion values
+      if (animatedStyle.motionValues) {
+        const mvs = animatedStyle.motionValues
+        const unsubs = mvs.map((mv) =>
+          mv.on('change', () => {
+            const currentValues = mvs.map((v) => v.get())
+            const nextStyle = animatedStyle.getStyle(...currentValues)
+            const animationConfig = MotionValueStrategy.get(mv)
+            const node = hostRef.current
+
+            const webStyle = getProps({ style: nextStyle }).style
+
+            if (webStyle && node instanceof HTMLElement) {
+              const motionAnimationConfig =
+                animationConfig?.type === 'timing'
+                  ? { type: 'tween', duration: (animationConfig?.duration || 0) / 1000 }
+                  : animationConfig?.type === 'direct'
+                    ? { type: 'tween', duration: 0 }
+                    : { type: 'spring', ...(animationConfig as any) }
+
+              const controls = animate(node, webStyle as any, motionAnimationConfig)
+              settlePendingMotionOnFinish(mv, controls)
+            }
+          })
+        )
+        return () => unsubs.forEach((fn) => fn())
+      }
+
+      // single-value path
+      if (!animatedStyle.motionValue) return
+
       return animatedStyle.motionValue.on('change', (value) => {
         const nextStyle = animatedStyle.getStyle(value)
-        const animationConfig = MotionValueStrategy.get(animatedStyle.motionValue)
+        const animationConfig = MotionValueStrategy.get(animatedStyle.motionValue!)
         const node = hostRef.current
 
         const webStyle = getProps({ style: nextStyle }).style
@@ -838,7 +952,8 @@ function createMotionView(defaultTag: string) {
                     ...(animationConfig as any),
                   }
 
-          animate(node, webStyle as any, motionAnimationConfig)
+          const controls = animate(node, webStyle as any, motionAnimationConfig)
+          settlePendingMotionOnFinish(animatedStyle.motionValue!, controls)
         }
       })
     }, [animatedStyle])
@@ -846,7 +961,7 @@ function createMotionView(defaultTag: string) {
     return <Element {...transformedProps} ref={composedRefs} />
   })
 
-  Component['acceptTagProp'] = true
+  Component['acceptRenderProp'] = true
 
   return Component
 }
@@ -869,22 +984,25 @@ function getDiff<T extends Record<string, unknown>>(
   return diff
 }
 
-// motion.dev can't animate to "transparent" - convert it to rgba based on previous value
-// if previous was rgba, use same rgb with alpha 0, otherwise use rgba(0,0,0,0)
+// motion.dev can't animate to "transparent" - convert it to rgba
+// try to extract RGB from previous or next value for smooth color transitions
 function fixTransparentColors(
   diff: Record<string, unknown>,
-  previous: Record<string, unknown> | null
+  previous: Record<string, unknown> | null,
+  next?: Record<string, unknown> | null
 ): Record<string, unknown> {
   let result = diff
   for (const key in diff) {
     if (diff[key] === 'transparent') {
-      const prev = previous?.[key]
       let fixed = 'rgba(0, 0, 0, 0)'
-      if (typeof prev === 'string') {
-        // match rgba(r, g, b, a) or rgb(r, g, b)
-        const rgbaMatch = prev.match(/^rgba?\(([^,]+),\s*([^,]+),\s*([^,)]+)/)
-        if (rgbaMatch) {
-          fixed = `rgba(${rgbaMatch[1]}, ${rgbaMatch[2]}, ${rgbaMatch[3]}, 0)`
+      const candidates = [previous?.[key], next?.[key]]
+      for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate !== 'transparent') {
+          const rgbaMatch = candidate.match(/^rgba?\(([^,]+),\s*([^,]+),\s*([^,)]+)/)
+          if (rgbaMatch) {
+            fixed = `rgba(${rgbaMatch[1]}, ${rgbaMatch[2]}, ${rgbaMatch[3]}, 0)`
+            break
+          }
         }
       }
       if (result === diff) {