@rootnative/inertia 0.0.3 → 0.0.5

package/src/motion/createMotionComponent.tsx

@@ -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,
@@ -81,6 +91,78 @@ const NUMERIC_TOP_LEVEL_KEYS = [
   'shadowOpacity',
   'shadowRadius',
   'elevation',
+  // ─── Added in 0.0.5 ──────────────────────────────────────────────────────
+  //
+  // Every key below rides the generic numeric path: one shared value, resolved
+  // on the JS thread, emitted by the worklet through the same `out[key] = v`
+  // branch as `opacity`. None needs a new interpolation mode, so the cost is
+  // the shared value plus a `DEFAULT_RESTING` entry.
+  //
+  // The load-bearing constraint is the resting default, not the plumbing. A
+  // key declared only in `gesture` / `exit` / a non-active variant rests at
+  // `DEFAULT_RESTING` unless the static `style` names it, and the animated
+  // style merges *after* `style` — so a non-identity default silently stomps
+  // the layout. That is the `0.0.3` P0 class, and it is why the sizing and
+  // spacing keys below default to `0` only in the sense RN itself does (an
+  // unset `padding` *is* 0); `minWidth`/`maxWidth`/`aspectRatio` are
+  // deliberately excluded — their "unset" is not a number, so no default can
+  // stand in for it without changing layout on activation.
+  //
+  // Per-corner radii. Animating one corner is common (a card expanding into a
+  // sheet keeps its top corners and squares off the bottom); `borderRadius`
+  // alone can't express it.
+  'borderTopLeftRadius',
+  'borderTopRightRadius',
+  'borderBottomLeftRadius',
+  'borderBottomRightRadius',
+  // Border widths. `borderWidth` is the common case; the per-edge keys matter
+  // for underline-style focus affordances (`borderBottomWidth` on a field).
+  'borderWidth',
+  'borderTopWidth',
+  'borderRightWidth',
+  'borderBottomWidth',
+  'borderLeftWidth',
+  // Absolute-position insets. Bread-and-butter for drawers, tooltips, and
+  // anything pinned to an edge that slides in.
+  'top',
+  'right',
+  'bottom',
+  'left',
+  // Spacing. Padding animates the box from the inside (a button growing its
+  // hit area on press); margin shifts it within its parent's flow.
+  'padding',
+  'paddingTop',
+  'paddingRight',
+  'paddingBottom',
+  'paddingLeft',
+  'paddingHorizontal',
+  'paddingVertical',
+  'margin',
+  'marginTop',
+  'marginRight',
+  'marginBottom',
+  'marginLeft',
+  'marginHorizontal',
+  'marginVertical',
+  // Flex sizing. `flex` / `flexGrow` interpolate the split between siblings —
+  // the idiomatic RN way to animate a pane resize without measuring.
+  'flex',
+  'flexGrow',
+  'flexShrink',
+  // Text metrics. `TextStyle`-only at the type level (`AnimateStyle<C>` gates
+  // them per primitive), but the runtime table is shared across primitives —
+  // an unused slot is one ref, same as `tintColor` has always been.
+  'fontSize',
+  'letterSpacing',
+  'lineHeight',
+  // Stacking. Integer-valued in practice, and interpolating it mid-flight is
+  // rarely what you want, but a `no-animation` transition on `zIndex` is the
+  // clean way to reorder at a step boundary in a sequence.
+  'zIndex',
+  // Gap. Row/column gaps animate a list's density without touching children.
+  'gap',
+  'rowGap',
+  'columnGap',
 ] as const
 
 // Color-valued keys. Reanimated's value setter detects color strings and
@@ -108,6 +190,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 +239,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 +248,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 +277,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,
@@ -160,6 +293,54 @@ const DEFAULT_RESTING: Record<AnimatableKey, number | string> = {
   shadowOpacity: 0,
   shadowRadius: 0,
   elevation: 0,
+  // 0.0.5 keys. Every one of these is 0 because that is RN's own unset value
+  // for it — an element with no `paddingTop` has 0 padding, no `borderWidth`
+  // has none, no `top` is unpinned at 0 within its positioning context. So a
+  // key that reaches its resting default lands where the element already was.
+  //
+  // The exception worth naming: `flex` / `flexGrow` / `flexShrink` do NOT have
+  // 0 as a universal identity (`flexShrink` defaults to 1 on the web, and RN's
+  // own default differs by axis). They are still 0 here, because the style-scan
+  // in the resting pass reads the real value off the static `style` whenever it
+  // is declared — and a consumer animating flex without declaring it is asking
+  // for the from-0 growth, which is the readable interpretation.
+  borderTopLeftRadius: 0,
+  borderTopRightRadius: 0,
+  borderBottomLeftRadius: 0,
+  borderBottomRightRadius: 0,
+  borderWidth: 0,
+  borderTopWidth: 0,
+  borderRightWidth: 0,
+  borderBottomWidth: 0,
+  borderLeftWidth: 0,
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+  padding: 0,
+  paddingTop: 0,
+  paddingRight: 0,
+  paddingBottom: 0,
+  paddingLeft: 0,
+  paddingHorizontal: 0,
+  paddingVertical: 0,
+  margin: 0,
+  marginTop: 0,
+  marginRight: 0,
+  marginBottom: 0,
+  marginLeft: 0,
+  marginHorizontal: 0,
+  marginVertical: 0,
+  flex: 0,
+  flexGrow: 0,
+  flexShrink: 0,
+  fontSize: 0,
+  letterSpacing: 0,
+  lineHeight: 0,
+  zIndex: 0,
+  gap: 0,
+  rowGap: 0,
+  columnGap: 0,
   // 'transparent' is the only safe universal default for colors: it works as
   // an initial seed for any color animation (no jarring opaque flash on mount
   // when `initial` is omitted) and rgba(0,0,0,0) interpolates cleanly into
@@ -171,6 +352,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 +580,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 +620,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,6 +668,27 @@ 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
@@ -473,21 +716,52 @@ export function createMotionComponent<C extends ComponentType<any>>(
       // a style it has no use for.
       const activeKeys = activeKeysRef.current!
       const everDriven = everDrivenRef.current
-      const styleResting: Partial<Record<AnimatableKey, number | string>> = {}
+      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 = StyleSheet.flatten(style as never) as
-          | Record<string, unknown>
-          | undefined
+        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
@@ -532,12 +806,25 @@ export function createMotionComponent<C extends ComponentType<any>>(
       // 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
@@ -666,6 +953,33 @@ export function createMotionComponent<C extends ComponentType<any>>(
           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
@@ -770,20 +1084,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
@@ -799,6 +1137,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
@@ -810,6 +1154,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)
 
@@ -848,6 +1197,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 },
@@ -876,12 +1242,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(
@@ -969,7 +1351,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
@@ -983,70 +1365,38 @@ type SharedValueMap = Record<AnimatableKey, SharedValue<number | string>>
  * are stable across renders (Reanimated's `useSharedValue` is a `useRef`
  * under the hood), so snapshotting the wrapping object once is safe.
  *
- * Hooks are called in a stable, lexical order — fine for rules-of-hooks.
- * Unused shared values are cheap; the worklet skips them via
- * `activeKeysRef`. Color keys are seeded with the initial color string so
- * Reanimated's value setter recognizes the slot as a color from the first
- * `withSpring` / `withTiming` call.
+ * Hooks are called by iterating `ALL_KEYS`, which is a module-level `as const`
+ * array — its length and order are fixed at module evaluation, so the hook
+ * sequence is identical on every render of every instance. That satisfies
+ * rules-of-hooks exactly as a hand-written list does, and it is what keeps this
+ * function from growing a line per key: the 0.0.5 additions took the table from
+ * 23 keys to 63, and 63 near-identical `useSharedValue` lines is both a bigger
+ * bundle and a standing invitation to add a key in one list but not the other
+ * (the failure mode is a `sharedValues[key]` of `undefined` inside the worklet,
+ * which is exactly how the first draft of that change broke).
+ *
+ * The ESLint exhaustive-deps rule can't see through the loop, hence the
+ * disable — the invariant it would check for us is asserted above instead.
+ *
+ * Unused shared values are cheap; the worklet skips them via `activeKeysRef`.
+ * Color keys are seeded with the initial color string so Reanimated's value
+ * setter recognizes the slot as a color from the first `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>(
-    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>(
-    init('shadowOffsetWidth'),
-  )
-  const shadowOffsetHeight = useSharedValue<number | string>(
-    init('shadowOffsetHeight'),
-  )
+  const entries: [AnimatableKey, SharedValue<AnimatableSlotValue>][] = []
+  for (const key of ALL_KEYS) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    entries.push([key, useSharedValue<AnimatableSlotValue>(init(key))])
+  }
 
   const ref = useRef<SharedValueMap | null>(null)
   if (ref.current === null) {
-    ref.current = {
-      translateX,
-      translateY,
-      scale,
-      scaleX,
-      scaleY,
-      rotate,
-      rotateX,
-      rotateY,
-      opacity,
-      width,
-      height,
-      borderRadius,
-      shadowOpacity,
-      shadowRadius,
-      elevation,
-      backgroundColor,
-      borderColor,
-      color,
-      tintColor,
-      shadowColor,
-      shadowOffsetWidth,
-      shadowOffsetHeight,
-    }
+    const map = {} as SharedValueMap
+    for (const [key, sv] of entries) map[key] = sv
+    ref.current = map
   }
 
   // Cancel every in-flight per-key animation when the primitive unmounts, so
@@ -1084,8 +1434,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
   },
@@ -1105,7 +1458,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'
@@ -1191,18 +1546,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
 }
 
 /**
@@ -1225,6 +1587,46 @@ 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**.
  *
@@ -1460,6 +1862,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)) {