@onlynative/inertia 0.0.1-alpha.8 → 0.0.1-alpha.9

package/dist/touch/index.d.mts

@@ -1,6 +1,6 @@
 import { PanResponderInstance } from 'react-native';
 import { useAnimatedStyle, SharedValue } from 'react-native-reanimated';
-import { T as TransitionConfig } from '../types-BwyvoH2V.mjs';
+import { T as TransitionConfig } from '../types-cU43dEmH.mjs';
 import 'react';
 
 /**

package/dist/touch/index.d.ts

@@ -1,6 +1,6 @@
 import { PanResponderInstance } from 'react-native';
 import { useAnimatedStyle, SharedValue } from 'react-native-reanimated';
-import { T as TransitionConfig } from '../types-BwyvoH2V.js';
+import { T as TransitionConfig } from '../types-cU43dEmH.js';
 import 'react';
 
 /**

package/dist/{types-BwyvoH2V.d.mts → types-cU43dEmH.d.mts}

@@ -1,4 +1,4 @@
-import { ComponentType } from 'react';
+import { ComponentType, ComponentProps, Ref, ReactElement } from 'react';
 import { StyleProp } from 'react-native';
 
 /**
@@ -210,8 +210,15 @@ interface VariantController<K extends string = string> {
 }
 /**
  * Props injected onto every Motion primitive.
+ *
+ * The second type parameter `V` is the concrete `variants` map. It is inferred
+ * from the `variants` prop at each JSX use (see `MotionComponent`), which is
+ * what lets `animate` narrow to the variant key union and reject typos. When
+ * no `variants` prop is passed, `V` falls back to `VariantsMap<C>` — whose key
+ * type is the open `string`, so `animate` still accepts any string and nothing
+ * regresses for the variant-less case.
  */
-interface MotionProps<C> {
+interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
     /**
      * Initial values applied on mount. Read once on mount and intentionally
      * non-reactive — to reset after a state change, change the component `key`,
@@ -222,10 +229,11 @@ interface MotionProps<C> {
     initial?: AnimateStyle<C> | false;
     /**
      * The animation target. A style object, a variant key (when `variants` is
-     * supplied), or an array of sequence steps. Variant keys autocomplete when
-     * `variants` is annotated `as const`.
+     * supplied), or an array of sequence steps. When `variants` is set, the
+     * string form is narrowed to the map's keys, so a key typo is a compile
+     * error and the keys autocomplete — no `as const` required.
      */
-    animate?: AnimateStyle<C> | string;
+    animate?: AnimateStyle<C> | (keyof V & string);
     /**
      * Values applied while the component exits via `<Presence>`.
      */
@@ -234,13 +242,13 @@ interface MotionProps<C> {
      * Named animation states. With `variants` set, `animate` accepts a key from
      * this map.
      */
-    variants?: VariantsMap<C>;
+    variants?: V;
     /**
      * Imperative controller from `useVariants(...)`. When supplied, `animate`
      * is read from `controller.current` and re-applied whenever the controller
      * transitions. `animate` and `controller` should not both be set.
      */
-    controller?: VariantController;
+    controller?: VariantController<keyof V & string>;
     /**
      * Gesture-driven sub-states (`pressed`, `focused`, `focusVisible`,
      * `hovered`). When omitted, no handlers are mounted on the underlying
@@ -282,8 +290,11 @@ interface MotionProps<C> {
      * recorded rect to its natural position via a FLIP transform stack.
      *
      * Reanimated 4 removed the `sharedTransitionTag` API — `layoutId` is the
-     * Inertia-side measure-based replacement. Rects are stored in window
-     * coordinates so the source and target can live on different screens.
+     * Inertia-side measure-based replacement. Rects are recorded in
+     * parent-relative coordinates (from `onLayout`), which composes when the
+     * source and target screens share an outer content container (the common
+     * stack-navigator case); nested-parent layouts need the v2
+     * window-coordinate path.
      *
      * The same `transition` prop drives the FLIP animation (spring by
      * default; `'timing'` honored; `'decay'` downgrades to spring; reduced
@@ -301,12 +312,28 @@ interface MotionProps<C> {
     onAnimationEnd?: (info: AnimationCallbackInfo<AnimateStyle<C>>) => void;
 }
 /**
- * The component type produced by `createMotionComponent`. Combines the
- * underlying component's props (minus `style`, which we replace with an
- * animated style) with the Motion-specific props above.
+ * Props of a Motion primitive for a given underlying component `C` and a
+ * concrete variants map `V`: the component's own props (minus `style`, which
+ * we replace with an animated style) intersected with the Motion props.
+ */
+type MotionComponentProps<C extends ComponentType<any>, V extends VariantsMap<ComponentProps<C>> = VariantsMap<ComponentProps<C>>> = Omit<ComponentProps<C>, 'style'> & MotionProps<ComponentProps<C>, V> & {
+    style?: ComponentProps<C>['style'];
+    ref?: Ref<unknown>;
+};
+/**
+ * The component type produced by `createMotionComponent`.
+ *
+ * It is a **generic call signature**, not a plain `ComponentType`: the variant
+ * map `V` is inferred from the `variants` prop at each JSX use. That inference
+ * is what narrows `animate`'s string form to the variant keys, so
+ * `<Motion.View variants={{ open, closed }} animate="opne" />` is a compile
+ * error and `open` / `closed` autocomplete. With no `variants` prop, `V` falls
+ * back to the open `VariantsMap`, so `animate` still accepts any string and the
+ * variant-less call site is unchanged.
  */
-type MotionComponent<C extends ComponentType<any>> = ComponentType<Omit<React.ComponentProps<C>, 'style'> & MotionProps<React.ComponentProps<C>> & {
-    style?: React.ComponentProps<C>['style'];
-}>;
+interface MotionComponent<C extends ComponentType<any>> {
+    <V extends VariantsMap<ComponentProps<C>> = VariantsMap<ComponentProps<C>>>(props: MotionComponentProps<C, V>): ReactElement | null;
+    displayName?: string;
+}
 
 export type { AnimatableValue as A, DecayTransition as D, EasingInput as E, GestureSubStates as G, MotionComponent as M, NoAnimationTransition as N, PerPropertyTransition as P, RepeatConfig as R, SpringTransition as S, TransitionConfig as T, VariantController as V, AnimateStyle as a, AnimationCallbackInfo as b, MotionProps as c, SequenceStep as d, TimingTransition as e, Transition as f, VariantsMap as g, GestureLayerTransitions as h };

package/dist/{types-BwyvoH2V.d.ts → types-cU43dEmH.d.ts}

@@ -1,4 +1,4 @@
-import { ComponentType } from 'react';
+import { ComponentType, ComponentProps, Ref, ReactElement } from 'react';
 import { StyleProp } from 'react-native';
 
 /**
@@ -210,8 +210,15 @@ interface VariantController<K extends string = string> {
 }
 /**
  * Props injected onto every Motion primitive.
+ *
+ * The second type parameter `V` is the concrete `variants` map. It is inferred
+ * from the `variants` prop at each JSX use (see `MotionComponent`), which is
+ * what lets `animate` narrow to the variant key union and reject typos. When
+ * no `variants` prop is passed, `V` falls back to `VariantsMap<C>` — whose key
+ * type is the open `string`, so `animate` still accepts any string and nothing
+ * regresses for the variant-less case.
  */
-interface MotionProps<C> {
+interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
     /**
      * Initial values applied on mount. Read once on mount and intentionally
      * non-reactive — to reset after a state change, change the component `key`,
@@ -222,10 +229,11 @@ interface MotionProps<C> {
     initial?: AnimateStyle<C> | false;
     /**
      * The animation target. A style object, a variant key (when `variants` is
-     * supplied), or an array of sequence steps. Variant keys autocomplete when
-     * `variants` is annotated `as const`.
+     * supplied), or an array of sequence steps. When `variants` is set, the
+     * string form is narrowed to the map's keys, so a key typo is a compile
+     * error and the keys autocomplete — no `as const` required.
      */
-    animate?: AnimateStyle<C> | string;
+    animate?: AnimateStyle<C> | (keyof V & string);
     /**
      * Values applied while the component exits via `<Presence>`.
      */
@@ -234,13 +242,13 @@ interface MotionProps<C> {
      * Named animation states. With `variants` set, `animate` accepts a key from
      * this map.
      */
-    variants?: VariantsMap<C>;
+    variants?: V;
     /**
      * Imperative controller from `useVariants(...)`. When supplied, `animate`
      * is read from `controller.current` and re-applied whenever the controller
      * transitions. `animate` and `controller` should not both be set.
      */
-    controller?: VariantController;
+    controller?: VariantController<keyof V & string>;
     /**
      * Gesture-driven sub-states (`pressed`, `focused`, `focusVisible`,
      * `hovered`). When omitted, no handlers are mounted on the underlying
@@ -282,8 +290,11 @@ interface MotionProps<C> {
      * recorded rect to its natural position via a FLIP transform stack.
      *
      * Reanimated 4 removed the `sharedTransitionTag` API — `layoutId` is the
-     * Inertia-side measure-based replacement. Rects are stored in window
-     * coordinates so the source and target can live on different screens.
+     * Inertia-side measure-based replacement. Rects are recorded in
+     * parent-relative coordinates (from `onLayout`), which composes when the
+     * source and target screens share an outer content container (the common
+     * stack-navigator case); nested-parent layouts need the v2
+     * window-coordinate path.
      *
      * The same `transition` prop drives the FLIP animation (spring by
      * default; `'timing'` honored; `'decay'` downgrades to spring; reduced
@@ -301,12 +312,28 @@ interface MotionProps<C> {
     onAnimationEnd?: (info: AnimationCallbackInfo<AnimateStyle<C>>) => void;
 }
 /**
- * The component type produced by `createMotionComponent`. Combines the
- * underlying component's props (minus `style`, which we replace with an
- * animated style) with the Motion-specific props above.
+ * Props of a Motion primitive for a given underlying component `C` and a
+ * concrete variants map `V`: the component's own props (minus `style`, which
+ * we replace with an animated style) intersected with the Motion props.
+ */
+type MotionComponentProps<C extends ComponentType<any>, V extends VariantsMap<ComponentProps<C>> = VariantsMap<ComponentProps<C>>> = Omit<ComponentProps<C>, 'style'> & MotionProps<ComponentProps<C>, V> & {
+    style?: ComponentProps<C>['style'];
+    ref?: Ref<unknown>;
+};
+/**
+ * The component type produced by `createMotionComponent`.
+ *
+ * It is a **generic call signature**, not a plain `ComponentType`: the variant
+ * map `V` is inferred from the `variants` prop at each JSX use. That inference
+ * is what narrows `animate`'s string form to the variant keys, so
+ * `<Motion.View variants={{ open, closed }} animate="opne" />` is a compile
+ * error and `open` / `closed` autocomplete. With no `variants` prop, `V` falls
+ * back to the open `VariantsMap`, so `animate` still accepts any string and the
+ * variant-less call site is unchanged.
  */
-type MotionComponent<C extends ComponentType<any>> = ComponentType<Omit<React.ComponentProps<C>, 'style'> & MotionProps<React.ComponentProps<C>> & {
-    style?: React.ComponentProps<C>['style'];
-}>;
+interface MotionComponent<C extends ComponentType<any>> {
+    <V extends VariantsMap<ComponentProps<C>> = VariantsMap<ComponentProps<C>>>(props: MotionComponentProps<C, V>): ReactElement | null;
+    displayName?: string;
+}
 
 export type { AnimatableValue as A, DecayTransition as D, EasingInput as E, GestureSubStates as G, MotionComponent as M, NoAnimationTransition as N, PerPropertyTransition as P, RepeatConfig as R, SpringTransition as S, TransitionConfig as T, VariantController as V, AnimateStyle as a, AnimationCallbackInfo as b, MotionProps as c, SequenceStep as d, TimingTransition as e, Transition as f, VariantsMap as g, GestureLayerTransitions as h };

package/dist/{useGesture-BPPp9LhV.d.ts → useGesture-B7A_1DVg.d.ts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { T as TransitionConfig, h as GestureLayerTransitions } from './types-BwyvoH2V.js';
+import { T as TransitionConfig, h as GestureLayerTransitions } from './types-cU43dEmH.js';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the

package/dist/{useGesture-BnBF4OtT.d.mts → useGesture-cimMrzC1.d.mts}

@@ -1,5 +1,5 @@
 import { SharedValue } from 'react-native-reanimated';
-import { T as TransitionConfig, h as GestureLayerTransitions } from './types-BwyvoH2V.mjs';
+import { T as TransitionConfig, h as GestureLayerTransitions } from './types-cU43dEmH.mjs';
 
 /**
  * Handler bag returned by `useGesture`. Spread on a `Pressable` to drive the

package/jest-setup.js

@@ -104,6 +104,10 @@ jest.mock('react-native-reanimated', () => {
       }
     },
     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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlynative/inertia",
-  "version": "0.0.1-alpha.8",
+  "version": "0.0.1-alpha.9",
   "description": "Declarative animation primitives for React Native, built on react-native-reanimated.",
   "license": "MIT",
   "author": "OnlyNative",
@@ -112,7 +112,13 @@
   "peerDependencies": {
     "react": ">=19.0.0",
     "react-native": ">=0.81.0",
-    "react-native-reanimated": ">=4.0.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",

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,
+]

package/src/layout/sharedRegistry.ts

@@ -14,12 +14,15 @@
  *      it becomes the FLIP source rect; the entry is removed so a third
  *      mount with the same id doesn't re-animate from a stale snapshot.
  *
- * Rects are stored in **window coordinates** (what `measureInWindow`
- * returns). Cross-screen transitions need this — parent-relative
- * coordinates are different on each screen and wouldn't compose.
+ * Rects are stored in **parent-relative coordinates** (what `onLayout`'s
+ * `nativeEvent.layout` reports). This composes for the common case where the
+ * source and target share an outer content container — e.g. a typical stack
+ * navigator. Nested-parent setups, where the two parents sit at different
+ * window offsets, need a window-coordinate path (`measureInWindow`); that is
+ * punted to v2 per the roadmap.
  */
 
-/** Window-relative rect of a measured element. */
+/** Parent-relative rect of a measured element (from `onLayout`). */
 export interface SharedRect {
   x: number
   y: number

package/src/motion/createMotionComponent.tsx

@@ -300,43 +300,73 @@ export function createMotionComponent<C extends ComponentType<any>>(
     const [focusVisible, setFocusVisible] = useState(false)
     const [hovered, setHovered] = useState(false)
 
-    // The set of keys this instance animates is locked at first render. With
-    // variants in play the union across all variants is what matters — a key
-    // touched by any variant must be active so the worklet picks it up when
-    // the controller transitions. Gesture sub-states join the same union so
-    // pressed/focused/focusVisible/hovered targets can drive any key they
-    // declare even when the base `animate` doesn't touch it.
-    const activeKeysRef = useRef<readonly AnimatableKey[] | null>(null)
-    if (activeKeysRef.current === null) {
-      const touched = new Set<AnimatableKey>()
-      collectTouchedKeys(touched, animateRecord)
-      if (initialRecord) collectTouchedKeys(touched, initialRecord)
-      if (variants) {
-        for (const variant of Object.values(variants) as object[]) {
-          if (!variant) continue
-          collectTouchedKeys(touched, variant as Record<string, unknown>)
-        }
+    // The set of keys this instance animates is a *monotonically growing*
+    // union, recomputed every render and expanded when a render introduces a
+    // key not seen before. It never shrinks. Two requirements meet here:
+    //
+    //   1. Variants and gesture sub-states contribute the union across *all*
+    //      their branches up front — a key touched by any variant must be
+    //      active so the worklet picks it up when the controller transitions
+    //      to a branch the base `animate` never mentions.
+    //   2. A literal `animate` object is reactive: a parent that changes
+    //      `animate={{ opacity: 1 }}` to `animate={{ opacity: 1, scale: 2 }}`
+    //      after mount must get `scale` animating. Freezing the set at first
+    //      render silently dropped the new key (its SV updated, but the
+    //      worklet — which iterates this set — never read it).
+    //
+    // Growing-only keeps the worklet stable: the `activeKeysRef.current` array
+    // identity only changes on the renders that actually add a key, so the
+    // `useAnimatedStyle` worklet (which reads `.current` each frame) sees the
+    // expansion without churning frame-to-frame.
+    const touched = new Set<AnimatableKey>()
+    collectTouchedKeys(touched, animateRecord)
+    if (initialRecord) collectTouchedKeys(touched, initialRecord)
+    if (variants) {
+      for (const variant of Object.values(variants) as object[]) {
+        if (!variant) continue
+        collectTouchedKeys(touched, variant as Record<string, unknown>)
       }
-      if (gesture) {
-        for (const subState of [
-          gesture.pressed,
-          gesture.focused,
-          gesture.focusVisible,
-          gesture.hovered,
-        ] as Array<object | undefined>) {
-          if (!subState) continue
-          collectTouchedKeys(touched, subState as Record<string, unknown>)
+    }
+    if (gesture) {
+      for (const subState of [
+        gesture.pressed,
+        gesture.focused,
+        gesture.focusVisible,
+        gesture.hovered,
+      ] as Array<object | undefined>) {
+        if (!subState) continue
+        collectTouchedKeys(touched, subState as Record<string, unknown>)
+      }
+    }
+    if (exitRecord) collectTouchedKeys(touched, exitRecord)
+
+    const activeKeysRef = useRef<readonly AnimatableKey[] | null>(null)
+    const hasTransformRef = useRef<boolean>(false)
+    const hasShadowOffsetRef = useRef<boolean>(false)
+    // Expand the active set only when this render touched a key we haven't
+    // recorded yet. When nothing new appears we keep the existing array
+    // identity so the worklet's captured ref doesn't see a fresh value.
+    const prevActive = activeKeysRef.current
+    let grew = prevActive === null
+    if (!grew && prevActive) {
+      for (const k of touched) {
+        if (!prevActive.includes(k)) {
+          grew = true
+          break
         }
       }
-      if (exitRecord) collectTouchedKeys(touched, exitRecord)
-      activeKeysRef.current = ALL_KEYS.filter((k) => touched.has(k))
     }
-    const hasTransformRef = useRef<boolean>(
-      activeKeysRef.current.some((k) => TRANSFORM_KEY_SET.has(k)),
-    )
-    const hasShadowOffsetRef = useRef<boolean>(
-      activeKeysRef.current.some((k) => SHADOW_OFFSET_KEY_SET.has(k)),
-    )
+    if (grew) {
+      const merged = new Set<AnimatableKey>(prevActive ?? [])
+      for (const k of touched) merged.add(k)
+      activeKeysRef.current = ALL_KEYS.filter((k) => merged.has(k))
+      hasTransformRef.current = activeKeysRef.current.some((k) =>
+        TRANSFORM_KEY_SET.has(k),
+      )
+      hasShadowOffsetRef.current = activeKeysRef.current.some((k) =>
+        SHADOW_OFFSET_KEY_SET.has(k),
+      )
+    }
 
     const sharedValues = useAnimatableSharedValues((key) => {
       // Shadow offset synthetics seed from the corresponding axis on the

package/src/motion/installCheck.ts

@@ -1,6 +1,7 @@
+import { reanimatedVersion } from 'react-native-reanimated'
+
 declare const __DEV__: boolean
 declare const process: { env?: Record<string, string | undefined> }
-declare const require: (path: string) => unknown
 
 let alreadyChecked = false
 
@@ -30,16 +31,11 @@ export function ensureReanimatedInstalled(): void {
   }
   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.
-  }
+  // Read the version off Reanimated's own runtime export rather than reaching
+  // into its `package.json`. A `require('.../package.json')` here would make
+  // esbuild emit a `__require` shim that throws on web bundlers (Expo web), and
+  // Reanimated's `exports` field may block the subpath anyway.
+  const version: string | undefined = reanimatedVersion
 
   if (version) {
     const major = parseInt(version.split('.')[0] ?? '0', 10)

package/src/types.ts

@@ -1,4 +1,9 @@
-import { type ComponentType } from 'react'
+import {
+  type ComponentProps,
+  type ComponentType,
+  type ReactElement,
+  type Ref,
+} from 'react'
 import { type StyleProp } from 'react-native'
 
 /**
@@ -239,8 +244,15 @@ export interface VariantController<K extends string = string> {
 
 /**
  * Props injected onto every Motion primitive.
+ *
+ * The second type parameter `V` is the concrete `variants` map. It is inferred
+ * from the `variants` prop at each JSX use (see `MotionComponent`), which is
+ * what lets `animate` narrow to the variant key union and reject typos. When
+ * no `variants` prop is passed, `V` falls back to `VariantsMap<C>` — whose key
+ * type is the open `string`, so `animate` still accepts any string and nothing
+ * regresses for the variant-less case.
  */
-export interface MotionProps<C> {
+export interface MotionProps<C, V extends VariantsMap<C> = VariantsMap<C>> {
   /**
    * Initial values applied on mount. Read once on mount and intentionally
    * non-reactive — to reset after a state change, change the component `key`,
@@ -251,10 +263,11 @@ export interface MotionProps<C> {
   initial?: AnimateStyle<C> | false
   /**
    * The animation target. A style object, a variant key (when `variants` is
-   * supplied), or an array of sequence steps. Variant keys autocomplete when
-   * `variants` is annotated `as const`.
+   * supplied), or an array of sequence steps. When `variants` is set, the
+   * string form is narrowed to the map's keys, so a key typo is a compile
+   * error and the keys autocomplete — no `as const` required.
    */
-  animate?: AnimateStyle<C> | string
+  animate?: AnimateStyle<C> | (keyof V & string)
   /**
    * Values applied while the component exits via `<Presence>`.
    */
@@ -263,13 +276,13 @@ export interface MotionProps<C> {
    * Named animation states. With `variants` set, `animate` accepts a key from
    * this map.
    */
-  variants?: VariantsMap<C>
+  variants?: V
   /**
    * Imperative controller from `useVariants(...)`. When supplied, `animate`
    * is read from `controller.current` and re-applied whenever the controller
    * transitions. `animate` and `controller` should not both be set.
    */
-  controller?: VariantController
+  controller?: VariantController<keyof V & string>
   /**
    * Gesture-driven sub-states (`pressed`, `focused`, `focusVisible`,
    * `hovered`). When omitted, no handlers are mounted on the underlying
@@ -311,8 +324,11 @@ export interface MotionProps<C> {
    * recorded rect to its natural position via a FLIP transform stack.
    *
    * Reanimated 4 removed the `sharedTransitionTag` API — `layoutId` is the
-   * Inertia-side measure-based replacement. Rects are stored in window
-   * coordinates so the source and target can live on different screens.
+   * Inertia-side measure-based replacement. Rects are recorded in
+   * parent-relative coordinates (from `onLayout`), which composes when the
+   * source and target screens share an outer content container (the common
+   * stack-navigator case); nested-parent layouts need the v2
+   * window-coordinate path.
    *
    * The same `transition` prop drives the FLIP animation (spring by
    * default; `'timing'` honored; `'decay'` downgrades to spring; reduced
@@ -331,14 +347,37 @@ export interface MotionProps<C> {
 }
 
 /**
- * The component type produced by `createMotionComponent`. Combines the
- * underlying component's props (minus `style`, which we replace with an
- * animated style) with the Motion-specific props above.
+ * Props of a Motion primitive for a given underlying component `C` and a
+ * concrete variants map `V`: the component's own props (minus `style`, which
+ * we replace with an animated style) intersected with the Motion props.
  */
-// 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>> & {
-      style?: React.ComponentProps<C>['style']
-    }
->
+export type MotionComponentProps<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  C extends ComponentType<any>,
+  V extends VariantsMap<ComponentProps<C>> = VariantsMap<ComponentProps<C>>,
+> = Omit<ComponentProps<C>, 'style'> &
+  MotionProps<ComponentProps<C>, V> & {
+    style?: ComponentProps<C>['style']
+    ref?: Ref<unknown>
+  }
+
+/**
+ * The component type produced by `createMotionComponent`.
+ *
+ * It is a **generic call signature**, not a plain `ComponentType`: the variant
+ * map `V` is inferred from the `variants` prop at each JSX use. That inference
+ * is what narrows `animate`'s string form to the variant keys, so
+ * `<Motion.View variants={{ open, closed }} animate="opne" />` is a compile
+ * error and `open` / `closed` autocomplete. With no `variants` prop, `V` falls
+ * back to the open `VariantsMap`, so `animate` still accepts any string and the
+ * variant-less call site is unchanged.
+ */
+export interface MotionComponent<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  C extends ComponentType<any>,
+> {
+  <V extends VariantsMap<ComponentProps<C>> = VariantsMap<ComponentProps<C>>>(
+    props: MotionComponentProps<C, V>,
+  ): ReactElement | null
+  displayName?: string
+}