@rootnative/inertia 0.0.6 → 0.0.8

package/dist/motion/View.mjs

@@ -1,4 +1,4 @@
-export { MotionView } from '../chunk-CMHVF6F4.mjs';
-import '../chunk-2ICQLWH2.mjs';
-import '../chunk-Z3HCJ43H.mjs';
-import '../chunk-REYL77RE.mjs';
+export { MotionView } from '../chunk-GSUC4HWP.mjs';
+import '../chunk-IX6SEOSK.mjs';
+import '../chunk-MFAFB4K7.mjs';
+import '../chunk-W7NTRSPD.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/touch/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkPM6CVGXJ_js = require('../chunk-PM6CVGXJ.js');
+var chunkWNVHPMBI_js = require('../chunk-WNVHPMBI.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 = chunkPM6CVGXJ_js.buildReleaseAnimation(
+            dragX.value = chunkWNVHPMBI_js.buildReleaseAnimation(
               result.x,
               toX
             );
           }
           if (result.y && lockY) {
             const toY = "to" in result.y ? result.y.to : y;
-            dragY.value = chunkPM6CVGXJ_js.buildReleaseAnimation(
+            dragY.value = chunkWNVHPMBI_js.buildReleaseAnimation(
               result.y,
               toY
             );

package/dist/touch/index.mjs

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

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

@@ -10,12 +10,28 @@ pnpm add @rootnative/inertia react-native-reanimated
 
 Enable the Reanimated Babel plugin per its install guide.
 
+## Which package has what
+
+The core package does not contain the gesture hooks, the gradient primitive, or the SVG primitives. Each is a separate install. `useSwipe` and `useDrag` are **not** in core — a swipe deck needs `@rootnative/inertia-gestures`.
+
+| You want | Package | Extra peer dependency |
+| --- | --- | --- |
+| `Motion.*`, `Presence`, `Stagger`, `MotionConfig`, every value-layer hook | `@rootnative/inertia` | — (core, always required) |
+| `useDrag`, `useSwipe`, `usePan` | `@rootnative/inertia-gestures` | `react-native-gesture-handler` |
+| Animatable linear gradients | `@rootnative/inertia-gradients` | `expo-linear-gradient` |
+| Animatable SVG paths and shapes | `@rootnative/inertia-svg` | `react-native-svg` |
+
+`useTouchDrag` is the exception: a drag hook in **core**, under the `@rootnative/inertia/touch` subpath, because PanResponder is built into React Native. Use it for drag without `react-native-gesture-handler`, or when the drag needs keyboard accessibility.
+
+All four packages ship in **lockstep** — same version, released together. Install the same version of every `@rootnative/inertia*` package you use. Two things that mislead: the `@rootnative/core` and `@rootnative/components` packages of RootNative UI are a different library on a different version line, and `npm view` shows an `alpha` dist-tag on these packages that is **older** than `latest` (a prerelease leftover — follow `latest`).
+
 ## Imports
 
 ```ts
 import {
   Motion,
   Presence,
+  Stagger,
   MotionConfig,
   useGesture,
   useVariants,
@@ -34,18 +50,23 @@ 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.
+- `<Stagger interval delay? from? enabled?>` — assigns each child a delay of `delay + position * interval` (ms), applied to the declarative animations (`initial` → `animate`, later `animate` changes) of every `Motion.*` primitive in that child's subtree. `from='last'` reverses the cascade; `enabled={false}` zeroes every delay (the "cascade in, snap out" switch). Composes with the child's own `transition.delay`; never delays `gesture` feedback, `<Presence>` exits, or reduced-motion snaps. Renders no host view. Custom animated components read the slot's delay with `useStaggerDelay()`.
 - `<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).
 - `useGestureLayer(states, options?)` — opt-in helper at `@rootnative/inertia/gesture-layer` for the **strongest-active-layer-wins** composition (MD3 state-layer haloes, iOS-translucent overlays). Supply per-state target maps (`rest` / `hovered` / `focused` / `focusVisible` / `pressed` / `disabled`); the hook owns the worklet. Numeric keys compose via clamped-max with `rest` as the floor; color keys compose via priority cascade with `interpolateColor`; `disabled` (JS-side flag) overrides every gesture layer. Returns `{ style, handlers, states }` — `states` is the per-state 0↔1 progress shared values (`hovered` / `focused` / `focusVisible` / `pressed` / `disabled`) behind the composed style, for deriving extra styles (e.g. `useShadow({ progress: states.hovered })`) from the same gesture wiring. Reach for plain `useGesture` for additive blends or per-key custom rules.
@@ -60,7 +81,7 @@ 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.
@@ -149,7 +170,7 @@ Auto-layout transitions ship via the `layout` prop (`true` / `TransitionConfig`)
 
 - `@rootnative/inertia-gradients` — `MotionLinearGradient` over `expo-linear-gradient`. Animatable: `colors`, `start`, `end`, `locations`.
 - `@rootnative/inertia-svg` — animatable SVG primitives over `react-native-svg`, all under the `MotionSvg` namespace (`MotionSvg.Path` / `.Circle` / `.Rect` / `.Line`) or as direct imports. `MotionPath` animates `d` (path morphing on structurally-compatible paths — same command sequence after implicit-repeat expansion; remount with `key` to switch shape), `fill`, `stroke`, `strokeWidth`, opacities, `strokeDashoffset`. `MotionCircle` / `MotionRect` / `MotionLine` animate their geometry props, paints, and `strokeDasharray` (element-wise; array length locked at mount). `createMotionSvgComponent(Component, { animatableProps, colorProps, arrayProps })` — the factory behind the prebuilt shapes — wraps any other `react-native-svg` element with the same `initial` / `animate` / `transition` surface; `transition` accepts named transitions from the nearest `<MotionConfig transitions>` (top-level and per-property).
-- `@rootnative/inertia-gestures` — `useDrag`, `useSwipe`, `usePan` over `react-native-gesture-handler`. `useDrag` accepts an `onRelease` worklet that returns per-axis Inertia release transitions (snap-to-tick spring, decay with bounds, etc.) — the release velocity stays on the UI thread, no JS round-trip.
+- `@rootnative/inertia-gestures` — `useDrag`, `useSwipe`, `usePan` over `react-native-gesture-handler`. `useDrag` accepts an `onRelease` worklet that returns per-axis Inertia release transitions (snap-to-tick spring, decay with bounds, etc.) — the release velocity stays on the UI thread, no JS round-trip. `useSwipe`'s snap-back is configurable (`releaseTransition`, inline or a named transition, release velocity passed in), and a committed swipe can exit the screen instead of snapping back: `onCommit` (UI-thread worklet, returns per-axis exit transitions) + `onSwipeEnd` (JS thread, fires when the release animation settles) — the card-deck shape.
 
 ## Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/inertia",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "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 {
@@ -32,12 +33,16 @@ export type {
 } from './config'
 export { Presence, usePresence } from './presence'
 export type { PresenceContextValue } from './presence'
+export { Stagger, useStaggerDelay } from './stagger'
+export type { StaggerProps } from './stagger'
 export {
+  applyDelay,
   buildReleaseAnimation,
   cubicBezier,
   resolveTransition,
   resolveAnimatableValue,
   ensureWorkletEasing,
+  type AnimationCallback,
 } from './transitions'
 // Seed value for any color shared value a custom animated component drives
 // through `resolveTransition`. Exported because the obvious choice —

package/src/motion/FlatList.tsx

@@ -0,0 +1,77 @@
+import type { FlatList as RNFlatList, FlatListProps } from 'react-native'
+import Animated from 'react-native-reanimated'
+import type { MotionProps, VariantsMap } from '../types'
+import { createMotionComponent } from './createMotionComponent'
+
+/**
+ * Animatable, virtualized `FlatList`.
+ *
+ * Built on Reanimated's `Animated.FlatList` rather than RN's `FlatList`. That
+ * wrapper supplies two things this primitive would otherwise have to
+ * re-implement: the `CellRendererComponent` injection that powers per-row
+ * `itemLayoutAnimation`, and a `scrollEventThrottle` default of 1.
+ *
+ * A note on that throttle default, because the reasoning is easy to get wrong
+ * from Reanimated's own source comment: it says RN defaults FlatList's
+ * `scrollEventThrottle` to 50, which **is stale**. On RN 0.81
+ * (`@react-native/virtualized-lists`, `VirtualizedList.js`) the default is
+ * `props.scrollEventThrottle ?? 0.0001` — effectively every frame. So the
+ * patch is belt-and-braces on current RN rather than the load-bearing reason
+ * to use the wrapper. It is still worth inheriting: it costs nothing, and it
+ * pins the behaviour if RN's default changes again. **Do not restate the "50"
+ * figure as fact** — verify against the installed RN before relying on it.
+ *
+ * This is the primitive that lets one list both virtualize and animate. The
+ * `useScroll()` handler works because `Motion.*` components are Reanimated
+ * animated components — the same mechanism `Motion.ScrollView` relies on, and
+ * nothing about it was ever specific to `ScrollView`:
+ *
+ * ```tsx
+ * const { scrollY, onScroll } = useScroll()
+ *
+ * <Motion.FlatList
+ *   data={items}
+ *   renderItem={renderItem}
+ *   onScroll={onScroll}
+ *   initial={{ opacity: 0 }}
+ *   animate={{ opacity: 1 }}
+ * />
+ * ```
+ *
+ * Two scoping notes:
+ *
+ * - `animate` / `initial` / `gesture` apply to the **scroll container**, not to
+ *   rows. Animate rows by using a `Motion.*` primitive inside `renderItem`.
+ * - The `layout` prop animates the list frame. Per-row layout animation is
+ *   Reanimated's `itemLayoutAnimation`, which is forwarded through untouched.
+ *   Note that row-level layout animation can fight the list's own measurement
+ *   passes — measure before adopting it.
+ */
+export const MotionFlatList = createMotionComponent(
+  Animated.FlatList as never,
+  // `createMotionComponent<C>` returns a non-generic `MotionComponent<C>`, so
+  // `data` / `renderItem` would collapse to `any` and lose `ItemT` inference.
+  // Restore it with the same call-signature cast Reanimated itself uses for
+  // this exact problem (see its `ReanimatedFlatList` export, and the
+  // `@ts-expect-error` above `AnimatedFlatList` explaining that
+  // `createAnimatedComponent` cannot create generic components).
+  //
+  // **Both** generics live on the one call signature, and that is deliberate:
+  // `ItemT` infers from `data` while `V` infers from `variants`, independently.
+  // Declaring only `ItemT` (the obvious first cut) silently drops the
+  // variant-key narrowing that `MotionComponent` provides on every other
+  // primitive — `animate="typo"` would stop being a compile error here and
+  // nowhere else. Both directions are pinned in
+  // `__type-tests__/flat-list.test-d.tsx`.
+) as unknown as <
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ItemT = any,
+  V extends VariantsMap<FlatListProps<ItemT>> = VariantsMap<
+    FlatListProps<ItemT>
+  >,
+>(
+  props: FlatListProps<ItemT> &
+    MotionProps<FlatListProps<ItemT>, V> & {
+      ref?: React.Ref<RNFlatList<ItemT>>
+    },
+) => React.ReactElement

package/src/motion/createMotionComponent.tsx

@@ -43,7 +43,9 @@ import {
   useSharedLayout,
 } from '../layout'
 import { usePresence } from '../presence'
+import { useStaggerDelay } from '../stagger'
 import {
+  applyDelay,
   isTopLevelTransition,
   resolveAnimatableValue,
   resolveTransition,
@@ -547,6 +549,13 @@ export function createMotionComponent<C extends ComponentType<any>>(
       // at app start — a runtime toggle takes effect on the next launch.
       const shouldReduceMotion = useShouldReduceMotion()
 
+      // Per-child delay assigned by the nearest <Stagger> ancestor; 0 outside
+      // one. Applied in the value-driving effect, not here: the effect's
+      // closure reads the value current at the render that starts an
+      // animation, and a delay change alone must not re-trigger anything —
+      // so it is deliberately absent from the effect's deps.
+      const staggerDelay = useStaggerDelay()
+
       // Pin the latest `onAnimationEnd` in a ref so the worklet callback always
       // dispatches against the current closure without re-resolving the
       // animation graph. Worklets can read refs via `runOnJS`.
@@ -962,6 +971,22 @@ export function createMotionComponent<C extends ComponentType<any>>(
                 transition,
               )
 
+        // <Stagger> delay for this run, wrapped around each key's fully
+        // resolved animation via `applyDelay` — once per animation, never
+        // merged into the base config (a sequence applies a base `delay` per
+        // step, which would stretch the whole sequence by N × delay). Composes
+        // with a consumer's own `transition.delay`, which `resolveTransition`
+        // has already applied inside.
+        //
+        // Deliberately 0 while exiting (an exit delayed by list position holds
+        // <Presence>'s unmount hostage to the cascade) and under reduced
+        // motion (a snap must not be deferred — same contract as `delayOf`
+        // returning `undefined` for `no-animation`).
+        const runStagger =
+          shouldReduceMotion || isExiting || staggerDelay <= 0
+            ? 0
+            : staggerDelay
+
         // Count transform axes participating in this effect run so the factory
         // can coalesce their terminal callbacks into a single transform-group
         // event. `undefined` when no transform axis is animating, which lets
@@ -996,6 +1021,7 @@ export function createMotionComponent<C extends ComponentType<any>>(
               boxShadowInsets,
               shadowTarget,
               cfg,
+              runStagger,
               makeKeyCallbackFactory(
                 'boxShadow',
                 sharedValues.boxShadow,
@@ -1051,12 +1077,15 @@ export function createMotionComponent<C extends ComponentType<any>>(
           // `'no-animation'` (and so under reduced motion) it is assigned
           // straight into the slot, and the next animation would start from a
           // value that can't be parsed.
-          sharedValues[key].value = resolveAnimatableValue(
-            COLOR_KEY_SET.has(key)
-              ? normalizeAnimatableColorTarget(target)
-              : target,
-            cfg,
-            factory,
+          sharedValues[key].value = applyDelay(
+            resolveAnimatableValue(
+              COLOR_KEY_SET.has(key)
+                ? normalizeAnimatableColorTarget(target)
+                : target,
+              cfg,
+              factory,
+            ),
+            runStagger,
           ) as never
         }
 
@@ -1655,6 +1684,7 @@ function driveBoxShadow(
   insetSlot: SharedValue<boolean[] | null>,
   target: BoxShadowInput,
   cfg: TransitionConfig | undefined,
+  staggerDelay: number,
   factory: CallbackFactory | undefined,
 ): void {
   const currentLayers = payloadToLayers(slot.value as BoxShadowPayload)
@@ -1666,10 +1696,15 @@ function driveBoxShadow(
   if (from.length !== currentLayers.length) slot.value = layersToPayload(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,
-    layersToPayload(to) as unknown as number,
-    factory?.('animation', undefined),
+  // The stagger wrap sits outside, same as the scalar path — this key can't
+  // be a sequence, but keeping the delay out of `cfg` keeps one rule.
+  slot.value = applyDelay(
+    resolveTransition(
+      cfg,
+      layersToPayload(to) as unknown as number,
+      factory?.('animation', undefined),
+    ),
+    staggerDelay,
   ) as AnimatableSlotValue
 }
 
@@ -2025,6 +2060,26 @@ function useGestureHandlers(
       // forward to those when present so wrapping consumers stay consistent.
       handlers.onPressIn = compose(rest.onPressIn, () => setPressed(true))
       handlers.onPressOut = compose(rest.onPressOut, () => setPressed(false))
+      // Web pointer events. `onTouchStart` reaches the DOM as a real
+      // `touchstart` listener under react-native-web, which a mouse never
+      // fires — so without these a plain `Motion.View` (anything that isn't a
+      // Pressable, i.e. has no `onPressIn` path) was inert under a desktop
+      // click while `Motion.Pressable` worked. Pointer events cover mouse, pen
+      // and touch, so `pressed` means "any pointer" on every platform.
+      //
+      // A web touch fires `touchstart` *and* `pointerdown`; both set the same
+      // boolean to the same value, so the overlap is idempotent, not a
+      // double-toggle. React Native has no pointer props, so these are inert
+      // on native and cost nothing there.
+      handlers.onPointerDown = compose(rest.onPointerDown, () =>
+        setPressed(true),
+      )
+      handlers.onPointerUp = compose(rest.onPointerUp, () => setPressed(false))
+      // Fires when the browser takes over the gesture (scroll, drag start) —
+      // without it the pressed layer would stick on after the pointer is gone.
+      handlers.onPointerCancel = compose(rest.onPointerCancel, () =>
+        setPressed(false),
+      )
     }
     // Mount onFocus/onBlur if either focus sub-state is declared. The two flags
     // are independent: `focused` always tracks focus; `focusVisible` only
@@ -2061,6 +2116,9 @@ function useGestureHandlers(
     rest.onTouchCancel,
     rest.onPressIn,
     rest.onPressOut,
+    rest.onPointerDown,
+    rest.onPointerUp,
+    rest.onPointerCancel,
     rest.onFocus,
     rest.onBlur,
     rest.onMouseEnter,

package/src/motion/index.ts

@@ -1,3 +1,4 @@
+import { MotionFlatList } from './FlatList'
 import { MotionImage } from './Image'
 import { MotionPressable } from './Pressable'
 import { MotionScrollView } from './ScrollView'
@@ -11,6 +12,7 @@ export {
   MotionImage,
   MotionPressable,
   MotionScrollView,
+  MotionFlatList,
 }
 
 /**
@@ -23,4 +25,5 @@ export const Motion = {
   Image: MotionImage,
   Pressable: MotionPressable,
   ScrollView: MotionScrollView,
+  FlatList: MotionFlatList,
 } as const

package/src/stagger/Stagger.tsx

@@ -0,0 +1,75 @@
+import { Children, isValidElement, type ReactNode } from 'react'
+import { StaggerContext } from './StaggerContext'
+
+export interface StaggerProps {
+  children?: ReactNode
+  /**
+   * Milliseconds between consecutive children. Child `i` (in render order)
+   * receives a delay of `delay + i * interval`.
+   */
+  interval: number
+  /**
+   * Base delay in milliseconds applied to every child before the interval,
+   * so the whole cascade can start late without pushing the spacing into
+   * each child. Defaults to `0`.
+   */
+  delay?: number
+  /**
+   * Which end of the child list starts the cascade. `'first'` (default)
+   * staggers top-down in render order; `'last'` reverses it, so the final
+   * child animates first.
+   */
+  from?: 'first' | 'last'
+  /**
+   * Turn the stagger on or off in one place. When `false`, every child gets
+   * a delay of `0` — the single-switch escape hatch for "cascade in, but
+   * not back out": pass `enabled={revealed}` and the hide direction snaps
+   * together. Defaults to `true`.
+   */
+  enabled?: boolean
+}
+
+/**
+ * Assign each child a stagger delay from its position, so a list entrance
+ * cascades without every child computing `index * ms` itself.
+ *
+ * The parent owns the timing: reordering, filtering, or reversing the list
+ * re-derives every delay from the new render order, and `enabled` turns the
+ * whole cascade off in one place. Each child slot gets its own provider, so
+ * a `Motion.*` primitive anywhere inside child `i`'s subtree inherits child
+ * `i`'s delay.
+ *
+ * The delay applies to the declarative animations of the `Motion.*`
+ * primitives underneath — the mount animation (`initial` → `animate`) and
+ * any later `animate` change. It deliberately does not delay `gesture`
+ * feedback, `<Presence>` exits, or reduced-motion snaps.
+ *
+ * `<Stagger>` renders no host view — only per-child context providers.
+ */
+export function Stagger({
+  children,
+  interval,
+  delay = 0,
+  from = 'first',
+  enabled = true,
+}: StaggerProps) {
+  // `Children.toArray` drops `null` / `undefined` / booleans, so conditional
+  // children don't leave holes in the cascade, and it assigns stable
+  // element keys that the providers below reuse.
+  const items = Children.toArray(children)
+  const count = items.length
+  return (
+    <>
+      {items.map((child, index) => {
+        const position = from === 'last' ? count - 1 - index : index
+        const childDelay = enabled ? delay + position * interval : 0
+        const key = isValidElement(child) ? (child.key ?? index) : index
+        return (
+          <StaggerContext.Provider key={key} value={childDelay}>
+            {child}
+          </StaggerContext.Provider>
+        )
+      })}
+    </>
+  )
+}

package/src/stagger/StaggerContext.ts

@@ -0,0 +1,25 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Per-child stagger delay in milliseconds, provided by `<Stagger>`. `0`
+ * outside a `<Stagger>` (or under a disabled one), which every consumer
+ * treats as "no stagger".
+ *
+ * Internal wiring — consumers use `<Stagger>`; custom animated components
+ * read the value through `useStaggerDelay()`.
+ */
+export const StaggerContext = createContext(0)
+
+/**
+ * The stagger delay (in milliseconds) assigned to this element's child slot
+ * by the nearest `<Stagger>` ancestor. `0` when there is none, when the
+ * stagger is disabled, or for the first child of a zero-`delay` stagger.
+ *
+ * The `Motion.*` primitives consume this automatically. Custom animated
+ * components built on `resolveTransition` / `resolveAnimatableValue` call
+ * this hook and add the returned value to their animation delay so they
+ * participate in a `<Stagger>` the same way the built-in primitives do.
+ */
+export function useStaggerDelay(): number {
+  return useContext(StaggerContext)
+}

package/src/stagger/index.ts

@@ -0,0 +1,2 @@
+export { Stagger, type StaggerProps } from './Stagger'
+export { useStaggerDelay } from './StaggerContext'

package/src/transitions/index.ts

@@ -1,4 +1,9 @@
-export { resolveTransition, type CallbackFactory } from './resolve'
+export {
+  applyDelay,
+  resolveTransition,
+  type AnimationCallback,
+  type CallbackFactory,
+} from './resolve'
 export { resolveAnimatableValue } from './resolveSequence'
 export { cubicBezier } from './cubicBezier'
 export { ensureWorkletEasing } from './easing'

package/src/transitions/resolve.ts

@@ -116,7 +116,13 @@ export function applyRepeat(
   return withRepeat(animation as never, count, alternate)
 }
 
-function applyDelay(animation: unknown, delay: number | undefined) {
+/**
+ * Wrap an animation in `withDelay`. A missing / zero / negative delay is a
+ * pass-through. Exported for the factory's stagger wrap, which must delay a
+ * fully-resolved animation exactly once — merging the delay into the base
+ * config instead would re-apply it per sequence step.
+ */
+export function applyDelay(animation: unknown, delay: number | undefined) {
   if (!delay || delay <= 0) return animation
   return withDelay(delay, animation as never)
 }