@onlynative/inertia 0.0.1-alpha.3 → 0.0.1-alpha.4

package/dist/{types-DAhX3fC2.d.mts → types-CjztO3RW.d.mts}

@@ -78,16 +78,41 @@ interface GestureLayerTransitions {
     hovered?: TransitionConfig;
 }
 type Transition<S> = TransitionConfig | (PerPropertyTransition<S> & GestureLayerTransitions);
+/**
+ * Transform shorthands that Inertia exposes on `animate` but that don't
+ * appear on RN's typed ViewStyle as top-level keys. RN keeps `scale`,
+ * `rotate`, `rotateX`, and `rotateY` inside the `transform` array; only
+ * `scaleX`/`scaleY` and `translateX`/`translateY` are surfaced as
+ * (deprecated) top-level shortcuts. Inertia's runtime treats these as
+ * transform-group keys (see `TRANSFORM_KEYS` in `createMotionComponent`),
+ * so they're documented as first-class animatables in `CLAUDE.md` and must
+ * be reachable from `animate` without dropping into the `transform: [...]`
+ * array form. Rotation values are degrees as numbers — the runtime appends
+ * `'deg'` before handing the transform to Reanimated.
+ */
+type AnimatableTransformExtras = {
+    scale?: AnimatableValue<number>;
+    rotate?: AnimatableValue<number>;
+    rotateX?: AnimatableValue<number>;
+    rotateY?: AnimatableValue<number>;
+};
 /**
  * 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
  * `Motion.View`, TextStyle on `Motion.Text`, etc. — no shared union.
+ *
+ * Some components (notably `Pressable`) type `style` as a union of
+ * `StyleProp<T>` and a callback `(state) => StyleProp<T>`. If we infer `S`
+ * directly from `StyleProp<infer S>`, the callback branch widens `S` to
+ * `unknown`, which collapses the animate map to `| {}` and silently
+ * accepts any key. Excluding functions first keeps inference tight.
  */
+type _StyleValue<T> = Exclude<T, (...args: any[]) => any>;
 type AnimateStyle<C> = C extends {
-    style?: StyleProp<infer S>;
-} ? {
+    style?: infer Raw;
+} ? _StyleValue<Raw> extends StyleProp<infer S> ? {
     [K in keyof S]?: AnimatableValue<S[K]>;
-} : never;
+} & AnimatableTransformExtras : never : never;
 interface AnimationCallbackInfo<S> {
     /**
      * The animatable key that just settled — typically a `keyof S` (e.g.
@@ -208,6 +233,26 @@ interface MotionProps<C> {
      * precedence over the top-level transition.
      */
     transition?: Transition<AnimateStyle<C>>;
+    /**
+     * Auto-layout animation. When the component's position or size changes
+     * because of a parent layout change (a flex sibling growing, a list
+     * reordering, a column toggling its width), interpolate between the old
+     * and new layout instead of snapping.
+     *
+     * - `true` — animate with the library's default spring.
+     * - `TransitionConfig` — spring (react-spring vocab) or timing config; the
+     *   resolver bridges to Reanimated's `LinearTransition` builder.
+     * - omitted / `false` — no layout animation (default).
+     *
+     * Only `'spring'` / `'timing'` / `'no-animation'` map to layout transitions
+     * — decay is downgraded to spring (no clear target). Reduced motion gates
+     * the prop the same way it gates `animate`.
+     *
+     * `layoutId` for shared element transitions across screens is deferred:
+     * Reanimated 4 dropped the underlying `sharedTransitionTag` API and a
+     * Inertia-side measure-based registry is the in-flight design.
+     */
+    layout?: boolean | TransitionConfig;
     /**
      * Fired once per logical animation completion. See `AnimationCallbackInfo`
      * for the payload shape — transform parents fire once, not per axis.
@@ -223,4 +268,4 @@ type MotionComponent<C extends ComponentType<any>> = ComponentType<Omit<React.Co
     style?: React.ComponentProps<C>['style'];
 }>;
 
-export type { AnimatableValue as A, DecayTransition as D, GestureSubStates as G, MotionComponent as M, NoAnimationTransition as N, PerPropertyTransition as P, RepeatConfig as R, SequenceStep as S, TransitionConfig as T, VariantController as V, AnimateStyle as a, AnimationCallbackInfo as b, MotionProps as c, SpringTransition as d, TimingTransition as e, Transition as f, VariantsMap as g };
+export type { AnimatableValue as A, DecayTransition as D, GestureLayerTransitions as G, MotionComponent as M, NoAnimationTransition as N, PerPropertyTransition as P, RepeatConfig as R, SpringTransition as S, TransitionConfig as T, VariantController as V, AnimateStyle as a, AnimationCallbackInfo as b, GestureSubStates as c, MotionProps as d, SequenceStep as e, TimingTransition as f, Transition as g, VariantsMap as h };

package/dist/{types-DAhX3fC2.d.ts → types-CjztO3RW.d.ts}

@@ -78,16 +78,41 @@ interface GestureLayerTransitions {
     hovered?: TransitionConfig;
 }
 type Transition<S> = TransitionConfig | (PerPropertyTransition<S> & GestureLayerTransitions);
+/**
+ * Transform shorthands that Inertia exposes on `animate` but that don't
+ * appear on RN's typed ViewStyle as top-level keys. RN keeps `scale`,
+ * `rotate`, `rotateX`, and `rotateY` inside the `transform` array; only
+ * `scaleX`/`scaleY` and `translateX`/`translateY` are surfaced as
+ * (deprecated) top-level shortcuts. Inertia's runtime treats these as
+ * transform-group keys (see `TRANSFORM_KEYS` in `createMotionComponent`),
+ * so they're documented as first-class animatables in `CLAUDE.md` and must
+ * be reachable from `animate` without dropping into the `transform: [...]`
+ * array form. Rotation values are degrees as numbers — the runtime appends
+ * `'deg'` before handing the transform to Reanimated.
+ */
+type AnimatableTransformExtras = {
+    scale?: AnimatableValue<number>;
+    rotate?: AnimatableValue<number>;
+    rotateX?: AnimatableValue<number>;
+    rotateY?: AnimatableValue<number>;
+};
 /**
  * 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
  * `Motion.View`, TextStyle on `Motion.Text`, etc. — no shared union.
+ *
+ * Some components (notably `Pressable`) type `style` as a union of
+ * `StyleProp<T>` and a callback `(state) => StyleProp<T>`. If we infer `S`
+ * directly from `StyleProp<infer S>`, the callback branch widens `S` to
+ * `unknown`, which collapses the animate map to `| {}` and silently
+ * accepts any key. Excluding functions first keeps inference tight.
  */
+type _StyleValue<T> = Exclude<T, (...args: any[]) => any>;
 type AnimateStyle<C> = C extends {
-    style?: StyleProp<infer S>;
-} ? {
+    style?: infer Raw;
+} ? _StyleValue<Raw> extends StyleProp<infer S> ? {
     [K in keyof S]?: AnimatableValue<S[K]>;
-} : never;
+} & AnimatableTransformExtras : never : never;
 interface AnimationCallbackInfo<S> {
     /**
      * The animatable key that just settled — typically a `keyof S` (e.g.
@@ -208,6 +233,26 @@ interface MotionProps<C> {
      * precedence over the top-level transition.
      */
     transition?: Transition<AnimateStyle<C>>;
+    /**
+     * Auto-layout animation. When the component's position or size changes
+     * because of a parent layout change (a flex sibling growing, a list
+     * reordering, a column toggling its width), interpolate between the old
+     * and new layout instead of snapping.
+     *
+     * - `true` — animate with the library's default spring.
+     * - `TransitionConfig` — spring (react-spring vocab) or timing config; the
+     *   resolver bridges to Reanimated's `LinearTransition` builder.
+     * - omitted / `false` — no layout animation (default).
+     *
+     * Only `'spring'` / `'timing'` / `'no-animation'` map to layout transitions
+     * — decay is downgraded to spring (no clear target). Reduced motion gates
+     * the prop the same way it gates `animate`.
+     *
+     * `layoutId` for shared element transitions across screens is deferred:
+     * Reanimated 4 dropped the underlying `sharedTransitionTag` API and a
+     * Inertia-side measure-based registry is the in-flight design.
+     */
+    layout?: boolean | TransitionConfig;
     /**
      * Fired once per logical animation completion. See `AnimationCallbackInfo`
      * for the payload shape — transform parents fire once, not per axis.
@@ -223,4 +268,4 @@ type MotionComponent<C extends ComponentType<any>> = ComponentType<Omit<React.Co
     style?: React.ComponentProps<C>['style'];
 }>;
 
-export type { AnimatableValue as A, DecayTransition as D, GestureSubStates as G, MotionComponent as M, NoAnimationTransition as N, PerPropertyTransition as P, RepeatConfig as R, SequenceStep as S, TransitionConfig as T, VariantController as V, AnimateStyle as a, AnimationCallbackInfo as b, MotionProps as c, SpringTransition as d, TimingTransition as e, Transition as f, VariantsMap as g };
+export type { AnimatableValue as A, DecayTransition as D, GestureLayerTransitions as G, MotionComponent as M, NoAnimationTransition as N, PerPropertyTransition as P, RepeatConfig as R, SpringTransition as S, TransitionConfig as T, VariantController as V, AnimateStyle as a, AnimationCallbackInfo as b, GestureSubStates as c, MotionProps as d, SequenceStep as e, TimingTransition as f, Transition as g, VariantsMap as h };

package/llms.txt

@@ -13,7 +13,18 @@ Enable the Reanimated Babel plugin per its install guide.
 ## Imports
 
 ```ts
-import { Motion, Presence, MotionConfig, useVariants } from '@onlynative/inertia'
+import {
+  Motion,
+  Presence,
+  MotionConfig,
+  useGesture,
+  useVariants,
+  useMotionValue,
+  useAnimation,
+  useSpring,
+  useTransform,
+  useScroll,
+} from '@onlynative/inertia'
 // or for tree-shaking:
 import { MotionView } from '@onlynative/inertia/view'
 import { MotionText } from '@onlynative/inertia/text'
@@ -27,12 +38,20 @@ import { MotionScrollView } from '@onlynative/inertia/scroll-view'
 - `Motion.View` / `Motion.Text` / `Motion.Image` / `Motion.Pressable` / `Motion.ScrollView` — animatable primitives. Per-primitive style inference (no shared `ViewStyle & TextStyle & ImageStyle` fallback).
 - `<Presence>` — mount / unmount transitions; children need explicit `key`s. Exiting children get `pointerEvents: 'none'` automatically.
 - `<MotionConfig reducedMotion="user" | "never" | "always">` — gates motion against the OS reduce-motion setting (default `"user"`).
+- `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).
 - `useVariants(variants, initial?)` — returns `{ current, transitionTo }` controller for the `controller` prop.
+- `useMotionValue(initial)` — thin pass-through over `useSharedValue<T>`. Returns a `SharedValue<T>` directly so it interops with every Reanimated API without unwrapping.
+- `useAnimation(target, transition?)` — drive a `SharedValue<number>` toward `target` with any `TransitionConfig` (spring / timing / decay / no-animation, plus `repeat`). The general-purpose value-layer hook for boolean-state progress, indeterminate loops, and anywhere the same value needs to feed multiple `useAnimatedStyle` blocks.
+- `useSpring(target, config?)` — spring-only shorthand. Animates a `SharedValue<number>` toward `target` with react-spring vocab. `target` may be a plain number (effect-driven) or a `SharedValue<number>` (UI-thread reaction); the latter is the gesture-smoothing path.
+- `useTransform(value, inputRange, outputRange, options?)` / `useTransform(transformer)` — interpolate a numeric shared value onto a number or color range, or derive any value from any number of shared values via a worklet. Non-worklet transformers are auto-wrapped.
+- `useScroll()` — returns `{ scrollX, scrollY, onScroll }` for use with `Motion.ScrollView`. Scroll events fire on the UI thread.
 - `createMotionComponent<C>(C)` — wrap any component with the same Motion prop surface, inferring style from `C`.
 
 ## Motion props
 
-`initial` (mount-only, non-reactive after first render — pass `false` to skip), `animate`, `exit`, `variants`, `controller`, `gesture`, `transition`, `onAnimationEnd`.
+`initial` (mount-only, non-reactive after first render — pass `false` to skip), `animate`, `exit`, `variants`, `controller`, `gesture`, `transition`, `layout`, `onAnimationEnd`.
+
+`layout` accepts `true` (default spring) or a `TransitionConfig` (spring / timing) and animates position + size changes that come from outside the `animate` flow (siblings reordering, dimensions toggling). `'decay'` downgrades to spring; `'no-animation'` and reduced motion both skip the animation.
 
 ## Transitions
 
@@ -92,11 +111,17 @@ transition={{
 
 ## Animatable properties (alpha)
 
-Numeric: `opacity`, `translateX`, `translateY`, `scale`, `scaleX`, `scaleY`, `rotate`, `width`, `height`, `borderRadius`.
+Numeric: `opacity`, `translateX`, `translateY`, `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`, `rotateY`, `width`, `height`, `borderRadius`. Rotation values are degrees; the factory wraps them as `'${value}deg'`. `rotateX` / `rotateY` need a sibling `perspective` style entry to render in 3D.
 
 Color: `backgroundColor`, `borderColor`, `color`, `tintColor` (Image only). Hex, `rgb()` / `rgba()`, `hsl()` / `hsla()`, and named colors all work; the target string is forwarded straight through `withSpring` / `withTiming` and Reanimated handles RGBA interpolation natively.
 
-Layout (`layout` / `layoutId`) and SVG path morphing are not in alpha.
+Auto-layout transitions ship via the `layout` prop (`true` / `TransitionConfig`) on every `Motion.*` primitive — see Layout. Shared element transitions (`layoutId`) are deferred: Reanimated 4 dropped the `sharedTransitionTag` API the previous design relied on.
+
+## Optional adapter packages
+
+- `@onlynative/inertia-gradients` — `MotionLinearGradient` over `expo-linear-gradient`. Animatable: `colors`, `start`, `end`, `locations`.
+- `@onlynative/inertia-svg` — `MotionPath` over `react-native-svg`. Animatable: `d` (path morphing on structurally-compatible paths), `fill`, `stroke`, `strokeWidth`, opacities, `strokeDashoffset`. Source and target paths must share the same command sequence after implicit-repeat expansion; remount with `key` to switch shape.
+- `@onlynative/inertia-gestures` — `useDrag`, `useSwipe`, `usePan` over `react-native-gesture-handler`.
 
 ## Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlynative/inertia",
-  "version": "0.0.1-alpha.3",
+  "version": "0.0.1-alpha.4",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "OnlyNative",

package/src/__type-tests__/animate.test-d.tsx

@@ -0,0 +1,88 @@
+/**
+ * Phase-1 acceptance: per-primitive style inference must reject keys that
+ * don't exist on the underlying component's style prop, at compile time.
+ *
+ * These assertions run as part of `tsc --noEmit` (typecheck CI step). They
+ * are not Jest tests — Jest's Babel transform strips `@ts-expect-error`,
+ * so a runtime check can't enforce a compile-time gate. If any
+ * `@ts-expect-error` here becomes unused (i.e. the line below it stops
+ * being a type error), tsc fails with "Unused '@ts-expect-error'
+ * directive" and Phase-1 has regressed.
+ *
+ * The file is excluded from the tsup build via the explicit entry list in
+ * tsup.config.ts, and from Jest via the `__tests__`-only testMatch glob.
+ *
+ * We assert against `AnimateStyle<...>` directly (rather than mounting JSX)
+ * because Prettier reflows multi-line JSX, which would push the actual
+ * error onto a different line than the `@ts-expect-error` directive.
+ * Direct value-to-type assignment lines stay one line, regardless of
+ * Prettier print width.
+ */
+
+import type { ComponentProps } from 'react'
+import type { Image, Pressable, ScrollView, Text, View } from 'react-native'
+import type { AnimateStyle } from '../types'
+
+type ViewAnimate = AnimateStyle<ComponentProps<typeof View>>
+type TextAnimate = AnimateStyle<ComponentProps<typeof Text>>
+type ImageAnimate = AnimateStyle<ComponentProps<typeof Image>>
+type PressableAnimate = AnimateStyle<ComponentProps<typeof Pressable>>
+type ScrollViewAnimate = AnimateStyle<ComponentProps<typeof ScrollView>>
+
+// ─── Motion.View / ViewStyle ────────────────────────────────────────────────
+
+const _viewAccepts: ViewAnimate = { opacity: 1, translateX: 10, scale: 1.1 }
+const _viewAcceptsRotate: ViewAnimate = { rotate: 45, rotateX: 30, rotateY: 60 }
+// @ts-expect-error rotate is a numeric degree value; strings like '45deg' aren't accepted
+const _viewRejectsRotateString: ViewAnimate = { rotate: '45deg' }
+// @ts-expect-error tintColor is ImageStyle-only and must be rejected on View
+const _viewRejectsTintColor: ViewAnimate = { tintColor: '#0a84ff' }
+// @ts-expect-error fontSize is TextStyle-only and must be rejected on View
+const _viewRejectsFontSize: ViewAnimate = { fontSize: 20 }
+// @ts-expect-error completely unknown keys must be rejected
+const _viewRejectsUnknown: ViewAnimate = { nonsenseKey: 1 }
+
+// ─── Motion.Text / TextStyle ────────────────────────────────────────────────
+
+const _textAccepts: TextAnimate = { opacity: 1, color: '#000', fontSize: 16 }
+// @ts-expect-error tintColor is ImageStyle-only and must be rejected on Text
+const _textRejectsTintColor: TextAnimate = { tintColor: '#0a84ff' }
+
+// ─── Motion.Image / ImageStyle ──────────────────────────────────────────────
+
+const _imageAccepts: ImageAnimate = { tintColor: '#0a84ff', opacity: 0.5 }
+// @ts-expect-error fontSize is TextStyle-only and must be rejected on Image
+const _imageRejectsFontSize: ImageAnimate = { fontSize: 20 }
+
+// ─── Motion.Pressable / Motion.ScrollView ───────────────────────────────────
+//
+// Both wrap View internally; their style surface is ViewStyle. Same rule as
+// Motion.View — no tintColor. Pressable's `style` is a union with a
+// `(state) => StyleProp<ViewStyle>` callback; the `_StyleValue` helper in
+// `types.ts` strips the function variant so inference stays tight.
+
+const _pressableAccepts: PressableAnimate = { opacity: 1, scale: 0.96 }
+// @ts-expect-error tintColor is ImageStyle-only and must be rejected on Pressable
+const _pressableRejectsTintColor: PressableAnimate = { tintColor: '#0a84ff' }
+
+const _scrollViewAccepts: ScrollViewAnimate = { opacity: 1, translateY: 10 }
+// @ts-expect-error tintColor is ImageStyle-only and must be rejected on ScrollView
+const _scrollViewRejectsTintColor: ScrollViewAnimate = { tintColor: '#0a84ff' }
+
+// Silence "declared but never read" — these exist purely as type assertions.
+export type _PhaseOneTypeAssertions = [
+  typeof _viewAccepts,
+  typeof _viewAcceptsRotate,
+  typeof _viewRejectsRotateString,
+  typeof _viewRejectsTintColor,
+  typeof _viewRejectsFontSize,
+  typeof _viewRejectsUnknown,
+  typeof _textAccepts,
+  typeof _textRejectsTintColor,
+  typeof _imageAccepts,
+  typeof _imageRejectsFontSize,
+  typeof _pressableAccepts,
+  typeof _pressableRejectsTintColor,
+  typeof _scrollViewAccepts,
+  typeof _scrollViewRejectsTintColor,
+]

package/src/index.ts

@@ -27,7 +27,22 @@ export {
   resolveAnimatableValue,
   ensureWorkletEasing,
 } from './transitions'
-export { useVariants } from './values'
+export {
+  useAnimation,
+  useGesture,
+  useMotionValue,
+  useScroll,
+  useSpring,
+  useTransform,
+  useVariants,
+} from './values'
+export type {
+  ExtrapolationMode,
+  UseGestureHandlers,
+  UseGestureResult,
+  UseScrollResult,
+  UseTransformOptions,
+} from './values'
 export type {
   AnimatableValue,
   AnimateStyle,

package/src/layout/index.ts

@@ -0,0 +1 @@
+export { resolveLayoutTransition, type LayoutProp } from './resolveLayout'

package/src/layout/resolveLayout.ts

@@ -0,0 +1,54 @@
+import { LinearTransition } from 'react-native-reanimated'
+import { ensureWorkletEasing } from '../transitions/easing'
+import { DEFAULT_SPRING, springToReanimated } from '../transitions/spring'
+import { type TransitionConfig } from '../types'
+
+export type LayoutProp = boolean | TransitionConfig | undefined
+
+/**
+ * Resolve the public `layout` prop into a Reanimated `LinearTransition` builder.
+ *
+ * - `undefined` / `false` / `{ type: 'no-animation' }` → `undefined` (no layout
+ *   animation; layout changes snap).
+ * - `true` → default spring with the library's tuned tension / friction / mass.
+ * - `{ type: 'spring', ... }` → spring with react-spring vocabulary, bridged
+ *   into `springify().damping().stiffness().mass()` via `springToReanimated`.
+ * - `{ type: 'timing', ... }` → `.duration().easing()`. User easing fns are
+ *   auto-wrapped as worklets (Reanimated 3.9+ validates this).
+ * - `{ type: 'decay', ... }` → silently downgrades to spring; decay doesn't
+ *   have a clear target for a layout transition.
+ *
+ * When `reducedMotion` is true the caller should pass `undefined` so the
+ * underlying component renders without a layout animation at all. We choose
+ * this over `LinearTransition.duration(0)` because Reanimated still runs the
+ * commit-tracking machinery in that case; the snap path is genuinely cheaper.
+ */
+export function resolveLayoutTransition(
+  layout: LayoutProp,
+): LinearTransition | undefined {
+  if (!layout) return undefined
+
+  const cfg: TransitionConfig = layout === true ? { type: 'spring' } : layout
+
+  if (cfg.type === 'no-animation') return undefined
+
+  if (cfg.type === 'timing') {
+    let builder = LinearTransition.duration(cfg.duration ?? 300)
+    const easing = ensureWorkletEasing(cfg.easing)
+    if (easing) builder = builder.easing(easing)
+    if (cfg.delay) builder = builder.delay(cfg.delay)
+    return builder
+  }
+
+  const spring = cfg.type === 'decay' ? ({ type: 'spring' } as const) : cfg
+  const { stiffness, damping, mass } = springToReanimated({
+    ...DEFAULT_SPRING,
+    ...spring,
+  })
+  let builder = LinearTransition.springify()
+    .stiffness(stiffness)
+    .damping(damping)
+    .mass(mass)
+  if ('delay' in spring && spring.delay) builder = builder.delay(spring.delay)
+  return builder
+}

package/src/motion/createMotionComponent.tsx

@@ -15,8 +15,14 @@ import Animated, {
 } from 'react-native-reanimated'
 import { useShouldReduceMotion } from '../config'
 import { isFocusVisible } from '../gestures'
+import { resolveLayoutTransition, type LayoutProp } from '../layout'
 import { usePresence } from '../presence'
-import { resolveAnimatableValue, resolveTransition } from '../transitions'
+import {
+  isTopLevelTransition,
+  resolveAnimatableValue,
+  resolveTransition,
+  stableSig,
+} from '../transitions'
 import { ensureReanimatedInstalled } from './installCheck'
 import {
   type AnimatableValue,
@@ -45,8 +51,17 @@ const TRANSFORM_KEYS = [
   'scaleX',
   'scaleY',
   'rotate',
+  'rotateX',
+  'rotateY',
 ] as const
 
+// Rotation keys land in the transform array as `{ rotate: '45deg' }` / `{
+// rotateX: '45deg' }` etc. — Reanimated needs the unit-suffixed string form.
+// We hold the underlying shared value as a plain number (degrees) and wrap
+// in the worklet so the resolver pipeline stays uniform with the other
+// numeric transform keys.
+const ROTATION_KEYS = new Set<string>(['rotate', 'rotateX', 'rotateY'])
+
 const NUMERIC_TOP_LEVEL_KEYS = [
   'opacity',
   'width',
@@ -110,6 +125,8 @@ const DEFAULT_RESTING: Record<AnimatableKey, number | string> = {
   scaleX: 1,
   scaleY: 1,
   rotate: 0,
+  rotateX: 0,
+  rotateY: 0,
   opacity: 1,
   width: 0,
   height: 0,
@@ -124,29 +141,6 @@ const DEFAULT_RESTING: Record<AnimatableKey, number | string> = {
   tintColor: 'transparent',
 }
 
-const TRANSITION_KEYS = new Set([
-  'type',
-  'tension',
-  'friction',
-  'mass',
-  'velocity',
-  'restSpeedThreshold',
-  'restDisplacementThreshold',
-  'duration',
-  'easing',
-  'delay',
-  'repeat',
-  'deceleration',
-  'clamp',
-])
-
-function isTopLevelTransition(t: unknown): t is TransitionConfig {
-  if (t === null || typeof t !== 'object') return false
-  const keys = Object.keys(t as object)
-  if (keys.length === 0) return false
-  return keys.every((k) => TRANSITION_KEYS.has(k))
-}
-
 function transitionFor<S>(
   prop: keyof S,
   transition: Transition<S> | undefined,
@@ -207,10 +201,11 @@ export function createMotionComponent<C extends ComponentType<any>>(
       variants,
       controller,
       gesture,
+      layout,
       onAnimationEnd,
       style,
       ...rest
-    } = props as Props & { style?: unknown }
+    } = props as Props & { style?: unknown; layout?: LayoutProp }
 
     // <Presence> contract: when an ancestor flips `isPresent` to false the
     // child stays rendered until `safeToRemove` is called, giving the exit
@@ -553,7 +548,7 @@ export function createMotionComponent<C extends ComponentType<any>>(
 
         if (TRANSFORM_KEY_SET.has(key)) {
           transform.push(
-            key === 'rotate' ? { rotate: `${v}deg` } : { [key]: v },
+            ROTATION_KEYS.has(key) ? { [key]: `${v}deg` } : { [key]: v },
           )
         } else {
           out[key] = v
@@ -585,11 +580,24 @@ export function createMotionComponent<C extends ComponentType<any>>(
       setHovered,
     )
 
+    // Resolve the `layout` prop into a Reanimated `LinearTransition` builder.
+    // Memoized on the value's stable signature so a fresh `layout={true}` or
+    // `layout={{ ... }}` literal each render doesn't rebuild the builder. When
+    // reduced motion is active we pass `undefined` — see `resolveLayout` for
+    // why we don't pass a duration-0 builder instead.
+    const layoutSig = stableSig(layout)
+    const layoutTransition = useMemo(
+      () => (shouldReduceMotion ? undefined : resolveLayoutTransition(layout)),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [layoutSig, shouldReduceMotion],
+    )
+
     return (
       <AnimatedComponent
         ref={ref as never}
         {...(rest as object)}
         {...gestureHandlers}
+        layout={layoutTransition}
         style={mergedStyle}
       />
     )
@@ -629,6 +637,8 @@ function useAnimatableSharedValues(
   const scaleX = useSharedValue<number | string>(init('scaleX'))
   const scaleY = useSharedValue<number | string>(init('scaleY'))
   const rotate = useSharedValue<number | string>(init('rotate'))
+  const rotateX = useSharedValue<number | string>(init('rotateX'))
+  const rotateY = useSharedValue<number | string>(init('rotateY'))
   const opacity = useSharedValue<number | string>(init('opacity'))
   const width = useSharedValue<number | string>(init('width'))
   const height = useSharedValue<number | string>(init('height'))
@@ -649,6 +659,8 @@ function useAnimatableSharedValues(
       scaleX,
       scaleY,
       rotate,
+      rotateX,
+      rotateY,
       opacity,
       width,
       height,
@@ -895,40 +907,6 @@ function restValue(
   return undefined
 }
 
-function stableSig(value: unknown): string {
-  if (value === undefined) return ''
-  try {
-    return stableStringify(value)
-  } catch {
-    return String(value)
-  }
-}
-
-/**
- * JSON.stringify with keys sorted at every level — gives a stable signature
- * regardless of property declaration order. Functions serialize as `null` so a
- * change in easing-fn reference is invisible here; that's fine for v0.1
- * (easing swaps are rare and the worklet wrapper handles correctness).
- */
-function stableStringify(v: unknown): string {
-  if (v === null || typeof v !== 'object') {
-    if (typeof v === 'function' || v === undefined) return 'null'
-    return JSON.stringify(v)
-  }
-  if (Array.isArray(v)) {
-    return '[' + v.map(stableStringify).join(',') + ']'
-  }
-  const obj = v as Record<string, unknown>
-  const keys = Object.keys(obj).sort()
-  return (
-    '{' +
-    keys
-      .map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k]))
-      .join(',') +
-    '}'
-  )
-}
-
 /**
  * Per-layer resolved targets: each declared gesture sub-state collapses to a
  * map of primitive endpoints (numbers or color strings), already passed

package/src/transitions/easing.ts

@@ -1,4 +1,6 @@
-import { isWorkletFunction } from 'react-native-reanimated'
+// `isWorkletFunction` lives in `react-native-worklets` (the Reanimated 4 peer
+// dep); Reanimated's own re-export is deprecated.
+import { isWorkletFunction } from 'react-native-worklets'
 
 /**
  * Reanimated 3.9+ validates that easing functions used in nested-transition

package/src/transitions/index.ts

@@ -1,2 +1,5 @@
 export { resolveTransition, resolveAnimatableValue } from './resolve'
 export { ensureWorkletEasing } from './easing'
+export { isTopLevelTransition, TRANSITION_CONFIG_KEYS } from './keys'
+export { stableSig } from './sig'
+export { DEFAULT_SPRING, springToReanimated } from './spring'

package/src/transitions/keys.ts

@@ -0,0 +1,32 @@
+import { type TransitionConfig } from '../types'
+
+/**
+ * Field names that may appear on a `TransitionConfig` (spring / timing /
+ * decay / no-animation). Used as a structural discriminator: if every key on
+ * an object is in this set, the object is treated as a top-level transition;
+ * otherwise it's a per-property / per-layer transition map.
+ *
+ * Adding a new field to `TransitionConfig` requires adding the name here.
+ */
+export const TRANSITION_CONFIG_KEYS = new Set([
+  'type',
+  'tension',
+  'friction',
+  'mass',
+  'velocity',
+  'restSpeedThreshold',
+  'restDisplacementThreshold',
+  'duration',
+  'easing',
+  'delay',
+  'repeat',
+  'deceleration',
+  'clamp',
+])
+
+export function isTopLevelTransition(t: unknown): t is TransitionConfig {
+  if (t === null || typeof t !== 'object') return false
+  const keys = Object.keys(t as object)
+  if (keys.length === 0) return false
+  return keys.every((k) => TRANSITION_CONFIG_KEYS.has(k))
+}

package/src/transitions/resolve.ts

@@ -8,6 +8,7 @@ import {
   withTiming,
 } from 'react-native-reanimated'
 import { ensureWorkletEasing } from './easing'
+import { springToReanimated } from './spring'
 import {
   type AnimatableValue,
   type DecayTransition,
@@ -39,32 +40,8 @@ export type CallbackFactory = (
   step: number | undefined,
 ) => AnimationCallback | undefined
 
-/**
- * Default spring physics, expressed in react-spring vocabulary. Conversion
- * to Reanimated's raw `stiffness` / `damping` lives below; raw config never
- * leaks past this module.
- */
-const DEFAULT_SPRING: Required<
-  Pick<SpringTransition, 'tension' | 'friction' | 'mass'>
-> = {
-  tension: 170,
-  friction: 26,
-  mass: 1,
-}
-
 const DEFAULT_TIMING_DURATION = 250
 
-function springToReanimated(t: SpringTransition) {
-  return {
-    stiffness: t.tension ?? DEFAULT_SPRING.tension,
-    damping: t.friction ?? DEFAULT_SPRING.friction,
-    mass: t.mass ?? DEFAULT_SPRING.mass,
-    velocity: t.velocity,
-    restSpeedThreshold: t.restSpeedThreshold,
-    restDisplacementThreshold: t.restDisplacementThreshold,
-  }
-}
-
 function buildSpring(
   cfg: SpringTransition,
   toValue: number | string,