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

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

@@ -62,17 +62,57 @@ type RepeatConfig = number | 'infinite' | {
 type PerPropertyTransition<S> = {
     [K in keyof S]?: TransitionConfig;
 };
-type Transition<S> = TransitionConfig | PerPropertyTransition<S>;
+/**
+ * Per-gesture-layer transition map. Each `gesture` sub-state animates a
+ * progress value 0↔1 with its own transition; the worklet composites the
+ * layers in priority order (`hovered → focused → focusVisible → pressed`).
+ *
+ * Keys live on the same `transition` object as `PerPropertyTransition` because
+ * the only other place they could go (nested inside `gesture` itself) would
+ * collide with the primitive's inferred style keys.
+ */
+interface GestureLayerTransitions {
+    pressed?: TransitionConfig;
+    focused?: TransitionConfig;
+    focusVisible?: TransitionConfig;
+    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.
@@ -109,18 +149,26 @@ type VariantsMap<C> = Record<string, AnimateStyle<C>>;
  * - `hovered` — web-only. Typed for cross-platform call sites; the runtime is
  *   a no-op on native.
  *
- * When a sub-state is active, its values override the base `animate` target
- * per-property. Priority on overlap (highest first):
- * `pressed` > `focusVisible` > `focused` > `hovered`. `focusVisible` layers
- * above `focused` so declaring both yields a state-layer on any focus and a
- * ring on keyboard focus only.
+ * Sub-states layer additively. Each declared sub-state owns an independent
+ * progress value (0↔1) that animates in/out with its own transition; the
+ * worklet composites layers in priority order (lowest-to-highest):
+ * `hovered → focused → focusVisible → pressed`. Per-property the chain is
  *
- * Sub-states stack as **single-state selection**, not blended interpolation:
- * the highest-priority active key's value wins per-property, with one
- * transition between target values. Mid-transition cross-fades between
- * sub-states (e.g. release-while-still-hovered) follow the standard `transition`
- * for that property — the resolver does not run multiple parallel
- * interpolations the way a hand-rolled chained-`interpolateColor` would.
+ *   v = base
+ *   v = lerp(v, hovered.value,      progressHovered)      // if declared
+ *   v = lerp(v, focused.value,      progressFocused)      // if declared
+ *   v = lerp(v, focusVisible.value, progressFocusVisible) // if declared
+ *   v = lerp(v, pressed.value,      progressPressed)      // if declared
+ *
+ * (Color-valued keys use `interpolateColor` instead of `lerp`.) When a single
+ * sub-state is active, this collapses to "the highest-priority declared layer
+ * wins". When multiple are mid-transition (e.g. release-while-still-hovered)
+ * each layer fades independently — a press layer fading out at 50ms while a
+ * hover layer holds at full opacity matches MD3 state-layer semantics.
+ *
+ * Configure per-layer fade timing via `transition.<stateName>` on the parent
+ * primitive (see `GestureLayerTransitions`); without it, layers default to
+ * the parent transition or the library default spring.
  */
 interface GestureSubStates<C> {
     pressed?: AnimateStyle<C>;
@@ -173,10 +221,11 @@ interface MotionProps<C> {
      */
     controller?: VariantController;
     /**
-     * Gesture-driven sub-states (`pressed`, `focused`, `hovered`). When omitted,
-     * no handlers are mounted on the underlying component. Sub-state values
-     * merge over `animate` per-property while the corresponding gesture is
-     * active.
+     * Gesture-driven sub-states (`pressed`, `focused`, `focusVisible`,
+     * `hovered`). When omitted, no handlers are mounted on the underlying
+     * component. Each declared sub-state animates as an independent layer
+     * fading in/out over the base `animate` target — see `GestureSubStates`
+     * for the composition model and per-layer transition wiring.
      */
     gesture?: GestureSubStates<C>;
     /**
@@ -184,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.
@@ -199,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-DeZZzE_e.d.ts → types-CjztO3RW.d.ts}

@@ -62,17 +62,57 @@ type RepeatConfig = number | 'infinite' | {
 type PerPropertyTransition<S> = {
     [K in keyof S]?: TransitionConfig;
 };
-type Transition<S> = TransitionConfig | PerPropertyTransition<S>;
+/**
+ * Per-gesture-layer transition map. Each `gesture` sub-state animates a
+ * progress value 0↔1 with its own transition; the worklet composites the
+ * layers in priority order (`hovered → focused → focusVisible → pressed`).
+ *
+ * Keys live on the same `transition` object as `PerPropertyTransition` because
+ * the only other place they could go (nested inside `gesture` itself) would
+ * collide with the primitive's inferred style keys.
+ */
+interface GestureLayerTransitions {
+    pressed?: TransitionConfig;
+    focused?: TransitionConfig;
+    focusVisible?: TransitionConfig;
+    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.
@@ -109,18 +149,26 @@ type VariantsMap<C> = Record<string, AnimateStyle<C>>;
  * - `hovered` — web-only. Typed for cross-platform call sites; the runtime is
  *   a no-op on native.
  *
- * When a sub-state is active, its values override the base `animate` target
- * per-property. Priority on overlap (highest first):
- * `pressed` > `focusVisible` > `focused` > `hovered`. `focusVisible` layers
- * above `focused` so declaring both yields a state-layer on any focus and a
- * ring on keyboard focus only.
+ * Sub-states layer additively. Each declared sub-state owns an independent
+ * progress value (0↔1) that animates in/out with its own transition; the
+ * worklet composites layers in priority order (lowest-to-highest):
+ * `hovered → focused → focusVisible → pressed`. Per-property the chain is
  *
- * Sub-states stack as **single-state selection**, not blended interpolation:
- * the highest-priority active key's value wins per-property, with one
- * transition between target values. Mid-transition cross-fades between
- * sub-states (e.g. release-while-still-hovered) follow the standard `transition`
- * for that property — the resolver does not run multiple parallel
- * interpolations the way a hand-rolled chained-`interpolateColor` would.
+ *   v = base
+ *   v = lerp(v, hovered.value,      progressHovered)      // if declared
+ *   v = lerp(v, focused.value,      progressFocused)      // if declared
+ *   v = lerp(v, focusVisible.value, progressFocusVisible) // if declared
+ *   v = lerp(v, pressed.value,      progressPressed)      // if declared
+ *
+ * (Color-valued keys use `interpolateColor` instead of `lerp`.) When a single
+ * sub-state is active, this collapses to "the highest-priority declared layer
+ * wins". When multiple are mid-transition (e.g. release-while-still-hovered)
+ * each layer fades independently — a press layer fading out at 50ms while a
+ * hover layer holds at full opacity matches MD3 state-layer semantics.
+ *
+ * Configure per-layer fade timing via `transition.<stateName>` on the parent
+ * primitive (see `GestureLayerTransitions`); without it, layers default to
+ * the parent transition or the library default spring.
  */
 interface GestureSubStates<C> {
     pressed?: AnimateStyle<C>;
@@ -173,10 +221,11 @@ interface MotionProps<C> {
      */
     controller?: VariantController;
     /**
-     * Gesture-driven sub-states (`pressed`, `focused`, `hovered`). When omitted,
-     * no handlers are mounted on the underlying component. Sub-state values
-     * merge over `animate` per-property while the corresponding gesture is
-     * active.
+     * Gesture-driven sub-states (`pressed`, `focused`, `focusVisible`,
+     * `hovered`). When omitted, no handlers are mounted on the underlying
+     * component. Each declared sub-state animates as an independent layer
+     * fading in/out over the base `animate` target — see `GestureSubStates`
+     * for the composition model and per-layer transition wiring.
      */
     gesture?: GestureSubStates<C>;
     /**
@@ -184,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.
@@ -199,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
 
@@ -62,18 +81,47 @@ Spring uses react-spring vocabulary (`tension`, `friction`, `mass`). Reanimated'
 ## Gestures
 
 ```tsx
-<Motion.View gesture={{ pressed: { scale: 0.96 }, focused: {...}, hovered: {...} }} />
+<Motion.View
+  gesture={{
+    hovered: { backgroundColor: '#0001' },
+    focused: { backgroundColor: '#0002' },
+    pressed: { backgroundColor: '#0003' },
+  }}
+  transition={{ type: 'timing', duration: 120 }}
+/>
 ```
 
-Sub-state priority: `hovered < focused < pressed`. `hovered` is a no-op on native.
+Sub-states layer **additively** in priority order: `hovered → focused → focusVisible → pressed`. Each declared sub-state owns an independent progress (0↔1) that fades in/out with its own transition; the worklet composites layers via `lerp` (numerics) / `interpolateColor` (colors). MD3 release-while-hovered behaves correctly — the press layer fades out without disturbing the hover layer.
+
+Per-layer transitions via `transition.<stateName>`:
+
+```tsx
+transition={{
+  pressed:  { type: 'timing', duration: 50 },
+  hovered:  { type: 'timing', duration: 90 },
+}}
+```
+
+`focusVisible` engages only on keyboard focus (W3C `:focus-visible`) so click-focus on web doesn't flash a ring; on native it tracks `focused`. `hovered` is a no-op on native.
+
+## Caveats
+
+- `Motion.Pressable` does **not** support function-form `style={({ pressed }) => ...}`. Reanimated's animated-component wrapper silently drops it. Drive press/focus/hover styling through `gesture` instead, or compute conditional styles once in render.
+- `initial` is read once on mount and intentionally non-reactive. To reset after a state change, change the component `key`, remount via `<Presence>`, or drive the value through a controller. Pass `initial={false}` to skip the initial-mount animation.
 
 ## 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.2",
+  "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
+}