@tamagui/animations-react-native 3.0.0-beta.922.1 → 3.0.0

package/src/{createAnimations.tsx → createAnimations.native.tsx}

@@ -1,9 +1,18 @@
-import { getEffectiveAnimation, normalizeTransition } from '@tamagui/animation-helpers'
+import {
+  easingToBezier,
+  forAnimationState,
+  getTransitionForKey,
+  resolveTransition,
+  type AnimationsConfig,
+  type ResolvedEntry,
+  type ResolvedTransition,
+} from '@tamagui/animation-helpers'
 import { isWeb, useIsomorphicLayoutEffect } from '@tamagui/constants'
 import { ResetPresence, usePresence } from '@tamagui/use-presence'
 import type {
   AnimatedNumberStrategy,
   AnimationDriverWithAnimatedNumbers,
+  NativeTextMetrics,
   TransitionProp,
   UniversalAnimatedNumber,
   UseAnimatedNumberReaction,
@@ -12,13 +21,9 @@ import type {
 import { useEvent } from '@tamagui/web'
 import { useThemeWithState } from '@tamagui/web/internal-runtime'
 import React from 'react'
-import {
-  Animated,
-  processColor,
-  type ColorValue,
-  type Text,
-  type View,
-} from 'react-native'
+import { Animated, Easing, processColor, TextInput, type ColorValue } from 'react-native'
+
+import type { CreateAnimationsOptions } from './types'
 
 // detect Fabric (New Architecture) — Paper doesn't support native driver for all style keys
 const isFabric =
@@ -33,27 +38,17 @@ const resolveDynamicValue = (value: any, isDark: boolean): any => {
   return value
 }
 
-type AnimationsConfig<A extends object = any> = { [Key in keyof A]: AnimationConfig }
-
-type SpringConfig = { type?: 'spring' } & Partial<
-  Pick<
-    Animated.SpringAnimationConfig,
-    | 'delay'
-    | 'bounciness'
-    | 'damping'
-    | 'friction'
-    | 'mass'
-    | 'overshootClamping'
-    | 'speed'
-    | 'stiffness'
-    | 'tension'
-    | 'velocity'
-  >
->
-
-type TimingConfig = { type: 'timing' } & Partial<Animated.TimingAnimationConfig>
-
-type AnimationConfig = SpringConfig | TimingConfig
+/** what `getAnimationConfig` hands to `Animated.spring` / `Animated.timing` */
+type AnimationConfig =
+  | ({ type: 'spring'; delay?: number } & Partial<
+      Pick<
+        Animated.SpringAnimationConfig,
+        'damping' | 'mass' | 'overshootClamping' | 'stiffness' | 'velocity'
+      >
+    >)
+  | ({ type: 'timing'; delay?: number } & Partial<
+      Pick<Animated.TimingAnimationConfig, 'duration' | 'easing'>
+    >)
 
 const animatedStyleKey = {
   transform: true,
@@ -70,8 +65,10 @@ const colorStyleKey = {
   borderBottomColor: true,
 }
 
-// layout dimension keys. these must run on the JS driver (useNativeDriver:false)
-// because the native animated module can't drive layout props.
+// layout dimensions. the native animated module has no whitelist entry for any
+// of them, so a node animating one runs its whole Animated graph on the JS
+// driver (useNativeDriver:false): Fabric cannot mix native- and JS-driven
+// values on one node.
 const layoutStyleKey = {
   height: true,
   width: true,
@@ -81,18 +78,67 @@ const layoutStyleKey = {
   maxWidth: true,
 }
 
+// text metrics have no whitelist entry either, but unlike a height they sit on
+// nearly every Text, so being covered by a broad `transition="medium"` must not
+// be enough to take the node off the native driver: an opacity fade over text
+// whose size is not changing would then run in JS. they join the Animated graph
+// only while they are actually moving, and the node's driver follows them.
+const textMetricStyleKey = {
+  fontSize: true,
+  lineHeight: true,
+}
+
+const jsDriverStyleKey = { ...layoutStyleKey, ...textMetricStyleKey }
+
 function hasAnimatedLayoutKey(
   style: Record<string, any>,
   isDark: boolean,
-  animateOnly?: string[]
+  resolved: ResolvedTransition
 ) {
   for (const key in layoutStyleKey) {
-    if (animateOnly && !animateOnly.includes(key)) continue
+    if (!getTransitionForKey(resolved, key)) continue
     if (typeof resolveDynamicValue(style[key], isDark) === 'number') return true
   }
   return false
 }
 
+// A numeric authored lineHeight is a RATIO of the resolved font size, not a
+// length. Core finalizes the destination to fontSize * ratio and reports the
+// ratio back on `nativeTextMetrics`, so the painted leading has to be
+// fontSize * ratio on EVERY frame, not only at the destination. This driver
+// gets that exactly by never animating the leading itself: it animates the
+// font size and the ratio, and paints their product as one Animated node.
+// An absolute px leading, and any raw react-native style, keeps its own value
+// and animates as an ordinary numeric key.
+const getLeadingRatio = (metrics: { lineHeight?: unknown } | undefined | null) => {
+  const ratio = metrics?.lineHeight
+  return typeof ratio === 'number' && Number.isFinite(ratio) && ratio >= 0
+    ? ratio
+    : undefined
+}
+
+// the product needs both factors as numbers in the style it is painting into.
+const paintsLeadingProduct = (
+  style: Record<string, any>,
+  ratio: number | undefined
+): ratio is number =>
+  ratio !== undefined &&
+  typeof style.fontSize === 'number' &&
+  typeof style.lineHeight === 'number'
+
+// a leading multiplied off an ANCESTOR's live font size: this node has none of
+// its own, core reports the ratio, and react-native inherits the size itself.
+const inheritedFontSizeNode = (
+  style: Record<string, any>,
+  ratio: number | undefined,
+  inheritedText: { fontSize: unknown; driver: string } | null | undefined
+) =>
+  ratio !== undefined &&
+  typeof style.fontSize !== 'number' &&
+  inheritedText?.driver === 'react-native'
+    ? (inheritedText.fontSize as Animated.Value)
+    : undefined
+
 // Only colors accepted by RN's own parser can enter interpolation. CSS-wide
 // keywords, unresolved tokens, var()/calc(), and empty strings otherwise reach
 // createInterpolationFromStringOutputRange / mapStringToNumericComponents and
@@ -116,13 +162,15 @@ const costlyToAnimateStyleKey = {
   ...colorStyleKey,
 }
 
-type CreateAnimationsOptions = {
-  // override native driver detection (default: auto-detect Fabric)
-  useNativeDriver?: boolean
-}
-
-export const AnimatedView: Animated.AnimatedComponent<typeof View> = Animated.View
-export const AnimatedText: Animated.AnimatedComponent<typeof Text> = Animated.Text
+export const AnimatedView: typeof Animated.View = Animated.View
+export const AnimatedText: typeof Animated.Text = Animated.Text
+// a TextInput never inherits font size from an ancestor Text on native, so the
+// binding hook has to hand it a host that accepts animated nodes of its own.
+// built on first use: the compiler evaluates tamagui.config.ts against a
+// react-native stub whose Animated cannot make one, and never binds any text.
+let animatedTextInput:
+  | ReturnType<typeof Animated.createAnimatedComponent<typeof TextInput>>
+  | undefined
 
 export function useAnimatedNumber(
   initial: number
@@ -161,7 +209,12 @@ export function useAnimatedNumber(
         : undefined
 
       if (type === 'direct') {
+        state.current.composite?.stop()
+        state.current.composite = null
         val.setValue(next)
+        // a direct set finishes the moment it lands. not calling back stranded
+        // everything waiting on it (sheet snap, presence completion).
+        onFinish?.()
       } else if (type === 'spring') {
         state.current.composite?.stop()
         const composite = Animated.spring(val, {
@@ -263,6 +316,33 @@ export function createAnimations<A extends AnimationsConfig>(
     useAnimatedNumbersStyle,
     usePresence,
     ResetPresence,
+
+    // binds a descendant that has no font size of its own to the ancestor's
+    // animated one. no clock here: the font size node is the ancestor's, and a
+    // ratio leading is a multiplication of it, so both land on the same frame.
+    useTextMetrics: ({ inheritedText, lineHeight }) => {
+      const node =
+        inheritedText?.driver === 'react-native'
+          ? (inheritedText.fontSize as Animated.Value)
+          : null
+      // an absolute or `normal` leading still needs the font size bound, it
+      // just keeps the leading the caller already resolved.
+      const ratio = typeof lineHeight === 'number' ? lineHeight : null
+      const style = React.useMemo(
+        () =>
+          node
+            ? ratio === null
+              ? { fontSize: node }
+              : { fontSize: node, lineHeight: Animated.multiply(node, ratio) }
+            : null,
+        [node, ratio]
+      )
+      const textChannel = inheritedText ?? null
+      if (!style) return { style: null, textChannel }
+      animatedTextInput ||= Animated.createAnimatedComponent(TextInput)
+      return { style, textChannel, Text: AnimatedText, TextInput: animatedTextInput }
+    },
+
     useAnimations: ({
       props,
       onTransition,
@@ -270,7 +350,9 @@ export function createAnimations<A extends AnimationsConfig>(
       componentState,
       presence,
       stateRef,
+      styleState,
       useStyleEmitter,
+      inheritedText,
     }) => {
       const isDisabled = isWeb && componentState.unmounted === true
       const isExiting = presence?.[0] === false
@@ -286,12 +368,86 @@ export function createAnimations<A extends AnimationsConfig>(
           phase === 'end' ? { phase, cause, finished } : { phase, cause }
         )
       }
+      // createComponent merges a colocated `transition` out of the active
+      // pseudo style (`enterStyle={{ opacity: 0, transition: '200ms' }}`), so
+      // this is the one that applies right now, not the base prop.
+      const effectiveTransition = (styleState?.effectiveTransition ?? props.transition) as
+        | TransitionProp
+        | null
+        | undefined
+
       const [, themeState] = useThemeWithState({})
       // Check scheme first, then fall back to checking theme name for 'dark'
       const isDark = themeState?.scheme === 'dark' || themeState?.name?.startsWith('dark')
 
       /** store Animated value of each key e.g: color: AnimatedValue */
       const animateStyles = React.useRef<Record<string, Animated.Value>>({})
+      // a ratio leading animates the RATIO, never the leading, and paints
+      // fontSize * ratio as one node. the ratio is not a style key, so it lives
+      // outside animateStyles (which the stale-key sweep and the emitter's
+      // structural-change check both treat as the rendered style's own keys).
+      const leadingRatioValue = React.useRef<Animated.Value | null>(null)
+      const leadingRatioRef = React.useRef<number | undefined>(undefined)
+      // whether the style React last committed paints the derived product. the
+      // emitter can only re-target existing Animated.Values, so a pass that
+      // disagrees with this has to force a commit to swap the node itself.
+      const paintsDerivedLeading = React.useRef(false)
+      // this subtree's live font size, published for descendants that inherit
+      // it. the channel's identity IS the node's, so a consumer that keeps the
+      // same channel keeps the same derived node.
+      const textChannelRef = React.useRef<{ fontSize: unknown; driver: string } | null>(
+        null
+      )
+      // core reports a numeric (ratio) leading on nativeTextMetrics; a px length
+      // and 'normal' are reported as themselves and stay independent keys.
+      leadingRatioRef.current = getLeadingRatio(styleState?.nativeTextMetrics)
+      // the text metrics the last pass painted, so the next one can tell a real
+      // change from a value that is simply present. a metric only joins the
+      // Animated graph while it is moving (see textMetricStyleKey), which is
+      // what keeps an ordinary opacity or transform animation over unchanged
+      // text on the native driver.
+      const paintedTextRef = React.useRef<{
+        fontSize?: unknown
+        lineHeight?: unknown
+        ratio?: number
+      }>({})
+      // a value already in the graph keeps moving until it arrives, so a
+      // re-render mid-flight never drops it back to a static style and snaps.
+      // the first pass has painted nothing yet, so nothing is moving there
+      // either: the metrics land as plain numbers and the node mounts on the
+      // native driver.
+      const movesTextValue = (key: 'fontSize' | 'lineHeight', target: unknown) => {
+        if (typeof target !== 'number') return false
+        const node = animateStyles.current[key]
+        const last = node ? (node['_value'] as unknown) : paintedTextRef.current[key]
+        return last !== undefined && last !== target
+      }
+      const movesLeadingRatio = (ratio: number | undefined) => {
+        if (ratio === undefined) return false
+        const node = leadingRatioValue.current
+        const last = node ? (node['_value'] as number) : paintedTextRef.current.ratio
+        return last !== undefined && last !== ratio
+      }
+      // the font size descendants read as this node's live size. it outlives
+      // any one animation: dropping it whenever the size came to rest would
+      // swap every descendant between Text and Animated.Text, remounting their
+      // subtrees, and a TextInput's focus and contents with them, every time an
+      // animation started or finished.
+      const fontSizeNode = React.useRef<Animated.Value | null>(null)
+      const animatedValueFor = (key: string) => {
+        const painted = animateStyles.current[key]
+        if (painted) return painted
+        if (key === 'fontSize' && fontSizeNode.current) return fontSizeNode.current
+        // a metric that was at rest is out of the graph, so the value it
+        // rejoins with has to start at what the last pass painted: a fresh
+        // Animated.Value starts AT its target, and would snap the metric.
+        if (textMetricStyleKey[key])
+          return new Animated.Value(paintedTextRef.current[key] as number)
+        return undefined
+      }
+      const leadingRatioValueFrom = () =>
+        leadingRatioValue.current ??
+        new Animated.Value(paintedTextRef.current.ratio as number)
       const animatedTranforms = React.useRef<{ [key: string]: Animated.Value }[]>([])
       const animationsState = React.useRef(
         new WeakMap<
@@ -332,9 +488,6 @@ export function createAnimations<A extends AnimationsConfig>(
         exitCycleIdRef.current++
       }
 
-      const animateOnly = (props.animateOnly as string[]) || []
-      const hasTransitionOnly = !!props.animateOnly
-
       // Track if we just finished entering (transition from entering to not entering)
       // must be declared before args array that uses justFinishedEntering
       const isEntering = !!componentState.unmounted
@@ -346,12 +499,14 @@ export function createAnimations<A extends AnimationsConfig>(
 
       const args = [
         JSON.stringify(style),
+        JSON.stringify(effectiveTransition),
         componentState,
         isExiting,
         !!onTransition,
         isDark,
         justFinishedEntering,
-        hasTransitionOnly,
+        leadingRatioRef.current,
+        inheritedText,
       ]
 
       const res = React.useMemo(() => {
@@ -366,17 +521,46 @@ export function createAnimations<A extends AnimationsConfig>(
             ? 'enter'
             : 'default'
 
+        // which style keys animate at all is the transition's own decision, so
+        // a property list narrows this the same way it narrows css
+        const resolved = forAnimationState(
+          resolveTransition(effectiveTransition, { animations }),
+          animationState
+        )
+
         const nonAnimatedStyle = {}
-        // animatedStyle owns every Animated.Value on the node. Fabric cannot mix
-        // native- and JS-driven values inside that shared graph, so one layout
-        // animation makes the whole node use the JS driver.
-        const useNativeDriverForNode =
-          nativeDriver &&
-          !hasAnimatedLayoutKey(
-            style,
-            isDark,
-            hasTransitionOnly ? animateOnly : undefined
-          )
+        // the leading is derived only while something can actually move it.
+        // when neither key is covered by the transition both fall through to
+        // nonAnimatedStyle and land together in one commit, which is already
+        // coherent and keeps the node on the native driver.
+        const paintedRatio = leadingRatioRef.current
+        const paintsProduct = paintsLeadingProduct(style, paintedRatio)
+        const movesFontSize = movesTextValue('fontSize', style.fontSize)
+        const movesLeading = paintsProduct
+          ? movesLeadingRatio(paintedRatio)
+          : movesTextValue('lineHeight', style.lineHeight)
+        // a metric that has arrived leaves the graph here rather than in the
+        // sweep at the end of the pass, so the node goes back to the native
+        // driver in the same commit that stops moving it. the same three
+        // conditions as that sweep: an exit and a latched pseudo both still own
+        // the keys they are painting.
+        if (!isExiting && !isDisabled && !pseudoActiveRef.current) {
+          if (!movesFontSize) delete animateStyles.current.fontSize
+          if (!movesLeading) delete animateStyles.current.lineHeight
+        }
+
+        // a font size a transition can move is published to descendants whether
+        // or not it happens to be moving right now, so their host component
+        // does not change under them when it starts.
+        if (
+          isDisabled ||
+          typeof style.fontSize !== 'number' ||
+          !getTransitionForKey(resolved, 'fontSize')
+        ) {
+          fontSizeNode.current = null
+        } else if (!fontSizeNode.current) {
+          fontSizeNode.current = new Animated.Value(style.fontSize)
+        }
 
         // track which animated keys/transforms the incoming style actually
         // carries this pass, so entries that left the style can be dropped
@@ -386,6 +570,34 @@ export function createAnimations<A extends AnimationsConfig>(
         let sawTransform = false
         let transformCount = 0
 
+        const derivesLeading =
+          !isDisabled &&
+          paintsProduct &&
+          (movesFontSize || movesLeading) &&
+          (!!getTransitionForKey(resolved, 'fontSize') ||
+            !!getTransitionForKey(resolved, 'lineHeight'))
+        // an inherited font size: core leaves this node's own fontSize out of
+        // the style and reports the ratio, so the leading is the ANCESTOR's
+        // live font size times this node's ratio. react-native inherits the
+        // size itself, and a length leading is inherited as a length.
+        const inheritedFontSize = isDisabled
+          ? undefined
+          : inheritedFontSizeNode(style, paintedRatio, inheritedText)
+
+        // animatedStyle owns every Animated.Value on the node. Fabric cannot mix
+        // native- and JS-driven values inside that shared graph, so one layout
+        // animation, one text metric on the move, or a leading multiplied off an
+        // ancestor's font size, makes the whole node use the JS driver. a metric
+        // another pass left in the graph counts too, or its next animation would
+        // start on a driver the node no longer runs on.
+        const useNativeDriverForNode =
+          nativeDriver &&
+          !hasAnimatedLayoutKey(style, isDark, resolved) &&
+          !movesFontSize &&
+          !movesLeading &&
+          !inheritedFontSize &&
+          !Object.keys(animateStyles.current).some((key) => jsDriverStyleKey[key])
+
         for (const key in style) {
           const rawVal = style[key]
           // Resolve dynamic theme values from flat theme clauses.
@@ -396,23 +608,49 @@ export function createAnimations<A extends AnimationsConfig>(
             continue
           }
 
+          // fontSize and lineHeight are owned by the derived-leading block below
+          if (
+            (derivesLeading || inheritedFontSize) &&
+            (key === 'fontSize' || key === 'lineHeight')
+          ) {
+            // unless the size is the factor at rest: the product multiplies the
+            // number it paints, and that number has to be painted
+            if (key === 'fontSize' && derivesLeading && !movesFontSize) {
+              nonAnimatedStyle[key] = val
+            }
+            continue
+          }
+
+          // a text metric at rest stays out of the Animated graph entirely: it
+          // paints as a plain style, and the node keeps the native driver
+          if (
+            textMetricStyleKey[key] &&
+            !(key === 'fontSize' ? movesFontSize : movesLeading)
+          ) {
+            nonAnimatedStyle[key] = val
+            continue
+          }
+
           if (
             animatedStyleKey[key] == null &&
             !costlyToAnimateStyleKey[key] &&
-            !layoutStyleKey[key]
+            !jsDriverStyleKey[key]
           ) {
             nonAnimatedStyle[key] = val
             continue
           }
 
-          if (hasTransitionOnly && !animateOnly.includes(key)) {
+          // `transform` is a container, not a property: its parts each resolve
+          // on their own below, and a part no entry covers gets `snapConfig`.
+          // the array cannot be split into animated and static halves here.
+          if (key !== 'transform' && !getTransitionForKey(resolved, key)) {
             nonAnimatedStyle[key] = val
             continue
           }
 
           // layout dimension keys only animate numbers — 'auto' (an open
           // accordion at rest) and percent strings apply as static styles
-          if (layoutStyleKey[key] && typeof val !== 'number') {
+          if (jsDriverStyleKey[key] && typeof val !== 'number') {
             nonAnimatedStyle[key] = val
             continue
           }
@@ -425,7 +663,7 @@ export function createAnimations<A extends AnimationsConfig>(
           }
 
           if (key !== 'transform') {
-            animateStyles.current[key] = update(key, animateStyles.current[key], val)
+            animateStyles.current[key] = update(key, animatedValueFor(key), val)
             seenAnimateKeys.add(key)
             continue
           }
@@ -451,6 +689,64 @@ export function createAnimations<A extends AnimationsConfig>(
           }
         }
 
+        // the derived leading: fontSize and the ratio each animate on their own
+        // resolved entry, and the painted leading is their product, so
+        // lineHeight is fontSize * ratio on every frame by construction rather
+        // than by two solvers happening to agree. a key the transition does not
+        // cover gets snapConfig here exactly as it would anywhere else, which
+        // makes `transition="fontSize 300ms"` move the leading with the size and
+        // `transition="lineHeight 300ms"` move the ratio over a size that has
+        // already arrived.
+        // the ratio is a factor exactly like the font size: a value of its own
+        // while it moves, the number it already paints while it does not
+        const ratioFactor = (): Animated.Value | number => {
+          if (!movesLeading) {
+            leadingRatioValue.current = null
+            return paintedRatio!
+          }
+          leadingRatioValue.current = update(
+            'lineHeight',
+            leadingRatioValueFrom(),
+            paintedRatio!
+          )
+          return leadingRatioValue.current
+        }
+        let derivedLeading: ReturnType<typeof Animated.multiply> | undefined
+        if (derivesLeading) {
+          // a factor at rest multiplies as the plain number it already paints,
+          // so the product does not carry a value nothing is moving
+          let fontSizeFactor: Animated.Value | number = style.fontSize
+          if (movesFontSize) {
+            fontSizeFactor = update(
+              'fontSize',
+              animatedValueFor('fontSize'),
+              style.fontSize
+            )
+            animateStyles.current.fontSize = fontSizeFactor
+            seenAnimateKeys.add('fontSize')
+          }
+          derivedLeading = Animated.multiply(fontSizeFactor, ratioFactor())
+        } else if (inheritedFontSize) {
+          derivedLeading = Animated.multiply(inheritedFontSize, ratioFactor())
+        } else if (!isDisabled) {
+          leadingRatioValue.current = null
+        }
+        paintsDerivedLeading.current = !!derivedLeading
+
+        // what descendants inherit from this node: its own animated font size
+        // when it has one, nothing when it has a font size of its own that is
+        // not animating (react-native inherits that statically), and otherwise
+        // whatever it inherited itself.
+        const ownFontSizeNode = fontSizeNode.current
+        const textChannel = ownFontSizeNode
+          ? textChannelRef.current?.fontSize === ownFontSizeNode
+            ? textChannelRef.current
+            : { fontSize: ownFontSizeNode, driver: 'react-native' }
+          : typeof style.fontSize === 'number'
+            ? null
+            : (inheritedText ?? null)
+        textChannelRef.current = textChannel
+
         // drop stale Animated.Values whose keys left the incoming style, so the
         // key genuinely leaves the rendered style object (a released height goes
         // back to auto instead of staying pinned at its last pixel value). skip
@@ -487,12 +783,22 @@ export function createAnimations<A extends AnimationsConfig>(
               animationsState.current!.get(v)?.interpolation || v,
             ])
           ),
+          ...(derivedLeading ? { lineHeight: derivedLeading } : null),
           ...animatedTransformStyle,
         }
 
+        if (!isDisabled) {
+          paintedTextRef.current = {
+            fontSize: style.fontSize,
+            lineHeight: style.lineHeight,
+            ratio: paintedRatio,
+          }
+        }
+
         return {
           runners,
           completions,
+          textChannel,
           style: [nonAnimatedStyle, animatedStyle],
         }
 
@@ -539,7 +845,7 @@ export function createAnimations<A extends AnimationsConfig>(
             const animationConfig = getAnimationConfig(
               key,
               animations,
-              props.transition,
+              effectiveTransition,
               animationState
             )
 
@@ -552,22 +858,19 @@ export function createAnimations<A extends AnimationsConfig>(
             runners.push(() => {
               value.stopAnimation()
 
-              function getAnimation() {
-                return Animated[animationConfig.type || 'spring'](value, {
-                  toValue: animateToValue,
-                  ...animationConfig,
-                  useNativeDriver: useNativeDriverForNode,
-                })
-              }
-
-              const animation = animationConfig.delay
-                ? Animated.sequence([
-                    Animated.delay(animationConfig.delay),
-                    getAnimation(),
-                  ])
-                : getAnimation()
+              // `delay` drives the sequence below, so it must not also ride
+              // along in the config or every delayed animation waits twice
+              const { type, delay, ...config } = animationConfig
+              const animation = Animated[type || 'spring'](value, {
+                toValue: animateToValue,
+                ...config,
+                useNativeDriver: useNativeDriverForNode,
+              })
+              const animation2 = delay
+                ? Animated.sequence([Animated.delay(delay), animation])
+                : animation
 
-              animation.start(({ finished }) => {
+              animation2.start(({ finished }) => {
                 // always resolve during exit (element is leaving anyway)
                 // for non-exit, only resolve on successful completion
                 if (finished || isExiting) {
@@ -710,26 +1013,72 @@ export function createAnimations<A extends AnimationsConfig>(
       // avoidReRenders: receive style changes imperatively from tamagui
       // and update Animated.Values directly without React re-renders
       // reuses the same update() + runner pattern as the useMemo path
-      useStyleEmitter?.((nextStyle, _effectiveTransition, pseudoActive) => {
+      // the fourth argument is the emitted style's own nativeTextMetrics: the
+      // emitter re-runs getSplitStyles outside render, so the ratio that
+      // describes the style it hands over is never the ratio the last render
+      // resolved (a pseudo can replace the leading with an absolute length).
+      const onEmittedStyle = (
+        nextStyle: Record<string, any>,
+        emittedTransition: TransitionProp | null | undefined,
+        pseudoActive?: boolean,
+        nextMetrics?: NativeTextMetrics
+      ) => {
         pseudoActiveRef.current = pseudoActive === true
         const runners: Function[] = []
         const seenAnimateKeys = new Set<string>()
         let transformCount = 0
         let animatedShapeChanged = false
+        // the emitter runs on a mounted node, so `default` is the state, but
+        // the transition is the one it was handed
+        const emittedResolved = forAnimationState(
+          resolveTransition(emittedTransition ?? effectiveTransition, { animations }),
+          'default'
+        )
+        const emittedRatio = getLeadingRatio(nextMetrics)
+        const emitterPaintsProduct = paintsLeadingProduct(nextStyle, emittedRatio)
+        // the same rule as the render path: a text metric joins the graph only
+        // while it is moving, so a pseudo that only changes an opacity leaves
+        // the node's font size out of it and keeps the native driver
+        const emitterMovesFontSize = movesTextValue('fontSize', nextStyle.fontSize)
+        const emitterMovesLeading = emitterPaintsProduct
+          ? movesLeadingRatio(emittedRatio)
+          : movesTextValue('lineHeight', nextStyle.lineHeight)
         // nextStyle is the complete style for this node, so the emitter makes
         // the same single driver decision as the render path. include the
         // currently rendered graph because its stale keys are not removed until
         // the structural-change commit below.
         const useNativeDriverForNode =
           nativeDriver &&
-          !hasAnimatedLayoutKey(nextStyle, isDark) &&
-          !Object.keys(animateStyles.current).some((key) => layoutStyleKey[key])
+          !hasAnimatedLayoutKey(nextStyle, isDark, emittedResolved) &&
+          !emitterMovesFontSize &&
+          !emitterMovesLeading &&
+          !inheritedFontSizeNode(nextStyle, emittedRatio, inheritedText) &&
+          !Object.keys(animateStyles.current).some((key) => jsDriverStyleKey[key])
+
+        const emitterDerivesLeading =
+          emitterPaintsProduct &&
+          (emitterMovesFontSize || emitterMovesLeading) &&
+          (!!getTransitionForKey(emittedResolved, 'fontSize') ||
+            !!getTransitionForKey(emittedResolved, 'lineHeight'))
 
         for (const key in nextStyle) {
           const rawVal = nextStyle[key]
           const val = resolveDynamicValue(rawVal, isDark)
           if (val === undefined) continue
 
+          if (emitterDerivesLeading && (key === 'fontSize' || key === 'lineHeight')) {
+            continue
+          }
+
+          // a metric at rest is not the emitter's to animate. it either already
+          // paints as a plain style or the commit below hands it to one.
+          if (
+            textMetricStyleKey[key] &&
+            !(key === 'fontSize' ? emitterMovesFontSize : emitterMovesLeading)
+          ) {
+            continue
+          }
+
           if (key === 'transform' && Array.isArray(val)) {
             for (const transform of val) {
               if (!transform) continue
@@ -744,19 +1093,52 @@ export function createAnimations<A extends AnimationsConfig>(
           } else if (
             animatedStyleKey[key] != null ||
             costlyToAnimateStyleKey[key] ||
-            layoutStyleKey[key]
+            jsDriverStyleKey[key]
           ) {
             // layout keys only animate numbers ('auto'/percents are static);
             // unparseable themed colors can't be interpolated — skip both and
             // let the next render apply them statically
-            if (layoutStyleKey[key] && typeof val !== 'number') continue
+            if (jsDriverStyleKey[key] && typeof val !== 'number') continue
             if (colorStyleKey[key] && !isAnimatableColor(val)) continue
             if (!animateStyles.current[key]) animatedShapeChanged = true
-            animateStyles.current[key] = update(key, animateStyles.current[key], val)
+            animateStyles.current[key] = update(key, animatedValueFor(key), val)
             seenAnimateKeys.add(key)
           }
         }
 
+        // the emitter can only re-target Animated.Values the committed style
+        // already paints. re-targeting the font size and the ratio keeps the
+        // product moving without a commit; a pass that disagrees with the
+        // committed style about whether the leading IS a product (a pseudo that
+        // overrides it with an absolute length, or the first pseudo pass on a
+        // node whose render never derived) needs the node swapped, which only a
+        // commit can do.
+        if (emitterDerivesLeading) {
+          if (emitterMovesFontSize) {
+            if (!animateStyles.current.fontSize) animatedShapeChanged = true
+            animateStyles.current.fontSize = update(
+              'fontSize',
+              animatedValueFor('fontSize'),
+              nextStyle.fontSize as number
+            )
+            seenAnimateKeys.add('fontSize')
+          }
+          // a factor at rest is left out: it multiplies as the number the
+          // painted product already carries. giving one a value the committed
+          // style does not paint is the shape change that commits.
+          if (emitterMovesLeading) {
+            if (!leadingRatioValue.current) animatedShapeChanged = true
+            leadingRatioValue.current = update(
+              'lineHeight',
+              leadingRatioValueFrom(),
+              emittedRatio!
+            )
+          }
+        }
+        if (emitterDerivesLeading !== paintsDerivedLeading.current) {
+          animatedShapeChanged = true
+        }
+
         // the emitter receives a complete style. keep the Animated style graph
         // equally complete, including a pseudo release that omits a pseudo-only
         // key. React Native needs a commit when that graph's shape changes.
@@ -771,6 +1153,12 @@ export function createAnimations<A extends AnimationsConfig>(
           animatedShapeChanged = true
         }
 
+        paintedTextRef.current = {
+          fontSize: nextStyle.fontSize,
+          lineHeight: nextStyle.lineHeight,
+          ratio: emittedRatio,
+        }
+
         // run the queued animations immediately
         runners.forEach((r) => r())
 
@@ -820,28 +1208,29 @@ export function createAnimations<A extends AnimationsConfig>(
             })
           }
 
+          // the emitter runs for pseudo-state changes on a mounted node, so
+          // `default` is the state, but the transition is the one it was handed
           const animationConfig = getAnimationConfig(
             key,
             animations,
-            props.transition,
+            emittedTransition ?? effectiveTransition,
             'default'
           )
           runners.push(() => {
             value.stopAnimation()
-            const anim = Animated[animationConfig.type || 'spring'](value, {
+            const { type, delay, ...config } = animationConfig
+            const anim = Animated[type || 'spring'](value, {
               toValue: animateToValue,
-              ...animationConfig,
+              ...config,
               useNativeDriver: useNativeDriverForNode,
             })
-            ;(animationConfig.delay
-              ? Animated.sequence([Animated.delay(animationConfig.delay), anim])
-              : anim
-            ).start()
+            ;(delay ? Animated.sequence([Animated.delay(delay), anim]) : anim).start()
           })
 
           return value
         }
-      })
+      }
+      useStyleEmitter?.(onEmittedStyle)
 
       if (process.env.NODE_ENV === 'development') {
         if (props['debug'] === 'verbose') {
@@ -887,56 +1276,59 @@ function getInterpolated(current: number, next: number, postfix = 'deg') {
   }
 }
 
-function getAnimationConfig(
-  key: string,
-  animations: AnimationsConfig,
-  transition?: TransitionProp,
-  animationState: 'enter' | 'exit' | 'default' = 'default'
-): AnimationConfig {
-  const normalized = normalizeTransition(transition)
-  const shortKey = transformShorthands[key]
-
-  // Check for property-specific animation
-  const propAnimation = normalized.properties[key] ?? normalized.properties[shortKey]
-
-  let animationType: string | null = null
-  let extraConf: any = {}
-
-  if (typeof propAnimation === 'string') {
-    // Direct animation name: { x: 'quick' }
-    animationType = propAnimation
-  } else if (propAnimation && typeof propAnimation === 'object') {
-    // Config object: { x: { type: 'quick', delay: 100 } }
-    // Use effective animation based on state if no explicit type in config
-    animationType =
-      propAnimation.type || getEffectiveAnimation(normalized, animationState)
-    extraConf = propAnimation
-  } else {
-    // Fall back to effective animation based on state (enter/exit/default)
-    animationType = getEffectiveAnimation(normalized, animationState)
-  }
-
-  // Apply global delay if no property-specific delay
-  if (normalized.delay && !extraConf.delay) {
-    extraConf = { ...extraConf, delay: normalized.delay }
+/**
+ * one resolved entry as a react-native Animated config.
+ *
+ * springs go in as stiffness/damping/mass, which is the parameterization RN
+ * actually integrates. `bounciness`/`speed` and `tension`/`friction` are older
+ * spellings of the same two numbers, so nothing is lost by not using them.
+ */
+function entryToRN(entry: ResolvedEntry): AnimationConfig {
+  const extra = entry.timing.kind === 'spring' ? entry.timing.extra : undefined
+
+  if (entry.timing.kind === 'spring') {
+    return {
+      type: 'spring',
+      stiffness: entry.timing.stiffness,
+      damping: entry.timing.damping,
+      mass: entry.timing.mass,
+      ...(typeof extra?.velocity === 'number' ? { velocity: extra.velocity } : null),
+      ...(typeof extra?.overshootClamping === 'boolean'
+        ? { overshootClamping: extra.overshootClamping }
+        : null),
+      ...(entry.delayMs ? { delay: entry.delayMs } : null),
+    }
   }
 
-  const found = animationType ? animations[animationType] : {}
+  const bezier = easingToBezier(entry.timing.easing)
   return {
-    ...found,
-    // Apply global spring config overrides (from transition={['bouncy', { stiffness: 1000 }]})
-    ...normalized.config,
-    // Property-specific config takes highest precedence
-    ...extraConf,
+    type: 'timing',
+    duration: entry.timing.durationMs,
+    // `linear()` and `steps()` have no bezier equivalent; RN's default easing
+    // is the honest answer rather than a curve we made up
+    ...(bezier
+      ? { easing: Easing.bezier(bezier[0], bezier[1], bezier[2], bezier[3]) }
+      : null),
+    ...(entry.delayMs ? { delay: entry.delayMs } : null),
   }
 }
 
-// try both combos
-const transformShorthands = {
-  x: 'translateX',
-  y: 'translateY',
-  translateX: 'x',
-  translateY: 'y',
+// a key the transition does not cover does not animate. snapping is what css
+// does for an unlisted property, so the drivers have to agree on it too.
+const snapConfig: AnimationConfig = { type: 'timing', duration: 0 }
+
+function getAnimationConfig(
+  key: string,
+  animations: AnimationsConfig,
+  transition?: TransitionProp | null,
+  animationState: 'enter' | 'exit' | 'default' = 'default'
+): AnimationConfig {
+  const resolved = forAnimationState(
+    resolveTransition(transition, { animations }),
+    animationState
+  )
+  const entry = getTransitionForKey(resolved, key)
+  return entry ? entryToRN(entry) : snapConfig
 }
 
 function getValue(input: number | string, isColor = false) {