@geenius/motion

Dual-engine animation package for the Geenius ecosystem. One component API across two interchangeable engines (motion12 adapter, React-only — and the self-made geenius engine, the only option for SolidJS and React Native). Five framework variants: react, react-css, react-native, solidjs, solidjs-css.

Status: REWRITE — dual-engine architecture. Most v1 surface is not_started; this README documents the target API.

Install

pnpm add @geenius/motion

Peer dependencies (install only what your framework needs):

| Subpath | Peers | | --- | --- | | ./react, ./react-css | react ^19, react-dom ^19 | | ./react-native | react-native ^0.76, react-native-reanimated ^3.16, react-native-gesture-handler ^2.20 | | ./solidjs, ./solidjs-css | solid-js ^1.9 | | ./engine-motion12 (optional) | motion ^12 |

motion@12 is only required if you opt into engine={motion12}. The default geenius engine has no third-party animation peer-dep on the web.

Import Paths

| Subpath | Surface | | --- | --- | | @geenius/motion | MotionEngine interface, types, tokens, presets, reduced-motion, errors | | @geenius/motion/engine-geenius | Self-made WAAPI / Reanimated 3 / pure-CSS engine + geenius instance | | @geenius/motion/engine-motion12 | Thin adapter over motion@12 + motion12 instance (React only) | | @geenius/motion/react | React bindings, motion.* factory, hooks, providers, primitives | | @geenius/motion/react-css | React BEM-class bindings | | @geenius/motion/react-css/styles.css | React CSS variant stylesheet | | @geenius/motion/react-native | RN bindings (Reanimated 3 worklets, Gesture Handler) | | @geenius/motion/solidjs | SolidJS bindings, signals, motion.* factory | | @geenius/motion/solidjs-css | SolidJS BEM-class bindings | | @geenius/motion/solidjs-css/styles.css | SolidJS CSS variant stylesheet |

Quickstart

import { MotionProvider, FadeIn, motion } from '@geenius/motion/react';
import { geenius } from '@geenius/motion/engine-geenius';

export function App() {
  return (
    <MotionProvider engine={geenius} reducedMotion="user">
      <FadeIn>
        <h1>Hello motion</h1>
      </FadeIn>
      <motion.button animate={{ scale: 1 }} initial={{ scale: 0.9 }}>
        Click
      </motion.button>
    </MotionProvider>
  );
}

Engine Selection

<MotionProvider engine={...}> is the only place engine choice lives. Components and primitives never reach into a concrete engine — they consume the shared MotionEngine interface.

| Engine | Default? | Frameworks | When to pick | | --- | --- | --- | --- | | geenius | yes | react, react-css, react-native, solidjs, solidjs-css | Default. No third-party animation peer-dep. Only option on SolidJS and React Native. | | motion12 | no | react, react-css | Opt-in for consumers who want Motion 12's web perf and accept the peer-dep weight. Throws MotionEngineUnsupportedError on SolidJS / React Native. |

import { motion12 } from '@geenius/motion/engine-motion12';

<MotionProvider engine={motion12}>
  {/* Same component API; different engine under the hood. */}
</MotionProvider>

Per-Framework Examples

React (Tailwind)

import { MotionProvider, FadeIn, StaggerContainer, ScaleIn } from '@geenius/motion/react';
import { geenius } from '@geenius/motion/engine-geenius';

<MotionProvider engine={geenius}>
  <StaggerContainer>
    <FadeIn>Item A</FadeIn>
    <ScaleIn delay={120}>Item B</ScaleIn>
  </StaggerContainer>
</MotionProvider>

React CSS (BEM + styles.css)

import '@geenius/motion/react-css/styles.css';
import { MotionProvider, FadeIn, Pulse } from '@geenius/motion/react-css';

<MotionProvider reducedMotion="user">
  <FadeIn>
    <Pulse>Live</Pulse>
  </FadeIn>
</MotionProvider>

React Native (Reanimated 3)

import { MotionProvider, FadeIn, useGesture } from '@geenius/motion/react-native';
import { View } from 'react-native';

export function Card() {
  const gesture = useGesture({ drag: { axis: 'x', momentum: true } });
  return (
    <MotionProvider>
      <FadeIn>
        <View {...gesture.props} />
      </FadeIn>
    </MotionProvider>
  );
}

SolidJS (Tailwind)

import { MotionProvider, FadeIn, motion, createScroll } from '@geenius/motion/solidjs';

export function Scene() {
  const scroll = createScroll();
  return (
    <MotionProvider>
      <FadeIn>Hello Solid</FadeIn>
      <motion.div animate={{ opacity: scroll.scrollYProgress() }} />
    </MotionProvider>
  );
}

SolidJS CSS (BEM + styles.css)

import '@geenius/motion/solidjs-css/styles.css';
import { MotionProvider, FadeIn, Pulse } from '@geenius/motion/solidjs-css';

<MotionProvider>
  <FadeIn>
    <Pulse>CSS-backed Solid motion</Pulse>
  </FadeIn>
</MotionProvider>

Signature Features

• Motion tokens — defineMotionTokens() first-class system for duration / easing / spring / distance / motion-language; flows into the canonical @geenius/tokens --gn-* namespace (--gn-duration-*, --gn-ease-*, --gn-distance-*, …) for *-css variants.
• Preset DSL — preset.slide.up('energetic', { delay: tokens.duration.fast }).
• View Transitions — useViewTransition() wraps document.startViewTransition() with engine fallback.
• Scroll choreography — useScrollTimeline() with scrub: true, scene ranges, parallax.
• FLIP layout — LayoutGroup + motion.div layout; web via getBoundingClientRect, RN via Reanimated useAnimatedStyle.
• Gesture composer — useGesture() for drag / pinch / hover / press / swipe with constraints, momentum, snap-back, axis lock; web pointer events or RN Gesture Handler.
• Motion DevTools — <MotionDevTools /> dev-only overlay (FPS, dropped frames, active animations, will-change audit, token inspector). Tree-shaken in production.
• Serializable MotionDescription — every primitive accepts a motion prop; the playground generates equivalent source for either engine from the same description.
• Reduced-motion granularity — 3 levels (off | subtle | full), not a binary; "user" maps OS reduce → subtle.
• Perf budgets — configureMotion({ perfBudget: { frameMs: 16, droppedFrameThreshold: 3 } }) warns in dev; test:perf enforces in CI.

Variants

| Variant | Engines | Default engine | Stylesheet | | --- | --- | --- | --- | | react | geenius, motion12 | geenius | — | | react-css | geenius, motion12 | geenius | ./react-css/styles.css | | react-native | geenius | geenius | — | | solidjs | geenius | geenius | — | | solidjs-css | geenius | geenius | ./solidjs-css/styles.css |

The 10 UI-library skins (shadcn, chakra, mui, mantine, antd, heroui, daisyui, ark, kobalte, solid-ui) are reclassified as binding-pack, inScope: false for v1, future subpath shape ./bindings/<library>.

Motion has no database persistence surface and publishes no DB-provider subpaths (dbProviders: [] in variants.json).

References

• Full API reference: .docs/DOCS/PACKAGES/MOTION.md
• PRD: .docs/PRDS/packages/PACKAGE_MOTION_PRD.md
• Plan: .docs/PLANS/packages/PACKAGE_MOTION_PLAN.md
• Features: .docs/FEATURES/packages/motion/FEATURES.md

License

FSL-1.1-Apache-2.0 — see LICENSE.