@rootnative/inertia 0.0.4 → 0.0.6

package/dist/motion/Pressable.mjs

@@ -1,4 +1,4 @@
-export { MotionPressable } from '../chunk-RF7J5FRM.mjs';
-import '../chunk-55W7BNO2.mjs';
-import '../chunk-QKC3APP4.mjs';
-import '../chunk-TU2XFPAK.mjs';
+export { MotionPressable } from '../chunk-C3EDC5ZW.mjs';
+import '../chunk-2ICQLWH2.mjs';
+import '../chunk-Z3HCJ43H.mjs';
+import '../chunk-REYL77RE.mjs';

package/dist/motion/ScrollView.d.mts

@@ -1,5 +1,5 @@
 import { ScrollView } from 'react-native';
-import { M as MotionComponent } from '../types-37pN82yh.mjs';
+import { M as MotionComponent } from '../types-BQgLJeQG.mjs';
 import 'react';
 
 /**

package/dist/motion/ScrollView.d.ts

@@ -1,5 +1,5 @@
 import { ScrollView } from 'react-native';
-import { M as MotionComponent } from '../types-37pN82yh.js';
+import { M as MotionComponent } from '../types-BQgLJeQG.js';
 import 'react';
 
 /**

package/dist/motion/ScrollView.js

@@ -1,13 +1,13 @@
 'use strict';
 
-var chunkXMEVPEMH_js = require('../chunk-XMEVPEMH.js');
-require('../chunk-MYE5NMXW.js');
-require('../chunk-WVRCKOPO.js');
-require('../chunk-7A6WTXNK.js');
+var chunkX7B5WR5A_js = require('../chunk-X7B5WR5A.js');
+require('../chunk-767UKZXG.js');
+require('../chunk-OBRGJAST.js');
+require('../chunk-PM6CVGXJ.js');
 
 
 
 Object.defineProperty(exports, "MotionScrollView", {
   enumerable: true,
-  get: function () { return chunkXMEVPEMH_js.MotionScrollView; }
+  get: function () { return chunkX7B5WR5A_js.MotionScrollView; }
 });

package/dist/motion/ScrollView.mjs

@@ -1,4 +1,4 @@
-export { MotionScrollView } from '../chunk-NAOXQJ7U.mjs';
-import '../chunk-55W7BNO2.mjs';
-import '../chunk-QKC3APP4.mjs';
-import '../chunk-TU2XFPAK.mjs';
+export { MotionScrollView } from '../chunk-BAAQI37F.mjs';
+import '../chunk-2ICQLWH2.mjs';
+import '../chunk-Z3HCJ43H.mjs';
+import '../chunk-REYL77RE.mjs';

package/dist/motion/Text.d.mts

@@ -1,5 +1,5 @@
 import { Text } from 'react-native';
-import { M as MotionComponent } from '../types-37pN82yh.mjs';
+import { M as MotionComponent } from '../types-BQgLJeQG.mjs';
 import 'react';
 
 /**

package/dist/motion/Text.d.ts

@@ -1,5 +1,5 @@
 import { Text } from 'react-native';
-import { M as MotionComponent } from '../types-37pN82yh.js';
+import { M as MotionComponent } from '../types-BQgLJeQG.js';
 import 'react';
 
 /**

package/dist/motion/Text.js

@@ -1,13 +1,13 @@
 'use strict';
 
-var chunkTVFNJ25Z_js = require('../chunk-TVFNJ25Z.js');
-require('../chunk-MYE5NMXW.js');
-require('../chunk-WVRCKOPO.js');
-require('../chunk-7A6WTXNK.js');
+var chunkSTARIT6W_js = require('../chunk-STARIT6W.js');
+require('../chunk-767UKZXG.js');
+require('../chunk-OBRGJAST.js');
+require('../chunk-PM6CVGXJ.js');
 
 
 
 Object.defineProperty(exports, "MotionText", {
   enumerable: true,
-  get: function () { return chunkTVFNJ25Z_js.MotionText; }
+  get: function () { return chunkSTARIT6W_js.MotionText; }
 });

package/dist/motion/Text.mjs

@@ -1,4 +1,4 @@
-export { MotionText } from '../chunk-4ASOELLA.mjs';
-import '../chunk-55W7BNO2.mjs';
-import '../chunk-QKC3APP4.mjs';
-import '../chunk-TU2XFPAK.mjs';
+export { MotionText } from '../chunk-F7LJX56B.mjs';
+import '../chunk-2ICQLWH2.mjs';
+import '../chunk-Z3HCJ43H.mjs';
+import '../chunk-REYL77RE.mjs';

package/dist/motion/View.d.mts

@@ -1,5 +1,5 @@
 import { View } from 'react-native';
-import { M as MotionComponent } from '../types-37pN82yh.mjs';
+import { M as MotionComponent } from '../types-BQgLJeQG.mjs';
 import 'react';
 
 /**

package/dist/motion/View.d.ts

@@ -1,5 +1,5 @@
 import { View } from 'react-native';
-import { M as MotionComponent } from '../types-37pN82yh.js';
+import { M as MotionComponent } from '../types-BQgLJeQG.js';
 import 'react';
 
 /**

package/dist/motion/View.js

@@ -1,13 +1,13 @@
 'use strict';
 
-var chunkVLDIFL3F_js = require('../chunk-VLDIFL3F.js');
-require('../chunk-MYE5NMXW.js');
-require('../chunk-WVRCKOPO.js');
-require('../chunk-7A6WTXNK.js');
+var chunkK5SI6VXS_js = require('../chunk-K5SI6VXS.js');
+require('../chunk-767UKZXG.js');
+require('../chunk-OBRGJAST.js');
+require('../chunk-PM6CVGXJ.js');
 
 
 
 Object.defineProperty(exports, "MotionView", {
   enumerable: true,
-  get: function () { return chunkVLDIFL3F_js.MotionView; }
+  get: function () { return chunkK5SI6VXS_js.MotionView; }
 });

package/dist/motion/View.mjs

@@ -1,4 +1,4 @@
-export { MotionView } from '../chunk-YKGY22SB.mjs';
-import '../chunk-55W7BNO2.mjs';
-import '../chunk-QKC3APP4.mjs';
-import '../chunk-TU2XFPAK.mjs';
+export { MotionView } from '../chunk-CMHVF6F4.mjs';
+import '../chunk-2ICQLWH2.mjs';
+import '../chunk-Z3HCJ43H.mjs';
+import '../chunk-REYL77RE.mjs';

package/dist/touch/index.d.mts

@@ -1,6 +1,6 @@
 import { PanResponderInstance } from 'react-native';
 import { useAnimatedStyle, SharedValue } from 'react-native-reanimated';
-import { T as TransitionConfig } from '../types-37pN82yh.mjs';
+import { T as TransitionConfig } from '../types-BQgLJeQG.mjs';
 import 'react';
 
 /**

package/dist/touch/index.d.ts

@@ -1,6 +1,6 @@
 import { PanResponderInstance } from 'react-native';
 import { useAnimatedStyle, SharedValue } from 'react-native-reanimated';
-import { T as TransitionConfig } from '../types-37pN82yh.js';
+import { T as TransitionConfig } from '../types-BQgLJeQG.js';
 import 'react';
 
 /**

package/dist/touch/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunk7A6WTXNK_js = require('../chunk-7A6WTXNK.js');
+var chunkPM6CVGXJ_js = require('../chunk-PM6CVGXJ.js');
 var react = require('react');
 var reactNative = require('react-native');
 var reactNativeReanimated = require('react-native-reanimated');
@@ -48,14 +48,14 @@ function useTouchDrag(options = {}) {
         if (result) {
           if (result.x && lockX) {
             const toX = "to" in result.x ? result.x.to : x;
-            dragX.value = chunk7A6WTXNK_js.buildReleaseAnimation(
+            dragX.value = chunkPM6CVGXJ_js.buildReleaseAnimation(
               result.x,
               toX
             );
           }
           if (result.y && lockY) {
             const toY = "to" in result.y ? result.y.to : y;
-            dragY.value = chunk7A6WTXNK_js.buildReleaseAnimation(
+            dragY.value = chunkPM6CVGXJ_js.buildReleaseAnimation(
               result.y,
               toY
             );

package/dist/touch/index.mjs

@@ -1,4 +1,4 @@
-import { buildReleaseAnimation } from '../chunk-TU2XFPAK.mjs';
+import { buildReleaseAnimation } from '../chunk-REYL77RE.mjs';
 import { useMemo } from 'react';
 import { PanResponder } from 'react-native';
 import { useSharedValue, useAnimatedStyle } from 'react-native-reanimated';

package/dist/{types-37pN82yh.d.mts → types-BQgLJeQG.d.mts}

@@ -184,6 +184,20 @@ type BoxShadowInput = string | ReadonlyArray<BoxShadowValue>;
 type AnimatableStructuredExtras<S> = 'boxShadow' extends keyof S ? {
     boxShadow?: BoxShadowInput;
 } : {};
+/**
+ * The `transform: [...]` array form, passed through as the underlying style
+ * types it. Inertia reads transform entries out of the array (see
+ * `styleValueFor` in `createMotionComponent`) rather than treating the array as
+ * an animatable scalar, so it is exempted from the `AnimatableValue` mapping —
+ * wrapping it there would offer a nonsensical `transform: [[...], [...]]`
+ * keyframe form.
+ *
+ * Conditional on `S` for the same reason as `boxShadow`: only appears where the
+ * underlying style actually has it.
+ */
+type AnimatableTransformArray<S> = 'transform' extends keyof S ? {
+    transform?: S['transform'];
+} : {};
 /**
  * The animation state shape inferred from the underlying component's style
  * prop. We narrow to the value side of `style` so consumers see ViewStyle on
@@ -196,11 +210,33 @@ type AnimatableStructuredExtras<S> = 'boxShadow' extends keyof S ? {
  * accepts any key. Excluding functions first keeps inference tight.
  */
 type _StyleValue<T> = Exclude<T, (...args: any[]) => any>;
+/**
+ * The style keys Inertia's runtime actually drives — the type-level mirror of
+ * `ALL_KEYS` in `createMotionComponent`, minus the `shadowOffset*` synthetics
+ * (consumers write the nested `shadowOffset` object, not the axes) and minus
+ * `boxShadow` (handled by `AnimatableStructuredExtras`, whose value shape
+ * deliberately departs from `AnimatableValue`).
+ *
+ * **This list and `ALL_KEYS` must stay in sync.** They are separate because one
+ * is a type and the other is a runtime array, and TypeScript can't derive the
+ * former from a value living in a module that imports this one. The direction
+ * that matters: a key here but not in `ALL_KEYS` typechecks and then silently
+ * does nothing at runtime — which is precisely the defect this type was
+ * introduced to kill. `animate-keys.test-d.tsx` pins the two together.
+ *
+ * Before 0.0.5 this type mapped over the component's *entire* style surface, so
+ * `animate={{ paddingTop: 40 }}` compiled cleanly and was then dropped on the
+ * floor — no error, no warning. That contradicted the library's own headline
+ * differentiator (wrong props should error, not go unnoticed), so the mapping is
+ * now an intersection: a key must be both animatable by Inertia *and* present on
+ * the underlying component's style prop.
+ */
+type AnimatableStyleKey = 'translateX' | 'translateY' | 'scaleX' | 'scaleY' | 'opacity' | 'width' | 'height' | 'borderRadius' | 'shadowOpacity' | 'shadowRadius' | 'elevation' | 'borderTopLeftRadius' | 'borderTopRightRadius' | 'borderBottomLeftRadius' | 'borderBottomRightRadius' | 'borderWidth' | 'borderTopWidth' | 'borderRightWidth' | 'borderBottomWidth' | 'borderLeftWidth' | 'top' | 'right' | 'bottom' | 'left' | 'padding' | 'paddingTop' | 'paddingRight' | 'paddingBottom' | 'paddingLeft' | 'paddingHorizontal' | 'paddingVertical' | 'margin' | 'marginTop' | 'marginRight' | 'marginBottom' | 'marginLeft' | 'marginHorizontal' | 'marginVertical' | 'flex' | 'flexGrow' | 'flexShrink' | 'fontSize' | 'letterSpacing' | 'lineHeight' | 'zIndex' | 'gap' | 'rowGap' | 'columnGap' | 'backgroundColor' | 'borderColor' | 'color' | 'tintColor' | 'shadowColor' | 'shadowOffset';
 type AnimateStyle<C> = C extends {
     style?: infer Raw;
-} ? _StyleValue<Raw> extends StyleProp<infer S> ? Omit<{
-    [K in keyof S]?: AnimatableValue<S[K]>;
-}, 'boxShadow'> & AnimatableTransformExtras & AnimatableStructuredExtras<S> : never : never;
+} ? _StyleValue<Raw> extends StyleProp<infer S> ? {
+    [K in keyof S as K extends AnimatableStyleKey ? K : never]?: K extends 'boxShadow' | 'transform' ? never : AnimatableValue<S[K]>;
+} & AnimatableTransformExtras & AnimatableStructuredExtras<S> & AnimatableTransformArray<S> : never : never;
 interface AnimationCallbackInfo<S> {
     /**
      * The animatable key that just settled — typically a `keyof S` (e.g.

package/dist/{types-37pN82yh.d.ts → types-BQgLJeQG.d.ts}

@@ -184,6 +184,20 @@ type BoxShadowInput = string | ReadonlyArray<BoxShadowValue>;
 type AnimatableStructuredExtras<S> = 'boxShadow' extends keyof S ? {
     boxShadow?: BoxShadowInput;
 } : {};
+/**
+ * The `transform: [...]` array form, passed through as the underlying style
+ * types it. Inertia reads transform entries out of the array (see
+ * `styleValueFor` in `createMotionComponent`) rather than treating the array as
+ * an animatable scalar, so it is exempted from the `AnimatableValue` mapping —
+ * wrapping it there would offer a nonsensical `transform: [[...], [...]]`
+ * keyframe form.
+ *
+ * Conditional on `S` for the same reason as `boxShadow`: only appears where the
+ * underlying style actually has it.
+ */
+type AnimatableTransformArray<S> = 'transform' extends keyof S ? {
+    transform?: S['transform'];
+} : {};
 /**
  * The animation state shape inferred from the underlying component's style
  * prop. We narrow to the value side of `style` so consumers see ViewStyle on
@@ -196,11 +210,33 @@ type AnimatableStructuredExtras<S> = 'boxShadow' extends keyof S ? {
  * accepts any key. Excluding functions first keeps inference tight.
  */
 type _StyleValue<T> = Exclude<T, (...args: any[]) => any>;
+/**
+ * The style keys Inertia's runtime actually drives — the type-level mirror of
+ * `ALL_KEYS` in `createMotionComponent`, minus the `shadowOffset*` synthetics
+ * (consumers write the nested `shadowOffset` object, not the axes) and minus
+ * `boxShadow` (handled by `AnimatableStructuredExtras`, whose value shape
+ * deliberately departs from `AnimatableValue`).
+ *
+ * **This list and `ALL_KEYS` must stay in sync.** They are separate because one
+ * is a type and the other is a runtime array, and TypeScript can't derive the
+ * former from a value living in a module that imports this one. The direction
+ * that matters: a key here but not in `ALL_KEYS` typechecks and then silently
+ * does nothing at runtime — which is precisely the defect this type was
+ * introduced to kill. `animate-keys.test-d.tsx` pins the two together.
+ *
+ * Before 0.0.5 this type mapped over the component's *entire* style surface, so
+ * `animate={{ paddingTop: 40 }}` compiled cleanly and was then dropped on the
+ * floor — no error, no warning. That contradicted the library's own headline
+ * differentiator (wrong props should error, not go unnoticed), so the mapping is
+ * now an intersection: a key must be both animatable by Inertia *and* present on
+ * the underlying component's style prop.
+ */
+type AnimatableStyleKey = 'translateX' | 'translateY' | 'scaleX' | 'scaleY' | 'opacity' | 'width' | 'height' | 'borderRadius' | 'shadowOpacity' | 'shadowRadius' | 'elevation' | 'borderTopLeftRadius' | 'borderTopRightRadius' | 'borderBottomLeftRadius' | 'borderBottomRightRadius' | 'borderWidth' | 'borderTopWidth' | 'borderRightWidth' | 'borderBottomWidth' | 'borderLeftWidth' | 'top' | 'right' | 'bottom' | 'left' | 'padding' | 'paddingTop' | 'paddingRight' | 'paddingBottom' | 'paddingLeft' | 'paddingHorizontal' | 'paddingVertical' | 'margin' | 'marginTop' | 'marginRight' | 'marginBottom' | 'marginLeft' | 'marginHorizontal' | 'marginVertical' | 'flex' | 'flexGrow' | 'flexShrink' | 'fontSize' | 'letterSpacing' | 'lineHeight' | 'zIndex' | 'gap' | 'rowGap' | 'columnGap' | 'backgroundColor' | 'borderColor' | 'color' | 'tintColor' | 'shadowColor' | 'shadowOffset';
 type AnimateStyle<C> = C extends {
     style?: infer Raw;
-} ? _StyleValue<Raw> extends StyleProp<infer S> ? Omit<{
-    [K in keyof S]?: AnimatableValue<S[K]>;
-}, 'boxShadow'> & AnimatableTransformExtras & AnimatableStructuredExtras<S> : never : never;
+} ? _StyleValue<Raw> extends StyleProp<infer S> ? {
+    [K in keyof S as K extends AnimatableStyleKey ? K : never]?: K extends 'boxShadow' | 'transform' ? never : AnimatableValue<S[K]>;
+} & AnimatableTransformExtras & AnimatableStructuredExtras<S> & AnimatableTransformArray<S> : never : never;
 interface AnimationCallbackInfo<S> {
     /**
      * The animatable key that just settled — typically a `keyof S` (e.g.

package/dist/{useGesture-Cl4uzZIr.d.ts → useGesture-B0_CzOUz.d.ts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { a as TransitionInput, G as GestureLayerTransitions } from './types-37pN82yh.js';
+import { a as TransitionInput, G as GestureLayerTransitions } from './types-BQgLJeQG.js';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the

package/dist/{useGesture-_IKkS8Dv.d.mts → useGesture-DfaTx-3t.d.mts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { a as TransitionInput, G as GestureLayerTransitions } from './types-37pN82yh.mjs';
+import { a as TransitionInput, G as GestureLayerTransitions } from './types-BQgLJeQG.mjs';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the

package/llms.txt

@@ -67,6 +67,7 @@ import { MotionScrollView } from '@rootnative/inertia/scroll-view'
 - `resolveAnimatableValue(value, base, factory?)` — one level up: resolves a full per-property `animate` value (plain target, `{ to, ...override }` step, or keyframe array → `withSequence` with sequence-level `repeat`) into one animation. Gives custom components the complete `animate` grammar.
 - `cubicBezier(x1, y1, x2, y2)` / `cubicBezier(css)` — builds a `timing.easing` value from cubic-bezier control points: four numbers, a W3C CSS `cubic-bezier(0.2, 0, 0, 1)` string (design-token form), or a CSS keyword (`'linear'` | `'ease'` | `'ease-in'` | `'ease-out'` | `'ease-in-out'`). Makes CSS-format easing tokens directly consumable — pair with named transitions to feed a theme's motion tokens into the registry. Invalid input throws (`x1`/`x2` must be within [0, 1]; `step-*` and `linear(...)` unsupported).
 - `ensureWorkletEasing(easing)` — normalizes any accepted easing input (plain function, worklet, or Reanimated 4 `EasingFunctionFactory`) into a worklet `withTiming` can consume. Only needed for manual `withTiming` calls — the resolvers and primitives apply it automatically.
+- `TRANSPARENT` — `'rgba(0, 0, 0, 0)'`, the value to seed a colour shared value with when a custom component has no other source. Not `'transparent'`: Reanimated's colour table maps that keyword to `undefined`, so it is the one CSS colour name `isColor()` rejects, and a slot resting at it cannot be animated away from — under `withTiming` the target still snaps in at the end, under `withSpring` (the default) the animation never settles. Only affects values passed to `withSpring` / `withTiming`; `interpolateColor` parses the keyword fine, so hooks that interpolate colours themselves are unaffected.
 - `SharedValue<T>` (type) — re-exported from the root entry so props/refs that carry a value-layer hook result can be typed without importing from `react-native-reanimated`.
 - `@rootnative/inertia/reanimated` — render-layer interop subpath: pure re-exports of `Animated`, `createAnimatedComponent`, `useAnimatedStyle`, `useAnimatedProps`, `useDerivedValue`, `interpolate`, `interpolateColor`, `Extrapolation`, `cancelAnimation` (plus `SharedValue` / `DerivedValue` / `AnimatedStyle` / `AnimatedProps` types) under their original Reanimated names, for components that own their own `useAnimatedStyle` worklet over Inertia-driven shared values. Names must stay original — the Reanimated Babel plugin auto-workletizes callbacks by callee name. The `with*` animation factories are deliberately not re-exported; start animations with `useAnimation` / `resolveTransition` / `buildReleaseAnimation`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/inertia",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "RootNative",

package/src/index.ts

@@ -39,6 +39,10 @@ export {
   resolveAnimatableValue,
   ensureWorkletEasing,
 } from './transitions'
+// Seed value for any color shared value a custom animated component drives
+// through `resolveTransition`. Exported because the obvious choice —
+// `'transparent'` — cannot be animated away from; see the symbol's own docs.
+export { TRANSPARENT } from './internal/color'
 export {
   useAnimation,
   useAnimator,

package/src/internal/boxShadow.ts

@@ -12,6 +12,8 @@
  * loudly there, not silently render the wrong elevation.
  */
 
+import { normalizeAnimatableColor, TRANSPARENT } from './color'
+
 /**
  * One layer of a `box-shadow`, structurally mirroring React Native's
  * `BoxShadowValue` (RN 0.76+ `boxShadow` style). Lengths are px numbers.
@@ -205,7 +207,7 @@ function invisibleLayer(inset: boolean): ResolvedBoxShadowLayer {
     offsetY: 0,
     blurRadius: 0,
     spreadDistance: 0,
-    color: 'transparent',
+    color: TRANSPARENT,
     inset,
   }
 }
@@ -225,10 +227,10 @@ function invisibleLayer(inset: boolean): ResolvedBoxShadowLayer {
  * drive, and nothing it can't.
  *
  * `inset` is deliberately absent. `withTiming` / `withSpring` recurse into
- * arrays and objects and animate each leaf, and a boolean leaf falls through
- * to the plain numeric path — `false + (false - false) * p` evaluates to `0`,
- * so an in-flight frame hands the native shadow a number where it expects a
- * boolean. Inset is instead carried alongside as a static per-layer flag (see
+ * objects and animate each leaf, and a boolean leaf falls through to the plain
+ * numeric path — `false + (false - false) * p` evaluates to `0`, so an
+ * in-flight frame hands the native shadow a number where it expects a boolean.
+ * Inset is instead carried alongside as a static per-layer flag (see
  * `SplitBoxShadow.insets`) and reattached when the style is emitted.
  */
 export interface AnimatedBoxShadowLayer {
@@ -295,10 +297,16 @@ function coerceLength(value: unknown, field: string): number {
   return parseFloat(trimmed)
 }
 
-/** Drop `inset`, leaving only the fields Reanimated may drive. */
+/**
+ * Drop `inset`, leaving only the fields Reanimated may drive, and rewrite a
+ * `'transparent'` colour to its RGBA spelling — see {@link TRANSPARENT} for
+ * why the CSS keyword cannot be animated. Done here rather than at parse time
+ * so the `useShadow` path, which interpolates colours itself and accepts the
+ * keyword happily, keeps the consumer's own spelling.
+ */
 function strip(layer: ResolvedBoxShadowLayer): AnimatedBoxShadowLayer {
-  const { inset: _inset, ...rest } = layer
-  return rest
+  const { inset: _inset, color, ...rest } = layer
+  return { ...rest, color: normalizeAnimatableColor(color) }
 }
 
 /**
@@ -335,7 +343,7 @@ export function normalizeBoxShadow(input: BoxShadowInput): SplitBoxShadow {
  * Prepare a from/to pair for a Reanimated-driven `boxShadow` animation.
  *
  * Both sides come back padded to the same layer count, because Reanimated's
- * `arrayOnStart` walks the **current** value's indices and reads `toValue[i]`
+ * `objectOnStart` walks the **current** value's keys and reads `toValue[key]`
  * for each — a target with fewer layers leaves the surplus leaves with
  * `toValue: undefined`, and a target with more never animates the extras at
  * all. `pairBoxShadowLayers` supplies the padding (a transparent zero layer,
@@ -373,3 +381,57 @@ export function prepareBoxShadowAnimation(
   }
   return { from, to, insets }
 }
+
+/**
+ * The shape a `boxShadow` shared value actually holds: layers keyed by their
+ * index (`{ 0: layer, 1: layer }`) rather than an array.
+ *
+ * **This is not cosmetic, and an array does not work here.** Reanimated's
+ * animation drivers walk a structured value by dispatching on each leaf's
+ * runtime shape, but the two container branches are not symmetrical
+ * (`animation/util.ts`):
+ *
+ * - `objectOnStart` re-assigns the **decorated** `onStart` onto each child
+ *   (`animation[key].onStart = animation.onStart`), so a child that is itself
+ *   an object or a colour is dispatched again, recursively.
+ * - `arrayOnStart` does not. Each element gets the **base** scalar `onStart`,
+ *   so anything other than a number is handed straight to the spring/timing
+ *   maths. A layer object yields `object - object` → `NaN`; a colour string
+ *   yields the same.
+ *
+ * The failure is silent and total: `withTiming` still snaps to the target when
+ * its duration elapses, so an array *looks* like it works, while `withSpring`
+ * — Inertia's default — decides it has settled only when
+ * `isAnimationTerminatingCalculation` says so, and every comparison against
+ * `NaN` is false. The animation never finishes, the shared value holds
+ * `'[object Object]NaN'` forever, `onAnimationEnd` never fires, and the frame
+ * loop never stops.
+ *
+ * Keying by index sends the layer list down the object branch, where the
+ * recursion works and each layer's colour reaches the RGBA-channel path.
+ */
+export type BoxShadowPayload = Record<string, AnimatedBoxShadowLayer>
+
+/** Index-key a layer list into the shape a shared value can animate. */
+export function layersToPayload(
+  layers: readonly AnimatedBoxShadowLayer[],
+): BoxShadowPayload {
+  const payload: BoxShadowPayload = {}
+  for (let i = 0; i < layers.length; i++) payload[i] = layers[i]!
+  return payload
+}
+
+/**
+ * Read an index-keyed payload back out as a layer list.
+ *
+ * Callable from a worklet: the loop stops at the first missing index rather
+ * than asking for the key set, so no `Object.keys` runs at frame time.
+ */
+export function payloadToLayers(
+  payload: BoxShadowPayload,
+): AnimatedBoxShadowLayer[] {
+  'worklet'
+  const layers: AnimatedBoxShadowLayer[] = []
+  for (let i = 0; payload[i] !== undefined; i++) layers.push(payload[i]!)
+  return layers
+}

package/src/internal/color.ts

@@ -0,0 +1,70 @@
+/**
+ * The one colour spelling Reanimated's animation drivers cannot accept.
+ *
+ * Reanimated dispatches an animation on the runtime shape of its **source**
+ * value, and `isColor()` is the gate for the RGBA-channel path. That gate is
+ * `processColorInitially(value) != null`, and Reanimated's colour-name table
+ * (`Colors.ts`) maps `transparent` to `undefined` — every other CSS colour
+ * name maps to a packed integer. So `'transparent'` is the single named colour
+ * that reports **false**.
+ *
+ * A value that fails the gate but is still a string falls to the
+ * prefix-number-suffix branch, which exists for values like `'100%'`. It runs
+ * `parseFloat('transparent')` → `NaN`, animates that, and re-attaches the
+ * prefix, so the slot fills with `'transparentNaN'`. Under `withTiming` the
+ * animation still snaps to its target when the duration elapses, which hides
+ * the fault; under `withSpring` — the library default — settling is decided by
+ * comparisons against `NaN`, which are all false, so the animation runs
+ * forever and the colour never appears.
+ *
+ * `'rgba(0, 0, 0, 0)'` is the same colour and passes the gate.
+ *
+ * This only applies to values handed to `withSpring` / `withTiming`.
+ * `interpolateColor` parses `'transparent'` correctly, which is why the
+ * gesture cascade, the shared-element carry, and `useShadow` are unaffected
+ * and keep the consumer's own spelling.
+ */
+export const TRANSPARENT = 'rgba(0, 0, 0, 0)'
+
+/**
+ * Rewrite `'transparent'` to a spelling Reanimated recognises. Any other value
+ * — a different colour, a number, a non-string — is returned untouched, by
+ * reference, so this costs nothing on the overwhelmingly common path.
+ */
+export function normalizeAnimatableColor<T>(value: T): T | string {
+  return value === 'transparent' ? TRANSPARENT : value
+}
+
+/**
+ * Apply {@link normalizeAnimatableColor} across a whole `animate` target for a
+ * colour key, including the sequence forms — a keyframe array whose entries are
+ * either raw values or `{ to, ...transitionOverride }` step objects.
+ *
+ * Returns the input by reference when nothing needed rewriting, so an
+ * unaffected target neither allocates nor breaks any identity a caller relies
+ * on.
+ */
+export function normalizeAnimatableColorTarget<T>(target: T): T {
+  if (typeof target === 'string') {
+    return normalizeAnimatableColor(target) as T
+  }
+  if (!Array.isArray(target)) return target
+
+  let changed = false
+  const next = target.map((step) => {
+    if (step === 'transparent') {
+      changed = true
+      return TRANSPARENT
+    }
+    if (
+      step !== null &&
+      typeof step === 'object' &&
+      (step as { to?: unknown }).to === 'transparent'
+    ) {
+      changed = true
+      return { ...(step as object), to: TRANSPARENT }
+    }
+    return step
+  })
+  return (changed ? next : target) as T
+}