@tamagui/animations-reanimated 2.4.5 → 2.5.0

package/src/createAnimations.tsx

@@ -13,6 +13,7 @@ import {
   type UniversalAnimatedNumber,
 } from '@tamagui/core'
 import { ResetPresence, usePresence } from '@tamagui/use-presence'
+import normalizeColor from '@react-native/normalize-colors'
 import React, { forwardRef, useMemo, useRef } from 'react'
 import type { SharedValue } from 'react-native-reanimated'
 import Animated_, {
@@ -73,6 +74,25 @@ const silenceAnimatedComponentDevCheck = (style: unknown) => {
 
 type ReanimatedAnimatedNumber = SharedValue<number>
 
+type AnimationSnapshot = {
+  animated: Record<string, unknown>
+  statics: Record<string, unknown>
+  transforms: Array<Record<string, unknown>>
+  gatedKeys: Record<string, boolean>
+  /**
+   * for each animated key (transform sub-keys as `transform:key`), the value the
+   * previous committed render painted for it, when one exists and is animatable.
+   * the worklet animates a mapper-fresh key FROM its seed instead of snapping —
+   * this is how an enterStyle value painted statically during mount becomes the
+   * start point once the key turns animated. keys with no seed paint their target
+   * directly (a key appearing from nothing has nothing to animate from).
+   */
+  seeds: Record<string, unknown>
+  removedKeys: Record<string, boolean>
+  removeTransform: boolean
+  clearValue: '' | null
+}
+
 /** Spring animation configuration */
 type SpringConfig = {
   type?: 'spring'
@@ -130,10 +150,212 @@ const cloneAnimationValue = (value: unknown): unknown => {
   return value
 }
 
+const cloneStyleRecord = (style: Record<string, unknown>): Record<string, unknown> => {
+  const next: Record<string, unknown> = {}
+  for (const key in style) {
+    next[key] = cloneAnimationValue(style[key])
+  }
+  return next
+}
+
 const cloneTransitionConfig = (config: TransitionConfig): TransitionConfig => {
   return cloneAnimationValue(config) as TransitionConfig
 }
 
+const getAnimatedTransforms = (value: unknown): Array<Record<string, unknown>> => {
+  if (!Array.isArray(value)) return []
+  return value.filter(
+    (item): item is Record<string, unknown> =>
+      item !== null && typeof item === 'object' && !Array.isArray(item)
+  )
+}
+
+const getRemovedAnimatedKeys = (
+  current: Set<string>,
+  previous: Set<string>
+): Record<string, boolean> => {
+  const removedKeys: Record<string, boolean> = {}
+  for (const key of previous) {
+    if (!current.has(key)) removedKeys[key] = true
+  }
+  return removedKeys
+}
+
+// implicit start values for style keys that were never painted (e.g. a key
+// introduced by exitStyle with no base value). most numerics default to 0.
+const getImplicitDefault = (
+  key: string,
+  targetValue: number | string
+): number | string => {
+  'worklet'
+  const value =
+    key === 'opacity' || key === 'scale' || key === 'scaleX' || key === 'scaleY' ? 1 : 0
+  if (typeof targetValue !== 'string') return value
+
+  // reanimated derives a string animation's suffix from its start value. keep
+  // units on implicit starts so fresh `50%` and `90deg` keys interpolate.
+  let suffixIndex = 0
+  while (suffixIndex < targetValue.length) {
+    const character = targetValue[suffixIndex]
+    const code = character.charCodeAt(0)
+    if (
+      (code >= 48 && code <= 57) ||
+      character === '.' ||
+      character === '-' ||
+      character === '+'
+    ) {
+      suffixIndex++
+    } else {
+      break
+    }
+  }
+  return suffixIndex > 0 ? `${value}${targetValue.slice(suffixIndex)}` : value
+}
+
+const COLOR_STYLE_KEYS: Record<string, boolean> = {
+  backgroundColor: true,
+  borderColor: true,
+  borderLeftColor: true,
+  borderRightColor: true,
+  borderTopColor: true,
+  borderBottomColor: true,
+  color: true,
+}
+
+// reanimated can pass either its rgba output or a processed numeric color back
+// as animation history. snapshot targets are normalized on the JS side below;
+// this worklet conversion exists only to validate that in-flight history.
+const toReanimatedColor = (value: unknown): unknown => {
+  'worklet'
+  if (typeof value === 'number') {
+    const color = value >>> 0
+    const alpha = ((color >>> 24) & 255) / 255
+    const red = (color >>> 16) & 255
+    const green = (color >>> 8) & 255
+    const blue = color & 255
+    return `rgba(${red}, ${green}, ${blue}, ${alpha})`
+  }
+  if (typeof value !== 'string') return value
+  const trimmed = value.trim()
+  if (trimmed === 'transparent') return 'rgba(0, 0, 0, 0)'
+  return trimmed
+}
+
+const isReanimatedColorHistory = (value: unknown): boolean => {
+  'worklet'
+  const normalized = toReanimatedColor(value)
+  return typeof normalized === 'string' && normalized.startsWith('rgba(')
+}
+
+const normalizeAnimationColor = (value: unknown): string | undefined => {
+  if (typeof value === 'number') {
+    return toReanimatedColor(value) as string
+  }
+  if (typeof value !== 'string') return
+
+  const color = normalizeColor(value)
+  if (color == null) return
+  const red = Math.round((color & 0xff000000) >>> 24)
+  const green = Math.round((color & 0x00ff0000) >>> 16)
+  const blue = Math.round((color & 0x0000ff00) >>> 8)
+  const alpha = (color & 0x000000ff) / 255
+  return `rgba(${red}, ${green}, ${blue}, ${alpha})`
+}
+
+const buildSnapshot = (
+  animated: Record<string, unknown>,
+  statics: Record<string, unknown>,
+  transforms: Array<Record<string, unknown>>,
+  previousKeys: Set<string>,
+  lastPainted: Record<string, unknown>
+) => {
+  const snapshotAnimated: Record<string, unknown> = {}
+  const snapshotStatics = cloneStyleRecord(statics)
+
+  for (const key in snapshotStatics) {
+    if (!COLOR_STYLE_KEYS[key]) continue
+    const normalized = normalizeAnimationColor(snapshotStatics[key])
+    if (normalized !== undefined) snapshotStatics[key] = normalized
+  }
+
+  for (const key in animated) {
+    if (key === 'transform') continue
+    const value = animated[key]
+    if (COLOR_STYLE_KEYS[key]) {
+      const normalized = normalizeAnimationColor(value)
+      if (normalized === undefined) {
+        // invalid colors must paint plainly. creating a descriptor makes
+        // reanimated's string interpolator emit '<letters>NaN'.
+        snapshotStatics[key] = cloneAnimationValue(value)
+        continue
+      }
+      snapshotAnimated[key] = normalized
+    } else {
+      snapshotAnimated[key] = cloneAnimationValue(value)
+    }
+  }
+
+  const snapshotTransforms = transforms.map(cloneStyleRecord)
+  const keys = new Set(Object.keys(snapshotAnimated))
+  for (const transform of snapshotTransforms) {
+    const key = Object.keys(transform)[0]
+    const value = key ? transform[key] : undefined
+    if (key && (typeof value === 'number' || typeof value === 'string')) {
+      keys.add(`transform:${key}`)
+    }
+  }
+
+  const seeds: Record<string, unknown> = {}
+  for (const key of keys) {
+    let value = lastPainted[key]
+    if (typeof value !== 'number' && typeof value !== 'string') continue
+    if (value === 'auto' || (typeof value === 'string' && value.startsWith('calc'))) {
+      continue
+    }
+    if (COLOR_STYLE_KEYS[key]) value = normalizeAnimationColor(value)
+    if (value !== undefined) seeds[key] = value
+  }
+
+  const gatedKeys: Record<string, boolean> = {}
+  for (const key of keys) gatedKeys[key] = true
+
+  const removedKeys = getRemovedAnimatedKeys(keys, previousKeys)
+  const painted: Record<string, unknown> = {
+    ...snapshotStatics,
+    ...snapshotAnimated,
+  }
+  const staticTransforms = getAnimatedTransforms(snapshotStatics.transform)
+  delete painted.transform
+  for (const transform of staticTransforms) {
+    const key = Object.keys(transform)[0]
+    if (key) painted[`transform:${key}`] = transform[key]
+  }
+  for (const transform of snapshotTransforms) {
+    const key = Object.keys(transform)[0]
+    if (key) painted[`transform:${key}`] = transform[key]
+  }
+
+  return {
+    value: {
+      animated: snapshotAnimated,
+      statics: snapshotStatics,
+      transforms: snapshotTransforms,
+      gatedKeys,
+      seeds,
+      removedKeys,
+      removeTransform: Object.keys(removedKeys).some((key) =>
+        key.startsWith('transform:')
+      ),
+      clearValue: isWeb ? '' : null,
+    },
+    painted,
+    keys,
+  }
+}
+
+const getGatedKeys = (snapshot: AnimationSnapshot): string[] =>
+  Object.keys(snapshot.gatedKeys)
+
 const createReanimatedConfig = (config: TransitionConfig): Record<string, unknown> => {
   'worklet'
   const next: Record<string, unknown> = {}
@@ -156,7 +378,9 @@ const createReanimatedConfig = (config: TransitionConfig): Record<string, unknow
 const applyAnimation = (
   targetValue: number | string,
   config: TransitionConfig,
-  callback?: AnimationCallback
+  callback?: AnimationCallback,
+  seedValue?: number | string,
+  validateStartAsColor = false
 ): number | string => {
   'worklet'
   const delay = config.delay
@@ -177,6 +401,32 @@ const applyAnimation = (
     )
   }
 
+  // reanimated starts a descriptor from its per-view history for the key — the
+  // key's last output value, or the descriptor's own toValue when there is
+  // none (an instant snap). both are wrong for a key that turns animated with
+  // a painted predecessor: history may hold a stale clear-value ('') from when
+  // the key was last removed, which poisons the start value (NaN frames). the
+  // wrapper substitutes the seed for whatever start value reanimated passes.
+  // color history gets the same treatment only when reanimated's own parser
+  // rejects it, preserving valid in-flight values during interruption.
+  if (seedValue !== undefined || validateStartAsColor) {
+    const innerOnStart = animatedValue.onStart
+    animatedValue.onStart = (
+      animation: unknown,
+      value: unknown,
+      timestamp: number,
+      previousAnimation: unknown
+    ) => {
+      'worklet'
+      const startValue = validateStartAsColor
+        ? isReanimatedColorHistory(value)
+          ? toReanimatedColor(value)
+          : (seedValue ?? targetValue)
+        : seedValue
+      innerOnStart(animation, startValue, timestamp, previousAnimation)
+    }
+  }
+
   if (delay && delay > 0) {
     animatedValue = withDelay(delay, animatedValue)
   }
@@ -184,6 +434,53 @@ const applyAnimation = (
   return animatedValue
 }
 
+const animateSnapshotValue = (
+  key: string,
+  implicitKey: string,
+  targetValue: number | string,
+  config: TransitionConfig,
+  previouslyEmitted: boolean,
+  seedValue: unknown,
+  gated: boolean,
+  currentlyExiting: boolean,
+  exitCycleId: number,
+  currentlyCompletingAnimation: boolean,
+  didAnimateCycleId: number,
+  markExitKeyDone: (key: string, cycleId: number, finished: boolean) => void,
+  markDidAnimateKeyDone: (key: string, cycleId: number, finished: boolean) => void,
+  validateStartAsColor = false
+): number | string => {
+  'worklet'
+
+  const cycleGated = gated && (currentlyExiting || currentlyCompletingAnimation)
+  if (!previouslyEmitted && seedValue === undefined && !cycleGated) {
+    return targetValue
+  }
+
+  let callback: AnimationCallback | undefined
+  if (gated && currentlyExiting) {
+    callback = (finished) => {
+      'worklet'
+      runOnJS(markExitKeyDone)(key, exitCycleId, finished ?? false)
+    }
+  } else if (gated && currentlyCompletingAnimation) {
+    callback = (finished) => {
+      'worklet'
+      runOnJS(markDidAnimateKeyDone)(key, didAnimateCycleId, finished ?? false)
+    }
+  }
+
+  return applyAnimation(
+    targetValue,
+    config,
+    callback,
+    previouslyEmitted
+      ? undefined
+      : ((seedValue ?? getImplicitDefault(implicitKey, targetValue)) as number | string),
+    validateStartAsColor
+  )
+}
+
 // =============================================================================
 // Animatable Properties
 // =============================================================================
@@ -271,6 +568,29 @@ const canAnimateProperty = (
   return true
 }
 
+const splitAnimationStyles = (
+  style: Record<string, unknown>,
+  isDark: boolean,
+  disableAnimation: boolean,
+  animateOnly?: string[]
+) => {
+  const animated: Record<string, unknown> = {}
+  const statics: Record<string, unknown> = {}
+
+  for (const key in style) {
+    const value = resolveDynamicValue(style[key], isDark)
+    if (value === undefined) continue
+
+    if (!disableAnimation && canAnimateProperty(key, value, animateOnly)) {
+      animated[key] = cloneAnimationValue(value)
+    } else {
+      statics[key] = cloneAnimationValue(value)
+    }
+  }
+
+  return { animated, statics }
+}
+
 // =============================================================================
 // Animated Components (Web)
 // =============================================================================
@@ -594,6 +914,7 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
         themeName,
         stateRef,
         styleState,
+        onDidAnimate,
       } = animationProps
 
       // State flags
@@ -629,6 +950,28 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
 
       // Get sendExitComplete callback from presence
       const sendExitComplete = presence?.[1]
+      const onDidAnimateRef = useRef(onDidAnimate)
+      useIsomorphicLayoutEffect(() => {
+        onDidAnimateRef.current = onDidAnimate
+      }, [onDidAnimate])
+
+      const didAnimateCycleIdRef = useRef(0)
+      const pendingDidAnimateKeysRef = useRef<Set<string>>(new Set())
+      const didAnimateCompletedRef = useRef(false)
+      const isCompletingAnimationRef = useSharedValue(false)
+      const didAnimateCycleIdShared = useSharedValue(0)
+      const markDidAnimateKeyDone = useEvent(
+        (key: string, cycleId: number, finished: boolean) => {
+          if (!finished || cycleId !== didAnimateCycleIdRef.current) return
+          if (didAnimateCompletedRef.current) return
+          pendingDidAnimateKeysRef.current.delete(key)
+          if (pendingDidAnimateKeysRef.current.size === 0) {
+            didAnimateCompletedRef.current = true
+            isCompletingAnimationRef.value = false
+            onDidAnimateRef.current?.()
+          }
+        }
+      )
 
       // =========================================================================
       // Exit cycle state for deterministic per-property completion tracking
@@ -671,6 +1014,9 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
         exitCycleIdRef.current++
         exitCompletedRef.current = false
         pendingExitKeysRef.current.clear()
+        didAnimateCycleIdRef.current++
+        pendingDidAnimateKeysRef.current.clear()
+        didAnimateCompletedRef.current = true
       }
       // invalidate pending callbacks when exit is canceled/interrupted
       if (justStoppedExiting) {
@@ -682,7 +1028,11 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
       useIsomorphicLayoutEffect(() => {
         isExitingRef.value = isExiting
         exitCycleIdShared.value = exitCycleIdRef.current
-      }, [isExiting, exitCycleIdRef.current])
+        if (justStartedExiting) {
+          isCompletingAnimationRef.value = false
+          didAnimateCycleIdShared.value = didAnimateCycleIdRef.current
+        }
+      }, [isExiting, exitCycleIdRef.current, justStartedExiting])
 
       // track previous exiting state
       React.useEffect(() => {
@@ -692,51 +1042,85 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
       // =========================================================================
       // avoidRerenders: SharedValues for style updates without re-renders
       // =========================================================================
-      const animatedTargetsRef = useSharedValue<Record<string, unknown> | null>(null)
-      const staticTargetsRef = useSharedValue<Record<string, unknown> | null>(null)
-      const transformTargetsRef = useSharedValue<Array<Record<string, unknown>> | null>(
-        null
-      )
+      const committedRenderKeysRef = useRef(new Set<string>())
+      // full painted style of the last committed source (render or emitter):
+      // statics + animated targets, transform sub-keys flattened as `transform:key`.
+      // seeds read from it.
+      const lastPaintedRef = useRef<Record<string, unknown>>({})
+      // per-key first-animated values React keeps painting under the mapper —
+      // see the styles memo below
+      const carryRef = useRef<Record<string, unknown>>({})
 
       // Separate styles into animated and static
-      const { animatedStyles, staticStyles } = useMemo(() => {
-        const animated: Record<string, unknown> = {}
-        const staticStyles: Record<string, unknown> = {}
+      const { animatedStyles, staticStyles, nextCarry } = useMemo(() => {
         const animateOnly = props.animateOnly as string[] | undefined
+        const { animated, statics } = splitAnimationStyles(
+          style as Record<string, unknown>,
+          isDark,
+          disableAnimation,
+          animateOnly
+        )
 
-        for (const key in style) {
-          const rawValue = (style as Record<string, unknown>)[key]
-          const value = resolveDynamicValue(rawValue, isDark)
-
-          if (value === undefined) continue
-
-          if (disableAnimation) {
-            staticStyles[key] = cloneAnimationValue(value)
-            continue
-          }
-
-          if (canAnimateProperty(key, value, animateOnly)) {
-            animated[key] = cloneAnimationValue(value)
-          } else {
-            staticStyles[key] = cloneAnimationValue(value)
-          }
+        // every animated key keeps its FIRST animated value in React's style for
+        // as long as it stays animated. the value never changes across renders,
+        // so React's per-key style diff never touches the key again and the
+        // mapper's inline writes survive every commit — reanimated's Fabric
+        // commit hook provides this guarantee on native, web has no equivalent.
+        // during enter the carry is the enterStyle (the mapper animates over it);
+        // a key appearing post-mount (a just-measured height) paints its value in
+        // the same commit the mapper first sees it, a frame before the mapper's
+        // first write.
+        // derive from committed state. mutating carryRef during render leaks
+        // abandoned concurrent renders into later commits.
+        const nextCarry = cloneStyleRecord(carryRef.current)
+        for (const key in nextCarry) {
+          if (!(key in animated)) delete nextCarry[key]
         }
-
-        // During mount, include animated values in static to prevent flicker
-        if (isMounting) {
-          for (const key in animated) {
-            staticStyles[key] = animated[key]
+        for (const key in animated) {
+          if (!(key in nextCarry)) {
+            nextCarry[key] = cloneAnimationValue(animated[key])
           }
+          statics[key] = nextCarry[key]
         }
 
-        return { animatedStyles: animated, staticStyles }
-      }, [disableAnimation, style, isDark, isMounting, props.animateOnly])
+        return { animatedStyles: animated, staticStyles: statics, nextCarry }
+      }, [disableAnimation, style, isDark, props.animateOnly])
+
+      const renderSnapshot = useMemo(
+        () =>
+          buildSnapshot(
+            animatedStyles,
+            staticStyles,
+            getAnimatedTransforms(animatedStyles.transform),
+            committedRenderKeysRef.current,
+            lastPaintedRef.current
+          ),
+        [animatedStyles, staticStyles]
+      )
+      const renderSnapshotRef = useSharedValue<AnimationSnapshot>({
+        animated: {},
+        statics: {},
+        transforms: [],
+        gatedKeys: {},
+        seeds: {},
+        removedKeys: {},
+        removeTransform: false,
+        clearValue: isWeb ? '' : null,
+      })
+      const emitterSnapshotRef = useSharedValue<AnimationSnapshot | null>(null)
+      const emitterKeysRef = useRef<Set<string> | null>(null)
+
+      useIsomorphicLayoutEffect(() => {
+        carryRef.current = nextCarry
+        committedRenderKeysRef.current = renderSnapshot.keys
+        lastPaintedRef.current = renderSnapshot.painted
+      }, [nextCarry, renderSnapshot])
 
       // reconcile the emitter latch with real re-renders.
       //
       // the avoidReRenders fast path lets a pure pseudo change (hover/press/focus) push
       // styles straight to the worklet via useStyleEmitter with no React commit — it sets
-      // animatedTargetsRef. the worklet then treats `animatedTargetsRef !== null` as a
+      // emitterSnapshotRef. the worklet then treats `emitterSnapshotRef !== null` as a
       // permanent latch: once the emitter has fired even once, it reads its last-emitted
       // snapshot and IGNORES `animatedStyles` from every subsequent re-render. so a base
       // style that changes through React (e.g. a row's `backgroundColor` flipping with an
@@ -763,14 +1147,39 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
       const pseudoActiveRef = useRef(false)
       const isExitingJSRef = useRef(false)
       isExitingJSRef.current = isExiting
+      // the committed render is the worklet's source of truth whenever the emitter is not
+      // latched, so every render must publish its snapshot — not just the renders that drop
+      // a latch. animated keys live only in this snapshot after mount (staticStyles carries
+      // them during mount only), so a render that never publishes leaves the worklet reading
+      // an empty snapshot and the animated properties never reach the screen at all.
+      const publishedSnapshotRef = useRef<object | null>(null)
       useIsomorphicLayoutEffect(() => {
-        if (
-          (isExiting || !pseudoActiveRef.current) &&
-          animatedTargetsRef.value !== null
-        ) {
-          animatedTargetsRef.value = null
-          staticTargetsRef.value = null
-          transformTargetsRef.value = null
+        const droppingLatch =
+          (isExiting || !pseudoActiveRef.current) && emitterSnapshotRef.value !== null
+        // when the latch drops, keys the emitter owned that this render no longer has must
+        // be cleared too, otherwise reanimated keeps painting the stale emitted value
+        const emitterKeys = droppingLatch ? emitterKeysRef.current : null
+
+        if (droppingLatch || publishedSnapshotRef.current !== renderSnapshot.value) {
+          const removedKeys = emitterKeys
+            ? {
+                ...renderSnapshot.value.removedKeys,
+                ...getRemovedAnimatedKeys(renderSnapshot.keys, emitterKeys),
+              }
+            : renderSnapshot.value.removedKeys
+          renderSnapshotRef.value = {
+            ...renderSnapshot.value,
+            removedKeys,
+            removeTransform: Object.keys(removedKeys).some((key) =>
+              key.startsWith('transform:')
+            ),
+          }
+          publishedSnapshotRef.current = renderSnapshot.value
+        }
+
+        if (droppingLatch) {
+          emitterSnapshotRef.value = null
+          emitterKeysRef.current = null
         }
       })
 
@@ -828,9 +1237,6 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
           // this emitter snapshot is a transient override to keep latched or a base it can drop.
           pseudoActiveRef.current = pseudoActive === true
           const animateOnly = props.animateOnly as string[] | undefined
-          const animated: Record<string, unknown> = {}
-          const statics: Record<string, unknown> = {}
-          const transforms: Array<Record<string, unknown>> = []
 
           // effectiveTransition is computed in createComponent based on entering/exiting pseudo states
           // rebuild config whenever transition changes (entering OR exiting pseudo states)
@@ -851,41 +1257,23 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
             isHydrating: configRef.value.isHydrating,
           }
 
-          for (const key in nextStyle) {
-            const rawValue = nextStyle[key]
-            const value = resolveDynamicValue(rawValue, isDark)
-
-            if (value == undefined) continue
-
-            if (configRef.value.disableAnimation) {
-              statics[key] = cloneAnimationValue(value)
-              continue
-            }
-
-            if (key === 'transform' && Array.isArray(value)) {
-              for (const t of value as Record<string, unknown>[]) {
-                if (t && typeof t === 'object') {
-                  const tKey = Object.keys(t)[0]
-                  const tVal = t[tKey]
-                  if (typeof tVal === 'number' || typeof tVal === 'string') {
-                    transforms.push(cloneAnimationValue(t) as Record<string, unknown>)
-                  }
-                }
-              }
-              continue
-            }
-
-            if (canAnimateProperty(key, value, animateOnly)) {
-              animated[key] = cloneAnimationValue(value)
-            } else {
-              statics[key] = cloneAnimationValue(value)
-            }
-          }
-
-          // update shared values - on web, the mapper watches these if passed in dependencies
-          animatedTargetsRef.value = animated
-          staticTargetsRef.value = statics
-          transformTargetsRef.value = transforms
+          const previousKeys = emitterKeysRef.current ?? committedRenderKeysRef.current
+          const { animated, statics } = splitAnimationStyles(
+            nextStyle,
+            isDark,
+            configRef.value.disableAnimation,
+            animateOnly
+          )
+          const snapshot = buildSnapshot(
+            animated,
+            statics,
+            getAnimatedTransforms(animated.transform),
+            previousKeys,
+            lastPaintedRef.current
+          )
+          emitterSnapshotRef.value = snapshot.value
+          emitterKeysRef.current = snapshot.keys
+          lastPaintedRef.current = snapshot.painted
 
           if (
             process.env.NODE_ENV === 'development' &&
@@ -895,7 +1283,7 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
             console.info('[animations-reanimated] useStyleEmitter update', {
               animated,
               statics,
-              transforms,
+              transforms: snapshot.value.transforms,
             })
           }
         }
@@ -905,37 +1293,54 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
       // This must happen BEFORE useAnimatedStyle runs so callbacks have a populated set
       const exitKeysRegistered = useRef(false)
       if (justStartedExiting && sendExitComplete) {
-        const exitKeys: string[] = []
-        const animateOnly = props.animateOnly as string[] | undefined
+        const exitKeys = getGatedKeys(renderSnapshot.value)
+        pendingExitKeysRef.current = new Set(exitKeys)
+        exitKeysRegistered.current = exitKeys.length > 0
+      }
 
-        // regular animated properties
-        for (const key in animatedStyles) {
-          if (key === 'transform') continue
-          if (canAnimateProperty(key, animatedStyles[key], animateOnly)) {
-            exitKeys.push(key)
-          }
-        }
+      // onDidAnimate is an internal completion hook used by components that
+      // need to retain content through an in-place style transition. register
+      // the exact keys that can animate before publishing the cycle to the
+      // worklet; shared values are only written from the layout effect, never
+      // from the mapper that reads them.
+      const previousDidAnimateStyleRef = useRef<string | null>(null)
+      const didAnimateStyle = onDidAnimate ? JSON.stringify(style) : null
+      const previousDidAnimateStyle = previousDidAnimateStyleRef.current
+      const shouldRegisterDidAnimate =
+        didAnimateStyle !== null &&
+        previousDidAnimateStyle !== null &&
+        previousDidAnimateStyle !== didAnimateStyle &&
+        !isExiting &&
+        !isEntering &&
+        !justFinishedEntering
+      const didAnimateKeys = shouldRegisterDidAnimate
+        ? getGatedKeys(renderSnapshot.value)
+        : []
 
-        // transform sub-keys (filter by animateOnly if specified)
-        const transforms = animatedStyles.transform
-        if (transforms && Array.isArray(transforms)) {
-          for (const t of transforms) {
-            if (!t) continue
-            const tKey = Object.keys(t)[0]
-            if (tKey) {
-              // check animateOnly filter for transform sub-keys
-              if (animateOnly && !animateOnly.includes(tKey)) {
-                continue
-              }
-              exitKeys.push(`transform:${tKey}`)
-            }
-          }
+      useIsomorphicLayoutEffect(() => {
+        if (didAnimateStyle === null) {
+          previousDidAnimateStyleRef.current = null
+          isCompletingAnimationRef.value = false
+          return
         }
 
-        // register keys for this cycle
-        pendingExitKeysRef.current = new Set(exitKeys)
-        exitKeysRegistered.current = exitKeys.length > 0
-      }
+        // only a committed render may advance the authoritative cycle. the
+        // captured previous value prevents StrictMode's repeated effect from
+        // registering the same transition twice.
+        const previousStyleStillCurrent =
+          previousDidAnimateStyleRef.current === previousDidAnimateStyle
+        previousDidAnimateStyleRef.current = didAnimateStyle
+        if (!shouldRegisterDidAnimate || !previousStyleStillCurrent) return
+
+        const cycleId = ++didAnimateCycleIdRef.current
+        pendingDidAnimateKeysRef.current = new Set(didAnimateKeys)
+        didAnimateCompletedRef.current = didAnimateKeys.length === 0
+        isCompletingAnimationRef.value = didAnimateKeys.length > 0
+        didAnimateCycleIdShared.value = cycleId
+        if (didAnimateKeys.length === 0) {
+          onDidAnimateRef.current?.()
+        }
+      }, [didAnimateStyle, shouldRegisterDidAnimate])
 
       // handle zero-animation case in effect (after render commit)
       React.useEffect(() => {
@@ -950,130 +1355,153 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
         }
       }, [justStartedExiting, sendExitComplete])
 
+      // the worklet's own record of which animated keys it has emitted (mirrors
+      // reanimated's per-view style history, which resets whenever a key leaves
+      // the output). a key not in here is fresh to the mapper no matter what
+      // React has committed — several renders can coalesce into one mapper run.
+      // mutated in place from the worklet; never watched, so writes don't
+      // retrigger the mapper.
+      const mapperStateRef = useSharedValue<{ emitted: Record<string, boolean> }>({
+        emitted: {},
+      })
       // Create animated style
       const animatedStyle = useAnimatedStyle(
         () => {
           'worklet'
 
-          if (disableAnimation || isHydrating) {
+          const mapperState = mapperStateRef.value
+          const config = configRef.value
+          if (config.disableAnimation || config.isHydrating) {
+            // the empty return wipes reanimated's per-key history, so ours
+            // resets with it
+            mapperState.emitted = {}
             return {}
           }
 
+          const previouslyEmitted = mapperState.emitted
+          const emitted: Record<string, boolean> = {}
+
           const result: Record<string, any> = {}
-          const config = configRef.value
 
           // Check if we have avoidRerenders updates from useStyleEmitter
-          const emitterAnimated = animatedTargetsRef.value
-          const emitterStatic = staticTargetsRef.value
-          const emitterTransforms = transformTargetsRef.value
-          const hasEmitterUpdates = emitterAnimated !== null
+          const emitterSnapshot = emitterSnapshotRef.value
+          const snapshot = emitterSnapshot ?? renderSnapshotRef.value
 
-          // Use emitter values if available, otherwise use React state values.
+          // Use emitter values if available, otherwise use the committed render snapshot.
           // statics must fall back to the render's staticStyles (not {}): once an
           // emitter snapshot has applied static keys, reanimated never unsets
           // them, so after the latch drops a stale emitted value (e.g. a border
           // color that missed animateOnly) would keep painting over the fresh
           // style prop forever
-          const animatedValues = hasEmitterUpdates ? emitterAnimated! : animatedStyles
-          const staticValues = hasEmitterUpdates ? emitterStatic! : staticStyles
+          const animatedValues = snapshot.animated
+          const staticValues = snapshot.statics
 
           // read exit state from shared values
           const currentlyExiting = isExitingRef.value
           const currentCycleId = exitCycleIdShared.value
+          const currentlyCompletingAnimation = isCompletingAnimationRef.value
+          const currentDidAnimateCycleId = didAnimateCycleIdShared.value
 
           // Include static values from emitter (for hover/press style changes)
           for (const key in staticValues) {
             result[key] = staticValues[key]
           }
+          for (const key in snapshot.removedKeys) {
+            if (!key.startsWith('transform:') && !(key in staticValues)) {
+              result[key] = snapshot.clearValue
+            }
+          }
 
           // Animate regular properties
           for (const key in animatedValues) {
             if (key === 'transform') continue
 
             const targetValue = animatedValues[key]
-            const propConfig = config.propertyConfigs[key] ?? config.baseConfig
-
-            // create callback for exit tracking
-            let callback: AnimationCallback | undefined
-            if (currentlyExiting) {
-              const capturedKey = key
-              const capturedCycleId = currentCycleId
-              callback = (finished) => {
-                'worklet'
-                runOnJS(markExitKeyDone)(capturedKey, capturedCycleId, finished ?? false)
-              }
+            emitted[key] = true
+            if (typeof targetValue !== 'number' && typeof targetValue !== 'string') {
+              result[key] = targetValue
+              continue
             }
-
-            result[key] = applyAnimation(targetValue as number, propConfig, callback)
+            result[key] = animateSnapshotValue(
+              key,
+              key,
+              targetValue,
+              config.propertyConfigs[key] ?? config.baseConfig,
+              !!previouslyEmitted[key],
+              snapshot.seeds[key],
+              !!snapshot.gatedKeys[key],
+              currentlyExiting,
+              currentCycleId,
+              currentlyCompletingAnimation,
+              currentDidAnimateCycleId,
+              markExitKeyDone,
+              markDidAnimateKeyDone,
+              !!COLOR_STYLE_KEYS[key]
+            )
           }
 
           // Handle transforms
-          const transforms = hasEmitterUpdates
-            ? emitterTransforms
-            : animatedStyles.transform
+          const transforms = snapshot.transforms
 
           // Animate transform properties with validation
-          if (transforms && Array.isArray(transforms)) {
+          if (transforms.length > 0 || snapshot.removeTransform) {
             const validTransforms: Record<string, unknown>[] = []
 
             for (const t of transforms) {
               if (!t) continue
               const keys = Object.keys(t)
               if (keys.length === 0) continue
-              const value = t[keys[0]]
+              const transformKey = keys[0]
+              const value = t[transformKey]
               if (typeof value === 'number' || typeof value === 'string') {
-                const transformKey = Object.keys(t)[0]
-                const targetValue = t[transformKey]
                 const propConfig =
                   config.propertyConfigs[transformKey] ?? config.baseConfig
 
-                // create callback for exit tracking (transform sub-key)
-                let callback: AnimationCallback | undefined
-                if (currentlyExiting) {
-                  const capturedKey = `transform:${transformKey}`
-                  const capturedCycleId = currentCycleId
-                  callback = (finished) => {
-                    'worklet'
-                    runOnJS(markExitKeyDone)(
-                      capturedKey,
-                      capturedCycleId,
-                      finished ?? false
-                    )
-                  }
-                }
-
+                const subKey = `transform:${transformKey}`
+                emitted[subKey] = true
                 validTransforms.push({
-                  [transformKey]: applyAnimation(
-                    targetValue as number,
+                  [transformKey]: animateSnapshotValue(
+                    subKey,
+                    transformKey,
+                    value,
                     propConfig,
-                    callback
+                    !!previouslyEmitted[subKey],
+                    snapshot.seeds[subKey],
+                    !!snapshot.gatedKeys[subKey],
+                    currentlyExiting,
+                    currentCycleId,
+                    currentlyCompletingAnimation,
+                    currentDidAnimateCycleId,
+                    markExitKeyDone,
+                    markDidAnimateKeyDone
                   ),
                 })
+              } else {
+                validTransforms.push(t)
               }
             }
 
-            if (validTransforms.length > 0) {
+            if (validTransforms.length > 0 || !('transform' in staticValues)) {
               result.transform = validTransforms
             }
           }
 
+          mapperState.emitted = emitted
+
           return result
         },
         isWeb
           ? [
-              animatedStyles,
-              staticStyles,
-              baseConfig,
-              propertyConfigs,
-              disableAnimation,
-              isHydrating,
-              // pass SharedValues so the mapper watches them on web (no babel plugin)
-              animatedTargetsRef,
-              staticTargetsRef,
-              transformTargetsRef,
+              // pass SharedValues so the stable mapper watches them on web (no babel plugin)
+              renderSnapshotRef,
+              emitterSnapshotRef,
+              configRef,
               isExitingRef,
               exitCycleIdShared,
               markExitKeyDone,
+              isCompletingAnimationRef,
+              didAnimateCycleIdShared,
+              markDidAnimateKeyDone,
             ]
           : undefined
       )
@@ -1097,6 +1525,9 @@ export function createAnimations<A extends Record<string, TransitionConfig>>(
         })
       }
 
+      // staticStyles carries animated keys only while mounting or on a key's
+      // first post-mount appearance; after that the mapper owns them and the
+      // commit bridge above keeps React commits from wiping its inline writes.
       return {
         style: [staticStyles, animatedStyle],
       }