@onlynative/inertia 0.0.1-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to `@onlynative/inertia` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Pre-`1.0`, breaking changes may land in minor versions and are called out under their release.
+
+## [Unreleased]
+
+## [0.0.1-alpha.0] — 2026-05-07
+
+Initial alpha publish. The full v0.1 surface is in place; APIs are still subject to change before `0.1.0`.
+
+### Added
+
+- **Primitives** — `Motion.View`, `Motion.Text`, `Motion.Image`, `Motion.Pressable`, `Motion.ScrollView` with per-primitive style inference (no shared `ViewStyle & TextStyle & ImageStyle` fallback).
+- **Subpath imports** — `@onlynative/inertia/view`, `/text`, `/image`, `/pressable`, `/scroll-view` for per-primitive tree-shaking. Bundle-size baselines recorded via `size-limit`.
+- **Transitions** — `spring` (default, react-spring vocabulary `tension`/`friction`/`mass`/`velocity`), `timing` (with auto-worklet-wrapped easing functions), `decay`, `no-animation`. Per-property `transition` shape takes precedence over top-level.
+- **Sequences and keyframes** — `animate={{ x: [0, 100, 0] }}` and `[{ to, ...override }]` step shape with per-step transition overrides.
+- **Repeat config** — unified `repeat: number | 'infinite' | { count, alternate }` shape; `alternate` defaults to `true`.
+- **Variants** — `variants={{ open, closed }}` + `animate="open"` props; `useVariants` hook returning `{ current, transitionTo, subscribe }` for programmatic flows; `controller` prop wires the hook back to the component.
+- **Gestures** — single `gesture` prop on every primitive: `pressed`, `focused`, `hovered` (web) sub-states. Pressable-based, zero overhead when omitted.
+- **`<Presence>`** — mount/unmount transitions on top of Reanimated's `entering` / `exiting`. Exiting children automatically receive `pointerEvents: 'none'`.
+- **`<MotionConfig reducedMotion>`** — `'user' | 'never' | 'always'` provider with `'user'` as the default. `useMotionConfig` and `useShouldReduceMotion` exposed for custom integrations.
+- **`onAnimationEnd`** — `{ key, finished, value, target, phase, step, iteration }` payload. Transform-group keys (`translateX`/`translateY`, `scaleX`/`scaleY`) coalesce so a single `translate` step fires once, not once per axis.
+- **Stable worklets, JS-thread resolver** — animate/transition objects compile to baked `withSpring` / `withTiming` / `withDecay` calls on the JS thread. Worklet bodies never iterate `Object.keys(...)` at frame time, and re-renders with unchanged values produce zero new UI-thread closures (regression-tested).
+- **`createMotionComponent<C>()`** — public factory for custom primitives, with style inference from `C`'s `style` prop.
+- **Docs** — Docusaurus site at `onlynative.github.io/inertia`; `llms.txt` and `llms-full.txt` shipped both on the docs site and in the npm tarball.
+
+### Known limitations
+
+- SVG path morphing, gradient interpolation, and shared-element transitions across screens are out of scope until `0.2.x` / `1.x` per the roadmap.
+- `react-native-gesture-handler` integration (drag, pan, swipe sub-states) lands in `0.2` via the optional `@onlynative/inertia-gestures` adapter.
+
+[unreleased]: https://github.com/onlynative/inertia/compare/v0.0.1-alpha.0...HEAD
+[0.0.1-alpha.0]: https://github.com/onlynative/inertia/releases/tag/v0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OnlyNative
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @onlynative/inertia
+
+[![npm](https://img.shields.io/npm/v/@onlynative/inertia.svg)](https://www.npmjs.com/package/@onlynative/inertia)
+[![Reanimated 4](https://img.shields.io/badge/reanimated-4.x-B57EDC)](https://docs.swmansion.com/react-native-reanimated/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Declarative animation primitives for React Native, built as a thin wrapper around [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). Inspired by Framer Motion (web) and react-spring (cross-platform).
+
+> **Status:** `0.0.1-alpha`. Pre-1.0 minor versions may break — see the root [README](https://github.com/onlynative/inertia#versioning--release).
+
+## Install
+
+```sh
+pnpm add @onlynative/inertia react-native-reanimated
+```
+
+Then enable the [Reanimated Babel plugin](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/installation).
+
+**Peer dependencies:** `react >=19.0.0`, `react-native >=0.81.0`, `react-native-reanimated >=4.0.0`.
+
+## Quick start
+
+```tsx
+import { Motion, Presence } from '@onlynative/inertia'
+
+export function FadeIn() {
+  return (
+    <Motion.View
+      initial={{ opacity: 0, translateY: 20 }}
+      animate={{ opacity: 1, translateY: 0 }}
+      transition={{
+        opacity: { type: 'timing', duration: 200 },
+        translateY: { type: 'spring', tension: 180, friction: 12 },
+      }}
+    />
+  )
+}
+```
+
+## What ships
+
+- **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, hovered }}`. 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'`).
+- **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.
+
+## Subpath imports
+
+```ts
+import { MotionView } from '@onlynative/inertia/view'
+import { MotionText } from '@onlynative/inertia/text'
+import { MotionImage } from '@onlynative/inertia/image'
+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).
+
+## Transitions
+
+| `type`               | Public config keys                                                                           | Maps to                            |
+| -------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
+| `'spring'` (default) | `tension`, `friction`, `mass`, `velocity`, `restSpeedThreshold`, `restDisplacementThreshold` | `withSpring`                       |
+| `'timing'`           | `duration`, `easing`, `delay`                                                                | `withTiming`                       |
+| `'decay'`            | `velocity`, `deceleration`, `clamp`                                                          | `withDecay`                        |
+| `'no-animation'`     | —                                                                                            | direct assignment, no interpolation |
+
+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.
+
+## Animatable properties
+
+`opacity`, `translateX`, `translateY`, `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`, `rotateY`, `backgroundColor`, `borderRadius`, `width`, `height`. Layout transforms via `transform: [...]`. Color interpolation uses Reanimated's color utilities.
+
+Out of scope for `0.x`: SVG path morphing, gradient interpolation, shared-element transitions across screens.
+
+## Documentation
+
+Full docs, every primitive's example screen, and an `llms-full.txt` reference live at:
+
+- [https://onlynative.github.io/inertia/](https://onlynative.github.io/inertia/)
+- [llms.txt](https://onlynative.github.io/inertia/llms.txt) — concise overview
+- [llms-full.txt](https://onlynative.github.io/inertia/llms-full.txt) — full API reference
+
+## License
+
+[MIT](./LICENSE) © OnlyNative

package/dist/index.d.mts

@@ -0,0 +1,185 @@
+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-CmbXx-G3.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-CmbXx-G3.mjs';
+export { MotionImage } from './motion/Image.mjs';
+export { MotionPressable } from './motion/Pressable.mjs';
+export { MotionScrollView } from './motion/ScrollView.mjs';
+export { MotionText } from './motion/Text.mjs';
+export { MotionView } from './motion/View.mjs';
+
+/**
+ * Factory that wraps a React Native primitive as a `Motion.*` component.
+ *
+ * The generic `C` flows through `MotionProps`, so `animate` / `initial` /
+ * `exit` / `transition` all infer from `C`'s `style` prop. There is no
+ * shared `ViewStyle & TextStyle & ImageStyle` fallback.
+ *
+ * Alpha scope: numeric properties listed in `ALL_KEYS`, applied via
+ * Reanimated shared values + `useAnimatedStyle`. Sequences, variants,
+ * gestures, color animation, and the cross-render memoization optimization
+ * land in later phases.
+ */
+declare function createMotionComponent<C extends ComponentType<any>>(Component: C): MotionComponent<C>;
+
+/**
+ * The `Motion.*` namespace. Each property is a primitive with its style prop
+ * inferred from the underlying RN component. There is no shared style fallback.
+ */
+declare const Motion: {
+    readonly View: MotionComponent<typeof react_native.View>;
+    readonly Text: MotionComponent<typeof react_native.Text>;
+    readonly Image: MotionComponent<typeof react_native.Image>;
+    readonly Pressable: MotionComponent<react.ForwardRefExoticComponent<react_native.PressableProps & react.RefAttributes<react_native.View>>>;
+    readonly ScrollView: MotionComponent<typeof react_native.ScrollView>;
+};
+
+/**
+ * How descendant Motion primitives should treat reduced-motion preferences.
+ *
+ * - `'user'` (default): defer to the OS accessibility setting via
+ *   Reanimated's `useReducedMotion()`. This is the only value that respects
+ *   user choice and is the right default for app-level wrappers.
+ * - `'never'`: animate regardless of OS setting. Use sparingly — e.g. for
+ *   onboarding transitions you've decided are essential.
+ * - `'always'`: never animate, regardless of OS setting. Useful for tests
+ *   and snapshots.
+ */
+type ReducedMotion = 'user' | 'never' | 'always';
+interface MotionConfigValue {
+    reducedMotion: ReducedMotion;
+}
+/**
+ * Read the active `<MotionConfig>` from a descendant. Returns the default
+ * (`'user'`) when no provider is present.
+ */
+declare function useMotionConfig(): MotionConfigValue;
+/**
+ * Resolve the active reduced-motion mode to a boolean. `'user'` consults
+ * Reanimated's OS-backed hook; `'always'` / `'never'` shortcut. Motion
+ * primitives call this to decide whether to swap transitions for
+ * `no-animation`.
+ */
+declare function useShouldReduceMotion(): boolean;
+
+/**
+ * Provider that controls how descendant Motion primitives respond to
+ * reduced-motion preferences. Wrap the root of your app once with the
+ * default (`reducedMotion="user"`) to respect the OS accessibility setting,
+ * or scope a subtree with `'always'` / `'never'` for specific use cases.
+ */
+declare function MotionConfig({ reducedMotion, children, }: {
+    reducedMotion?: ReducedMotion;
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * Wrap a list of children with mount / unmount transitions. When a child is
+ * removed from the incoming list it stays in the snapshot until its exit
+ * animation completes; descendants consume the per-child `<PresenceContext>`
+ * to coordinate.
+ *
+ * Children must be `<Motion.*>` primitives (or any component that consumes
+ * `usePresence()` and calls `safeToRemove`). Plain elements without that
+ * contract will linger in the snapshot once removed; document that and pick
+ * the right primitive.
+ *
+ * Children also need explicit `key`s so removal is detectable across
+ * renders. Without a key, React falls back to positional identity and
+ * removal looks like a prop change — Presence has nothing to mark exiting.
+ */
+declare function Presence({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * Per-child contract between `<Presence>` and its descendant Motion
+ * primitives. `<Presence>` provides a fresh value to each rendered child;
+ * Motion primitives consume it to gate exit animations.
+ *
+ * - `isPresent`: `true` while the child is in the incoming children list.
+ *   Flips to `false` when the parent removes it; the child remains rendered
+ *   until `safeToRemove` is called.
+ * - `safeToRemove`: callback the child invokes when its exit animation has
+ *   settled. `<Presence>` then drops the snapshot entry and unmounts.
+ */
+interface PresenceContextValue {
+    isPresent: boolean;
+    safeToRemove: () => void;
+}
+/**
+ * Read the surrounding `<Presence>` contract from a child component. Returns
+ * `null` when there is no `<Presence>` ancestor — useful for components that
+ * want to support both standalone and Presence-wrapped use without branching.
+ */
+declare function usePresence(): PresenceContextValue | null;
+
+/**
+ * UI-thread callback Reanimated invokes when an animation settles. Must be a
+ * worklet — callers either author one with `'worklet'` or build one via
+ * `runOnJS(...)` to bridge to JS-thread code.
+ */
+type AnimationCallback = (finished?: boolean, current?: number | string) => void;
+/**
+ * Per-step callback factory. Resolvers call this with the step's phase and
+ * sequence index (or `undefined` for non-sequence animations) and attach the
+ * resulting callback to the underlying `withSpring` / `withTiming` /
+ * `withDecay` call.
+ */
+type CallbackFactory = (phase: 'step' | 'animation', step: number | undefined) => AnimationCallback | undefined;
+/**
+ * Build a Reanimated animation for a single property. Runs on the JS thread
+ * once per change and produces a baked `withSpring` / `withTiming` /
+ * `withDecay` (optionally wrapped in `withDelay` / `withRepeat`) call. The
+ * worklet body only consumes the result.
+ *
+ * `callback`, when provided, fires once when the underlying single-shot
+ * animation settles. Repeat-wrapped animations forward the callback to
+ * `withRepeat`, so it fires once per iteration as Reanimated does.
+ */
+declare function resolveTransition(config: TransitionConfig | undefined, toValue: number | string, callback?: AnimationCallback): unknown;
+/**
+ * Resolve a per-property `animate` value into a Reanimated animation.
+ *
+ * Handles the three shapes of `AnimatableValue`:
+ *   1. plain value      → single `resolveTransition` call
+ *   2. `{ to, ...over }` → single step with the override merged into `base`
+ *   3. array of either   → `withSequence` of resolved steps, with the
+ *      top-level `repeat` applied at the **sequence level** (not per step).
+ *      Per-step `repeat` overrides remain step-local.
+ */
+declare function resolveAnimatableValue<V extends number | string>(value: AnimatableValue<V>, base: TransitionConfig | undefined, factory?: CallbackFactory): unknown;
+
+/**
+ * Reanimated 3.9+ validates that easing functions used in nested-transition
+ * contexts (variants, sequences, per-property maps) are worklets, and crashes
+ * with `[Reanimated] The easing function is not a worklet` otherwise. The
+ * library accepts plain functions on the public surface; this helper wraps
+ * them so consumers don't have to think about the worklet boundary.
+ *
+ * If the input is already a worklet (has been processed by the worklets babel
+ * plugin), it's returned as-is. Otherwise it's wrapped in a function whose
+ * body declares the `'worklet'` directive — when our source is processed by
+ * the consumer's worklets babel plugin (the default Expo/RN setup), the
+ * wrapper becomes a real worklet that captures the user fn via closure.
+ *
+ * The user fn must be pure: no JS-thread captured refs, no shared mutable
+ * state, no calls to non-worklet APIs.
+ */
+declare function ensureWorkletEasing(easing: ((t: number) => number) | undefined): ((t: number) => number) | undefined;
+
+/**
+ * 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.
+ */
+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 };

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+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-CmbXx-G3.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-CmbXx-G3.js';
+export { MotionImage } from './motion/Image.js';
+export { MotionPressable } from './motion/Pressable.js';
+export { MotionScrollView } from './motion/ScrollView.js';
+export { MotionText } from './motion/Text.js';
+export { MotionView } from './motion/View.js';
+
+/**
+ * Factory that wraps a React Native primitive as a `Motion.*` component.
+ *
+ * The generic `C` flows through `MotionProps`, so `animate` / `initial` /
+ * `exit` / `transition` all infer from `C`'s `style` prop. There is no
+ * shared `ViewStyle & TextStyle & ImageStyle` fallback.
+ *
+ * Alpha scope: numeric properties listed in `ALL_KEYS`, applied via
+ * Reanimated shared values + `useAnimatedStyle`. Sequences, variants,
+ * gestures, color animation, and the cross-render memoization optimization
+ * land in later phases.
+ */
+declare function createMotionComponent<C extends ComponentType<any>>(Component: C): MotionComponent<C>;
+
+/**
+ * The `Motion.*` namespace. Each property is a primitive with its style prop
+ * inferred from the underlying RN component. There is no shared style fallback.
+ */
+declare const Motion: {
+    readonly View: MotionComponent<typeof react_native.View>;
+    readonly Text: MotionComponent<typeof react_native.Text>;
+    readonly Image: MotionComponent<typeof react_native.Image>;
+    readonly Pressable: MotionComponent<react.ForwardRefExoticComponent<react_native.PressableProps & react.RefAttributes<react_native.View>>>;
+    readonly ScrollView: MotionComponent<typeof react_native.ScrollView>;
+};
+
+/**
+ * How descendant Motion primitives should treat reduced-motion preferences.
+ *
+ * - `'user'` (default): defer to the OS accessibility setting via
+ *   Reanimated's `useReducedMotion()`. This is the only value that respects
+ *   user choice and is the right default for app-level wrappers.
+ * - `'never'`: animate regardless of OS setting. Use sparingly — e.g. for
+ *   onboarding transitions you've decided are essential.
+ * - `'always'`: never animate, regardless of OS setting. Useful for tests
+ *   and snapshots.
+ */
+type ReducedMotion = 'user' | 'never' | 'always';
+interface MotionConfigValue {
+    reducedMotion: ReducedMotion;
+}
+/**
+ * Read the active `<MotionConfig>` from a descendant. Returns the default
+ * (`'user'`) when no provider is present.
+ */
+declare function useMotionConfig(): MotionConfigValue;
+/**
+ * Resolve the active reduced-motion mode to a boolean. `'user'` consults
+ * Reanimated's OS-backed hook; `'always'` / `'never'` shortcut. Motion
+ * primitives call this to decide whether to swap transitions for
+ * `no-animation`.
+ */
+declare function useShouldReduceMotion(): boolean;
+
+/**
+ * Provider that controls how descendant Motion primitives respond to
+ * reduced-motion preferences. Wrap the root of your app once with the
+ * default (`reducedMotion="user"`) to respect the OS accessibility setting,
+ * or scope a subtree with `'always'` / `'never'` for specific use cases.
+ */
+declare function MotionConfig({ reducedMotion, children, }: {
+    reducedMotion?: ReducedMotion;
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * Wrap a list of children with mount / unmount transitions. When a child is
+ * removed from the incoming list it stays in the snapshot until its exit
+ * animation completes; descendants consume the per-child `<PresenceContext>`
+ * to coordinate.
+ *
+ * Children must be `<Motion.*>` primitives (or any component that consumes
+ * `usePresence()` and calls `safeToRemove`). Plain elements without that
+ * contract will linger in the snapshot once removed; document that and pick
+ * the right primitive.
+ *
+ * Children also need explicit `key`s so removal is detectable across
+ * renders. Without a key, React falls back to positional identity and
+ * removal looks like a prop change — Presence has nothing to mark exiting.
+ */
+declare function Presence({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * Per-child contract between `<Presence>` and its descendant Motion
+ * primitives. `<Presence>` provides a fresh value to each rendered child;
+ * Motion primitives consume it to gate exit animations.
+ *
+ * - `isPresent`: `true` while the child is in the incoming children list.
+ *   Flips to `false` when the parent removes it; the child remains rendered
+ *   until `safeToRemove` is called.
+ * - `safeToRemove`: callback the child invokes when its exit animation has
+ *   settled. `<Presence>` then drops the snapshot entry and unmounts.
+ */
+interface PresenceContextValue {
+    isPresent: boolean;
+    safeToRemove: () => void;
+}
+/**
+ * Read the surrounding `<Presence>` contract from a child component. Returns
+ * `null` when there is no `<Presence>` ancestor — useful for components that
+ * want to support both standalone and Presence-wrapped use without branching.
+ */
+declare function usePresence(): PresenceContextValue | null;
+
+/**
+ * UI-thread callback Reanimated invokes when an animation settles. Must be a
+ * worklet — callers either author one with `'worklet'` or build one via
+ * `runOnJS(...)` to bridge to JS-thread code.
+ */
+type AnimationCallback = (finished?: boolean, current?: number | string) => void;
+/**
+ * Per-step callback factory. Resolvers call this with the step's phase and
+ * sequence index (or `undefined` for non-sequence animations) and attach the
+ * resulting callback to the underlying `withSpring` / `withTiming` /
+ * `withDecay` call.
+ */
+type CallbackFactory = (phase: 'step' | 'animation', step: number | undefined) => AnimationCallback | undefined;
+/**
+ * Build a Reanimated animation for a single property. Runs on the JS thread
+ * once per change and produces a baked `withSpring` / `withTiming` /
+ * `withDecay` (optionally wrapped in `withDelay` / `withRepeat`) call. The
+ * worklet body only consumes the result.
+ *
+ * `callback`, when provided, fires once when the underlying single-shot
+ * animation settles. Repeat-wrapped animations forward the callback to
+ * `withRepeat`, so it fires once per iteration as Reanimated does.
+ */
+declare function resolveTransition(config: TransitionConfig | undefined, toValue: number | string, callback?: AnimationCallback): unknown;
+/**
+ * Resolve a per-property `animate` value into a Reanimated animation.
+ *
+ * Handles the three shapes of `AnimatableValue`:
+ *   1. plain value      → single `resolveTransition` call
+ *   2. `{ to, ...over }` → single step with the override merged into `base`
+ *   3. array of either   → `withSequence` of resolved steps, with the
+ *      top-level `repeat` applied at the **sequence level** (not per step).
+ *      Per-step `repeat` overrides remain step-local.
+ */
+declare function resolveAnimatableValue<V extends number | string>(value: AnimatableValue<V>, base: TransitionConfig | undefined, factory?: CallbackFactory): unknown;
+
+/**
+ * Reanimated 3.9+ validates that easing functions used in nested-transition
+ * contexts (variants, sequences, per-property maps) are worklets, and crashes
+ * with `[Reanimated] The easing function is not a worklet` otherwise. The
+ * library accepts plain functions on the public surface; this helper wraps
+ * them so consumers don't have to think about the worklet boundary.
+ *
+ * If the input is already a worklet (has been processed by the worklets babel
+ * plugin), it's returned as-is. Otherwise it's wrapped in a function whose
+ * body declares the `'worklet'` directive — when our source is processed by
+ * the consumer's worklets babel plugin (the default Expo/RN setup), the
+ * wrapper becomes a real worklet that captures the user fn via closure.
+ *
+ * The user fn must be pure: no JS-thread captured refs, no shared mutable
+ * state, no calls to non-worklet APIs.
+ */
+declare function ensureWorkletEasing(easing: ((t: number) => number) | undefined): ((t: number) => number) | undefined;
+
+/**
+ * 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.
+ */
+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 };