@rootnative/inertia 0.0.0-alpha.0 → 0.0.0-alpha.2

package/dist/{types-cU43dEmH.d.mts → types-BzEgiUdJ.d.mts}

@@ -60,6 +60,51 @@ interface NoAnimationTransition {
     type: 'no-animation';
 }
 type TransitionConfig = SpringTransition | TimingTransition | DecayTransition | NoAnimationTransition;
+/**
+ * Augmentation point for typed named transitions. Empty by default — the
+ * registry is data fed to `<MotionConfig transitions={...}>` at runtime, so
+ * out of the box any string is accepted wherever a `TransitionName` is.
+ *
+ * Consumers who want their registered names to autocomplete (and typos to be
+ * compile errors) augment this interface with their design system's names:
+ *
+ * ```ts
+ * declare module '@rootnative/inertia' {
+ *   interface RegisteredTransitions {
+ *     'state-hover': TransitionConfig
+ *     'selection': TransitionConfig
+ *   }
+ * }
+ * ```
+ *
+ * The value type is ignored — only the keys matter. Inertia itself never
+ * declares a name here: presets are consumer data, not library surface.
+ */
+interface RegisteredTransitions {
+}
+/**
+ * A named transition registered on the nearest `<MotionConfig transitions>`.
+ * Accepted anywhere a `TransitionConfig` is: the `transition` prop (top-level
+ * and per-property), the `layout` prop, and the value-layer hooks. Resolution
+ * happens on the JS thread against the nearest provider; unknown names warn
+ * in dev and fall back to the library default spring.
+ *
+ * Plain `string` until `RegisteredTransitions` is augmented; with an
+ * augmentation in place it narrows to the registered keys.
+ */
+type TransitionName = keyof RegisteredTransitions extends never ? string : keyof RegisteredTransitions & string;
+/**
+ * The registry shape accepted by `<MotionConfig transitions={...}>`: named
+ * `TransitionConfig`s. Names are consumer vocabulary (design tokens, semantic
+ * roles); Inertia ships no presets.
+ */
+type NamedTransitions = Partial<Record<TransitionName, TransitionConfig>>;
+/**
+ * A transition given either inline (`TransitionConfig`) or by registered name
+ * (`TransitionName`). This is the input type everywhere the public surface
+ * accepts a single transition.
+ */
+type TransitionInput = TransitionConfig | TransitionName;
 /**
  * Repeat config — one shape, not three flags. Default `alternate: true`.
  */
@@ -73,7 +118,7 @@ type RepeatConfig = number | 'infinite' | {
  * here.
  */
 type PerPropertyTransition<S> = {
-    [K in keyof S]?: TransitionConfig;
+    [K in keyof S]?: TransitionInput;
 };
 /**
  * Per-gesture-layer transition map. Each `gesture` sub-state animates a
@@ -85,12 +130,12 @@ type PerPropertyTransition<S> = {
  * collide with the primitive's inferred style keys.
  */
 interface GestureLayerTransitions {
-    pressed?: TransitionConfig;
-    focused?: TransitionConfig;
-    focusVisible?: TransitionConfig;
-    hovered?: TransitionConfig;
+    pressed?: TransitionInput;
+    focused?: TransitionInput;
+    focusVisible?: TransitionInput;
+    hovered?: TransitionInput;
 }
-type Transition<S> = TransitionConfig | (PerPropertyTransition<S> & GestureLayerTransitions);
+type Transition<S> = TransitionInput | (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`,
@@ -259,7 +304,9 @@ interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
     gesture?: GestureSubStates<C>;
     /**
      * Per-property or top-level transition config. Per-property entries take
-     * precedence over the top-level transition.
+     * precedence over the top-level transition. Anywhere a config object is
+     * accepted (top-level, per-property, per gesture layer) a `TransitionName`
+     * registered on the nearest `<MotionConfig transitions>` is accepted too.
      */
     transition?: Transition<AnimateStyle<C>>;
     /**
@@ -271,6 +318,8 @@ interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
      * - `true` — animate with the library's default spring.
      * - `TransitionConfig` — spring (react-spring vocab) or timing config; the
      *   resolver bridges to Reanimated's `LinearTransition` builder.
+     * - `TransitionName` — a name registered on the nearest
+     *   `<MotionConfig transitions>`.
      * - omitted / `false` — no layout animation (default).
      *
      * Only `'spring'` / `'timing'` / `'no-animation'` map to layout transitions
@@ -282,7 +331,7 @@ interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
      * own layout changes, `layoutId` animates from a different element's
      * last measured rect to this element's current rect.
      */
-    layout?: boolean | TransitionConfig;
+    layout?: boolean | TransitionInput;
     /**
      * Shared-element transition id. When a Motion primitive with `layoutId`
      * unmounts, its last on-screen rect is recorded under that id; the next
@@ -336,4 +385,4 @@ interface MotionComponent<C extends ComponentType<any>> {
     displayName?: string;
 }
 
-export type { AnimatableValue as A, DecayTransition as D, EasingInput as E, GestureSubStates 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, MotionProps as c, SequenceStep as d, TimingTransition as e, Transition as f, VariantsMap as g, GestureLayerTransitions as h };
+export type { AnimatableValue as A, DecayTransition as D, EasingInput as E, GestureSubStates as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionInput as T, VariantController as V, TransitionConfig as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, MotionProps as g, NoAnimationTransition as h, RepeatConfig as i, SequenceStep as j, TimingTransition as k, Transition as l, VariantsMap as m, GestureLayerTransitions as n };

package/dist/{types-cU43dEmH.d.ts → types-BzEgiUdJ.d.ts}

@@ -60,6 +60,51 @@ interface NoAnimationTransition {
     type: 'no-animation';
 }
 type TransitionConfig = SpringTransition | TimingTransition | DecayTransition | NoAnimationTransition;
+/**
+ * Augmentation point for typed named transitions. Empty by default — the
+ * registry is data fed to `<MotionConfig transitions={...}>` at runtime, so
+ * out of the box any string is accepted wherever a `TransitionName` is.
+ *
+ * Consumers who want their registered names to autocomplete (and typos to be
+ * compile errors) augment this interface with their design system's names:
+ *
+ * ```ts
+ * declare module '@rootnative/inertia' {
+ *   interface RegisteredTransitions {
+ *     'state-hover': TransitionConfig
+ *     'selection': TransitionConfig
+ *   }
+ * }
+ * ```
+ *
+ * The value type is ignored — only the keys matter. Inertia itself never
+ * declares a name here: presets are consumer data, not library surface.
+ */
+interface RegisteredTransitions {
+}
+/**
+ * A named transition registered on the nearest `<MotionConfig transitions>`.
+ * Accepted anywhere a `TransitionConfig` is: the `transition` prop (top-level
+ * and per-property), the `layout` prop, and the value-layer hooks. Resolution
+ * happens on the JS thread against the nearest provider; unknown names warn
+ * in dev and fall back to the library default spring.
+ *
+ * Plain `string` until `RegisteredTransitions` is augmented; with an
+ * augmentation in place it narrows to the registered keys.
+ */
+type TransitionName = keyof RegisteredTransitions extends never ? string : keyof RegisteredTransitions & string;
+/**
+ * The registry shape accepted by `<MotionConfig transitions={...}>`: named
+ * `TransitionConfig`s. Names are consumer vocabulary (design tokens, semantic
+ * roles); Inertia ships no presets.
+ */
+type NamedTransitions = Partial<Record<TransitionName, TransitionConfig>>;
+/**
+ * A transition given either inline (`TransitionConfig`) or by registered name
+ * (`TransitionName`). This is the input type everywhere the public surface
+ * accepts a single transition.
+ */
+type TransitionInput = TransitionConfig | TransitionName;
 /**
  * Repeat config — one shape, not three flags. Default `alternate: true`.
  */
@@ -73,7 +118,7 @@ type RepeatConfig = number | 'infinite' | {
  * here.
  */
 type PerPropertyTransition<S> = {
-    [K in keyof S]?: TransitionConfig;
+    [K in keyof S]?: TransitionInput;
 };
 /**
  * Per-gesture-layer transition map. Each `gesture` sub-state animates a
@@ -85,12 +130,12 @@ type PerPropertyTransition<S> = {
  * collide with the primitive's inferred style keys.
  */
 interface GestureLayerTransitions {
-    pressed?: TransitionConfig;
-    focused?: TransitionConfig;
-    focusVisible?: TransitionConfig;
-    hovered?: TransitionConfig;
+    pressed?: TransitionInput;
+    focused?: TransitionInput;
+    focusVisible?: TransitionInput;
+    hovered?: TransitionInput;
 }
-type Transition<S> = TransitionConfig | (PerPropertyTransition<S> & GestureLayerTransitions);
+type Transition<S> = TransitionInput | (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`,
@@ -259,7 +304,9 @@ interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
     gesture?: GestureSubStates<C>;
     /**
      * Per-property or top-level transition config. Per-property entries take
-     * precedence over the top-level transition.
+     * precedence over the top-level transition. Anywhere a config object is
+     * accepted (top-level, per-property, per gesture layer) a `TransitionName`
+     * registered on the nearest `<MotionConfig transitions>` is accepted too.
      */
     transition?: Transition<AnimateStyle<C>>;
     /**
@@ -271,6 +318,8 @@ interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
      * - `true` — animate with the library's default spring.
      * - `TransitionConfig` — spring (react-spring vocab) or timing config; the
      *   resolver bridges to Reanimated's `LinearTransition` builder.
+     * - `TransitionName` — a name registered on the nearest
+     *   `<MotionConfig transitions>`.
      * - omitted / `false` — no layout animation (default).
      *
      * Only `'spring'` / `'timing'` / `'no-animation'` map to layout transitions
@@ -282,7 +331,7 @@ interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
      * own layout changes, `layoutId` animates from a different element's
      * last measured rect to this element's current rect.
      */
-    layout?: boolean | TransitionConfig;
+    layout?: boolean | TransitionInput;
     /**
      * Shared-element transition id. When a Motion primitive with `layoutId`
      * unmounts, its last on-screen rect is recorded under that id; the next
@@ -336,4 +385,4 @@ interface MotionComponent<C extends ComponentType<any>> {
     displayName?: string;
 }
 
-export type { AnimatableValue as A, DecayTransition as D, EasingInput as E, GestureSubStates 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, MotionProps as c, SequenceStep as d, TimingTransition as e, Transition as f, VariantsMap as g, GestureLayerTransitions as h };
+export type { AnimatableValue as A, DecayTransition as D, EasingInput as E, GestureSubStates as G, MotionComponent as M, NamedTransitions as N, PerPropertyTransition as P, RegisteredTransitions as R, SpringTransition as S, TransitionInput as T, VariantController as V, TransitionConfig as a, TransitionName as b, AnimateStyle as c, AnimationCallbackInfo as d, EasingFunction as e, EasingFunctionFactory as f, MotionProps as g, NoAnimationTransition as h, RepeatConfig as i, SequenceStep as j, TimingTransition as k, Transition as l, VariantsMap as m, GestureLayerTransitions as n };

package/dist/{useGesture-BnY65PlQ.d.ts → useGesture-BRLgiNOC.d.ts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { T as TransitionConfig, h as GestureLayerTransitions } from './types-cU43dEmH.js';
+import { T as TransitionInput, n as GestureLayerTransitions } from './types-BzEgiUdJ.js';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the
@@ -42,8 +42,10 @@ interface UseGestureResult {
  *
  * Transitions follow the same shape as the `gesture` prop's accompanying
  * `transition`: pass a single `TransitionConfig` to use for every layer, or a
- * `GestureLayerTransitions` map to give each layer its own. Layers without an
- * explicit transition fall back to the library default spring.
+ * `GestureLayerTransitions` map to give each layer its own. A `TransitionName`
+ * registered on the nearest `<MotionConfig transitions>` is accepted in both
+ * positions (top-level and per-layer). Layers without an explicit transition
+ * fall back to the library default spring.
  *
  * Reduced motion (via `<MotionConfig reducedMotion>`) collapses every
  * transition to `no-animation` so state changes snap instead of interpolating
@@ -79,6 +81,6 @@ interface UseGestureResult {
  * }
  * ```
  */
-declare function useGesture(transition?: TransitionConfig | GestureLayerTransitions): UseGestureResult;
+declare function useGesture(transition?: TransitionInput | GestureLayerTransitions): UseGestureResult;
 
 export { type UseGestureHandlers as U, type UseGestureResult as a, useGesture as u };

package/dist/{useGesture-DxtXdz-K.d.mts → useGesture-C0GBS7d2.d.mts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { T as TransitionConfig, h as GestureLayerTransitions } from './types-cU43dEmH.mjs';
+import { T as TransitionInput, n as GestureLayerTransitions } from './types-BzEgiUdJ.mjs';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the
@@ -42,8 +42,10 @@ interface UseGestureResult {
  *
  * Transitions follow the same shape as the `gesture` prop's accompanying
  * `transition`: pass a single `TransitionConfig` to use for every layer, or a
- * `GestureLayerTransitions` map to give each layer its own. Layers without an
- * explicit transition fall back to the library default spring.
+ * `GestureLayerTransitions` map to give each layer its own. A `TransitionName`
+ * registered on the nearest `<MotionConfig transitions>` is accepted in both
+ * positions (top-level and per-layer). Layers without an explicit transition
+ * fall back to the library default spring.
  *
  * Reduced motion (via `<MotionConfig reducedMotion>`) collapses every
  * transition to `no-animation` so state changes snap instead of interpolating
@@ -79,6 +81,6 @@ interface UseGestureResult {
  * }
  * ```
  */
-declare function useGesture(transition?: TransitionConfig | GestureLayerTransitions): UseGestureResult;
+declare function useGesture(transition?: TransitionInput | GestureLayerTransitions): UseGestureResult;
 
 export { type UseGestureHandlers as U, type UseGestureResult as a, useGesture as u };

package/llms.txt

@@ -42,13 +42,13 @@ import { MotionScrollView } from '@rootnative/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"`).
+- `<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 }`. Reach for plain `useGesture` for additive blends or per-key custom rules.
+- `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.
 - `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.
+- `useAnimation(target, transition?)` — drive a `SharedValue<number>` toward `target` with any `TransitionConfig` (spring / timing / decay / no-animation, plus `repeat`) or a registered `TransitionName`. 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 (or a spring-typed registered `TransitionName`; non-spring names warn and fall back to the default spring). `target` may be a plain number (effect-driven) or a `SharedValue<number>` (UI-thread reaction); the latter is the gesture-smoothing path.
 - `useBooleanSpring(active, config?)` — sugar over `useSpring` for the recurring "spring 0↔1 progress from a boolean" shape (checkbox checks, accordion expansions, drawer open/closed). Identical mechanics to `useSpring(active ? 1 : 0, config)` — the named form so the call site reads as the boolean it represents.
 - `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.
 - `useShadow({ from, to, progress })` — pure value-layer interpolator between two `ShadowConfig`s (`shadowOpacity` / `shadowRadius` / `shadowOffset` / `elevation` / `shadowColor`) driven by a `SharedValue<number>` (0→1). Returns an animated style fragment to spread onto `style`; only emits keys present on either side, absent sides default to natural zero. The hook does not animate on its own — drive `progress` with a spring, a scroll-derived `useTransform`, or any other shared value source.
@@ -56,6 +56,10 @@ import { MotionScrollView } from '@rootnative/inertia/scroll-view'
 - `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`.
 - `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.
 
 ## Motion props
 
@@ -132,7 +136,7 @@ Auto-layout transitions ship via the `layout` prop (`true` / `TransitionConfig`)
 ## Optional adapter packages
 
 - `@rootnative/inertia-gradients` — `MotionLinearGradient` over `expo-linear-gradient`. Animatable: `colors`, `start`, `end`, `locations`.
-- `@rootnative/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.
+- `@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.
 
 ## Docs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootnative/inertia",
-  "version": "0.0.0-alpha.0",
+  "version": "0.0.0-alpha.2",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "RootNative",
@@ -107,6 +107,7 @@
     "LICENSE",
     "CHANGELOG.md",
     "!**/__tests__",
+    "!**/__type-tests__",
     "!**/*.test.*"
   ],
   "peerDependencies": {

package/src/config/MotionConfig.tsx

@@ -1,26 +1,72 @@
 import { type ReactNode, useMemo } from 'react'
+import { stableSig } from '../transitions/sig'
+import { type NamedTransitions } from '../types'
 import {
   MotionConfigContext,
   type MotionConfigValue,
   type ReducedMotion,
+  useMotionConfig,
 } from './MotionConfigContext'
 
+export interface MotionConfigProps {
+  /**
+   * How descendants respond to reduced-motion preferences. Inherits from the
+   * nearest ancestor `<MotionConfig>` when omitted (the root default is
+   * `'user'` — respect the OS accessibility setting).
+   */
+  reducedMotion?: ReducedMotion
+  /**
+   * Named transitions available to every descendant wherever a
+   * `TransitionConfig` is accepted — the `transition` prop (top-level and
+   * per-property), the `layout` prop, and the value-layer hooks:
+   *
+   * ```tsx
+   * <MotionConfig
+   *   transitions={{
+   *     'state-press': { type: 'timing', duration: 100 },
+   *     selection: { type: 'spring', tension: 380, friction: 33 },
+   *   }}
+   * >
+   *   <Motion.View animate={{ scale: 1 }} transition="selection" />
+   * </MotionConfig>
+   * ```
+   *
+   * Names resolve at the nearest provider; nested providers merge with the
+   * ancestor registry, child entries overriding same-named ancestor entries.
+   * Unknown names warn in dev and fall back to the library default spring.
+   * Names are consumer vocabulary — Inertia ships no presets.
+   */
+  transitions?: NamedTransitions
+  children: ReactNode
+}
+
 /**
- * Provider that controls how descendant Motion primitives respond to
- * reduced-motion preferences. Wrap the root of your app once with the
+ * Provider for subtree-wide animation config: reduced-motion behaviour and
+ * the named-transition registry. Wrap the root of your app once with the
  * default (`reducedMotion="user"`) to respect the OS accessibility setting,
  * or scope a subtree with `'always'` / `'never'` for specific use cases.
+ * Nested providers inherit from their ancestor: an omitted prop keeps the
+ * ancestor's value, and `transitions` maps merge per name (child wins).
  */
 export function MotionConfig({
-  reducedMotion = 'user',
+  reducedMotion,
+  transitions,
   children,
-}: {
-  reducedMotion?: ReducedMotion
-  children: ReactNode
-}) {
+}: MotionConfigProps) {
+  const parent = useMotionConfig()
+  // Keyed on the structural signature, not object identity — consumers
+  // routinely pass a fresh `transitions={{ ... }}` literal each render and
+  // must not re-render every Motion descendant for it.
+  const transitionsSig = stableSig(transitions)
   const value = useMemo<MotionConfigValue>(
-    () => ({ reducedMotion }),
-    [reducedMotion],
+    () => ({
+      reducedMotion: reducedMotion ?? parent.reducedMotion,
+      transitions: transitions
+        ? { ...parent.transitions, ...transitions }
+        : parent.transitions,
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [reducedMotion, transitionsSig, parent],
   )
   return (
     <MotionConfigContext.Provider value={value}>

package/src/config/MotionConfigContext.ts

@@ -1,5 +1,6 @@
 import { createContext, useContext } from 'react'
 import { useReducedMotion } from 'react-native-reanimated'
+import { type NamedTransitions } from '../types'
 
 /**
  * How descendant Motion primitives should treat reduced-motion preferences.
@@ -16,14 +17,22 @@ export type ReducedMotion = 'user' | 'never' | 'always'
 
 export interface MotionConfigValue {
   reducedMotion: ReducedMotion
+  /**
+   * Named transitions registered by ancestor `<MotionConfig transitions>`
+   * providers, already merged (nearest provider wins per name). Empty with no
+   * provider — every name then resolves to the unknown-name fallback.
+   */
+  transitions: NamedTransitions
 }
 
 /**
  * Default config used when a Motion primitive is rendered without a
- * `<MotionConfig>` ancestor. `'user'` means respect the OS setting.
+ * `<MotionConfig>` ancestor. `'user'` means respect the OS setting; no
+ * transitions are registered.
  */
 export const DEFAULT_MOTION_CONFIG: MotionConfigValue = {
   reducedMotion: 'user',
+  transitions: {},
 }
 
 export const MotionConfigContext = createContext<MotionConfigValue>(
@@ -44,6 +53,17 @@ export function useMotionConfig(): MotionConfigValue {
  * primitives call this to decide whether to swap transitions for
  * `no-animation`.
  */
+/**
+ * Read the merged named-transition registry from the nearest `<MotionConfig>`
+ * ancestors. This is what the Motion primitives and value-layer hooks consult
+ * when a `TransitionName` string is passed where a `TransitionConfig` is
+ * accepted; custom animated components (and adapter packages) use it together
+ * with `resolveNamedTransition` to support names on their own surface.
+ */
+export function useNamedTransitions(): NamedTransitions {
+  return useMotionConfig().transitions
+}
+
 export function useShouldReduceMotion(): boolean {
   const { reducedMotion } = useMotionConfig()
   const osReduced = useReducedMotion()

package/src/config/index.ts

@@ -1,9 +1,15 @@
-export { MotionConfig } from './MotionConfig'
+export { MotionConfig, type MotionConfigProps } from './MotionConfig'
 export {
   MotionConfigContext,
   DEFAULT_MOTION_CONFIG,
   useMotionConfig,
+  useNamedTransitions,
   useShouldReduceMotion,
   type MotionConfigValue,
   type ReducedMotion,
 } from './MotionConfigContext'
+export {
+  lookupNamedTransition,
+  resolveNamedTransition,
+  resolveNamedTransitionProp,
+} from './namedTransitions'

package/src/config/namedTransitions.ts

@@ -0,0 +1,80 @@
+import { isTopLevelTransition } from '../transitions/keys'
+import {
+  type NamedTransitions,
+  type Transition,
+  type TransitionConfig,
+  type TransitionInput,
+} from '../types'
+
+declare const __DEV__: boolean
+
+/**
+ * Fallback used when a name isn't found in the registry: the library default
+ * spring, matching what an omitted transition resolves to everywhere else.
+ */
+const UNKNOWN_NAME_FALLBACK: TransitionConfig = { type: 'spring' }
+
+/**
+ * Look a registered transition name up in a registry. Unknown names warn in
+ * dev and fall back to the library default spring — the animation still runs,
+ * it just isn't the one the token intended, which is the same failure
+ * softness the web platform gives an unknown CSS keyword.
+ */
+export function lookupNamedTransition(
+  name: string,
+  registry: NamedTransitions,
+): TransitionConfig {
+  const cfg = registry[name]
+  if (cfg) return cfg
+  if (__DEV__) {
+    console.warn(
+      `[inertia] Unknown transition name "${name}" — falling back to the ` +
+        `default spring. Register it on a provider: ` +
+        `<MotionConfig transitions={{ '${name}': { ... } }}>.`,
+    )
+  }
+  return UNKNOWN_NAME_FALLBACK
+}
+
+/**
+ * Resolve a single transition input — a `TransitionConfig` passes through
+ * untouched, a `TransitionName` is looked up in `registry`. This is the
+ * building block adapter packages use to accept names wherever they accept a
+ * config (pair it with `useNamedTransitions()` for the registry).
+ */
+export function resolveNamedTransition(
+  input: TransitionInput | undefined,
+  registry: NamedTransitions,
+): TransitionConfig | undefined {
+  if (input === undefined) return undefined
+  if (typeof input === 'string') return lookupNamedTransition(input, registry)
+  return input
+}
+
+/**
+ * Resolve every name inside a `transition` prop value — the top-level string
+ * form, and string values on the per-property / gesture-layer map form.
+ * Identity-preserving: when the input contains no names it is returned
+ * unchanged, so signature- and identity-keyed memoization downstream is
+ * unaffected for the config-object path.
+ */
+export function resolveNamedTransitionProp<S>(
+  transition: Transition<S> | undefined,
+  registry: NamedTransitions,
+): Exclude<Transition<S>, string> | undefined {
+  if (transition === undefined) return undefined
+  if (typeof transition === 'string') {
+    return lookupNamedTransition(transition, registry)
+  }
+  if (isTopLevelTransition(transition)) return transition
+  const map = transition as Record<string, unknown>
+  let out: Record<string, unknown> | null = null
+  for (const key in map) {
+    const value = map[key]
+    if (typeof value === 'string') {
+      if (out === null) out = { ...map }
+      out[key] = lookupNamedTransition(value, registry)
+    }
+  }
+  return (out ?? transition) as Exclude<Transition<S>, string>
+}

package/src/gestureLayer/index.ts

@@ -14,6 +14,7 @@
  */
 export { useGestureLayer } from './useGestureLayer'
 export type {
+  GestureLayerProgress,
   GestureLayerStates,
   GestureLayerStyle,
   UseGestureLayerOptions,