Aetheris Motion is a high-performance, physics-native animation framework for React. It utilizes a zero-reconciliation architecture designed to minimize the overhead associated with React's virtual DOM and render cycles. By leveraging a centralized requestAnimationFrame ticker and a stable Runge-Kutta (RK4) integrator, Aetheris achieves consistent 60fps+ motion even in high-density environments.

Traditional animation libraries often rely on state interpolation which triggers React re-renders for every frame. Aetheris bypasses this by updating DOM attributes directly via a specialized batching system. This physics-first approach ensures that motion properties such as mass, tension, and friction result in natural, organic movement that remains numerically stable across varying hardware capabilities.

Installation

Install via your preferred package manager:

npm install aetheris
# or
pnpm add aetheris
# or
yarn add aetheris

Quick Start

The following example demonstrates a basic implementation using the a.div proxy component. All motion is handled outside of the React render loop.

import React from "react";
import { MotionProvider, a } from "aetheris";

export default function App() {
  return (
    <MotionProvider>
      <a.div
        style={{
          width: 200,
          height: 200,
          background: "#0070f3",
        }}
      />
    </MotionProvider>
  );
}

Physics API Reference

The following table defines the core physics properties used by the Aetheris solver:

Property	Type	Default	Description
mass	number	1.0	The inertia of the object. Higher values result in slower acceleration and deceleration.
tension	number	170.0	The stiffness of the spring. Higher values increase the natural frequency and snap.
friction	number	26.0	The damping coefficient. Higher values reduce overshoot and settle the object faster.
velocity	number	0.0	The initial velocity applied to the spring-solver.

Documentation

Full API documentation and advanced usage guides are available in the official repository.

License

This project is licensed under the MIT License.

Contributing

See CONTRIBUTING.md for architectural mandates (zero-reconciliation) and testing requirements.

Core Values

Global Ticker — single requestAnimationFrame loop for all motion subscribers.

Architecture & Core Systems

Aetheris operates on several foundational principles:

Global Ticker: A unified requestAnimationFrame loop that drives all motion subscribers, ensuring frame-perfect synchronization across the entire UI.
RK4 Integration: All springs are integrated using a 4th-order Runge-Kutta solver, providing numerical stability and preventing oscillation drift at varying frame rates.
Batching & Write-Back: Motion values undergo a three-stage lifecycle—calculate, batch, and commit—to prevent layout thrashing and minimize main-thread blocking.

Performance Profile

Zero-Reconciliation: Standard React props are bypassed for high-frequency updates, ensuring the React scheduler remains free for application logic.
W3C Standard Compliance: Utilizes will-change and hardware-accelerated transforms to ensure motion remains off-loaded to the GPU where possible.

Technical Support

For architectural inquiries or implementation support, please refer to the documentation in the docs directory or open a technical issue.

� Project Structure

aetheris/
├── src/
│   ├── core/              # The Engine: Ticker, Batcher, Physics Solver, MotionValue
│   ├── hooks/             # Reactive hooks (useAnimationFrame, useAetherisProps)
│   ├── text/              # Text-based animations (Scramble, Physics Split)
│   ├── backgrounds/       # GPU-accelerated field & mesh backgrounds
│   ├── hover/             # Reactive mouse-tracking effects
│   ├── scroll/            # Momentum-based scroll triggers
│   ├── buttons/           # Tactile & Particle-based interaction
│   ├── cards/             # 3D Depth & Parallax systems
│   └── cursor/            # Physics-based custom cursor followers
├── dist/                  # Optimized production bundles (ESM/CJS)
└── examples/
    └── playground/        # Interactive showcase & real-time prop editor