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

package/src/motion/installCheck.ts

@@ -0,0 +1,69 @@
+declare const __DEV__: boolean
+declare const process: { env?: Record<string, string | undefined> }
+declare const require: (path: string) => unknown
+
+let alreadyChecked = false
+
+/**
+ * Surface a clear, actionable error at first `createMotionComponent` call when
+ * the consumer's Reanimated install is broken. Production builds, repeat calls,
+ * and Jest test runs are all skipped — the check is purely a dev-time
+ * paper-cut sander for the two failure modes we can detect from JS:
+ *
+ * 1. `react-native-reanimated` resolves but is on a v3.x line we don't
+ *    support (the plugin name and worklet runtime both changed at v4).
+ * 2. The worklets babel plugin (`react-native-worklets/plugin` in v4) isn't
+ *    wired into `babel.config.js`, so `'worklet'` directives are dead strings
+ *    and the first `withSpring` / `withTiming` call would crash on the UI
+ *    thread with a generic "non-worklet function called" error.
+ *
+ * The "Reanimated isn't installed at all" case isn't handled here — Metro
+ * fails to resolve the static `import 'react-native-reanimated'` at the top
+ * of `createMotionComponent.tsx` long before this check runs.
+ */
+export function ensureReanimatedInstalled(): void {
+  if (!__DEV__ || alreadyChecked) return
+  // The standard `react-native-reanimated/mock` doesn't run the worklets
+  // babel plugin, so the marker probe would false-positive every test run.
+  if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'test') {
+    return
+  }
+  alreadyChecked = true
+
+  let version: string | undefined
+  try {
+    const pkg = require('react-native-reanimated/package.json') as {
+      version?: string
+    }
+    version = pkg.version
+  } catch {
+    // package.json subpath blocked by `exports` field — skip the version
+    // probe rather than emit a misleading error.
+  }
+
+  if (version) {
+    const major = parseInt(version.split('.')[0] ?? '0', 10)
+    if (major < 4) {
+      console.error(
+        `[inertia] react-native-reanimated v${version} is installed, but @onlynative/inertia requires v4.0.0 or later. ` +
+          `Upgrade with \`pnpm add react-native-reanimated@^4\` (or your package manager's equivalent).`,
+      )
+      return
+    }
+  }
+
+  // The worklets plugin rewrites any function carrying a top-of-body
+  // `'worklet'` directive to expose a `__workletHash` property at runtime.
+  // Its absence means the plugin didn't run.
+  const probe = function probe() {
+    'worklet'
+    return 0
+  } as { __workletHash?: number }
+  if (typeof probe.__workletHash !== 'number') {
+    console.error(
+      `[inertia] The Reanimated worklets babel plugin is not configured. ` +
+        `Add \`'react-native-worklets/plugin'\` as the LAST entry in the \`plugins\` array of your \`babel.config.js\`, ` +
+        `then restart Metro with a fresh cache: \`npx expo start -c\` or \`npx react-native start --reset-cache\`.`,
+    )
+  }
+}

package/src/transitions/easing.ts

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

package/src/transitions/index.ts

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

package/src/transitions/keys.ts

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

package/src/transitions/resolve.ts

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

package/src/transitions/sig.ts

@@ -0,0 +1,40 @@
+/**
+ * Stable string signature for an arbitrary value — used as a dep-array
+ * member so a fresh object literal each render doesn't re-fire an effect
+ * unless something structurally changed. Functions serialize as `null`
+ * (their identity isn't useful in a sig); `undefined` collapses to an empty
+ * string so omitted props compare equal across renders.
+ */
+export function stableSig(value: unknown): string {
+  if (value === undefined) return ''
+  try {
+    return stableStringify(value)
+  } catch {
+    return String(value)
+  }
+}
+
+/**
+ * JSON.stringify with keys sorted at every level so a sig is invariant under
+ * property-declaration order. Functions and `undefined` both serialize as
+ * `null` — we accept the latter's information loss (rare in practice) in
+ * exchange for not crashing on circular function-bearing graphs.
+ */
+function stableStringify(v: unknown): string {
+  if (v === null || typeof v !== 'object') {
+    if (typeof v === 'function' || v === undefined) return 'null'
+    return JSON.stringify(v)
+  }
+  if (Array.isArray(v)) {
+    return '[' + v.map(stableStringify).join(',') + ']'
+  }
+  const obj = v as Record<string, unknown>
+  const keys = Object.keys(obj).sort()
+  return (
+    '{' +
+    keys
+      .map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k]))
+      .join(',') +
+    '}'
+  )
+}

package/src/transitions/spring.ts

@@ -0,0 +1,41 @@
+import { type SpringTransition } from '../types'
+
+/**
+ * Default spring physics, expressed in react-spring vocabulary.
+ *
+ * `tension: 170` / `friction: 26` / `mass: 1` was picked over Reanimated's
+ * raw `stiffness: 100` / `damping: 10` default because the raw default
+ * overshoots noticeably for the small (~100px) translates that dominate
+ * UI work — buttons, sheets, popovers. These numbers settle in ~350ms with
+ * a single, almost-imperceptible overshoot, which matches the perceptual
+ * target the rest of the library is tuned against.
+ */
+export const DEFAULT_SPRING: Required<
+  Pick<SpringTransition, 'tension' | 'friction' | 'mass'>
+> = {
+  tension: 170,
+  friction: 26,
+  mass: 1,
+}
+
+/**
+ * Convert public react-spring vocabulary (`tension` / `friction` / `mass`)
+ * to Reanimated's raw `stiffness` / `damping` / `mass`. This is the single
+ * place the mapping lives; resolvers, value hooks, and any future surface
+ * that needs a Reanimated spring config import from here.
+ *
+ * The mapping is identity (tension ≡ stiffness, friction ≡ damping) — the
+ * names differ but the underlying physics constants are the same. We don't
+ * surface the raw names publicly because the react-spring vocabulary is
+ * what designers and prior-art consumers expect.
+ */
+export function springToReanimated(t: SpringTransition) {
+  return {
+    stiffness: t.tension ?? DEFAULT_SPRING.tension,
+    damping: t.friction ?? DEFAULT_SPRING.friction,
+    mass: t.mass ?? DEFAULT_SPRING.mass,
+    velocity: t.velocity,
+    restSpeedThreshold: t.restSpeedThreshold,
+    restDisplacementThreshold: t.restDisplacementThreshold,
+  }
+}

package/src/types.ts

@@ -75,15 +75,63 @@ export type PerPropertyTransition<S> = {
   [K in keyof S]?: TransitionConfig
 }
 
-export 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.
+ */
+export interface GestureLayerTransitions {
+  pressed?: TransitionConfig
+  focused?: TransitionConfig
+  focusVisible?: TransitionConfig
+  hovered?: TransitionConfig
+}
+
+export 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.
  */
-export type AnimateStyle<C> = C extends { style?: StyleProp<infer S> }
-  ? { [K in keyof S]?: AnimatableValue<S[K]> }
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type _StyleValue<T> = Exclude<T, (...args: any[]) => any>
+
+export type AnimateStyle<C> = C extends { style?: infer Raw }
+  ? _StyleValue<Raw> extends StyleProp<infer S>
+    ? { [K in keyof S]?: AnimatableValue<S[K]> } & AnimatableTransformExtras
+    : never
   : never
 
 export interface AnimationCallbackInfo<S> {
@@ -124,18 +172,26 @@ export 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
+ *
+ *   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
  *
- * 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.
+ * (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.
  */
 export interface GestureSubStates<C> {
   pressed?: AnimateStyle<C>
@@ -193,10 +249,11 @@ export 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>
   /**
@@ -204,6 +261,26 @@ export 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.
@@ -216,6 +293,7 @@ export interface MotionProps<C> {
  * underlying component's props (minus `style`, which we replace with an
  * animated style) with the Motion-specific props above.
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type MotionComponent<C extends ComponentType<any>> = ComponentType<
   Omit<React.ComponentProps<C>, 'style'> &
     MotionProps<React.ComponentProps<C>> & {

package/src/values/index.ts

@@ -1 +1,15 @@
+export { useAnimation } from './useAnimation'
+export {
+  useGesture,
+  type UseGestureHandlers,
+  type UseGestureResult,
+} from './useGesture'
+export { useMotionValue } from './useMotionValue'
+export { useSpring } from './useSpring'
+export {
+  useTransform,
+  type ExtrapolationMode,
+  type UseTransformOptions,
+} from './useTransform'
+export { useScroll, type UseScrollResult } from './useScroll'
 export { useVariants } from './useVariants'

package/src/values/useAnimation.ts

@@ -0,0 +1,69 @@
+import { useEffect } from 'react'
+import { useSharedValue, type SharedValue } from 'react-native-reanimated'
+import { useShouldReduceMotion } from '../config'
+import { resolveTransition, stableSig } from '../transitions'
+import { type TransitionConfig } from '../types'
+
+/**
+ * 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 },
+ * })
+ * ```
+ */
+export function useAnimation(
+  target: number,
+  transition?: TransitionConfig,
+): SharedValue<number> {
+  const output = useSharedValue<number>(target)
+  const shouldReduceMotion = useShouldReduceMotion()
+  const cfgSig = stableSig(transition)
+
+  useEffect(() => {
+    const cfg = shouldReduceMotion
+      ? ({ type: 'no-animation' } as const)
+      : (transition ?? ({ type: 'spring' } as const))
+    output.value = resolveTransition(cfg, target) as never
+    // `output` is identity-stable per hook instance.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [target, cfgSig, shouldReduceMotion])
+
+  return output
+}

package/src/values/useGesture.ts

@@ -0,0 +1,144 @@
+import { useCallback, useMemo } from 'react'
+import { useSharedValue, type SharedValue } from 'react-native-reanimated'
+import { useShouldReduceMotion } from '../config'
+import { isFocusVisible } from '../gestures'
+import { isTopLevelTransition, resolveTransition } from '../transitions'
+import { type GestureLayerTransitions, type TransitionConfig } from '../types'
+
+type LayerName = 'pressed' | 'focused' | 'focusVisible' | 'hovered'
+
+/**
+ * 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.
+ */
+export interface UseGestureHandlers {
+  onPressIn: () => void
+  onPressOut: () => void
+  onHoverIn: () => void
+  onHoverOut: () => void
+  onFocus: () => void
+  onBlur: () => void
+}
+
+export 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>
+ *   )
+ * }
+ * ```
+ */
+export function useGesture(
+  transition?: TransitionConfig | GestureLayerTransitions,
+): UseGestureResult {
+  const pressed = useSharedValue(0)
+  const focused = useSharedValue(0)
+  const focusVisible = useSharedValue(0)
+  const hovered = useSharedValue(0)
+  const shouldReduceMotion = useShouldReduceMotion()
+
+  const setLayer = useCallback(
+    (sv: SharedValue<number>, layer: LayerName, target: 0 | 1) => {
+      const cfg = shouldReduceMotion
+        ? ({ type: 'no-animation' } as const)
+        : (layerTransition(layer, transition) ?? ({ type: 'spring' } as const))
+      sv.value = resolveTransition(cfg, target) as never
+    },
+    // The transition is intentionally read on every call rather than cooked
+    // into the dep array — a fresh literal each render would otherwise
+    // rebuild the handler bag and break composing consumers that key off
+    // handler identity. `transition` is read inside the callback closure;
+    // shared values are stable so the only dep that matters is the reduce-
+    // motion flag.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [shouldReduceMotion],
+  )
+
+  const handlers = useMemo<UseGestureHandlers>(
+    () => ({
+      onPressIn: () => setLayer(pressed, 'pressed', 1),
+      onPressOut: () => setLayer(pressed, 'pressed', 0),
+      onHoverIn: () => setLayer(hovered, 'hovered', 1),
+      onHoverOut: () => setLayer(hovered, 'hovered', 0),
+      onFocus: () => {
+        setLayer(focused, 'focused', 1)
+        if (isFocusVisible()) setLayer(focusVisible, 'focusVisible', 1)
+      },
+      onBlur: () => {
+        setLayer(focused, 'focused', 0)
+        setLayer(focusVisible, 'focusVisible', 0)
+      },
+    }),
+    [setLayer, pressed, focused, focusVisible, hovered],
+  )
+
+  return { pressed, focused, focusVisible, hovered, handlers }
+}
+
+function layerTransition(
+  layer: LayerName,
+  transition: TransitionConfig | GestureLayerTransitions | undefined,
+): TransitionConfig | undefined {
+  if (!transition) return undefined
+  if (isTopLevelTransition(transition)) return transition
+  return (transition as GestureLayerTransitions)[layer]
+}

package/src/values/useMotionValue.ts

@@ -0,0 +1,33 @@
+import { useSharedValue, type SharedValue } from 'react-native-reanimated'
+
+/**
+ * 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 }}
+ * ```
+ */
+export function useMotionValue<T extends number | string>(
+  initial: T,
+): SharedValue<T> {
+  return useSharedValue<T>(initial)
+}