@rootnative/inertia 0.0.5 → 0.0.7

package/dist/motion/Image.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkGPOMFIIU_js = require('../chunk-GPOMFIIU.js');
-require('../chunk-VQ5D35UA.js');
+var chunkYUTS6JRU_js = require('../chunk-YUTS6JRU.js');
+require('../chunk-6V7MOBXO.js');
 require('../chunk-OBRGJAST.js');
 require('../chunk-PM6CVGXJ.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PM6CVGXJ.js');
 
 Object.defineProperty(exports, "MotionImage", {
   enumerable: true,
-  get: function () { return chunkGPOMFIIU_js.MotionImage; }
+  get: function () { return chunkYUTS6JRU_js.MotionImage; }
 });

package/dist/motion/Image.mjs

@@ -1,4 +1,4 @@
-export { MotionImage } from '../chunk-XSK5MNUH.mjs';
-import '../chunk-RIVVBABB.mjs';
+export { MotionImage } from '../chunk-KBFN4TRO.mjs';
+import '../chunk-HPJMIBBK.mjs';
 import '../chunk-Z3HCJ43H.mjs';
 import '../chunk-REYL77RE.mjs';

package/dist/motion/Pressable.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import * as react_native from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.mjs';
+import { M as MotionComponent } from '../types-DyJpG64F.mjs';
 
 /**
  * Animatable `Pressable`. The `gesture` prop's `pressed` sub-state hooks into

package/dist/motion/Pressable.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import * as react_native from 'react-native';
-import { M as MotionComponent } from '../types-BQgLJeQG.js';
+import { M as MotionComponent } from '../types-DyJpG64F.js';
 
 /**
  * Animatable `Pressable`. The `gesture` prop's `pressed` sub-state hooks into

package/dist/motion/Pressable.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk27U6766G_js = require('../chunk-27U6766G.js');
-require('../chunk-VQ5D35UA.js');
+var chunkWGCF3WQG_js = require('../chunk-WGCF3WQG.js');
+require('../chunk-6V7MOBXO.js');
 require('../chunk-OBRGJAST.js');
 require('../chunk-PM6CVGXJ.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PM6CVGXJ.js');
 
 Object.defineProperty(exports, "MotionPressable", {
   enumerable: true,
-  get: function () { return chunk27U6766G_js.MotionPressable; }
+  get: function () { return chunkWGCF3WQG_js.MotionPressable; }
 });

package/dist/motion/Pressable.mjs

@@ -1,4 +1,4 @@
-export { MotionPressable } from '../chunk-OAUWLPQH.mjs';
-import '../chunk-RIVVBABB.mjs';
+export { MotionPressable } from '../chunk-52QSN2VQ.mjs';
+import '../chunk-HPJMIBBK.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-BQgLJeQG.mjs';
+import { M as MotionComponent } from '../types-DyJpG64F.mjs';
 import 'react';
 
 /**

package/dist/motion/ScrollView.d.ts

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

package/dist/motion/ScrollView.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkQQVDZKSD_js = require('../chunk-QQVDZKSD.js');
-require('../chunk-VQ5D35UA.js');
+var chunkQYR66E2G_js = require('../chunk-QYR66E2G.js');
+require('../chunk-6V7MOBXO.js');
 require('../chunk-OBRGJAST.js');
 require('../chunk-PM6CVGXJ.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PM6CVGXJ.js');
 
 Object.defineProperty(exports, "MotionScrollView", {
   enumerable: true,
-  get: function () { return chunkQQVDZKSD_js.MotionScrollView; }
+  get: function () { return chunkQYR66E2G_js.MotionScrollView; }
 });

package/dist/motion/ScrollView.mjs

@@ -1,4 +1,4 @@
-export { MotionScrollView } from '../chunk-27MKBTSG.mjs';
-import '../chunk-RIVVBABB.mjs';
+export { MotionScrollView } from '../chunk-VSK2E35J.mjs';
+import '../chunk-HPJMIBBK.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-BQgLJeQG.mjs';
+import { M as MotionComponent } from '../types-DyJpG64F.mjs';
 import 'react';
 
 /**

package/dist/motion/Text.d.ts

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

package/dist/motion/Text.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk67GHRCF6_js = require('../chunk-67GHRCF6.js');
-require('../chunk-VQ5D35UA.js');
+var chunkZSOCRHU3_js = require('../chunk-ZSOCRHU3.js');
+require('../chunk-6V7MOBXO.js');
 require('../chunk-OBRGJAST.js');
 require('../chunk-PM6CVGXJ.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PM6CVGXJ.js');
 
 Object.defineProperty(exports, "MotionText", {
   enumerable: true,
-  get: function () { return chunk67GHRCF6_js.MotionText; }
+  get: function () { return chunkZSOCRHU3_js.MotionText; }
 });

package/dist/motion/Text.mjs

@@ -1,4 +1,4 @@
-export { MotionText } from '../chunk-COEJVWRZ.mjs';
-import '../chunk-RIVVBABB.mjs';
+export { MotionText } from '../chunk-WMLS4TMX.mjs';
+import '../chunk-HPJMIBBK.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-BQgLJeQG.mjs';
+import { M as MotionComponent } from '../types-DyJpG64F.mjs';
 import 'react';
 
 /**

package/dist/motion/View.d.ts

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

package/dist/motion/View.js

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkK63LXGKS_js = require('../chunk-K63LXGKS.js');
-require('../chunk-VQ5D35UA.js');
+var chunkNPJ46457_js = require('../chunk-NPJ46457.js');
+require('../chunk-6V7MOBXO.js');
 require('../chunk-OBRGJAST.js');
 require('../chunk-PM6CVGXJ.js');
 
@@ -9,5 +9,5 @@ require('../chunk-PM6CVGXJ.js');
 
 Object.defineProperty(exports, "MotionView", {
   enumerable: true,
-  get: function () { return chunkK63LXGKS_js.MotionView; }
+  get: function () { return chunkNPJ46457_js.MotionView; }
 });

package/dist/motion/View.mjs

@@ -1,4 +1,4 @@
-export { MotionView } from '../chunk-GTJ6VAH5.mjs';
-import '../chunk-RIVVBABB.mjs';
+export { MotionView } from '../chunk-RUIOM2YZ.mjs';
+import '../chunk-HPJMIBBK.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-BQgLJeQG.mjs';
+import { T as TransitionConfig } from '../types-DyJpG64F.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-BQgLJeQG.js';
+import { T as TransitionConfig } from '../types-DyJpG64F.js';
 import 'react';
 
 /**

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

@@ -456,4 +456,4 @@ interface MotionComponent<C extends ComponentType<any>> {
     displayName?: string;
 }
 
-export type { AnimatableValue as A, BoxShadowInput as B, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantController as V, TransitionInput as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, GestureSubStates as g, MotionProps as h, NoAnimationTransition as i, RepeatConfig as j, SequenceStep as k, TimingTransition as l, Transition as m, VariantsMap as n };
+export type { AnimatableValue as A, BoxShadowInput as B, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantsMap as V, MotionProps as a, TransitionInput as b, TransitionName as c, VariantController as d, AnimateStyle as e, AnimationCallbackInfo as f, EasingFunction as g, EasingFunctionFactory as h, GestureSubStates as i, NoAnimationTransition as j, RepeatConfig as k, SequenceStep as l, TimingTransition as m, Transition as n };

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

@@ -456,4 +456,4 @@ interface MotionComponent<C extends ComponentType<any>> {
     displayName?: string;
 }
 
-export type { AnimatableValue as A, BoxShadowInput as B, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantController as V, TransitionInput as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, GestureSubStates as g, MotionProps as h, NoAnimationTransition as i, RepeatConfig as j, SequenceStep as k, TimingTransition as l, Transition as m, VariantsMap as n };
+export type { AnimatableValue as A, BoxShadowInput as B, DecayTransition as D, EasingInput as E, GestureLayerTransitions as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionConfig as T, VariantsMap as V, MotionProps as a, TransitionInput as b, TransitionName as c, VariantController as d, AnimateStyle as e, AnimationCallbackInfo as f, EasingFunction as g, EasingFunctionFactory as h, GestureSubStates as i, NoAnimationTransition as j, RepeatConfig as k, SequenceStep as l, TimingTransition as m, Transition as n };

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

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

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

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

package/jest-setup.js

@@ -45,7 +45,7 @@ jest.mock('react-native/Libraries/Text/Text', () => {
 //      run; targets snap in one step.
 jest.mock('react-native-reanimated', () => {
   const React = require('react')
-  const { Image, ScrollView, Text, View } = require('react-native')
+  const { FlatList, Image, ScrollView, Text, View } = require('react-native')
 
   const wrap = (Component, displayName) => {
     const Wrapped = React.forwardRef((props, ref) =>
@@ -59,6 +59,10 @@ jest.mock('react-native-reanimated', () => {
   const AnimatedText = wrap(Text, 'Animated.Text')
   const AnimatedImage = wrap(Image, 'Animated.Image')
   const AnimatedScrollView = wrap(ScrollView, 'Animated.ScrollView')
+  // Reanimated's real `Animated.FlatList` also defaults `scrollEventThrottle`
+  // to 1 and injects a `CellRendererComponent`; neither is observable in this
+  // mock, so the wrapper is a plain pass-through like the others.
+  const AnimatedFlatList = wrap(FlatList, 'Animated.FlatList')
 
   return {
     __esModule: true,
@@ -67,6 +71,7 @@ jest.mock('react-native-reanimated', () => {
       Text: AnimatedText,
       Image: AnimatedImage,
       ScrollView: AnimatedScrollView,
+      FlatList: AnimatedFlatList,
       createAnimatedComponent: (c) =>
         wrap(c, `Animated(${c.displayName ?? c.name ?? 'Component'})`),
     },
@@ -74,6 +79,7 @@ jest.mock('react-native-reanimated', () => {
     Text: AnimatedText,
     Image: AnimatedImage,
     ScrollView: AnimatedScrollView,
+    FlatList: AnimatedFlatList,
     useSharedValue: (initial) => {
       const ref = React.useRef(null)
       if (ref.current === null) ref.current = { value: initial }

package/llms.txt

@@ -34,17 +34,21 @@ import {
 import { useGestureLayer } from '@rootnative/inertia/gesture-layer'
 // Render-layer Reanimated interop for custom animated components:
 import { Animated, useAnimatedStyle } from '@rootnative/inertia/reanimated'
-// or for tree-shaking the primitives:
+// or for tree-shaking the primitives. NOTE: these subpaths export a
+// differently NAMED symbol — `MotionScrollView`, not `Motion.ScrollView`.
+// `Motion` itself is only exported from the package root above, and there
+// is no '@rootnative/inertia/motion' subpath.
 import { MotionView } from '@rootnative/inertia/view'
 import { MotionText } from '@rootnative/inertia/text'
 import { MotionImage } from '@rootnative/inertia/image'
 import { MotionPressable } from '@rootnative/inertia/pressable'
 import { MotionScrollView } from '@rootnative/inertia/scroll-view'
+import { MotionFlatList } from '@rootnative/inertia/flat-list'
 ```
 
 ## Public API
 
-- `Motion.View` / `Motion.Text` / `Motion.Image` / `Motion.Pressable` / `Motion.ScrollView` — animatable primitives. Per-primitive style inference (no shared `ViewStyle & TextStyle & ImageStyle` fallback).
+- `Motion.View` / `Motion.Text` / `Motion.Image` / `Motion.Pressable` / `Motion.ScrollView` / `Motion.FlatList` — animatable primitives. Per-primitive style inference (no shared `ViewStyle & TextStyle & ImageStyle` fallback). `Motion.FlatList` is the **virtualized** animated scroller: it takes `useScroll`'s `onScroll` handler and keeps `data` / `renderItem` item-type inference, so a long list can virtualize and animate at once. Animation props apply to the scroll container; animate rows with a `Motion.*` inside `renderItem`.
 - `<Presence>` — mount / unmount transitions; children need explicit `key`s. Exiting children get `pointerEvents: 'none'` automatically.
 - `<MotionConfig reducedMotion="user" | "never" | "always" transitions={{ name: TransitionConfig }}>` — gates motion against the OS reduce-motion setting (default `"user"`) and registers named transitions for the subtree. A registered name is accepted anywhere a `TransitionConfig` is: the `transition` prop (top-level and per-property/per-layer), the `layout` prop, and the value-layer hooks (`transition="selection"`, `useBooleanSpring(checked, 'selection')`). Nested providers merge (child overrides per name); unknown names warn in dev and fall back to the default spring. Names are consumer vocabulary — no presets ship with the library. Optional compile-time narrowing via `declare module '@rootnative/inertia' { interface RegisteredTransitions { ... } }`. Custom components join the registry with `useNamedTransitions()` + `resolveNamedTransition(input, registry)`.
 - `useGesture(transition?)` — hook-form of the `gesture` prop. Returns 0↔1 progress shared values (`pressed`, `focused`, `focusVisible`, `hovered`) plus a `handlers` bag to spread on a `Pressable`. Use when one gesture needs to drive multiple animated siblings (focus rings, MD3 state-layer halos, multi-element compositions).
@@ -60,13 +64,14 @@ import { MotionScrollView } from '@rootnative/inertia/scroll-view'
 - `useColorTransition(progress, [from, to], options?)` — pure value-layer interpolator for a single color channel, driven by a `SharedValue<number>` (0→1). Returns an animated style fragment with one color key (default `backgroundColor`; configurable via `options.key` to `color` / `borderColor` / `tintColor` / `shadowColor` / per-side border colors). For raw `SharedValue<string>` output, use `useTransform(progress, [0, 1], [from, to])` instead.
 - `useColorCascade(rest, layers, options?)` — pure value-layer interpolator compositing a **priority-ordered** stack of color layers over a base `rest` color; each `layers` entry is `{ progress: SharedValue<number>, color: string }`, later entries win as their progress rises (equivalent to the nested `focus(error(hover(rest)))` `interpolateColor` chain). `options.key` reuses `ColorStyleKey` (default `backgroundColor`). Returns a spreadable animated style fragment; memoized on a colors+key signature. Color-only by design — cascade a numeric key separately via `useInterpolatedStyle` + `useTransform` max. `useColorTransition` stays the single-layer fast path.
 - `useInterpolatedStyle(progress, map, options?)` — pure value-layer interpolator mapping one `SharedValue<number>` onto **N** style props at once, returned as a spreadable animated style fragment (the multi-key, style-fragment counterpart to `useTransform`'s output-range form). Numeric keys (`opacity` / `height` / `fontSize` / …) route through `interpolate`; transform keys (`translateX` / `scale` / `rotate` / …) lift into a `transform` array in map key-order (`rotate*` emit `'<n>deg'`); color keys (`backgroundColor` / `borderColor` / …) route through `interpolateColor` (a multi-stop `useColorTransition`). Stop types are compile-checked. `options.inputRange` (default `[0,1]` / evenly-spaced) and `options.extrapolate` (default `'clamp'`) apply to every key. Memoized on an order-preserving signature. For function-valued or multi-source composition, drop to `useTransform`'s worklet form or a hand-rolled `useAnimatedStyle`.
-- `useScroll()` — returns `{ scrollX, scrollY, onScroll }` for use with `Motion.ScrollView`. Scroll events fire on the UI thread.
+- `useScroll()` — returns `{ scrollX, scrollY, onScroll }` for use with `Motion.ScrollView` or `Motion.FlatList`. Scroll events fire on the UI thread. Set `scrollEventThrottle={16}` on a `Motion.ScrollView`; `Motion.FlatList` defaults it to 1.
 - `createMotionComponent<C>(C)` — wrap any component with the same Motion prop surface, inferring style from `C`.
 - `buildReleaseAnimation(transition, toValue)` — worklet-safe single-step animation builder (spring / timing / decay / no-animation). For assigning Inertia-resolved animations to shared values from inside a gesture worklet. Used internally by `@rootnative/inertia-gestures`'s `useDrag({ onRelease })`.
 - `resolveTransition(config, toValue, callback?)` — JS-thread resolver: bakes a `TransitionConfig` + target into a Reanimated animation (`withSpring` / `withTiming` / `withDecay`, plus `delay` / `repeat` wrapping) ready to assign to a shared value. The building block for custom animated components that accept Inertia's `transition` shape; this is what the gradient and SVG adapter packages use.
 - `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.5",
+  "version": "0.0.7",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "RootNative",
@@ -72,6 +72,13 @@
       "import": "./dist/motion/ScrollView.mjs",
       "require": "./dist/motion/ScrollView.js"
     },
+    "./flat-list": {
+      "types": "./dist/motion/FlatList.d.ts",
+      "react-native": "./src/motion/FlatList.tsx",
+      "source": "./src/motion/FlatList.tsx",
+      "import": "./dist/motion/FlatList.mjs",
+      "require": "./dist/motion/FlatList.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "react-native": "./src/testing/index.ts",

package/src/index.ts

@@ -16,6 +16,7 @@ export {
   MotionImage,
   MotionPressable,
   MotionScrollView,
+  MotionFlatList,
   createMotionComponent,
 } from './motion'
 export {
@@ -39,6 +40,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
+}