@rootnative/inertia 0.0.2 → 0.0.4

package/src/motion/createMotionComponent.tsx

@@ -14,7 +14,7 @@ import Animated, {
   useSharedValue,
   type SharedValue,
 } from 'react-native-reanimated'
-import { type LayoutChangeEvent } from 'react-native'
+import { StyleSheet, type LayoutChangeEvent } from 'react-native'
 import {
   lookupNamedTransition,
   resolveNamedTransitionProp,
@@ -22,9 +22,17 @@ import {
   useShouldReduceMotion,
 } from '../config'
 import { isFocusVisible } from '../gestures'
+import {
+  normalizeBoxShadow,
+  prepareBoxShadowAnimation,
+  type AnimatedBoxShadowLayer,
+  type SplitBoxShadow,
+} from '../internal/boxShadow'
+import { warnOnce } from '../internal/warnOnce'
 import {
   resolveLayoutTransition,
   type LayoutProp,
+  type SharedStyleSnapshot,
   useSharedLayout,
 } from '../layout'
 import { usePresence } from '../presence'
@@ -33,6 +41,7 @@ import {
   resolveAnimatableValue,
   resolveTransition,
   stableSig,
+  type CallbackFactory,
 } from '../transitions'
 import { ensureReanimatedInstalled } from './installCheck'
 import {
@@ -42,6 +51,7 @@ import {
   type GestureLayerTransitions,
   type GestureSubStates,
   type MotionComponent,
+  type BoxShadowInput,
   type MotionProps,
   type PerPropertyTransition,
   type Transition,
@@ -108,6 +118,42 @@ const COLOR_KEYS = [
 // these keys directly.
 const SHADOW_OFFSET_KEYS = ['shadowOffsetWidth', 'shadowOffsetHeight'] as const
 
+// Keys whose shared value holds a structure rather than a scalar. `boxShadow`
+// is the only one: its slot carries an array of layer objects, which
+// Reanimated's animation drivers recurse into, animating each leaf number and
+// color independently (`arrayOnStart` → `objectOnStart` in Reanimated's
+// `animation/util.ts`).
+//
+// Passing the CSS string through instead would NOT work — a box-shadow string
+// isn't a color, so it lands in Reanimated's prefix-number-suffix branch,
+// which is built for values like '100%' and would pull a single number out of
+// a four-value shadow. All string parsing therefore happens on the JS thread,
+// once per change, in `internal/boxShadow.ts`.
+const STRUCTURED_KEYS = ['boxShadow'] as const
+
+// Keys a shared-element transition (`layoutId`) carries from the source
+// element to the target, crossfading them alongside the rect FLIP. Everything
+// here is either a scalar or a color, so the worklet's existing lerp /
+// `interpolateColor` branches handle it with no new machinery.
+//
+// Transform keys are deliberately absent: they are the FLIP's job, and
+// carrying them too would apply the same displacement twice.
+//
+// So is `shadowColor`, despite being a color key. Carrying one of the four
+// native shadow props crossfades a shadow's *color* over geometry that snapped
+// — a worse result than letting the whole shadow snap together. (It would also
+// pull `shadowColor` into the active set on any `layoutId` element whose style
+// declares it, tripping the `boxShadow`-with-native-`shadow*` warning for a
+// consumer who never asked for either.)
+const SHARED_STYLE_KEYS = [
+  'opacity',
+  'borderRadius',
+  'backgroundColor',
+  'borderColor',
+  'color',
+  'tintColor',
+] as const
+
 /**
  * Per-effect transform-group coordinator. Counts how many transform-axis
  * terminal callbacks are still pending; when the last one fires, the
@@ -121,6 +167,7 @@ const ALL_KEYS = [
   ...NUMERIC_TOP_LEVEL_KEYS,
   ...COLOR_KEYS,
   ...SHADOW_OFFSET_KEYS,
+  ...STRUCTURED_KEYS,
 ] as const
 type AnimatableKey = (typeof ALL_KEYS)[number]
 type TransformKey = (typeof TRANSFORM_KEYS)[number]
@@ -129,6 +176,20 @@ type ShadowOffsetKey = (typeof SHADOW_OFFSET_KEYS)[number]
 const TRANSFORM_KEY_SET = new Set<AnimatableKey>(TRANSFORM_KEYS)
 const COLOR_KEY_SET = new Set<AnimatableKey>(COLOR_KEYS)
 const SHADOW_OFFSET_KEY_SET = new Set<AnimatableKey>(SHADOW_OFFSET_KEYS)
+const STRUCTURED_KEY_SET = new Set<AnimatableKey>(STRUCTURED_KEYS)
+const SHARED_STYLE_KEY_SET = new Set<AnimatableKey>(SHARED_STYLE_KEYS)
+
+/**
+ * What a per-key shared value can hold. Scalars for every key except
+ * `boxShadow`, whose slot carries the layer array (see `STRUCTURED_KEYS`).
+ */
+type AnimatableSlotValue = number | string | readonly AnimatedBoxShadowLayer[]
+
+/**
+ * Resting `boxShadow` — no shadow at all. Frozen and hoisted so every
+ * primitive shares one reference and an untouched slot never allocates.
+ */
+const NO_BOX_SHADOW: readonly AnimatedBoxShadowLayer[] = Object.freeze([])
 
 const GESTURE_LAYER_NAMES = [
   'hovered',
@@ -144,7 +205,7 @@ const GESTURE_LAYER_NAME_SET = new Set<string>(GESTURE_LAYER_NAMES)
 // Reanimated's style merging treats it as a no-op when present.
 const EXITING_POINTER_EVENTS_STYLE = { pointerEvents: 'none' } as const
 
-const DEFAULT_RESTING: Record<AnimatableKey, number | string> = {
+const DEFAULT_RESTING: Record<AnimatableKey, AnimatableSlotValue> = {
   translateX: 0,
   translateY: 0,
   scale: 1,
@@ -171,6 +232,7 @@ const DEFAULT_RESTING: Record<AnimatableKey, number | string> = {
   shadowColor: 'transparent',
   shadowOffsetWidth: 0,
   shadowOffsetHeight: 0,
+  boxShadow: NO_BOX_SHADOW,
 }
 
 // Both lookups run after the factory has resolved registered transition
@@ -398,6 +460,24 @@ export function createMotionComponent<C extends ComponentType<any>>(
       // identity only changes on the renders that actually add a key, so the
       // `useAnimatedStyle` worklet (which reads `.current` each frame) sees the
       // expansion without churning frame-to-frame.
+      const hasLayoutId = layoutId !== undefined
+
+      // The static `style`, flattened at most once per render and only when
+      // something asks for it. Two readers: the shared-element key scan just
+      // below, and the resting-value pass further down. A plain `animate`-only
+      // instance triggers neither and never pays for the flatten.
+      let flatStyle: Record<string, unknown> | undefined
+      let flatStyleRead = false
+      const getFlatStyle = () => {
+        if (!flatStyleRead) {
+          flatStyleRead = true
+          flatStyle = StyleSheet.flatten(style as never) as
+            | Record<string, unknown>
+            | undefined
+        }
+        return flatStyle
+      }
+
       const touched = new Set<AnimatableKey>()
       collectTouchedKeys(touched, animateRecord)
       if (initialRecord) collectTouchedKeys(touched, initialRecord)
@@ -420,9 +500,31 @@ export function createMotionComponent<C extends ComponentType<any>>(
       }
       if (exitRecord) collectTouchedKeys(touched, exitRecord)
 
+      // Shared-element style carry: a `layoutId` element crossfades the carried
+      // keys from its counterpart, so those keys have to be in the active set
+      // for the worklet to emit them at all.
+      //
+      // Only keys this element already has a value for join — from a record
+      // above, or from the static style. Never invented: activating a key with
+      // no source value rests it at `DEFAULT_RESTING`, and for `color` on a
+      // `Motion.Text` that inherits its colour from a parent, that default is
+      // `'transparent'` — invisible text on an element the consumer only asked
+      // to move. Same failure mode as the `0.0.3` P0, reached from the other
+      // side.
+      if (hasLayoutId) {
+        const flat = getFlatStyle()
+        if (flat) {
+          for (const key of SHARED_STYLE_KEYS) {
+            if (touched.has(key)) continue
+            if (styleValueFor(flat, key) !== undefined) touched.add(key)
+          }
+        }
+      }
+
       const activeKeysRef = useRef<readonly AnimatableKey[] | null>(null)
       const hasTransformRef = useRef<boolean>(false)
       const hasShadowOffsetRef = useRef<boolean>(false)
+      const hasBoxShadowRef = useRef<boolean>(false)
       // Expand the active set only when this render touched a key we haven't
       // recorded yet. When nothing new appears we keep the existing array
       // identity so the worklet's captured ref doesn't see a fresh value.
@@ -446,18 +548,111 @@ export function createMotionComponent<C extends ComponentType<any>>(
         hasShadowOffsetRef.current = activeKeysRef.current.some((k) =>
           SHADOW_OFFSET_KEY_SET.has(k),
         )
+        hasBoxShadowRef.current = activeKeysRef.current.includes('boxShadow')
+        // Animating `boxShadow` alongside the native `shadow*` keys puts two
+        // shadow systems on one element; whichever the underlying view resolves
+        // last wins, and the result reads as a bug rather than a choice.
+        // Checked here rather than per render — the active key set is what
+        // decides it, and this block only runs when that set grows.
+        if (
+          __DEV__ &&
+          hasBoxShadowRef.current &&
+          activeKeysRef.current.some(
+            (k) => k !== 'boxShadow' && k.startsWith('shadow'),
+          )
+        ) {
+          warnOnce(
+            'boxShadow-with-native-shadow',
+            '[inertia] `boxShadow` is animated alongside the native `shadow*` ' +
+              'keys on the same element, which applies two shadow systems at ' +
+              'once. Pick one: `boxShadow` for the cross-platform CSS form, or ' +
+              'the native `shadow*` keys.',
+          )
+        }
+      }
+
+      // Which keys a record actually drives *right now*. Everything else in
+      // the active set is there only because a gesture sub-state, an `exit`
+      // target, or a variant branch that isn't current mentions it. Those must
+      // rest at whatever the static `style` says — the animated style merges
+      // AFTER `style`, so resting them at `DEFAULT_RESTING` silently stomps it
+      // (`borderColor` → 'transparent', `width` → 0, and so on for every key
+      // whose default isn't an identity). Transforms and `opacity` hid this
+      // bug for a long time: their defaults happen to be no-ops.
+      const drivenNow = new Set<AnimatableKey>()
+      collectTouchedKeys(drivenNow, animateRecord)
+      if (initialRecord) collectTouchedKeys(drivenNow, initialRecord)
+      if (isExiting && exitRecord) collectTouchedKeys(drivenNow, exitRecord)
+
+      // Monotonic, like the active set. Once a record has driven a key we stop
+      // syncing it to the style, so transitioning to a variant that doesn't
+      // mention the key leaves it where the previous variant put it — the
+      // existing semantic — instead of snapping back to the style value.
+      const everDrivenRef = useRef<Set<AnimatableKey>>(new Set())
+      for (const k of drivenNow) everDrivenRef.current.add(k)
+
+      // Resting values pulled off the static `style`, for active keys nothing
+      // has driven. Gated so the common `animate`-only instance never flattens
+      // a style it has no use for.
+      const activeKeys = activeKeysRef.current!
+      const everDriven = everDrivenRef.current
+      const styleResting: Partial<Record<AnimatableKey, AnimatableSlotValue>> =
+        {}
+      // `boxShadow`'s resting value is two halves (animated layers + static
+      // inset flags), so it can't ride the scalar map above.
+      let styleRestingShadow: SplitBoxShadow | null = null
+      if (activeKeys.some((k) => !everDriven.has(k))) {
+        const flat = getFlatStyle()
+        if (flat) {
+          for (const key of activeKeys) {
+            if (everDriven.has(key)) continue
+            if (key === 'boxShadow') {
+              const raw = flat.boxShadow as BoxShadowInput | undefined
+              if (raw !== undefined) {
+                styleRestingShadow = normalizeBoxShadow(raw)
+                styleResting.boxShadow = styleRestingShadow.layers
+              }
+              continue
+            }
+            const v = styleValueFor(flat, key)
+            if (v !== undefined) styleResting[key] = v
+          }
+        }
+      }
+
+      // Seed the `boxShadow` slot once, at mount, on the same precedence chain
+      // every other key uses (`initial` → `animate` → static style → default).
+      // Held in a ref rather than recomputed per render because resolving it
+      // may parse a CSS string, and the value is only ever read on the mount
+      // pass.
+      const boxShadowSeedRef = useRef<SplitBoxShadow | null>(null)
+      if (boxShadowSeedRef.current === null) {
+        const source =
+          initial === false
+            ? animateRecord.boxShadow
+            : (initialRecord?.boxShadow ?? animateRecord.boxShadow)
+        boxShadowSeedRef.current =
+          source !== undefined
+            ? normalizeBoxShadow(source)
+            : (styleRestingShadow ?? {
+                layers: [...NO_BOX_SHADOW],
+                insets: null,
+              })
       }
 
       const sharedValues = useAnimatableSharedValues((key) => {
+        if (key === 'boxShadow') return boxShadowSeedRef.current!.layers
         // Shadow offset synthetics seed from the corresponding axis on the
         // `shadowOffset: { width, height }` source — the consumer doesn't write
         // `shadowOffsetWidth` / `shadowOffsetHeight` directly. Fall back to the
-        // generic resting default when neither initial nor animate touched it.
+        // static style, then the generic resting default, when neither initial
+        // nor animate touched it.
         if (SHADOW_OFFSET_KEY_SET.has(key)) {
           const axis = shadowOffsetAxisFor(key as ShadowOffsetKey)
           if (initial === false) {
             return (
               shadowOffsetAxisValue(animateRecord.shadowOffset, axis) ??
+              styleResting[key] ??
               DEFAULT_RESTING[key]
             )
           }
@@ -469,20 +664,52 @@ export function createMotionComponent<C extends ComponentType<any>>(
               axis,
             ) ??
             shadowOffsetAxisValue(animateRecord.shadowOffset, axis) ??
+            styleResting[key] ??
             DEFAULT_RESTING[key]
           )
         }
         if (initial === false) {
           const a = animateRecord[key]
-          return restValue(a) ?? DEFAULT_RESTING[key]
+          return restValue(a) ?? styleResting[key] ?? DEFAULT_RESTING[key]
         }
         return (
           initialRecord?.[key] ??
           restValue(animateRecord[key]) ??
+          styleResting[key] ??
           DEFAULT_RESTING[key]
         )
       })
 
+      // Keep never-driven keys tracking the *live* static style. The seed above
+      // only runs at mount, but the animated style emits these keys on every
+      // frame — so without this a `style` that changes afterwards (a theme
+      // swap, a conditional colour) would stay invisible for any key some
+      // gesture / exit / variant branch happens to mention. Direct assignment,
+      // not an animation: this is a static value, not a target.
+      // Static `inset` flags for the layers currently in the `boxShadow` slot,
+      // parallel to `sharedValues.boxShadow`. Kept out of the animated payload
+      // because Reanimated would drive the boolean down its numeric path and
+      // hand native a number mid-flight; see `AnimatedBoxShadowLayer`. `null`
+      // whenever no layer is inset, which lets the worklet emit the animated
+      // array with no per-frame reassembly at all.
+      const boxShadowInsets = useSharedValue<boolean[] | null>(
+        boxShadowSeedRef.current.insets,
+      )
+
+      const styleRestingSig = stableSig(styleResting)
+      useEffect(() => {
+        for (const key of activeKeysRef.current!) {
+          if (everDrivenRef.current.has(key)) continue
+          sharedValues[key].value = (styleResting[key] ??
+            DEFAULT_RESTING[key]) as never
+          if (key === 'boxShadow') {
+            boxShadowInsets.value = styleRestingShadow?.insets ?? null
+          }
+        }
+        // `styleResting` is rebuilt each render; its signature is the real dep.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, [styleRestingSig])
+
       // One progress SV per gesture layer, allocated unconditionally for hook
       // stability. Each layer's progress animates 0↔1 with its own transition
       // when its activation flips; the worklet reads them when compositing.
@@ -568,20 +795,71 @@ export function createMotionComponent<C extends ComponentType<any>>(
           }
         }
 
+        // Per-key transition resolution, hoisted out of the loop below so the
+        // transform-group count can ask about a key's config before the loop
+        // reaches it. Reduced motion overrides every per-key transition (and
+        // any nested sequence-step transition) with `no-animation`, which the
+        // resolver turns into a direct value assignment. Sequences still
+        // iterate but each step settles instantly, matching the "snap to final
+        // state" expectation.
+        const configFor = (key: AnimatableKey): TransitionConfig | undefined =>
+          shouldReduceMotion
+            ? ({ type: 'no-animation' } as const)
+            : transitionFor(
+                SHADOW_OFFSET_KEY_SET.has(key)
+                  ? ('shadowOffset' as keyof typeof baseRecord)
+                  : key,
+                transition,
+              )
+
         // Count transform axes participating in this effect run so the factory
         // can coalesce their terminal callbacks into a single transform-group
         // event. `undefined` when no transform axis is animating, which lets
         // the factory skip the coalescing branch entirely.
+        //
+        // Endless axes are excluded. A `repeat: 'infinite'` axis never reaches
+        // the terminal `'animation'` phase, so counting it would pin
+        // `remaining` permanently above zero — a sibling axis with a finite
+        // transition would settle, decrement, and have its completion silently
+        // swallowed. An axis that never finishes simply isn't part of the group
+        // that does.
         let transformPending = 0
         for (const k of ALL_KEYS) {
-          if (TRANSFORM_KEY_SET.has(k) && baseRecord[k] !== undefined) {
-            transformPending++
-          }
+          if (!TRANSFORM_KEY_SET.has(k) || baseRecord[k] === undefined) continue
+          if (!reachesTerminalPhase(configFor(k))) continue
+          transformPending++
         }
         const transformGroup: TransformGroup | undefined =
           transformPending > 0 ? { remaining: transformPending } : undefined
 
         for (const key of ALL_KEYS) {
+          // Structured keys don't go through `resolveAnimatableValue` — their
+          // target is already an array, which that resolver would read as a
+          // keyframe sequence.
+          if (key === 'boxShadow') {
+            const shadowTarget = baseRecord.boxShadow
+            if (shadowTarget === undefined) continue
+            const cfg = configFor('boxShadow')
+            if (isExiting && reachesTerminalPhase(cfg)) pending++
+            driveBoxShadow(
+              sharedValues.boxShadow,
+              boxShadowInsets,
+              shadowTarget,
+              cfg,
+              makeKeyCallbackFactory(
+                'boxShadow',
+                sharedValues.boxShadow,
+                // The declared target, not the padded one — the padding is an
+                // implementation detail of getting Reanimated to interpolate.
+                shadowTarget,
+                onAnimationEndRef,
+                { stepCount: 1, totalIterations: totalIterationsOf(cfg) },
+                isExiting ? onSettle : undefined,
+                undefined,
+              ),
+            )
+            continue
+          }
           // Shadow offset synthetics read their target from the nested
           // `shadowOffset: { width, height }` source on `baseRecord` — the
           // animate / exit record never has `shadowOffsetWidth` etc. on it
@@ -595,20 +873,15 @@ export function createMotionComponent<C extends ComponentType<any>>(
                 )
               : baseRecord[key]
           if (target === undefined) continue
-          // Reduced-motion overrides every per-key transition (and any nested
-          // sequence-step transition) with `no-animation`, which the resolver
-          // turns into a direct value assignment. Sequences still iterate but
-          // each step settles instantly, which matches the "snap to final
-          // state" expectation.
-          const cfg = shouldReduceMotion
-            ? ({ type: 'no-animation' } as const)
-            : transitionFor(
-                SHADOW_OFFSET_KEY_SET.has(key)
-                  ? ('shadowOffset' as keyof typeof baseRecord)
-                  : key,
-                transition,
-              )
-          if (isExiting) pending++
+          const cfg = configFor(key)
+          // <Presence> waits on this counter before unmounting, so only count
+          // keys that can actually settle. An endless exit animation (a
+          // `repeat: 'infinite'` transition inherited by `exit`, e.g. a pulsing
+          // element inside <Presence>) would otherwise never call
+          // `safeToRemove` and the child would stay mounted forever. Finite
+          // keys still gate the unmount; if every exit key is endless, the
+          // post-loop `pending === 0` release fires immediately.
+          if (isExiting && reachesTerminalPhase(cfg)) pending++
           const factory = makeKeyCallbackFactory(
             key,
             sharedValues[key],
@@ -691,20 +964,44 @@ export function createMotionComponent<C extends ComponentType<any>>(
       // transform array so they compose with the user's animate transforms —
       // multiple `translateX` entries sum, multiple `scaleX` entries multiply,
       // which is exactly the FLIP semantic.
+      //
+      // The style half rides the same wiring: `readStyles` lets a later mount
+      // (or our own unmount) snapshot the carried keys straight off the shared
+      // values, and the worklet below crossfades a consumed snapshot out over
+      // whatever this element resolves to. Reached through a ref inside the
+      // hook, so building it inline here costs nothing downstream.
+      const readSharedStyles = () => {
+        if (!hasLayoutId) return undefined
+        const out: SharedStyleSnapshot = {}
+        let any = false
+        for (const key of activeKeysRef.current!) {
+          if (!SHARED_STYLE_KEY_SET.has(key)) continue
+          const v = sharedValues[key].value
+          // Structured slots can't be carried, and a key nothing ever gave a
+          // value to has nothing to hand over.
+          if (typeof v !== 'number' && typeof v !== 'string') continue
+          out[key] = v
+          any = true
+        }
+        return any ? out : undefined
+      }
+
       const sharedLayout = useSharedLayout({
         layoutId,
         userRef: ref,
         transition: isTopLevelTransition(transition) ? transition : undefined,
         shouldReduceMotion,
         userOnLayout,
+        readStyles: readSharedStyles,
       })
       const flip = sharedLayout.flip
-      const hasLayoutId = layoutId !== undefined
+      const carry = sharedLayout.carry
 
       const animatedStyle = useAnimatedStyle(() => {
         const activeKeys = activeKeysRef.current!
         const hasTransform = hasTransformRef.current
         const hasShadowOffset = hasShadowOffsetRef.current
+        const hasBoxShadow = hasBoxShadowRef.current
         const out: Record<string, unknown> = {}
         const transform: Array<Record<string, unknown>> = []
         // shadow-offset reassembly buffers. The two synthetic axis SVs feed in
@@ -720,6 +1017,12 @@ export function createMotionComponent<C extends ComponentType<any>>(
         const pfv = focusVisibleProgress.value
         const pp = pressedProgress.value
 
+        // Shared-element style carry. Both reads are cheap and the pair rests
+        // at (null, 0), so a primitive that isn't mid-transition — which is
+        // every primitive, almost all of the time — pays one comparison.
+        const carried = carry.snapshot.value
+        const pc = carry.progress.value
+
         const layers = gestureSV.value
         // Locals are suffixed `Layer` so they don't shadow the outer `pressed` /
         // `focused` / `focusVisible` / `hovered` JS-state booleans — Reanimated's
@@ -731,6 +1034,11 @@ export function createMotionComponent<C extends ComponentType<any>>(
         const pressedLayer = layers ? layers.pressed : null
 
         for (const key of activeKeys) {
+          // `boxShadow` is emitted after the loop: its value is a layer array,
+          // which none of the scalar compositing below can act on. Gesture
+          // sub-states are rejected for this key upstream, so there is no
+          // layer contribution to skip past either.
+          if (key === 'boxShadow') continue
           let v = sharedValues[key].value
           const isColor = COLOR_KEY_SET.has(key)
 
@@ -769,6 +1077,23 @@ export function createMotionComponent<C extends ComponentType<any>>(
               : (v as number) + ((t as number) - (v as number)) * pp
           }
 
+          // Shared-element carry sits above every gesture layer: the element
+          // is arriving from somewhere else, and where it came from outranks
+          // how it is being touched right now. `pc` runs 1 → 0, so the first
+          // frame shows the source's value and the last shows this element's
+          // own — including whatever the layers underneath contributed.
+          //
+          // Transform keys never appear in a snapshot (the FLIP owns them), so
+          // this can't double-apply displacement.
+          if (carried !== null && pc > 0) {
+            const s = carried[key]
+            if (s !== undefined) {
+              v = isColor
+                ? interpolateColor(pc, [0, 1], [v as string, s as string])
+                : (v as number) + ((s as number) - (v as number)) * pc
+            }
+          }
+
           if (TRANSFORM_KEY_SET.has(key)) {
             transform.push(
               ROTATION_KEYS.has(key) ? { [key]: `${v}deg` } : { [key]: v },
@@ -797,12 +1122,28 @@ export function createMotionComponent<C extends ComponentType<any>>(
         if (hasShadowOffset) {
           out.shadowOffset = { width: shadowOffsetW, height: shadowOffsetH }
         }
+        if (hasBoxShadow) {
+          const layers = sharedValues.boxShadow
+            .value as readonly AnimatedBoxShadowLayer[]
+          const insets = boxShadowInsets.value
+          // Fast path — no inset layer anywhere, so the animated array is
+          // already exactly what RN wants and crosses over untouched.
+          if (insets === null) {
+            out.boxShadow = layers
+          } else {
+            const withInset = []
+            for (let i = 0; i < layers.length; i++) {
+              withInset.push({ ...layers[i], inset: insets[i] })
+            }
+            out.boxShadow = withInset
+          }
+        }
         return out
       })
 
       // Exiting children are tap-deaf: the next press should fall through to
       // whatever is underneath, not re-trigger a soon-to-unmount node. This is
-      // the moti #297 fix and a v0.1 acceptance criterion. RN 0.71+ deprecates
+      // the moti #297 fix and a `0.0.1` acceptance criterion. RN 0.71+ deprecates
       // `pointerEvents` as a prop in favor of the style key, so we merge it
       // alongside the animated style instead of spreading as a prop.
       const mergedStyle = useMemo(
@@ -890,7 +1231,7 @@ function hasMotionProps(props: Record<string, unknown>): boolean {
   return false
 }
 
-type SharedValueMap = Record<AnimatableKey, SharedValue<number | string>>
+type SharedValueMap = Record<AnimatableKey, SharedValue<AnimatableSlotValue>>
 
 /**
  * Allocate one shared value per animatable key in `ALL_KEYS` and return a
@@ -911,36 +1252,39 @@ type SharedValueMap = Record<AnimatableKey, SharedValue<number | string>>
  * `withSpring` / `withTiming` call.
  */
 function useAnimatableSharedValues(
-  init: (key: AnimatableKey) => number | string,
+  init: (key: AnimatableKey) => AnimatableSlotValue,
 ): SharedValueMap {
-  const translateX = useSharedValue<number | string>(init('translateX'))
-  const translateY = useSharedValue<number | string>(init('translateY'))
-  const scale = useSharedValue<number | string>(init('scale'))
-  const scaleX = useSharedValue<number | string>(init('scaleX'))
-  const scaleY = useSharedValue<number | string>(init('scaleY'))
-  const rotate = useSharedValue<number | string>(init('rotate'))
-  const rotateX = useSharedValue<number | string>(init('rotateX'))
-  const rotateY = useSharedValue<number | string>(init('rotateY'))
-  const opacity = useSharedValue<number | string>(init('opacity'))
-  const width = useSharedValue<number | string>(init('width'))
-  const height = useSharedValue<number | string>(init('height'))
-  const borderRadius = useSharedValue<number | string>(init('borderRadius'))
-  const shadowOpacity = useSharedValue<number | string>(init('shadowOpacity'))
-  const shadowRadius = useSharedValue<number | string>(init('shadowRadius'))
-  const elevation = useSharedValue<number | string>(init('elevation'))
-  const backgroundColor = useSharedValue<number | string>(
+  const translateX = useSharedValue<AnimatableSlotValue>(init('translateX'))
+  const translateY = useSharedValue<AnimatableSlotValue>(init('translateY'))
+  const scale = useSharedValue<AnimatableSlotValue>(init('scale'))
+  const scaleX = useSharedValue<AnimatableSlotValue>(init('scaleX'))
+  const scaleY = useSharedValue<AnimatableSlotValue>(init('scaleY'))
+  const rotate = useSharedValue<AnimatableSlotValue>(init('rotate'))
+  const rotateX = useSharedValue<AnimatableSlotValue>(init('rotateX'))
+  const rotateY = useSharedValue<AnimatableSlotValue>(init('rotateY'))
+  const opacity = useSharedValue<AnimatableSlotValue>(init('opacity'))
+  const width = useSharedValue<AnimatableSlotValue>(init('width'))
+  const height = useSharedValue<AnimatableSlotValue>(init('height'))
+  const borderRadius = useSharedValue<AnimatableSlotValue>(init('borderRadius'))
+  const shadowOpacity = useSharedValue<AnimatableSlotValue>(
+    init('shadowOpacity'),
+  )
+  const shadowRadius = useSharedValue<AnimatableSlotValue>(init('shadowRadius'))
+  const elevation = useSharedValue<AnimatableSlotValue>(init('elevation'))
+  const backgroundColor = useSharedValue<AnimatableSlotValue>(
     init('backgroundColor'),
   )
-  const borderColor = useSharedValue<number | string>(init('borderColor'))
-  const color = useSharedValue<number | string>(init('color'))
-  const tintColor = useSharedValue<number | string>(init('tintColor'))
-  const shadowColor = useSharedValue<number | string>(init('shadowColor'))
-  const shadowOffsetWidth = useSharedValue<number | string>(
+  const borderColor = useSharedValue<AnimatableSlotValue>(init('borderColor'))
+  const color = useSharedValue<AnimatableSlotValue>(init('color'))
+  const tintColor = useSharedValue<AnimatableSlotValue>(init('tintColor'))
+  const shadowColor = useSharedValue<AnimatableSlotValue>(init('shadowColor'))
+  const shadowOffsetWidth = useSharedValue<AnimatableSlotValue>(
     init('shadowOffsetWidth'),
   )
-  const shadowOffsetHeight = useSharedValue<number | string>(
+  const shadowOffsetHeight = useSharedValue<AnimatableSlotValue>(
     init('shadowOffsetHeight'),
   )
+  const boxShadow = useSharedValue<AnimatableSlotValue>(init('boxShadow'))
 
   const ref = useRef<SharedValueMap | null>(null)
   if (ref.current === null) {
@@ -967,6 +1311,7 @@ function useAnimatableSharedValues(
       shadowColor,
       shadowOffsetWidth,
       shadowOffsetHeight,
+      boxShadow,
     }
   }
 
@@ -1005,8 +1350,11 @@ function useAnimatableSharedValues(
  */
 function makeKeyCallbackFactory(
   key: string,
-  sharedValue: SharedValue<number | string>,
-  target: number | string | undefined,
+  sharedValue: SharedValue<AnimatableSlotValue>,
+  // Widened past the scalar surface for `boxShadow`, whose declared target is
+  // a CSS string or a layer array. Reaches the consumer as
+  // `AnimationCallbackInfo.target`, which is `unknown`.
+  target: number | string | BoxShadowInput | undefined,
   onAnimationEndRef: {
     current: ((info: AnimationCallbackInfo<unknown>) => void) | undefined
   },
@@ -1026,7 +1374,9 @@ function makeKeyCallbackFactory(
     rawPhase: 'step' | 'animation',
     step: number | undefined,
     finished: boolean,
-    value: number | string | undefined,
+    // Widened for `boxShadow`, whose settled value is a layer array. Surfaces
+    // on `AnimationCallbackInfo.value`, which is `unknown` either way.
+    value: AnimatableSlotValue | undefined,
   ) => {
     const isLastIteration = state.iteration >= meta.totalIterations - 1
     let phase: 'step' | 'sequence' | 'repeat' | 'animation'
@@ -1112,18 +1462,25 @@ function makeKeyCallbackFactory(
  * nested object decomposes into the `shadowOffsetWidth` / `shadowOffsetHeight`
  * synthetic axes downstream; consumers don't see the synthetics.
  *
- * v0.1 contract: `shadowOffset` accepts a single `{ width, height }` literal
- * (no sequences, no `{ to }` step objects, no array keyframes). Sequence
- * forms on the nested axes can land in v0.2 if real consumers ask for them.
+ * Contract since `0.0.1`: `shadowOffset` accepts a single `{ width, height }`
+ * literal (no sequences, no `{ to }` step objects, no array keyframes).
+ * Sequence forms on the nested axes can land later if real consumers ask.
  */
+type ScalarKey = Exclude<AnimatableKey, (typeof STRUCTURED_KEYS)[number]>
+
 type InternalAnimateRecord = Partial<
-  Record<AnimatableKey, AnimatableValue<number | string>>
+  Record<ScalarKey, AnimatableValue<number | string>>
 > & {
   shadowOffset?: { width?: number; height?: number }
+  // Structured keys depart from `AnimatableValue` — see `STRUCTURED_KEYS`.
+  // Kept out of the mapped half above so the two don't intersect into an
+  // uninhabitable `AnimatableValue<number | string> & BoxShadowInput`.
+  boxShadow?: BoxShadowInput
 }
 
-type InternalInitialRecord = Partial<Record<AnimatableKey, number | string>> & {
+type InternalInitialRecord = Partial<Record<ScalarKey, number | string>> & {
   shadowOffset?: { width?: number; height?: number }
+  boxShadow?: BoxShadowInput
 }
 
 /**
@@ -1146,6 +1503,107 @@ function shadowOffsetAxisValue(
   return source?.[axis]
 }
 
+/**
+ * Drive the `boxShadow` slot toward a new target.
+ *
+ * Two things make this different from the scalar path:
+ *
+ *  1. **Both endpoints are padded to a common layer count first.** Reanimated's
+ *     array driver iterates the *current* value's indices and pairs each with
+ *     `toValue[i]`, so a target with a different layer count either strands
+ *     leaves at `toValue: undefined` or never animates the extras. When the
+ *     padding changes the slot's shape, we snap it to the padded base before
+ *     starting the animation — otherwise the animation would begin from a
+ *     differently-shaped value and the pairing would be lost again.
+ *  2. **`inset` travels separately**, in its own slot, because Reanimated
+ *     would drive the boolean down the numeric path.
+ */
+function driveBoxShadow(
+  slot: SharedValue<AnimatableSlotValue>,
+  insetSlot: SharedValue<boolean[] | null>,
+  target: BoxShadowInput,
+  cfg: TransitionConfig | undefined,
+  factory: CallbackFactory | undefined,
+): void {
+  const currentLayers = Array.isArray(slot.value)
+    ? (slot.value as readonly AnimatedBoxShadowLayer[])
+    : NO_BOX_SHADOW
+  const { from, to, insets } = prepareBoxShadowAnimation(
+    { layers: [...currentLayers], insets: insetSlot.value },
+    target,
+  )
+  insetSlot.value = insets
+  if (from.length !== currentLayers.length) slot.value = from
+  // `resolveTransition` is typed for the scalar surface it was written for;
+  // Reanimated itself accepts the structured target and recurses into it.
+  slot.value = resolveTransition(
+    cfg,
+    to as unknown as number,
+    factory?.('animation', undefined),
+  ) as AnimatableSlotValue
+}
+
+/**
+ * Read an animatable key's resting value out of a **flattened style object**.
+ *
+ * Used for keys that are in the active set but that no record drives — they
+ * have to rest wherever the static `style` put them, because the animated
+ * style merges after `style` and would otherwise override it.
+ *
+ * Three shapes need unwrapping: transform keys live inside the `transform`
+ * array rather than at the top level, `shadowOffset*` synthetics decompose
+ * from the nested object, and rotations are unit-suffixed strings on a style
+ * but plain degrees in our shared values.
+ *
+ * Type-narrow deliberately: only numbers are accepted for numeric slots, so a
+ * `width: '100%'` is left to `DEFAULT_RESTING` rather than seeded into a slot
+ * that a later `withTiming` would try to interpolate as a number.
+ */
+function styleValueFor(
+  flat: Record<string, unknown>,
+  key: AnimatableKey,
+): number | string | undefined {
+  if (SHADOW_OFFSET_KEY_SET.has(key)) {
+    return shadowOffsetAxisValue(
+      flat.shadowOffset as { width?: number; height?: number } | undefined,
+      shadowOffsetAxisFor(key as ShadowOffsetKey),
+    )
+  }
+  if (TRANSFORM_KEY_SET.has(key)) {
+    const list = flat.transform
+    if (!Array.isArray(list)) return undefined
+    for (const entry of list) {
+      if (!entry || typeof entry !== 'object') continue
+      const v = (entry as Record<string, unknown>)[key]
+      if (v === undefined) continue
+      if (ROTATION_KEYS.has(key)) return parseAngleDegrees(v)
+      return typeof v === 'number' ? v : undefined
+    }
+    return undefined
+  }
+  const v = flat[key]
+  if (COLOR_KEY_SET.has(key)) {
+    return typeof v === 'string' || typeof v === 'number' ? v : undefined
+  }
+  return typeof v === 'number' ? v : undefined
+}
+
+/**
+ * Style rotations are unit-suffixed strings (`'45deg'`, `'0.5rad'`); the shared
+ * value behind a rotation key holds plain degrees. Anything we can't convert
+ * confidently returns `undefined` so the caller falls back to the resting
+ * default instead of guessing at a unit.
+ */
+function parseAngleDegrees(v: unknown): number | undefined {
+  if (typeof v === 'number') return v
+  if (typeof v !== 'string') return undefined
+  const deg = /^(-?\d*\.?\d+)deg$/.exec(v)
+  if (deg) return Number(deg[1])
+  const rad = /^(-?\d*\.?\d+)rad$/.exec(v)
+  if (rad) return (Number(rad[1]) * 180) / Math.PI
+  return undefined
+}
+
 /**
  * Populate `touched` with the `AnimatableKey`s mentioned in `record`. Direct
  * matches (e.g. `opacity`, `width`) come from the key iteration; the nested
@@ -1190,6 +1648,22 @@ function totalIterationsOf(cfg: TransitionConfig | undefined): number {
   return r.count
 }
 
+/**
+ * Whether an animation built from `cfg` will ever reach its terminal
+ * `'animation'` phase. Everything finite does; `repeat: 'infinite'` never
+ * does, because `dispatch` only promotes a callback to the terminal phase once
+ * `iteration >= totalIterations - 1`, and that comparison is unreachable
+ * against `Infinity`.
+ *
+ * Anything counting pending completions must exclude endless animations, or
+ * the counter never drains: one endless transform axis swallowed every sibling
+ * axis's `onAnimationEnd`, and one endless `exit` key left a `<Presence>` child
+ * mounted forever because `safeToRemove` was gated behind it.
+ */
+function reachesTerminalPhase(cfg: TransitionConfig | undefined): boolean {
+  return Number.isFinite(totalIterationsOf(cfg))
+}
+
 /**
  * Pull a single end-value out of an `AnimatableValue` for the
  * `AnimationCallbackInfo.target` field. Plain numbers/strings come through;
@@ -1304,6 +1778,27 @@ function resolveGestureLayers(
     if (!subState) continue
     const resolved: Record<string, number | string> = {}
     for (const key of ALL_KEYS) {
+      // Structured keys have no place in the layer cascade: compositing them
+      // would mean per-layer, per-field interpolation on the UI thread for
+      // every primitive, whether or not it animates a shadow. Rejected for
+      // now rather than half-supported — a silently-ignored `boxShadow` in a
+      // `gesture` sub-state is exactly the class of bug this library exists
+      // to avoid, so say so.
+      if (STRUCTURED_KEY_SET.has(key)) {
+        if (
+          __DEV__ &&
+          (subState as Record<string, unknown>)[key] !== undefined
+        ) {
+          warnOnce(
+            `gesture-structured-${layer}-${key}`,
+            `[inertia] \`${key}\` is not supported inside \`gesture.${layer}\` ` +
+              'and will be ignored. Drive it from `animate` (optionally via a ' +
+              'variant keyed off the same state), or interpolate it yourself ' +
+              'with `useShadow`.',
+          )
+        }
+        continue
+      }
       // Shadow offset synthetics decompose from the nested `shadowOffset:
       // { width, height }` source on the sub-state, the same as on `animate`.
       if (SHADOW_OFFSET_KEY_SET.has(key)) {