@rootnative/inertia 0.0.0-alpha.0

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 '@rootnative/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)
+}

package/src/values/useScroll.ts

@@ -0,0 +1,72 @@
+import {
+  useAnimatedScrollHandler,
+  useSharedValue,
+  type SharedValue,
+} from 'react-native-reanimated'
+import { type NativeScrollEvent, type NativeSyntheticEvent } from 'react-native'
+
+export 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.
+ */
+export function useScroll(): UseScrollResult {
+  const scrollX = useSharedValue(0)
+  const scrollY = useSharedValue(0)
+
+  const handler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      'worklet'
+      scrollX.value = event.contentOffset.x
+      scrollY.value = event.contentOffset.y
+    },
+  })
+
+  // `useAnimatedScrollHandler` returns an opaque worklet bag whose JS-side
+  // type is `(event) => void` but actually carries native event-handler
+  // wiring. Cast through `unknown` because the public RN `onScroll` type
+  // wants a `NativeSyntheticEvent`-taking function and Reanimated's handler
+  // is structurally compatible — the cast is to satisfy the consumer's
+  // prop type at the call site.
+  return {
+    scrollX,
+    scrollY,
+    onScroll: handler as unknown as (
+      event: NativeSyntheticEvent<NativeScrollEvent>,
+    ) => void,
+  }
+}

package/src/values/useShadow.ts

@@ -0,0 +1,116 @@
+import {
+  interpolate,
+  interpolateColor,
+  useAnimatedStyle,
+  type SharedValue,
+} from 'react-native-reanimated'
+
+/**
+ * Shape accepted on either end of a `useShadow` tween. Every field is
+ * optional — only keys present on at least one side participate in the
+ * output style. Mirrors the flat shadow keys on `Motion.View`'s `animate`
+ * surface, plus the nested `shadowOffset` source.
+ */
+export interface ShadowConfig {
+  shadowOpacity?: number
+  shadowRadius?: number
+  shadowOffset?: { width?: number; height?: number }
+  /** Android elevation. iOS shadow consumers can leave this off. */
+  elevation?: number
+  shadowColor?: string
+}
+
+export interface UseShadowOptions {
+  /** Shadow state at `progress === 0`. */
+  from: ShadowConfig
+  /** Shadow state at `progress === 1`. */
+  to: ShadowConfig
+  /**
+   * Driver — typically 0→1. Whatever produces it (a `useSpring`, a gesture
+   * progress value, a scroll-derived `useTransform`) is the caller's
+   * concern. The hook is a pure interpolator; it does not animate on its
+   * own. Values outside `[0, 1]` clamp.
+   */
+  progress: SharedValue<number>
+}
+
+/**
+ * Interpolate between two shadow configs as `progress` moves 0→1, returning
+ * an animated style fragment that can be spread onto any Reanimated-aware
+ * view (including `Motion.*` primitives and a hand-rolled `Animated.View`).
+ *
+ * ```tsx
+ * const progress = useSpring(isElevated ? 1 : 0)
+ * const shadowStyle = useShadow({
+ *   from: { shadowOpacity: 0.08, shadowRadius: 2, shadowOffset: { width: 0, height: 1 }, elevation: 1 },
+ *   to:   { shadowOpacity: 0.24, shadowRadius: 12, shadowOffset: { width: 0, height: 8 }, elevation: 8 },
+ *   progress,
+ * })
+ *
+ * return <Motion.View style={[styles.card, shadowStyle]} />
+ * ```
+ *
+ * Only keys present on either `from` or `to` are emitted. A key present on
+ * one side and absent on the other tweens from the present value to the
+ * absent side's natural zero (`0` for numbers, `'transparent'` for
+ * `shadowColor`, `{ width: 0, height: 0 }` for `shadowOffset`). This is a
+ * pure interpolator — to "animate" the shadow, drive `progress` with a
+ * spring, timing, or gesture upstream.
+ */
+export function useShadow({
+  from,
+  to,
+  progress,
+}: UseShadowOptions): ReturnType<typeof useAnimatedStyle> {
+  // Resolve presence + endpoints once on the JS thread so the worklet body
+  // consumes flat literals — consistent with the JS-thread resolver
+  // principle that keeps `Object.keys`-style walks off the UI thread.
+  const hasOpacity =
+    from.shadowOpacity !== undefined || to.shadowOpacity !== undefined
+  const hasRadius =
+    from.shadowRadius !== undefined || to.shadowRadius !== undefined
+  const hasElevation =
+    from.elevation !== undefined || to.elevation !== undefined
+  const hasColor =
+    from.shadowColor !== undefined || to.shadowColor !== undefined
+  const hasOffset =
+    from.shadowOffset !== undefined || to.shadowOffset !== undefined
+
+  const opacityFrom = from.shadowOpacity ?? 0
+  const opacityTo = to.shadowOpacity ?? 0
+  const radiusFrom = from.shadowRadius ?? 0
+  const radiusTo = to.shadowRadius ?? 0
+  const elevationFrom = from.elevation ?? 0
+  const elevationTo = to.elevation ?? 0
+  const colorFrom = from.shadowColor ?? 'transparent'
+  const colorTo = to.shadowColor ?? 'transparent'
+  const offsetWFrom = from.shadowOffset?.width ?? 0
+  const offsetWTo = to.shadowOffset?.width ?? 0
+  const offsetHFrom = from.shadowOffset?.height ?? 0
+  const offsetHTo = to.shadowOffset?.height ?? 0
+
+  return useAnimatedStyle(() => {
+    'worklet'
+    const t = progress.value
+    const out: Record<string, unknown> = {}
+    if (hasOpacity) {
+      out.shadowOpacity = interpolate(t, [0, 1], [opacityFrom, opacityTo])
+    }
+    if (hasRadius) {
+      out.shadowRadius = interpolate(t, [0, 1], [radiusFrom, radiusTo])
+    }
+    if (hasElevation) {
+      out.elevation = interpolate(t, [0, 1], [elevationFrom, elevationTo])
+    }
+    if (hasColor) {
+      out.shadowColor = interpolateColor(t, [0, 1], [colorFrom, colorTo])
+    }
+    if (hasOffset) {
+      out.shadowOffset = {
+        width: interpolate(t, [0, 1], [offsetWFrom, offsetWTo]),
+        height: interpolate(t, [0, 1], [offsetHFrom, offsetHTo]),
+      }
+    }
+    return out
+  })
+}

package/src/values/useSpring.ts

@@ -0,0 +1,98 @@
+import { useEffect, useMemo } from 'react'
+import {
+  useAnimatedReaction,
+  useSharedValue,
+  withSpring,
+  type SharedValue,
+} from 'react-native-reanimated'
+import { springToReanimated } from '../transitions/spring'
+import { type SpringTransition } from '../types'
+
+/**
+ * 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.
+ */
+export function useSpring(
+  target: number | SharedValue<number>,
+  config?: SpringTransition,
+): SharedValue<number> {
+  // Reanimated config is rebuilt only when the public config object changes
+  // shape. The worklet path reads this from JS-thread closure capture, which
+  // is fine: it's the resolved config that's invariant across UI-thread
+  // ticks, not a JS-thread reference that would go stale.
+  const reanimConfig = useMemo(
+    () => springToReanimated(config ?? {}),
+    // Keyed on the resolved primitive fields rather than the `config` object
+    // identity: callers routinely pass a fresh object literal each render, so
+    // depending on `config` itself would rebuild the Reanimated config on
+    // every render and defeat the memo.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      config?.tension,
+      config?.friction,
+      config?.mass,
+      config?.velocity,
+      config?.restSpeedThreshold,
+      config?.restDisplacementThreshold,
+    ],
+  )
+
+  const isSharedTarget = isSharedValue(target)
+  const initial = isSharedTarget ? target.value : (target as number)
+  const output = useSharedValue<number>(initial)
+
+  // Plain-number path. The reaction below is a no-op when `target` is a
+  // number, so this effect carries the change. Reading `target` directly in
+  // the dep array means React drives the schedule; we don't have to babysit
+  // a stale closure.
+  useEffect(() => {
+    if (isSharedTarget) return
+    output.value = withSpring(target as number, reanimConfig)
+    // `output` is identity-stable per hook instance (Reanimated guarantee).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isSharedTarget, target, reanimConfig])
+
+  // SharedValue path. `useAnimatedReaction` runs the prepare worklet whenever
+  // its returned value changes; we read `.value` off the target SV and pipe
+  // it through `withSpring` on the UI thread. When the target is a plain
+  // number we never declare a source so the reaction is inert (returns
+  // `null`, never fires `react`).
+  useAnimatedReaction(
+    () => {
+      'worklet'
+      if (!isSharedTarget) return null
+      return (target as SharedValue<number>).value
+    },
+    (next, prev) => {
+      'worklet'
+      if (next === null || next === prev) return
+      output.value = withSpring(next, reanimConfig)
+    },
+    [isSharedTarget, reanimConfig],
+  )
+
+  return output
+}
+
+function isSharedValue(v: unknown): v is SharedValue<number> {
+  // SharedValues are plain objects with a single `value` accessor — there is
+  // no public constructor or instanceof check. Reading `'value' in v` on any
+  // POJO would also pass, but the hook's call site already narrows the type;
+  // this guard exists to dispatch between the two implementation paths, not
+  // to validate untrusted input.
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    'value' in (v as Record<string, unknown>)
+  )
+}

package/src/values/useTransform.ts

@@ -0,0 +1,132 @@
+import {
+  Extrapolation,
+  interpolate,
+  interpolateColor,
+  useDerivedValue,
+  type SharedValue,
+} from 'react-native-reanimated'
+// `isWorkletFunction` was re-exported from `react-native-reanimated` historically
+// but is deprecated there in favor of importing from `react-native-worklets`.
+// `react-native-worklets` is a required peer of Reanimated 4, so the direct
+// import is always available wherever Inertia is.
+import { isWorkletFunction } from 'react-native-worklets'
+
+/**
+ * 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.
+ */
+export type ExtrapolationMode = 'clamp' | 'identity' | 'extend'
+
+export 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.
+ */
+export 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.
+ */
+export function useTransform(
+  value: SharedValue<number>,
+  inputRange: readonly number[],
+  outputRange: readonly number[],
+  options?: UseTransformOptions,
+): SharedValue<number>
+export function useTransform(
+  value: SharedValue<number>,
+  inputRange: readonly number[],
+  outputRange: readonly string[],
+  options?: UseTransformOptions,
+): SharedValue<string>
+
+export function useTransform<T>(
+  arg1: (() => T) | SharedValue<number>,
+  inputRange?: readonly number[],
+  outputRange?: readonly number[] | readonly string[],
+  options?: UseTransformOptions,
+): SharedValue<T> | SharedValue<number> | SharedValue<string> {
+  // Build the producer worklet on the JS thread, then call
+  // `useDerivedValue` exactly once. Keeping the hook call unconditional
+  // satisfies rules-of-hooks; per-call branching (transformer vs
+  // interpolation) is decided once at JS time, never at frame time.
+  let producer: () => unknown
+  if (typeof arg1 === 'function') {
+    // Transformer overload. The public surface accepts a plain function;
+    // Reanimated 3.9+ requires worklets in nested-derivation contexts, so
+    // we auto-wrap at JS time the same way `ensureWorkletEasing` does.
+    const userFn = arg1 as () => T
+    producer = isWorkletFunction(userFn)
+      ? userFn
+      : () => {
+          'worklet'
+          return userFn()
+        }
+  } else {
+    // Interpolation overload. We pre-resolve everything JS-side so the
+    // worklet body only consumes flat values.
+    const source = arg1
+    const input = inputRange as readonly number[]
+    const output = outputRange as readonly (number | string)[]
+    const isColor = output.length > 0 && typeof output[0] === 'string'
+    const extrapolateLeft = mapExtrapolation(options?.extrapolateLeft)
+    const extrapolateRight = mapExtrapolation(options?.extrapolateRight)
+    producer = isColor
+      ? () => {
+          'worklet'
+          return interpolateColor(
+            source.value,
+            input as number[],
+            output as string[],
+          )
+        }
+      : () => {
+          'worklet'
+          return interpolate(
+            source.value,
+            input as number[],
+            output as number[],
+            { extrapolateLeft, extrapolateRight },
+          )
+        }
+  }
+
+  return useDerivedValue(producer as () => never) as unknown as
+    | SharedValue<T>
+    | SharedValue<number>
+    | SharedValue<string>
+}
+
+function mapExtrapolation(mode: ExtrapolationMode | undefined): Extrapolation {
+  if (mode === 'identity') return Extrapolation.IDENTITY
+  if (mode === 'extend') return Extrapolation.EXTEND
+  return Extrapolation.CLAMP
+}

package/src/values/useVariants.ts

@@ -0,0 +1,60 @@
+import { useMemo, useRef } from 'react'
+import { type VariantController } from '../types'
+
+/**
+ * Build a controller for a variants map. The controller is the imperative
+ * escape hatch — pass it to a Motion primitive via `controller={...}` and
+ * call `controller.transitionTo('open')` from event handlers, async chains,
+ * etc. The hook name mirrors the prop name (`variants`) so the relationship
+ * is obvious.
+ *
+ * The controller is identity-stable across renders. State changes are
+ * delivered to subscribers via `subscribe` — Motion primitives subscribe
+ * internally and re-resolve `animate` on each transition.
+ */
+export function useVariants<V extends Readonly<Record<string, object>>>(
+  variants: V,
+  initial?: keyof V & string,
+): VariantController<keyof V & string> {
+  // Pin the variants object reference for the lifetime of the controller.
+  // Consumers shouldn't recreate the map on every render anyway, but if they
+  // do, the controller still works against the first definition's keys.
+  const variantsRef = useRef(variants)
+
+  return useMemo(() => {
+    const listeners = new Set<(next: keyof V & string) => void>()
+    let current =
+      initial ??
+      ((Object.keys(variantsRef.current)[0] ?? '') as keyof V & string)
+
+    const controller: VariantController<keyof V & string> = {
+      get current() {
+        return current
+      },
+      transitionTo(next) {
+        if (next === current) return
+        if (!(next in variantsRef.current)) {
+          if (__DEV__) {
+            console.warn(
+              `[inertia] useVariants: unknown variant "${String(next)}". Known keys: ${Object.keys(variantsRef.current).join(', ')}`,
+            )
+          }
+          return
+        }
+        current = next
+        for (const fn of listeners) fn(next)
+      },
+      subscribe(listener) {
+        listeners.add(listener)
+        return () => {
+          listeners.delete(listener)
+        }
+      },
+    }
+    return controller
+    // Identity-stable controller — only build once.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+}
+
+declare const __DEV__: boolean