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

package/README.md

@@ -42,9 +42,11 @@ export function FadeIn() {
 - **Primitives** — `Motion.View`, `Motion.Text`, `Motion.Image`, `Motion.Pressable`, `Motion.ScrollView`. Per-primitive style inference (no shared `ViewStyle & TextStyle & ImageStyle` fallback).
 - **Sequences and keyframes** — `animate={{ x: [0, 100, 0] }}` with per-step transitions; unified `repeat: number | 'infinite' | { count, alternate }`.
 - **Variants** — `variants={{ open, closed }}` with `animate="open"`. Programmatic control via `useVariants` + `controller={...}`.
-- **Gestures** — single `gesture` prop on every primitive: `gesture={{ pressed, focused, focusVisible, hovered }}`. `focusVisible` engages only on keyboard focus (W3C `:focus-visible`) so click-focus on web doesn't flash a ring; on native it tracks `focused`. Zero overhead when omitted.
+- **Gestures** — single `gesture` prop on every primitive: `gesture={{ pressed, focused, focusVisible, hovered }}`. Sub-states layer **additively** in priority order (`hovered → focused → focusVisible → pressed`); each layer fades in/out on its own progress so MD3 release-while-hovered cross-fades correctly. Per-layer transitions via `transition.<stateName>`. `focusVisible` engages only on keyboard focus (W3C `:focus-visible`) so click-focus on web doesn't flash a ring; on native it tracks `focused`. Zero overhead when omitted.
 - **`<Presence>`** — mount/unmount transitions; exiting children automatically receive `pointerEvents: 'none'`.
 - **`<MotionConfig reducedMotion>`** — OS reduce-motion honored end-to-end (`'user' | 'never' | 'always'`).
+- **`layout` prop** — auto-layout transitions on every primitive, bridging Reanimated's `LinearTransition` via the same react-spring vocab (`tension`/`friction`/`mass`). Accepts `boolean | TransitionConfig`.
+- **Value-layer hooks** — `useMotionValue`, `useSpring`, `useAnimation`, `useTransform`, `useScroll`, `useVariants`, `useGesture`. The escape hatch for animations the prop surface can't express — sibling overlays driven by a parent gesture, indeterminate loops on standalone shared values, gesture-smoothed inputs, etc.
 - **Per-primitive subpath imports** — `@onlynative/inertia/view`, `/text`, `/image`, `/pressable`, `/scroll-view`.
 - **JS-thread resolver, memoized worklets** — animate/transition objects compile to baked `withSpring` / `withTiming` / `withDecay` calls on the JS thread; the worklet body never iterates `Object.keys(...)` at frame time.
 
@@ -58,7 +60,13 @@ import { MotionPressable } from '@onlynative/inertia/pressable'
 import { MotionScrollView } from '@onlynative/inertia/scroll-view'
 ```
 
-A `Motion.View`-only import currently bundles to ~3.2 kB brotlied (excluding peers).
+Or the barrel — same primitives, named imports tree-shake cleanly because the package is `sideEffects: false`:
+
+```ts
+import { MotionView } from '@onlynative/inertia'
+```
+
+Both forms land at ~4.1–4.2 kB brotlied for a single primitive (peers excluded). The full namespace (`import { Motion } from '@onlynative/inertia'`, then `Motion.View`) cannot tree-shake — accessing one property of a literal object holds the whole object live — and lands at ~4.8 kB. CI checks all three forms via `size-limit` so the gap doesn't drift.
 
 ## Transitions
 
@@ -71,11 +79,44 @@ A `Motion.View`-only import currently bundles to ~3.2 kB brotlied (excluding pee
 
 Plus, on any transition: `delay`, `repeat`. Per-property transitions take precedence over the top-level transition. Spring config uses **react-spring vocabulary** (`tension`/`friction`); Reanimated's raw `stiffness`/`damping` is never on the public surface.
 
+## Caveats
+
+- **`Motion.Pressable` does not support function-form `style`.** RN's `Pressable` accepts `style={({ pressed }) => ...}` and re-runs it per state change; Inertia inherits Reanimated's `createAnimatedComponent` wrapper, which silently drops that form (no error, no warning). Drive press/focus/hover styling through `gesture` instead, or compute conditional styles once in render. See [primitives/pressable](https://onlynative.github.io/inertia/docs/primitives/pressable#style-must-be-a-value-not-a-function).
+- **`initial` is read once on mount.** Mutating `initial` after first render does nothing — change the component `key`, remount via `<Presence>`, or drive the value through a controller. Pass `initial={false}` to skip the initial-mount animation entirely.
+
 ## Animatable properties
 
 Numeric: `opacity`, `translateX`, `translateY`, `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`, `rotateY`, `width`, `height`, `borderRadius`. Color: `backgroundColor`, `borderColor`, `color`, `tintColor` (Image only — `Motion.View` rejects it at compile time). Layout transforms via `transform: [...]`. Color targets are forwarded straight through `withSpring` / `withTiming`; Reanimated's value setter packs the string to RGBA and interpolates on the UI thread.
 
-Out of scope for `0.x`: SVG path morphing, gradient interpolation, shared-element transitions across screens.
+SVG path morphing ships in the [`@onlynative/inertia-svg`](../svg) adapter (`MotionPath`). Out of scope for `0.x`: shared-element transitions across screens (Reanimated 4 dropped `sharedTransitionTag`; a measure-based replacement is in design).
+
+## When not to use the core package alone
+
+Three sibling packages extend Inertia for capabilities that need extra peer dependencies. The core stays minimal so apps that don't need these don't pay for them.
+
+**Continuous gestures** — the `gesture` prop in `@onlynative/inertia` covers `pressed` / `focused` / `focusVisible` / `hovered` (the Pressable-shaped sub-states). For drag, pan, or swipe, use [`@onlynative/inertia-gestures`](../gestures):
+
+- `useDrag` — one- or two-axis drag with optional constraints and rubber-band elasticity
+- `usePan` — camera-style pan with momentum on release
+- `useSwipe` — directional commit-or-snap-back (distance + velocity thresholds)
+
+```sh
+pnpm add @onlynative/inertia-gestures react-native-gesture-handler
+```
+
+**Animated gradients** — colors / start / end / locations interpolation on a linear gradient lives in [`@onlynative/inertia-gradients`](../gradients), wrapping `expo-linear-gradient`:
+
+```sh
+pnpm add @onlynative/inertia-gradients expo-linear-gradient
+```
+
+**SVG path morphing** — `MotionPath` lives in [`@onlynative/inertia-svg`](../svg), wrapping `react-native-svg`. Animates path data (`d`) on structurally-compatible paths via element-wise scalar interpolation, plus `fill` / `stroke` / `strokeWidth` / opacities / `strokeDashoffset`:
+
+```sh
+pnpm add @onlynative/inertia-svg react-native-svg
+```
+
+Keeping `react-native-gesture-handler`, `expo-linear-gradient`, and `react-native-svg` out of the core peer set means apps that animate buttons, sheets, and basic styles don't pay for capabilities they never invoke.
 
 ## Documentation
 

package/dist/index.d.mts

@@ -1,8 +1,10 @@
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import * as react_native from 'react-native';
-import { M as MotionComponent, A as AnimatableValue, T as TransitionConfig, V as VariantController } from './types-DeZZzE_e.mjs';
-export { a as AnimateStyle, b as AnimationCallbackInfo, D as DecayTransition, G as GestureSubStates, c as MotionProps, N as NoAnimationTransition, P as PerPropertyTransition, R as RepeatConfig, S as SequenceStep, d as SpringTransition, e as TimingTransition, f as Transition, g as VariantsMap } from './types-DeZZzE_e.mjs';
+import { NativeSyntheticEvent, NativeScrollEvent } from 'react-native';
+import { M as MotionComponent, A as AnimatableValue, T as TransitionConfig, G as GestureLayerTransitions, S as SpringTransition, V as VariantController } from './types-CjztO3RW.mjs';
+export { a as AnimateStyle, b as AnimationCallbackInfo, D as DecayTransition, c as GestureSubStates, d as MotionProps, N as NoAnimationTransition, P as PerPropertyTransition, R as RepeatConfig, e as SequenceStep, f as TimingTransition, g as Transition, h as VariantsMap } from './types-CjztO3RW.mjs';
+import { SharedValue } from 'react-native-reanimated';
 export { MotionImage } from './motion/Image.mjs';
 export { MotionPressable } from './motion/Pressable.mjs';
 export { MotionScrollView } from './motion/ScrollView.mjs';
@@ -168,6 +170,260 @@ declare function resolveAnimatableValue<V extends number | string>(value: Animat
  */
 declare function ensureWorkletEasing(easing: ((t: number) => number) | undefined): ((t: number) => number) | undefined;
 
+/**
+ * Drive a `SharedValue<number>` toward `target` with **any** transition shape
+ * — spring, timing, decay, or no-animation. The general-purpose value-layer
+ * hook: reach for it when you need raw `useSharedValue + useEffect + withX`
+ * outside the declarative `animate` flow.
+ *
+ * Re-runs whenever `target` changes shape (`target` is in the dep array) or
+ * the transition signature changes (kept stable via JSON-style hashing).
+ * Reduced motion (via `<MotionConfig reducedMotion>`) collapses the
+ * transition to `no-animation` so the value snaps instead of interpolating.
+ *
+ * **Spring shorthand.** Prefer [`useSpring`](./useSpring) when you only want
+ * spring physics — it accepts the same `tension`/`friction`/`mass` config and
+ * also supports a `SharedValue<number>` as the target (UI-thread reactive
+ * source). `useAnimation` is JS-thread-driven only.
+ *
+ * **Loops.** Repeat is part of `TransitionConfig` and flows through
+ * untouched — `useAnimation(1, { type: 'timing', duration: 1800, repeat: {
+ * count: 'infinite', alternate: false } })` produces an indeterminate-style
+ * progress driver.
+ *
+ * @example
+ * ```ts
+ * // Toggle progress (Switch / Checkbox / Radio).
+ * const progress = useAnimation(isChecked ? 1 : 0, {
+ *   type: 'spring',
+ *   tension: 380,
+ *   friction: 33,
+ * })
+ *
+ * // Float a TextField label when the value becomes non-empty.
+ * const floated = useAnimation(hasValue ? 1 : 0, {
+ *   type: 'timing',
+ *   duration: 150,
+ * })
+ *
+ * // Indeterminate progress slider (loops forever, snaps back).
+ * const slide = useAnimation(1, {
+ *   type: 'timing',
+ *   duration: 1800,
+ *   repeat: { count: 'infinite', alternate: false },
+ * })
+ * ```
+ */
+declare function useAnimation(target: number, transition?: TransitionConfig): SharedValue<number>;
+
+/**
+ * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the
+ * shared values returned alongside.
+ *
+ * Hover handlers use `Pressable`'s own `onHoverIn` / `onHoverOut` names (web
+ * only — no-ops on native). `onFocus` consults `isFocusVisible()` before
+ * raising the keyboard-only `focusVisible` layer; `focused` always raises.
+ */
+interface UseGestureHandlers {
+    onPressIn: () => void;
+    onPressOut: () => void;
+    onHoverIn: () => void;
+    onHoverOut: () => void;
+    onFocus: () => void;
+    onBlur: () => void;
+}
+interface UseGestureResult {
+    /** 0↔1 progress for the pressed layer. */
+    pressed: SharedValue<number>;
+    /** 0↔1 progress for the focused layer (any focus modality). */
+    focused: SharedValue<number>;
+    /** 0↔1 progress for the focusVisible layer (keyboard focus only). */
+    focusVisible: SharedValue<number>;
+    /** 0↔1 progress for the hovered layer (web only — stays at 0 on native). */
+    hovered: SharedValue<number>;
+    /** Handlers to spread on the receiving `Pressable`. */
+    handlers: UseGestureHandlers;
+}
+/**
+ * Build a gesture-layer controller. The hook-form of the `gesture` prop —
+ * reach for it when you need to drive multiple animated views from the same
+ * gesture state (a focus ring + state-layer halo + content tint all on one
+ * Pressable), which the prop-form's "animate the receiver's own style" model
+ * can't express.
+ *
+ * Returns four 0↔1 shared values (one per layer) and a handler bag to spread
+ * on a `Pressable`. The shared values are stable across renders — feed them
+ * into any number of `useAnimatedStyle` blocks anywhere in the tree.
+ *
+ * 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.
+ *
+ * Reduced motion (via `<MotionConfig reducedMotion>`) collapses every
+ * transition to `no-animation` so state changes snap instead of interpolating
+ * — same behaviour the gesture prop applies.
+ *
+ * @example
+ * ```tsx
+ * import { useAnimatedStyle } from 'react-native-reanimated'
+ * import { useGesture } from '@onlynative/inertia'
+ *
+ * function Card() {
+ *   const { pressed, focused, hovered, handlers } = useGesture({
+ *     pressed: { type: 'timing', duration: 100 },
+ *     hovered: { type: 'timing', duration: 150 },
+ *     focused: { type: 'timing', duration: 200 },
+ *   })
+ *
+ *   const ringStyle = useAnimatedStyle(() => ({ opacity: focused.value }))
+ *   const haloStyle = useAnimatedStyle(() => ({
+ *     opacity: Math.max(
+ *       hovered.value * 0.08,
+ *       focused.value * 0.10,
+ *       pressed.value * 0.10,
+ *     ),
+ *   }))
+ *
+ *   return (
+ *     <Pressable {...handlers}>
+ *       <Animated.View style={ringStyle} />
+ *       <Animated.View style={haloStyle} />
+ *     </Pressable>
+ *   )
+ * }
+ * ```
+ */
+declare function useGesture(transition?: TransitionConfig | GestureLayerTransitions): UseGestureResult;
+
+/**
+ * Create an animatable value owned by JS but readable from worklets.
+ *
+ * This is the escape-hatch primitive that the rest of the value-layer hooks
+ * (`useSpring`, `useTransform`, `useScroll`) compose against. It is a thin
+ * pass-through over Reanimated's `useSharedValue`: a `SharedValue<T>` with
+ * `.value` for direct reads/writes (UI-thread reads in worklets, JS-thread
+ * writes from event handlers / effects).
+ *
+ * We intentionally do not introduce a `MotionValue` wrapper class around the
+ * shared value. The simplest object that interops with `useAnimatedStyle`,
+ * `useDerivedValue`, and every other Reanimated API _is_ the shared value
+ * itself; adding a `{ get, set, value }` shell would force consumers to
+ * unwrap it at every Reanimated boundary and break worklet capture.
+ *
+ * Worklet read:
+ * ```ts
+ * const x = useMotionValue(0)
+ * useAnimatedStyle(() => ({ transform: [{ translateX: x.value }] }))
+ * ```
+ *
+ * JS write:
+ * ```ts
+ * onPress={() => { x.value = 100 }}
+ * ```
+ */
+declare function useMotionValue<T extends number | string>(initial: T): SharedValue<T>;
+
+/**
+ * Animate a shared value toward `target` with spring physics, using the
+ * library's react-spring vocabulary (`tension` / `friction` / `mass`).
+ *
+ * `target` may be a plain number or a `SharedValue<number>`. The plain-number
+ * path drives the spring from a JS `useEffect`, so the animation re-runs on
+ * every render where `target` changes. The shared-value path drives the
+ * spring from a Reanimated reaction on the UI thread, so values produced by
+ * gestures, scroll handlers, or other worklets flow through without bouncing
+ * back to JS.
+ *
+ * Both call sites end up at the same `withSpring` invocation; the split is
+ * just about which thread observes the source change.
+ */
+declare function useSpring(target: number | SharedValue<number>, config?: SpringTransition): SharedValue<number>;
+
+/**
+ * Extrapolation behavior at the edges of the input range. Mirrors
+ * Reanimated's enum so consumers don't need a separate import.
+ *
+ * - `'clamp'` (default) — output stays pinned at the first/last value
+ *   outside the input range. Matches Framer Motion's default.
+ * - `'identity'` — return the input unchanged outside the range.
+ * - `'extend'` — continue the linear slope beyond the range.
+ */
+type ExtrapolationMode = 'clamp' | 'identity' | 'extend';
+interface UseTransformOptions {
+    extrapolateLeft?: ExtrapolationMode;
+    extrapolateRight?: ExtrapolationMode;
+}
+/**
+ * Derive a value from one or more shared values via a transformer worklet.
+ *
+ * ```ts
+ * const x = useMotionValue(0)
+ * const y = useMotionValue(0)
+ * const distance = useTransform(() => Math.sqrt(x.value ** 2 + y.value ** 2))
+ * ```
+ *
+ * The transformer must be a worklet (or a plain function we auto-wrap —
+ * see the easing wrapper for the rationale). It runs on the UI thread on
+ * every frame where any read shared value changes.
+ */
+declare function useTransform<T>(transformer: () => T): SharedValue<T>;
+/**
+ * Interpolate a numeric shared value onto a range of numbers or colors.
+ *
+ * ```ts
+ * const scroll = useMotionValue(0)
+ * const headerOpacity = useTransform(scroll, [0, 100], [1, 0])
+ * const headerColor  = useTransform(scroll, [0, 100], ['#fff', '#000'])
+ * ```
+ *
+ * When `outputRange` is numeric, this maps to Reanimated's `interpolate`;
+ * when it's a tuple of color strings, it maps to `interpolateColor`. The
+ * input range must be monotonically increasing.
+ */
+declare function useTransform(value: SharedValue<number>, inputRange: readonly number[], outputRange: readonly number[], options?: UseTransformOptions): SharedValue<number>;
+declare function useTransform(value: SharedValue<number>, inputRange: readonly number[], outputRange: readonly string[], options?: UseTransformOptions): SharedValue<string>;
+
+interface UseScrollResult {
+    /** Horizontal scroll offset in points. */
+    scrollX: SharedValue<number>;
+    /** Vertical scroll offset in points. */
+    scrollY: SharedValue<number>;
+    /**
+     * Handler to pass to a `Motion.ScrollView`'s `onScroll` prop (or any other
+     * Reanimated `Animated.ScrollView`). The handler is opaque to JS — it runs
+     * as a worklet — but the type narrows to the same shape RN's native
+     * `onScroll` prop expects so it composes cleanly.
+     */
+    onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+}
+/**
+ * Track the scroll offset of a `Motion.ScrollView` as shared values.
+ *
+ * ```tsx
+ * const { scrollY, onScroll } = useScroll()
+ * const headerOpacity = useTransform(scrollY, [0, 100], [1, 0])
+ *
+ * return (
+ *   <>
+ *     <Motion.View animate={{ opacity: headerOpacity }} />
+ *     <Motion.ScrollView onScroll={onScroll} scrollEventThrottle={16}>
+ *       …
+ *     </Motion.ScrollView>
+ *   </>
+ * )
+ * ```
+ *
+ * Scroll events fire on the UI thread, so `scrollX` / `scrollY` are safe to
+ * read from any worklet (`useAnimatedStyle`, `useDerivedValue`,
+ * `useTransform`) without a JS-thread bounce.
+ *
+ * Remember to set `scrollEventThrottle={16}` on the `ScrollView` for 60Hz
+ * updates — RN's default is to dispatch on every event, which on iOS still
+ * means one per frame, but Android benefits from the explicit cap.
+ */
+declare function useScroll(): UseScrollResult;
+
 /**
  * Build a controller for a variants map. The controller is the imperative
  * escape hatch — pass it to a Motion primitive via `controller={...}` and
@@ -181,4 +437,4 @@ declare function ensureWorkletEasing(easing: ((t: number) => number) | undefined
  */
 declare function useVariants<V extends Readonly<Record<string, object>>>(variants: V, initial?: keyof V & string): VariantController<keyof V & string>;
 
-export { AnimatableValue, Motion, MotionComponent, MotionConfig, type MotionConfigValue, Presence, type PresenceContextValue, type ReducedMotion, TransitionConfig, VariantController, createMotionComponent, ensureWorkletEasing, resolveAnimatableValue, resolveTransition, useMotionConfig, usePresence, useShouldReduceMotion, useVariants };
+export { AnimatableValue, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigValue, Presence, type PresenceContextValue, type ReducedMotion, SpringTransition, TransitionConfig, type UseGestureHandlers, type UseGestureResult, type UseScrollResult, type UseTransformOptions, VariantController, createMotionComponent, ensureWorkletEasing, resolveAnimatableValue, resolveTransition, useAnimation, useGesture, useMotionConfig, useMotionValue, usePresence, useScroll, useShouldReduceMotion, useSpring, useTransform, useVariants };

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import * as react_native from 'react-native';
-import { M as MotionComponent, A as AnimatableValue, T as TransitionConfig, V as VariantController } from './types-DeZZzE_e.js';
-export { a as AnimateStyle, b as AnimationCallbackInfo, D as DecayTransition, G as GestureSubStates, c as MotionProps, N as NoAnimationTransition, P as PerPropertyTransition, R as RepeatConfig, S as SequenceStep, d as SpringTransition, e as TimingTransition, f as Transition, g as VariantsMap } from './types-DeZZzE_e.js';
+import { NativeSyntheticEvent, NativeScrollEvent } from 'react-native';
+import { M as MotionComponent, A as AnimatableValue, T as TransitionConfig, G as GestureLayerTransitions, S as SpringTransition, V as VariantController } from './types-CjztO3RW.js';
+export { a as AnimateStyle, b as AnimationCallbackInfo, D as DecayTransition, c as GestureSubStates, d as MotionProps, N as NoAnimationTransition, P as PerPropertyTransition, R as RepeatConfig, e as SequenceStep, f as TimingTransition, g as Transition, h as VariantsMap } from './types-CjztO3RW.js';
+import { SharedValue } from 'react-native-reanimated';
 export { MotionImage } from './motion/Image.js';
 export { MotionPressable } from './motion/Pressable.js';
 export { MotionScrollView } from './motion/ScrollView.js';
@@ -168,6 +170,260 @@ declare function resolveAnimatableValue<V extends number | string>(value: Animat
  */
 declare function ensureWorkletEasing(easing: ((t: number) => number) | undefined): ((t: number) => number) | undefined;
 
+/**
+ * Drive a `SharedValue<number>` toward `target` with **any** transition shape
+ * — spring, timing, decay, or no-animation. The general-purpose value-layer
+ * hook: reach for it when you need raw `useSharedValue + useEffect + withX`
+ * outside the declarative `animate` flow.
+ *
+ * Re-runs whenever `target` changes shape (`target` is in the dep array) or
+ * the transition signature changes (kept stable via JSON-style hashing).
+ * Reduced motion (via `<MotionConfig reducedMotion>`) collapses the
+ * transition to `no-animation` so the value snaps instead of interpolating.
+ *
+ * **Spring shorthand.** Prefer [`useSpring`](./useSpring) when you only want
+ * spring physics — it accepts the same `tension`/`friction`/`mass` config and
+ * also supports a `SharedValue<number>` as the target (UI-thread reactive
+ * source). `useAnimation` is JS-thread-driven only.
+ *
+ * **Loops.** Repeat is part of `TransitionConfig` and flows through
+ * untouched — `useAnimation(1, { type: 'timing', duration: 1800, repeat: {
+ * count: 'infinite', alternate: false } })` produces an indeterminate-style
+ * progress driver.
+ *
+ * @example
+ * ```ts
+ * // Toggle progress (Switch / Checkbox / Radio).
+ * const progress = useAnimation(isChecked ? 1 : 0, {
+ *   type: 'spring',
+ *   tension: 380,
+ *   friction: 33,
+ * })
+ *
+ * // Float a TextField label when the value becomes non-empty.
+ * const floated = useAnimation(hasValue ? 1 : 0, {
+ *   type: 'timing',
+ *   duration: 150,
+ * })
+ *
+ * // Indeterminate progress slider (loops forever, snaps back).
+ * const slide = useAnimation(1, {
+ *   type: 'timing',
+ *   duration: 1800,
+ *   repeat: { count: 'infinite', alternate: false },
+ * })
+ * ```
+ */
+declare function useAnimation(target: number, transition?: TransitionConfig): SharedValue<number>;
+
+/**
+ * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the
+ * shared values returned alongside.
+ *
+ * Hover handlers use `Pressable`'s own `onHoverIn` / `onHoverOut` names (web
+ * only — no-ops on native). `onFocus` consults `isFocusVisible()` before
+ * raising the keyboard-only `focusVisible` layer; `focused` always raises.
+ */
+interface UseGestureHandlers {
+    onPressIn: () => void;
+    onPressOut: () => void;
+    onHoverIn: () => void;
+    onHoverOut: () => void;
+    onFocus: () => void;
+    onBlur: () => void;
+}
+interface UseGestureResult {
+    /** 0↔1 progress for the pressed layer. */
+    pressed: SharedValue<number>;
+    /** 0↔1 progress for the focused layer (any focus modality). */
+    focused: SharedValue<number>;
+    /** 0↔1 progress for the focusVisible layer (keyboard focus only). */
+    focusVisible: SharedValue<number>;
+    /** 0↔1 progress for the hovered layer (web only — stays at 0 on native). */
+    hovered: SharedValue<number>;
+    /** Handlers to spread on the receiving `Pressable`. */
+    handlers: UseGestureHandlers;
+}
+/**
+ * Build a gesture-layer controller. The hook-form of the `gesture` prop —
+ * reach for it when you need to drive multiple animated views from the same
+ * gesture state (a focus ring + state-layer halo + content tint all on one
+ * Pressable), which the prop-form's "animate the receiver's own style" model
+ * can't express.
+ *
+ * Returns four 0↔1 shared values (one per layer) and a handler bag to spread
+ * on a `Pressable`. The shared values are stable across renders — feed them
+ * into any number of `useAnimatedStyle` blocks anywhere in the tree.
+ *
+ * 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.
+ *
+ * Reduced motion (via `<MotionConfig reducedMotion>`) collapses every
+ * transition to `no-animation` so state changes snap instead of interpolating
+ * — same behaviour the gesture prop applies.
+ *
+ * @example
+ * ```tsx
+ * import { useAnimatedStyle } from 'react-native-reanimated'
+ * import { useGesture } from '@onlynative/inertia'
+ *
+ * function Card() {
+ *   const { pressed, focused, hovered, handlers } = useGesture({
+ *     pressed: { type: 'timing', duration: 100 },
+ *     hovered: { type: 'timing', duration: 150 },
+ *     focused: { type: 'timing', duration: 200 },
+ *   })
+ *
+ *   const ringStyle = useAnimatedStyle(() => ({ opacity: focused.value }))
+ *   const haloStyle = useAnimatedStyle(() => ({
+ *     opacity: Math.max(
+ *       hovered.value * 0.08,
+ *       focused.value * 0.10,
+ *       pressed.value * 0.10,
+ *     ),
+ *   }))
+ *
+ *   return (
+ *     <Pressable {...handlers}>
+ *       <Animated.View style={ringStyle} />
+ *       <Animated.View style={haloStyle} />
+ *     </Pressable>
+ *   )
+ * }
+ * ```
+ */
+declare function useGesture(transition?: TransitionConfig | GestureLayerTransitions): UseGestureResult;
+
+/**
+ * Create an animatable value owned by JS but readable from worklets.
+ *
+ * This is the escape-hatch primitive that the rest of the value-layer hooks
+ * (`useSpring`, `useTransform`, `useScroll`) compose against. It is a thin
+ * pass-through over Reanimated's `useSharedValue`: a `SharedValue<T>` with
+ * `.value` for direct reads/writes (UI-thread reads in worklets, JS-thread
+ * writes from event handlers / effects).
+ *
+ * We intentionally do not introduce a `MotionValue` wrapper class around the
+ * shared value. The simplest object that interops with `useAnimatedStyle`,
+ * `useDerivedValue`, and every other Reanimated API _is_ the shared value
+ * itself; adding a `{ get, set, value }` shell would force consumers to
+ * unwrap it at every Reanimated boundary and break worklet capture.
+ *
+ * Worklet read:
+ * ```ts
+ * const x = useMotionValue(0)
+ * useAnimatedStyle(() => ({ transform: [{ translateX: x.value }] }))
+ * ```
+ *
+ * JS write:
+ * ```ts
+ * onPress={() => { x.value = 100 }}
+ * ```
+ */
+declare function useMotionValue<T extends number | string>(initial: T): SharedValue<T>;
+
+/**
+ * Animate a shared value toward `target` with spring physics, using the
+ * library's react-spring vocabulary (`tension` / `friction` / `mass`).
+ *
+ * `target` may be a plain number or a `SharedValue<number>`. The plain-number
+ * path drives the spring from a JS `useEffect`, so the animation re-runs on
+ * every render where `target` changes. The shared-value path drives the
+ * spring from a Reanimated reaction on the UI thread, so values produced by
+ * gestures, scroll handlers, or other worklets flow through without bouncing
+ * back to JS.
+ *
+ * Both call sites end up at the same `withSpring` invocation; the split is
+ * just about which thread observes the source change.
+ */
+declare function useSpring(target: number | SharedValue<number>, config?: SpringTransition): SharedValue<number>;
+
+/**
+ * Extrapolation behavior at the edges of the input range. Mirrors
+ * Reanimated's enum so consumers don't need a separate import.
+ *
+ * - `'clamp'` (default) — output stays pinned at the first/last value
+ *   outside the input range. Matches Framer Motion's default.
+ * - `'identity'` — return the input unchanged outside the range.
+ * - `'extend'` — continue the linear slope beyond the range.
+ */
+type ExtrapolationMode = 'clamp' | 'identity' | 'extend';
+interface UseTransformOptions {
+    extrapolateLeft?: ExtrapolationMode;
+    extrapolateRight?: ExtrapolationMode;
+}
+/**
+ * Derive a value from one or more shared values via a transformer worklet.
+ *
+ * ```ts
+ * const x = useMotionValue(0)
+ * const y = useMotionValue(0)
+ * const distance = useTransform(() => Math.sqrt(x.value ** 2 + y.value ** 2))
+ * ```
+ *
+ * The transformer must be a worklet (or a plain function we auto-wrap —
+ * see the easing wrapper for the rationale). It runs on the UI thread on
+ * every frame where any read shared value changes.
+ */
+declare function useTransform<T>(transformer: () => T): SharedValue<T>;
+/**
+ * Interpolate a numeric shared value onto a range of numbers or colors.
+ *
+ * ```ts
+ * const scroll = useMotionValue(0)
+ * const headerOpacity = useTransform(scroll, [0, 100], [1, 0])
+ * const headerColor  = useTransform(scroll, [0, 100], ['#fff', '#000'])
+ * ```
+ *
+ * When `outputRange` is numeric, this maps to Reanimated's `interpolate`;
+ * when it's a tuple of color strings, it maps to `interpolateColor`. The
+ * input range must be monotonically increasing.
+ */
+declare function useTransform(value: SharedValue<number>, inputRange: readonly number[], outputRange: readonly number[], options?: UseTransformOptions): SharedValue<number>;
+declare function useTransform(value: SharedValue<number>, inputRange: readonly number[], outputRange: readonly string[], options?: UseTransformOptions): SharedValue<string>;
+
+interface UseScrollResult {
+    /** Horizontal scroll offset in points. */
+    scrollX: SharedValue<number>;
+    /** Vertical scroll offset in points. */
+    scrollY: SharedValue<number>;
+    /**
+     * Handler to pass to a `Motion.ScrollView`'s `onScroll` prop (or any other
+     * Reanimated `Animated.ScrollView`). The handler is opaque to JS — it runs
+     * as a worklet — but the type narrows to the same shape RN's native
+     * `onScroll` prop expects so it composes cleanly.
+     */
+    onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+}
+/**
+ * Track the scroll offset of a `Motion.ScrollView` as shared values.
+ *
+ * ```tsx
+ * const { scrollY, onScroll } = useScroll()
+ * const headerOpacity = useTransform(scrollY, [0, 100], [1, 0])
+ *
+ * return (
+ *   <>
+ *     <Motion.View animate={{ opacity: headerOpacity }} />
+ *     <Motion.ScrollView onScroll={onScroll} scrollEventThrottle={16}>
+ *       …
+ *     </Motion.ScrollView>
+ *   </>
+ * )
+ * ```
+ *
+ * Scroll events fire on the UI thread, so `scrollX` / `scrollY` are safe to
+ * read from any worklet (`useAnimatedStyle`, `useDerivedValue`,
+ * `useTransform`) without a JS-thread bounce.
+ *
+ * Remember to set `scrollEventThrottle={16}` on the `ScrollView` for 60Hz
+ * updates — RN's default is to dispatch on every event, which on iOS still
+ * means one per frame, but Android benefits from the explicit cap.
+ */
+declare function useScroll(): UseScrollResult;
+
 /**
  * Build a controller for a variants map. The controller is the imperative
  * escape hatch — pass it to a Motion primitive via `controller={...}` and
@@ -181,4 +437,4 @@ declare function ensureWorkletEasing(easing: ((t: number) => number) | undefined
  */
 declare function useVariants<V extends Readonly<Record<string, object>>>(variants: V, initial?: keyof V & string): VariantController<keyof V & string>;
 
-export { AnimatableValue, Motion, MotionComponent, MotionConfig, type MotionConfigValue, Presence, type PresenceContextValue, type ReducedMotion, TransitionConfig, VariantController, createMotionComponent, ensureWorkletEasing, resolveAnimatableValue, resolveTransition, useMotionConfig, usePresence, useShouldReduceMotion, useVariants };
+export { AnimatableValue, type ExtrapolationMode, Motion, MotionComponent, MotionConfig, type MotionConfigValue, Presence, type PresenceContextValue, type ReducedMotion, SpringTransition, TransitionConfig, type UseGestureHandlers, type UseGestureResult, type UseScrollResult, type UseTransformOptions, VariantController, createMotionComponent, ensureWorkletEasing, resolveAnimatableValue, resolveTransition, useAnimation, useGesture, useMotionConfig, useMotionValue, usePresence, useScroll, useShouldReduceMotion, useSpring, useTransform, useVariants };