@rootnative/inertia 0.0.0-alpha.0

package/jest-setup.js

@@ -0,0 +1,213 @@
+// Inertia's Jest setup. Loaded automatically by `@rootnative/inertia/jest-preset`,
+// or addable to a hand-rolled config via `setupFiles`.
+//
+// The mocks here cover everything the core, gestures, gradients, and svg
+// packages exercise. Re-create this list locally only if you can't use the
+// preset (e.g. you have a custom transform pipeline that conflicts).
+
+// `react-native-worklets` is a required peer of Reanimated 4 and ships its
+// own native module. The source files import `isWorkletFunction` from it
+// directly (Reanimated's re-export is deprecated); under Jest we stub the
+// surface so the source guard works the same way the Reanimated mock does.
+jest.mock('react-native-worklets', () => ({
+  __esModule: true,
+  isWorkletFunction: () => false,
+}))
+
+// Override RN's Text mock — the default mockComponent crashes on arrow function
+// components exported by RN 0.81's Flow `component` syntax.
+jest.mock('react-native/Libraries/Text/Text', () => {
+  const React = require('react')
+  const Text = React.forwardRef(({ children, ...props }, ref) =>
+    React.createElement('RCTText', { ...props, ref }, children),
+  )
+  Text.displayName = 'Text'
+  return { __esModule: true, default: Text }
+})
+
+// Reanimated mock — STATIC RENDER, with stable `useSharedValue` semantics.
+//
+// `useAnimatedStyle` invokes the worklet exactly once per render and returns
+// a plain object. It does not subscribe to shared-value mutations — to
+// observe a post-mount target value you must trigger a re-render (the
+// `renderWithMotion` / `flushMotion` helpers in `@rootnative/inertia/testing`
+// do this for you).
+//
+// `useSharedValue` is backed by `useRef` so the same `{ value }` object
+// persists across renders. After a `useEffect` assigns the target, the next
+// render reads it back.
+//
+// What this means for tests:
+//   ✅ assert at-rest structure / role / accessibility / static styles
+//   ✅ assert post-effect target styles by re-rendering (use
+//      `renderWithMotion` from the testing subpath)
+//   ❌ frame-level intermediate states are not observable — physics doesn't
+//      run; targets snap in one step.
+jest.mock('react-native-reanimated', () => {
+  const React = require('react')
+  const { Image, ScrollView, Text, View } = require('react-native')
+
+  const wrap = (Component, displayName) => {
+    const Wrapped = React.forwardRef((props, ref) =>
+      React.createElement(Component, { ...props, ref }),
+    )
+    Wrapped.displayName = displayName
+    return Wrapped
+  }
+
+  const AnimatedView = wrap(View, 'Animated.View')
+  const AnimatedText = wrap(Text, 'Animated.Text')
+  const AnimatedImage = wrap(Image, 'Animated.Image')
+  const AnimatedScrollView = wrap(ScrollView, 'Animated.ScrollView')
+
+  return {
+    __esModule: true,
+    default: {
+      View: AnimatedView,
+      Text: AnimatedText,
+      Image: AnimatedImage,
+      ScrollView: AnimatedScrollView,
+      createAnimatedComponent: (c) =>
+        wrap(c, `Animated(${c.displayName ?? c.name ?? 'Component'})`),
+    },
+    View: AnimatedView,
+    Text: AnimatedText,
+    Image: AnimatedImage,
+    ScrollView: AnimatedScrollView,
+    useSharedValue: (initial) => {
+      const ref = React.useRef(null)
+      if (ref.current === null) ref.current = { value: initial }
+      return ref.current
+    },
+    useDerivedValue: (fn) => ({ value: fn() }),
+    useAnimatedStyle: (fn) => fn(),
+    useAnimatedProps: (fn) => fn(),
+    useAnimatedReaction: (prepare, react) => {
+      // Best-effort sync invocation: run prepare() once, hand the result to
+      // react() so tests can observe the side effect (e.g. `useSpring`
+      // forwarding a target into its output shared value). Physics still
+      // doesn't run — `withSpring` is the identity in this mock.
+      const value = typeof prepare === 'function' ? prepare() : undefined
+      if (typeof react === 'function') react(value, undefined)
+    },
+    useAnimatedScrollHandler: (handlers) => {
+      // The real handler is an opaque worklet bag; in tests we return a plain
+      // function that invokes the appropriate user handler synchronously so
+      // assertions on scroll-driven shared values work without a native event
+      // loop. Shape: `useAnimatedScrollHandler({ onScroll })` or
+      // `useAnimatedScrollHandler(onScroll)`.
+      const onScroll =
+        typeof handlers === 'function' ? handlers : handlers?.onScroll
+      return (event) => {
+        if (typeof onScroll === 'function')
+          onScroll(event?.nativeEvent ?? event)
+      }
+    },
+    useReducedMotion: () => false,
+    // Inertia's dev-time install check reads this to detect a too-old
+    // Reanimated. The check is skipped under NODE_ENV=test, but the named
+    // import must still resolve for consumers' test suites.
+    reanimatedVersion: '4.0.0',
+    isWorkletFunction: () => false,
+    cancelAnimation: () => {},
+    runOnJS: (fn) => fn,
+    runOnUI: (fn) => fn,
+    withSpring: (v) => v,
+    withTiming: (v) => v,
+    withDecay: (v) => v,
+    withDelay: (_d, v) => v,
+    withRepeat: (v) => v,
+    withSequence: (...args) => args[args.length - 1],
+    Easing: {
+      // Reanimated 4's `Easing.bezier(...)` returns an `EasingFunctionFactory`
+      // (`{ factory: () => EasingFunction }`), not a bare function. We surface
+      // both shapes: the returned value is callable (backward-compat with
+      // pre-4 call sites that did `Easing.bezier(...)(t)`) AND has `.factory()`
+      // so the canonical Reanimated 4 unwrap `Easing.bezier(...).factory()`
+      // works under Jest without consumer overrides.
+      bezier: () => {
+        const fn = () => 0
+        fn.factory = () => fn
+        return fn
+      },
+      ease: () => 0,
+      linear: (t) => t,
+      quad: () => 0,
+      cubic: () => 0,
+      sin: () => 0,
+      circle: () => 0,
+      exp: () => 0,
+      poly: () => () => 0,
+      back: () => () => 0,
+      bounce: () => 0,
+      elastic: () => () => 0,
+      in: (fn) => fn,
+      out: (fn) => fn,
+      inOut: (fn) => fn,
+      step0: () => 0,
+      step1: () => 0,
+    },
+    interpolate: (value, _input, output) =>
+      value >= 1 ? output[output.length - 1] : output[0],
+    interpolateColor: (value, _input, output) =>
+      value >= 1 ? output[output.length - 1] : output[0],
+    Extrapolation: { CLAMP: 'clamp', IDENTITY: 'identity', EXTEND: 'extend' },
+    // Layout-animation builder stub. The real builder is chainable and records
+    // spring / timing config; tests assert against the recorded fields. Each
+    // chain call returns a fresh instance with the field set so the resolver's
+    // immutable-chain idiom (rebinding `builder = builder.x(...)`) works.
+    LinearTransition: (() => {
+      class LinearTransitionStub {
+        constructor() {
+          this.__kind = 'LinearTransition'
+        }
+        _clone(patch) {
+          const next = new LinearTransitionStub()
+          Object.assign(next, this, patch)
+          return next
+        }
+        springify(duration) {
+          return this._clone({ __mode: 'spring', __duration: duration })
+        }
+        damping(v) {
+          return this._clone({ damping: v })
+        }
+        stiffness(v) {
+          return this._clone({ stiffness: v })
+        }
+        mass(v) {
+          return this._clone({ mass: v })
+        }
+        dampingRatio(v) {
+          return this._clone({ dampingRatio: v })
+        }
+        duration(v) {
+          return this._clone({ __mode: 'timing', __duration: v })
+        }
+        easing(fn) {
+          return this._clone({ easing: fn })
+        }
+        delay(v) {
+          return this._clone({ delay: v })
+        }
+        reduceMotion(v) {
+          return this._clone({ reduceMotion: v })
+        }
+      }
+      const proxy = new Proxy(LinearTransitionStub, {
+        get(target, prop) {
+          if (prop in target) return target[prop]
+          // Forward static-style invocations to a fresh instance so
+          // `LinearTransition.springify()` works as well as
+          // `new LinearTransition().springify()`.
+          return (...args) => {
+            const instance = new LinearTransitionStub()
+            return instance[prop](...args)
+          }
+        },
+      })
+      return proxy
+    })(),
+    ReduceMotion: { System: 'system', Always: 'always', Never: 'never' },
+  }
+})

package/llms.txt

@@ -0,0 +1,142 @@
+# Inertia
+
+> Declarative animation primitives for React Native, built on react-native-reanimated. Inspired by Framer Motion (web) and react-spring (cross-platform). DX-first — animations are props on a component, not imperative shared values, worklets, and `useAnimatedStyle` boilerplate.
+
+## Install
+
+```sh
+pnpm add @rootnative/inertia react-native-reanimated
+```
+
+Enable the Reanimated Babel plugin per its install guide.
+
+## Imports
+
+```ts
+import {
+  Motion,
+  Presence,
+  MotionConfig,
+  useGesture,
+  useVariants,
+  useMotionValue,
+  useAnimation,
+  useSpring,
+  useBooleanSpring,
+  useTransform,
+  useShadow,
+  useColorTransition,
+  useScroll,
+} from '@rootnative/inertia'
+// Opt-in MD3 / iOS state-layer overlay helper:
+import { useGestureLayer } from '@rootnative/inertia/gesture-layer'
+// or for tree-shaking the primitives:
+import { MotionView } from '@rootnative/inertia/view'
+import { MotionText } from '@rootnative/inertia/text'
+import { MotionImage } from '@rootnative/inertia/image'
+import { MotionPressable } from '@rootnative/inertia/pressable'
+import { MotionScrollView } from '@rootnative/inertia/scroll-view'
+```
+
+## Public API
+
+- `Motion.View` / `Motion.Text` / `Motion.Image` / `Motion.Pressable` / `Motion.ScrollView` — animatable primitives. Per-primitive style inference (no shared `ViewStyle & TextStyle & ImageStyle` fallback).
+- `<Presence>` — mount / unmount transitions; children need explicit `key`s. Exiting children get `pointerEvents: 'none'` automatically.
+- `<MotionConfig reducedMotion="user" | "never" | "always">` — gates motion against the OS reduce-motion setting (default `"user"`).
+- `useGesture(transition?)` — hook-form of the `gesture` prop. Returns 0↔1 progress shared values (`pressed`, `focused`, `focusVisible`, `hovered`) plus a `handlers` bag to spread on a `Pressable`. Use when one gesture needs to drive multiple animated siblings (focus rings, MD3 state-layer halos, multi-element compositions).
+- `useGestureLayer(states, options?)` — opt-in helper at `@rootnative/inertia/gesture-layer` for the **strongest-active-layer-wins** composition (MD3 state-layer haloes, iOS-translucent overlays). Supply per-state target maps (`rest` / `hovered` / `focused` / `focusVisible` / `pressed` / `disabled`); the hook owns the worklet. Numeric keys compose via clamped-max with `rest` as the floor; color keys compose via priority cascade with `interpolateColor`; `disabled` (JS-side flag) overrides every gesture layer. Returns `{ style, handlers }`. Reach for plain `useGesture` for additive blends or per-key custom rules.
+- `useVariants(variants, initial?)` — returns `{ current, transitionTo }` controller for the `controller` prop.
+- `useMotionValue(initial)` — thin pass-through over `useSharedValue<T>`. Returns a `SharedValue<T>` directly so it interops with every Reanimated API without unwrapping.
+- `useAnimation(target, transition?)` — drive a `SharedValue<number>` toward `target` with any `TransitionConfig` (spring / timing / decay / no-animation, plus `repeat`). The general-purpose value-layer hook for boolean-state progress, indeterminate loops, and anywhere the same value needs to feed multiple `useAnimatedStyle` blocks.
+- `useSpring(target, config?)` — spring-only shorthand. Animates a `SharedValue<number>` toward `target` with react-spring vocab. `target` may be a plain number (effect-driven) or a `SharedValue<number>` (UI-thread reaction); the latter is the gesture-smoothing path.
+- `useBooleanSpring(active, config?)` — sugar over `useSpring` for the recurring "spring 0↔1 progress from a boolean" shape (checkbox checks, accordion expansions, drawer open/closed). Identical mechanics to `useSpring(active ? 1 : 0, config)` — the named form so the call site reads as the boolean it represents.
+- `useTransform(value, inputRange, outputRange, options?)` / `useTransform(transformer)` — interpolate a numeric shared value onto a number or color range, or derive any value from any number of shared values via a worklet. Non-worklet transformers are auto-wrapped.
+- `useShadow({ from, to, progress })` — pure value-layer interpolator between two `ShadowConfig`s (`shadowOpacity` / `shadowRadius` / `shadowOffset` / `elevation` / `shadowColor`) driven by a `SharedValue<number>` (0→1). Returns an animated style fragment to spread onto `style`; only emits keys present on either side, absent sides default to natural zero. The hook does not animate on its own — drive `progress` with a spring, a scroll-derived `useTransform`, or any other shared value source.
+- `useColorTransition(progress, [from, to], options?)` — pure value-layer interpolator for a single color channel, driven by a `SharedValue<number>` (0→1). Returns an animated style fragment with one color key (default `backgroundColor`; configurable via `options.key` to `color` / `borderColor` / `tintColor` / `shadowColor` / per-side border colors). For raw `SharedValue<string>` output, use `useTransform(progress, [0, 1], [from, to])` instead.
+- `useScroll()` — returns `{ scrollX, scrollY, onScroll }` for use with `Motion.ScrollView`. Scroll events fire on the UI thread.
+- `createMotionComponent<C>(C)` — wrap any component with the same Motion prop surface, inferring style from `C`.
+- `buildReleaseAnimation(transition, toValue)` — worklet-safe single-step animation builder (spring / timing / decay / no-animation). For assigning Inertia-resolved animations to shared values from inside a gesture worklet. Used internally by `@rootnative/inertia-gestures`'s `useDrag({ onRelease })`.
+
+## Motion props
+
+`initial` (mount-only, non-reactive after first render — pass `false` to skip), `animate`, `exit`, `variants`, `controller`, `gesture`, `transition`, `layout`, `onAnimationEnd`.
+
+`layout` accepts `true` (default spring) or a `TransitionConfig` (spring / timing) and animates position + size changes that come from outside the `animate` flow (siblings reordering, dimensions toggling). `'decay'` downgrades to spring; `'no-animation'` and reduced motion both skip the animation.
+
+## Transitions
+
+| `type`           | Public config                                                    | Default? |
+| ---------------- | ---------------------------------------------------------------- | -------- |
+| `'spring'`       | `tension`, `friction`, `mass`, `velocity`, `delay`, `repeat`     | yes      |
+| `'timing'`       | `duration`, `easing` (`EasingFunction` or Reanimated 4 `EasingFunctionFactory` — `Easing.bezier(...)` works directly, no `.factory()` call needed), `delay`, `repeat` |          |
+| `'decay'`        | `velocity`, `deceleration`, `clamp`, `delay`                     |          |
+| `'no-animation'` | —                                                                |          |
+
+Spring uses react-spring vocabulary (`tension`, `friction`, `mass`). Reanimated's raw `stiffness` / `damping` never appear in the public API. Per-property `transition` entries override the top-level config.
+
+## Sequences and repeat
+
+```tsx
+<Motion.View
+  animate={{
+    translateX: [0, 100, 0],
+    opacity: [0, { to: 1, type: 'spring' }, { to: 0, delay: 500 }],
+  }}
+  transition={{ repeat: 'infinite' }}
+/>
+```
+
+`repeat`: `number` (finite, alternating) | `'infinite'` | `{ count, alternate }`.
+
+## Gestures
+
+```tsx
+<Motion.View
+  gesture={{
+    hovered: { backgroundColor: '#0001' },
+    focused: { backgroundColor: '#0002' },
+    pressed: { backgroundColor: '#0003' },
+  }}
+  transition={{ type: 'timing', duration: 120 }}
+/>
+```
+
+Sub-states composite as a **priority cascade** in the order `hovered → focused → focusVisible → pressed` (highest-priority active layer's target wins — values are never summed). Each declared sub-state owns an independent progress (0↔1) that fades in/out with its own transition; the worklet composites layers via `lerp` (numerics) / `interpolateColor` (colors). MD3 release-while-hovered behaves correctly — the press layer fades out without disturbing the hover layer.
+
+Per-layer transitions via `transition.<stateName>`:
+
+```tsx
+transition={{
+  pressed:  { type: 'timing', duration: 50 },
+  hovered:  { type: 'timing', duration: 90 },
+}}
+```
+
+`focusVisible` engages only on keyboard focus (W3C `:focus-visible`) so click-focus on web doesn't flash a ring; on native it tracks `focused`. `hovered` is a no-op on native.
+
+## Caveats
+
+- Every `Motion.*` primitive **throws in dev** when `style` is a function. Reanimated's animated-component wrapper would silently drop the function-form `style={({ pressed }) => ...}` that RN's `Pressable` accepts, so the throw catches the footgun at the source. Drive press/focus/hover styling through `gesture` instead, or compute conditional styles once in render. Production builds skip the check (the styles would still be dropped — catching it in dev is the safety net).
+- `initial` is read once on mount and intentionally non-reactive. To reset after a state change, change the component `key`, remount via `<Presence>`, or drive the value through a controller. Pass `initial={false}` to skip the initial-mount animation.
+
+## Animatable properties (alpha)
+
+Numeric: `opacity`, `translateX`, `translateY`, `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`, `rotateY`, `width`, `height`, `borderRadius`, `shadowOpacity`, `shadowRadius`, `elevation`. Rotation values are degrees; the factory wraps them as `'${value}deg'`. `rotateX` / `rotateY` need a sibling `perspective` style entry to render in 3D.
+
+Color: `backgroundColor`, `borderColor`, `color`, `tintColor` (Image only), `shadowColor`. Hex, `rgb()` / `rgba()`, `hsl()` / `hsla()`, and named colors all work; the target string is forwarded straight through `withSpring` / `withTiming` and Reanimated handles RGBA interpolation natively.
+
+Nested object: `shadowOffset: { width, height }`. The only nested-object style on the surface — internally decomposes into two synthetic axis SVs that the worklet recomposes into a single `shadowOffset` prop. v0.1 supports the **single-value form only** (`{ width: 0, height: 4 }`); sequences / array keyframes / per-axis transition splits are out of scope, drop to `useMotionValue` for those.
+
+Auto-layout transitions ship via the `layout` prop (`true` / `TransitionConfig`) on every `Motion.*` primitive — see Layout. Shared element transitions ship via the `layoutId` prop: pair the same id on a source and target `Motion.*` and Inertia FLIPs between them on mount (parent-relative coords, rect-only animation, 1s TTL).
+
+## Optional adapter packages
+
+- `@rootnative/inertia-gradients` — `MotionLinearGradient` over `expo-linear-gradient`. Animatable: `colors`, `start`, `end`, `locations`.
+- `@rootnative/inertia-svg` — `MotionPath` over `react-native-svg`. Animatable: `d` (path morphing on structurally-compatible paths), `fill`, `stroke`, `strokeWidth`, opacities, `strokeDashoffset`. Source and target paths must share the same command sequence after implicit-repeat expansion; remount with `key` to switch shape.
+- `@rootnative/inertia-gestures` — `useDrag`, `useSwipe`, `usePan` over `react-native-gesture-handler`. `useDrag` accepts an `onRelease` worklet that returns per-axis Inertia release transitions (snap-to-tick spring, decay with bounds, etc.) — the release velocity stays on the UI thread, no JS round-trip.
+
+## Docs
+
+- Full docs: https://rootnative.github.io/inertia/
+- Per-page LLM reference: https://rootnative.github.io/inertia/llms-full.txt
+- Source: https://github.com/rootnative/inertia

package/package.json

@@ -0,0 +1,151 @@
+{
+  "name": "@rootnative/inertia",
+  "version": "0.0.0-alpha.0",
+  "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
+  "license": "MIT",
+  "author": "RootNative",
+  "homepage": "https://github.com/rootnative/inertia",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rootnative/inertia.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/rootnative/inertia/issues"
+  },
+  "keywords": [
+    "react-native",
+    "reanimated",
+    "animation",
+    "motion",
+    "expo",
+    "framer-motion",
+    "react-spring",
+    "declarative"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "react-native": "./src/index.ts",
+  "source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./src/index.ts",
+      "source": "./src/index.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./view": {
+      "types": "./dist/motion/View.d.ts",
+      "react-native": "./src/motion/View.tsx",
+      "source": "./src/motion/View.tsx",
+      "import": "./dist/motion/View.mjs",
+      "require": "./dist/motion/View.js"
+    },
+    "./text": {
+      "types": "./dist/motion/Text.d.ts",
+      "react-native": "./src/motion/Text.tsx",
+      "source": "./src/motion/Text.tsx",
+      "import": "./dist/motion/Text.mjs",
+      "require": "./dist/motion/Text.js"
+    },
+    "./image": {
+      "types": "./dist/motion/Image.d.ts",
+      "react-native": "./src/motion/Image.tsx",
+      "source": "./src/motion/Image.tsx",
+      "import": "./dist/motion/Image.mjs",
+      "require": "./dist/motion/Image.js"
+    },
+    "./pressable": {
+      "types": "./dist/motion/Pressable.d.ts",
+      "react-native": "./src/motion/Pressable.tsx",
+      "source": "./src/motion/Pressable.tsx",
+      "import": "./dist/motion/Pressable.mjs",
+      "require": "./dist/motion/Pressable.js"
+    },
+    "./scroll-view": {
+      "types": "./dist/motion/ScrollView.d.ts",
+      "react-native": "./src/motion/ScrollView.tsx",
+      "source": "./src/motion/ScrollView.tsx",
+      "import": "./dist/motion/ScrollView.mjs",
+      "require": "./dist/motion/ScrollView.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "react-native": "./src/testing/index.ts",
+      "source": "./src/testing/index.ts",
+      "import": "./dist/testing/index.mjs",
+      "require": "./dist/testing/index.js"
+    },
+    "./touch": {
+      "types": "./dist/touch/index.d.ts",
+      "react-native": "./src/touch/index.ts",
+      "source": "./src/touch/index.ts",
+      "import": "./dist/touch/index.mjs",
+      "require": "./dist/touch/index.js"
+    },
+    "./gesture-layer": {
+      "types": "./dist/gestureLayer/index.d.ts",
+      "react-native": "./src/gestureLayer/index.ts",
+      "source": "./src/gestureLayer/index.ts",
+      "import": "./dist/gestureLayer/index.mjs",
+      "require": "./dist/gestureLayer/index.js"
+    },
+    "./jest-preset": "./jest-preset.js",
+    "./jest-setup": "./jest-setup.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "jest-preset.js",
+    "jest-setup.js",
+    "llms.txt",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "!**/__tests__",
+    "!**/*.test.*"
+  ],
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-native": ">=0.81.0",
+    "react-native-reanimated": ">=4.0.0",
+    "react-native-worklets": ">=0.5.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native-worklets": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@react-native/babel-preset": "^0.81.5",
+    "@size-limit/preset-small-lib": "^11.1.0",
+    "@testing-library/react-native": "^13.3.3",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.1.0",
+    "jest": "^29.7.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-reanimated": "~4.1.1",
+    "react-test-renderer": "19.1.0",
+    "size-limit": "^11.1.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "size": "size-limit",
+    "size:why": "size-limit --why",
+    "lint": "eslint .",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  }
+}

package/src/__type-tests__/animate.test-d.tsx

@@ -0,0 +1,88 @@
+/**
+ * Phase-1 acceptance: per-primitive style inference must reject keys that
+ * don't exist on the underlying component's style prop, at compile time.
+ *
+ * These assertions run as part of `tsc --noEmit` (typecheck CI step). They
+ * are not Jest tests — Jest's Babel transform strips `@ts-expect-error`,
+ * so a runtime check can't enforce a compile-time gate. If any
+ * `@ts-expect-error` here becomes unused (i.e. the line below it stops
+ * being a type error), tsc fails with "Unused '@ts-expect-error'
+ * directive" and Phase-1 has regressed.
+ *
+ * The file is excluded from the tsup build via the explicit entry list in
+ * tsup.config.ts, and from Jest via the `__tests__`-only testMatch glob.
+ *
+ * We assert against `AnimateStyle<...>` directly (rather than mounting JSX)
+ * because Prettier reflows multi-line JSX, which would push the actual
+ * error onto a different line than the `@ts-expect-error` directive.
+ * Direct value-to-type assignment lines stay one line, regardless of
+ * Prettier print width.
+ */
+
+import type { ComponentProps } from 'react'
+import type { Image, Pressable, ScrollView, Text, View } from 'react-native'
+import type { AnimateStyle } from '../types'
+
+type ViewAnimate = AnimateStyle<ComponentProps<typeof View>>
+type TextAnimate = AnimateStyle<ComponentProps<typeof Text>>
+type ImageAnimate = AnimateStyle<ComponentProps<typeof Image>>
+type PressableAnimate = AnimateStyle<ComponentProps<typeof Pressable>>
+type ScrollViewAnimate = AnimateStyle<ComponentProps<typeof ScrollView>>
+
+// ─── Motion.View / ViewStyle ────────────────────────────────────────────────
+
+const _viewAccepts: ViewAnimate = { opacity: 1, translateX: 10, scale: 1.1 }
+const _viewAcceptsRotate: ViewAnimate = { rotate: 45, rotateX: 30, rotateY: 60 }
+// @ts-expect-error rotate is a numeric degree value; strings like '45deg' aren't accepted
+const _viewRejectsRotateString: ViewAnimate = { rotate: '45deg' }
+// @ts-expect-error tintColor is ImageStyle-only and must be rejected on View
+const _viewRejectsTintColor: ViewAnimate = { tintColor: '#0a84ff' }
+// @ts-expect-error fontSize is TextStyle-only and must be rejected on View
+const _viewRejectsFontSize: ViewAnimate = { fontSize: 20 }
+// @ts-expect-error completely unknown keys must be rejected
+const _viewRejectsUnknown: ViewAnimate = { nonsenseKey: 1 }
+
+// ─── Motion.Text / TextStyle ────────────────────────────────────────────────
+
+const _textAccepts: TextAnimate = { opacity: 1, color: '#000', fontSize: 16 }
+// @ts-expect-error tintColor is ImageStyle-only and must be rejected on Text
+const _textRejectsTintColor: TextAnimate = { tintColor: '#0a84ff' }
+
+// ─── Motion.Image / ImageStyle ──────────────────────────────────────────────
+
+const _imageAccepts: ImageAnimate = { tintColor: '#0a84ff', opacity: 0.5 }
+// @ts-expect-error fontSize is TextStyle-only and must be rejected on Image
+const _imageRejectsFontSize: ImageAnimate = { fontSize: 20 }
+
+// ─── Motion.Pressable / Motion.ScrollView ───────────────────────────────────
+//
+// Both wrap View internally; their style surface is ViewStyle. Same rule as
+// Motion.View — no tintColor. Pressable's `style` is a union with a
+// `(state) => StyleProp<ViewStyle>` callback; the `_StyleValue` helper in
+// `types.ts` strips the function variant so inference stays tight.
+
+const _pressableAccepts: PressableAnimate = { opacity: 1, scale: 0.96 }
+// @ts-expect-error tintColor is ImageStyle-only and must be rejected on Pressable
+const _pressableRejectsTintColor: PressableAnimate = { tintColor: '#0a84ff' }
+
+const _scrollViewAccepts: ScrollViewAnimate = { opacity: 1, translateY: 10 }
+// @ts-expect-error tintColor is ImageStyle-only and must be rejected on ScrollView
+const _scrollViewRejectsTintColor: ScrollViewAnimate = { tintColor: '#0a84ff' }
+
+// Silence "declared but never read" — these exist purely as type assertions.
+export type _PhaseOneTypeAssertions = [
+  typeof _viewAccepts,
+  typeof _viewAcceptsRotate,
+  typeof _viewRejectsRotateString,
+  typeof _viewRejectsTintColor,
+  typeof _viewRejectsFontSize,
+  typeof _viewRejectsUnknown,
+  typeof _textAccepts,
+  typeof _textRejectsTintColor,
+  typeof _imageAccepts,
+  typeof _imageRejectsFontSize,
+  typeof _pressableAccepts,
+  typeof _pressableRejectsTintColor,
+  typeof _scrollViewAccepts,
+  typeof _scrollViewRejectsTintColor,
+]

package/src/__type-tests__/variants.test-d.tsx

@@ -0,0 +1,67 @@
+/**
+ * Compile-time gate for variant-key narrowing on `animate`.
+ *
+ * CLAUDE.md Principle 5 / line 43: "Variant string keys must autocomplete on
+ * `animate`." That requires the `variants` map to be inferred at the JSX call
+ * site and `animate`'s string form to be narrowed to its keys — so a key typo
+ * is a type error, not a silent runtime no-op. These assertions run under
+ * `tsc --noEmit` (the typecheck CI step); if a `@ts-expect-error` here stops
+ * being an error, tsc fails with "Unused '@ts-expect-error' directive" and the
+ * differentiator has regressed.
+ *
+ * Unlike `animate.test-d.tsx`, these MUST mount JSX: the narrowing depends on
+ * `V` being inferred from the `variants` prop at the call site, which only
+ * happens through the generic component call signature.
+ */
+
+import { Motion } from '../motion'
+
+const variants = {
+  open: { opacity: 1, translateY: 0 },
+  closed: { opacity: 0, translateY: 100 },
+} as const
+
+// ─── Variant key narrowing ──────────────────────────────────────────────────
+
+// A declared key is accepted (and `open` / `closed` autocomplete here).
+const _acceptsKnownKey = <Motion.View variants={variants} animate="open" />
+const _acceptsOtherKey = <Motion.View variants={variants} animate="closed" />
+
+// A typo'd key is a compile error rather than a silent no-op.
+// @ts-expect-error 'opne' is not a key of `variants`
+const _rejectsTypoKey = <Motion.View variants={variants} animate="opne" />
+
+// The style-object form still works alongside `variants` (escape hatch for a
+// one-off target that isn't a named state).
+const _acceptsStyleObject = (
+  <Motion.View variants={variants} animate={{ opacity: 0.5 }} />
+)
+
+// `as const` is NOT required — an inline object literal narrows just as well.
+const inlineVariants = { a: { opacity: 1 }, b: { opacity: 0 } }
+const _inlineVariantsNarrow = (
+  <Motion.View variants={inlineVariants} animate="a" />
+)
+const _inlineVariantsReject = (
+  // @ts-expect-error 'c' is not a key of the inline variants map
+  <Motion.View variants={inlineVariants} animate="c" />
+)
+
+// ─── No variants → string stays open (back-compat) ──────────────────────────
+
+// Without `variants`, the string form is unconstrained, so this must NOT error
+// (the variant-less call site is unchanged by the narrowing machinery).
+const _noVariantsAnyString = <Motion.View animate="whatever" />
+const _noVariantsStyleObject = <Motion.View animate={{ translateX: 10 }} />
+
+// Silence "declared but never read" — these exist purely as type assertions.
+export type _VariantTypeAssertions = [
+  typeof _acceptsKnownKey,
+  typeof _acceptsOtherKey,
+  typeof _rejectsTypoKey,
+  typeof _acceptsStyleObject,
+  typeof _inlineVariantsNarrow,
+  typeof _inlineVariantsReject,
+  typeof _noVariantsAnyString,
+  typeof _noVariantsStyleObject,
+]