@mlola-ui/motion 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mlola
+
+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,36 @@
+# @mlola-ui/motion
+
+Native kinetic primitives for Mlola UI. Pointer tilt, magnetic pull, digit
+reels, soft text swaps, and a spring integrator — all reduced-motion aware, and
+none of them a continuous animation loop while idle.
+
+The engine already samples a damped oscillator into CSS `linear()` easings, so
+static transitions carry the theme's motion without any JavaScript. This
+package is for the interruptible, pointer-driven cases CSS cannot express.
+
+## Install
+
+```bash
+npm install @mlola-ui/motion
+```
+
+## Use
+
+```tsx
+import { Magnetic, Tilt3D } from "@mlola-ui/motion";
+
+<Magnetic pull={0.2}><button className="ml-button">Join</button></Magnetic>;
+```
+
+## Exports
+
+| Path | What it is |
+| --- | --- |
+| `@mlola-ui/motion` | `Magnetic`, `Tilt3D`, `AnimatedCounter`, `TextSwap`, `ShimmerText` |
+| `@mlola-ui/motion/physics` | `integrateSpring`, `createSpringAnimation`, presets |
+| `@mlola-ui/motion/raf` | frame batching helpers |
+
+Requires React and ReactDOM 18 or newer as peers. Every spatial effect collapses
+under `prefers-reduced-motion: reduce`.
+
+MIT licensed. Part of [Mlola UI](https://ui.mlola.com).

package/motion.css

@@ -0,0 +1,288 @@
+/*
+ * @mlola-ui/motion
+ * Micro-transitions & physics-inspired animations.
+ *
+ * Designed to feel crisp, organic, and never mechanical:
+ * - Springs use cubic-bezier(0.16, 1, 0.3, 1) and (0.34, 1.56, 0.64, 1)
+ * - Shimmers and glares use CSS masks + gradients
+ * - Respects prefers-reduced-motion
+ */
+
+:root {
+  --ease-spring-soft: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-spring-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
+  --ease-in-out-smooth: cubic-bezier(0.65, 0, 0.35, 1);
+  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
+
+  --duration-micro: 120ms;
+  --duration-short: 180ms;
+  --duration-normal: 260ms;
+  --duration-smooth: 420ms;
+  --duration-slow: 700ms;
+}
+
+@layer utilities {
+  /* ── 3D tilt & perspective ── */
+  .perspective-1000 {
+    perspective: 1000px;
+  }
+  .preserve-3d {
+    transform-style: preserve-3d;
+  }
+  .backface-hidden {
+    backface-visibility: hidden;
+  }
+
+  /* ── Transitions: kinetic spring patterns ── */
+  .motion-spring {
+    transition-timing-function: var(--ease-spring-soft);
+    transition-duration: var(--duration-normal);
+  }
+  .motion-bounce {
+    transition-timing-function: var(--ease-spring-bounce);
+    transition-duration: var(--duration-smooth);
+  }
+
+  /* Glassmorphism surfaces */
+  .glass-card {
+    background: color-mix(in srgb, var(--card) 75%, transparent);
+    backdrop-filter: blur(16px) saturate(180%);
+    -webkit-backdrop-filter: blur(16px) saturate(180%);
+    border: 1px solid color-mix(in srgb, var(--border) 60%, transparent);
+  }
+
+  .glass-panel {
+    background: color-mix(in srgb, var(--background) 80%, transparent);
+    backdrop-filter: blur(20px) saturate(190%);
+    -webkit-backdrop-filter: blur(20px) saturate(190%);
+    border: 1px solid color-mix(in srgb, var(--border) 70%, transparent);
+  }
+
+  /* Gradient border highlight */
+  .border-glow {
+    position: relative;
+  }
+  .border-glow::before {
+    content: "";
+    position: absolute;
+    inset: -1px;
+    border-radius: inherit;
+    padding: 1px;
+    background: linear-gradient(135deg, color-mix(in srgb, var(--signal) 60%, transparent), transparent 60%);
+    -webkit-mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
+    mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
+    -webkit-mask-composite: xor;
+    mask-composite: exclude;
+    pointer-events: none;
+  }
+
+  /* Shimmer text sweep */
+  .animate-shimmer {
+    background: linear-gradient(
+      90deg,
+      color-mix(in srgb, var(--foreground) 70%, transparent) 0%,
+      var(--signal) 50%,
+      color-mix(in srgb, var(--foreground) 70%, transparent) 100%
+    );
+    background-size: 200% auto;
+    background-clip: text;
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    animation: shimmer-sweep 3s ease-in-out infinite;
+  }
+
+  /* Error shake */
+  .animate-shake {
+    animation: shake 450ms cubic-bezier(0.36, 0.07, 0.19, 0.97) both;
+  }
+
+  /* Pop-in (badges, counters, success checks) */
+  .animate-pop-in {
+    animation: pop-in 240ms var(--ease-spring-bounce) both;
+  }
+
+  /* Pulse glow on signal ring */
+  .animate-pulse-glow {
+    animation: pulse-glow 2.4s ease-in-out infinite;
+  }
+
+  /* 3D float */
+  .animate-float {
+    animation: float-3d 6s ease-in-out infinite;
+  }
+
+  /* Ambient glow orb */
+  .ambient-orb {
+    position: absolute;
+    border-radius: 9999px;
+    filter: blur(70px);
+    pointer-events: none;
+    opacity: 0.45;
+    animation: orb-pulse 8s ease-in-out infinite alternate;
+  }
+}
+
+@keyframes shimmer-sweep {
+  0% {
+    background-position: 200% center;
+  }
+  100% {
+    background-position: -200% center;
+  }
+}
+
+@keyframes shake {
+  10%, 90% {
+    transform: translate3d(-1px, 0, 0);
+  }
+  20%, 80% {
+    transform: translate3d(2px, 0, 0);
+  }
+  30%, 50%, 70% {
+    transform: translate3d(-4px, 0, 0);
+  }
+  40%, 60% {
+    transform: translate3d(4px, 0, 0);
+  }
+}
+
+@keyframes pop-in {
+  0% {
+    opacity: 0;
+    transform: scale(0.7) translateY(4px);
+  }
+  100% {
+    opacity: 1;
+    transform: scale(1) translateY(0);
+  }
+}
+
+@keyframes pulse-glow {
+  0%, 100% {
+    box-shadow: 0 0 0 0 color-mix(in srgb, var(--signal) 40%, transparent);
+  }
+  50% {
+    box-shadow: 0 0 0 14px color-mix(in srgb, var(--signal) 0%, transparent);
+  }
+}
+
+@keyframes float-3d {
+  0%, 100% {
+    transform: translateY(0) rotateX(0deg) rotateY(0deg);
+  }
+  50% {
+    transform: translateY(-8px) rotateX(2deg) rotateY(-3deg);
+  }
+}
+
+@keyframes orb-pulse {
+  0% {
+    transform: scale(1) translate(0, 0);
+    opacity: 0.35;
+  }
+  100% {
+    transform: scale(1.15) translate(20px, -20px);
+    opacity: 0.55;
+  }
+}
+
+@keyframes counter-flip {
+  0% {
+    opacity: 0;
+    transform: translateY(10px) rotateX(-45deg);
+    filter: blur(2px);
+  }
+  100% {
+    opacity: 1;
+    transform: translateY(0) rotateX(0);
+    filter: blur(0);
+  }
+}
+
+@keyframes text-swap {
+  0% {
+    opacity: 0;
+    transform: translateY(6px);
+    filter: blur(4px);
+  }
+  100% {
+    opacity: 1;
+    transform: translateY(0);
+    filter: blur(0);
+  }
+}
+
+@layer mlola.motion {
+  /* A light surface is already near white, so `screen` has no headroom and the
+     glare disappears. Tint the surface in light, lift it in dark. */
+  .ml-motion-tilt-glare {
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    pointer-events: none;
+    opacity: var(--mlola-glare-opacity, 0);
+    transition: opacity 240ms ease;
+    background: radial-gradient(
+      circle at var(--mlola-glare-x, 50%) var(--mlola-glare-y, 50%),
+      color-mix(in srgb, var(--ml-primary) 34%, transparent),
+      transparent 62%
+    );
+    mix-blend-mode: multiply;
+  }
+
+  [data-mode="dark"] .ml-motion-tilt-glare {
+    background: radial-gradient(
+      circle at var(--mlola-glare-x, 50%) var(--mlola-glare-y, 50%),
+      color-mix(in srgb, var(--ml-primary) 42%, transparent),
+      transparent 62%
+    );
+    mix-blend-mode: screen;
+  }
+
+  .ml-motion-counter {
+    display: inline-flex;
+    font-variant-numeric: tabular-nums;
+  }
+
+  .ml-motion-counter-digit {
+    display: inline-block;
+  }
+
+  .ml-motion-text {
+    display: inline-block;
+  }
+
+  .ml-motion-shimmer {
+    background: linear-gradient(
+      90deg,
+      color-mix(in srgb, var(--foreground) 70%, transparent) 0%,
+      var(--signal) 50%,
+      color-mix(in srgb, var(--foreground) 70%, transparent) 100%
+    );
+    background-size: 200% auto;
+    background-clip: text;
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    animation: shimmer-sweep 3s ease-in-out infinite;
+  }
+
+  .ml-motion-magnetic {
+    display: inline-block;
+  }
+
+  .ml-motion-origin-morph {
+    transform: translateZ(0);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .animate-shimmer,
+  .animate-shake,
+  .animate-pop-in,
+  .animate-pulse-glow,
+  .animate-float,
+  .ambient-orb,
+  .ml-motion-shimmer {
+    animation: none !important;
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@mlola-ui/motion",
+  "version": "1.0.0",
+  "description": "Reduced-motion-aware kinetic primitives for Mlola UI",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "sideEffects": [
+    "./motion.css"
+  ],
+  "files": [
+    "src",
+    "motion.css"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./physics": "./src/spring.ts",
+    "./raf": "./src/raf.ts",
+    "./motion.css": "./motion.css"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "license": "MIT",
+  "author": "Mlola",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mlolahq/mlola-ui.git",
+    "directory": "packages/motion"
+  },
+  "homepage": "https://ui.mlola.com",
+  "bugs": {
+    "url": "https://github.com/mlolahq/mlola-ui/issues"
+  },
+  "keywords": [
+    "mlola",
+    "ui",
+    "motion",
+    "spring",
+    "animation",
+    "css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./pointer-math";
+export * from "./primitives";
+export * from "./raf";
+export * from "./reduced-motion";
+export * from "./spring";
+export * from "./tilt-3d";

package/src/pointer-math.ts

@@ -0,0 +1,54 @@
+export interface PointerKinetics {
+  x: number;
+  y: number;
+  deltaX: number;
+  deltaY: number;
+  velocityX: number;
+  velocityY: number;
+  speed: number;
+  angle: number;
+  timestamp: number;
+  pointerType: string;
+  active: boolean;
+}
+
+export const idlePointerKinetics: PointerKinetics = Object.freeze({
+  x: 0,
+  y: 0,
+  deltaX: 0,
+  deltaY: 0,
+  velocityX: 0,
+  velocityY: 0,
+  speed: 0,
+  angle: 0,
+  timestamp: 0,
+  pointerType: "",
+  active: false,
+});
+
+export function calculatePointerKinetics(
+  previous: PointerKinetics,
+  point: Pick<PointerKinetics, "x" | "y" | "timestamp" | "pointerType">,
+  smoothing = 0.25
+): PointerKinetics {
+  const deltaX = previous.active ? point.x - previous.x : 0;
+  const deltaY = previous.active ? point.y - previous.y : 0;
+  const elapsed = previous.active
+    ? Math.max(1, Math.min(64, point.timestamp - previous.timestamp))
+    : 16;
+  const instantX = (deltaX / elapsed) * 1000;
+  const instantY = (deltaY / elapsed) * 1000;
+  const blend = Math.max(0, Math.min(1, smoothing));
+  const velocityX = previous.velocityX + (instantX - previous.velocityX) * blend;
+  const velocityY = previous.velocityY + (instantY - previous.velocityY) * blend;
+  return {
+    ...point,
+    deltaX,
+    deltaY,
+    velocityX,
+    velocityY,
+    speed: Math.hypot(velocityX, velocityY),
+    angle: Math.atan2(velocityY, velocityX),
+    active: true,
+  };
+}

package/src/primitives.tsx

@@ -0,0 +1,230 @@
+"use client";
+
+import * as React from "react";
+import { useReducedMotion } from "./reduced-motion";
+import { createSpringAnimation, springPresets } from "./spring";
+
+function joinClasses(...values: Array<string | false | null | undefined>) {
+  return values.filter(Boolean).join(" ");
+}
+
+export interface AnimatedCounterProps extends React.HTMLAttributes<HTMLSpanElement> {
+  value: number | string;
+  stagger?: number;
+}
+
+export function AnimatedCounter({
+  value,
+  className,
+  stagger = 35,
+  ...props
+}: AnimatedCounterProps) {
+  const reducedMotion = useReducedMotion();
+  const text = String(value);
+  return (
+    <span
+      {...props}
+      className={joinClasses("ml-motion-counter", className)}
+      aria-label={props["aria-label"] ?? text}
+    >
+      {Array.from(text).map((character, index) => (
+        <span
+          aria-hidden="true"
+          key={`${index}-${character}`}
+          className="ml-motion-counter-digit"
+          style={
+            reducedMotion
+              ? undefined
+              : {
+                  animation: "counter-flip 280ms cubic-bezier(0.34, 1.56, 0.64, 1) both",
+                  animationDelay: `${index * stagger}ms`,
+                }
+          }
+        >
+          {character}
+        </span>
+      ))}
+    </span>
+  );
+}
+
+export interface TextSwapProps extends React.HTMLAttributes<HTMLSpanElement> {
+  text: string;
+}
+
+export function TextSwap({ text, className, style, ...props }: TextSwapProps) {
+  const reducedMotion = useReducedMotion();
+  return (
+    <span
+      {...props}
+      key={text}
+      className={joinClasses("ml-motion-text", className)}
+      style={{
+        animation: reducedMotion
+          ? undefined
+          : "text-swap 240ms cubic-bezier(0.16, 1, 0.3, 1) both",
+        ...style,
+      }}
+    >
+      {text}
+    </span>
+  );
+}
+
+export function ShimmerText({
+  children,
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLSpanElement>) {
+  const reducedMotion = useReducedMotion();
+  return (
+    <span
+      {...props}
+      className={joinClasses(!reducedMotion && "ml-motion-shimmer", className)}
+    >
+      {children}
+    </span>
+  );
+}
+
+export interface MagneticProps extends React.HTMLAttributes<HTMLDivElement> {
+  pull?: number;
+}
+
+export const Magnetic = React.forwardRef<HTMLDivElement, MagneticProps>(
+  (
+    {
+      children,
+      pull = 0.25,
+      className,
+      style,
+      onPointerMove,
+      onPointerLeave,
+      onPointerCancel,
+      ...props
+    },
+    forwardedRef
+  ) => {
+    const reducedMotion = useReducedMotion();
+    const nodeRef = React.useRef<HTMLDivElement>(null);
+    const offset = React.useRef({ x: 0, y: 0 });
+    const setRef = React.useCallback(
+      (node: HTMLDivElement | null) => {
+        nodeRef.current = node;
+        if (typeof forwardedRef === "function") forwardedRef(node);
+        else if (forwardedRef) forwardedRef.current = node;
+      },
+      [forwardedRef]
+    );
+
+    // The pull is a real spring, not a CSS transition: it can be interrupted
+    // mid-flight, and the loop stops the moment it comes to rest.
+    const paint = React.useCallback(() => {
+      const node = nodeRef.current;
+      if (!node) return;
+      node.style.transform = `translate3d(${offset.current.x.toFixed(2)}px, ${offset.current.y.toFixed(2)}px, 0)`;
+    }, []);
+    const springX = React.useMemo(
+      () =>
+        createSpringAnimation({
+          options: springPresets.snappy,
+          onUpdate: (value) => {
+            offset.current.x = value;
+            paint();
+          },
+        }),
+      [paint]
+    );
+    const springY = React.useMemo(
+      () =>
+        createSpringAnimation({
+          options: springPresets.snappy,
+          onUpdate: (value) => {
+            offset.current.y = value;
+            paint();
+          },
+        }),
+      [paint]
+    );
+
+    React.useEffect(
+      () => () => {
+        springX.stop();
+        springY.stop();
+      },
+      [springX, springY]
+    );
+
+    const moveTo = (x: number, y: number) => {
+      springX.setTarget(x);
+      springY.setTarget(y);
+    };
+    const reset = () => moveTo(0, 0);
+
+    const handlePointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
+      onPointerMove?.(event);
+      const node = nodeRef.current;
+      if (event.defaultPrevented || reducedMotion || event.pointerType === "touch" || !node) return;
+      const rect = node.getBoundingClientRect();
+      moveTo(
+        (event.clientX - (rect.left + rect.width / 2)) * pull,
+        (event.clientY - (rect.top + rect.height / 2)) * pull
+      );
+    };
+
+    React.useEffect(() => {
+      if (!reducedMotion) return;
+      springX.set(0);
+      springY.set(0);
+    }, [reducedMotion, springX, springY]);
+
+    return (
+      <div
+        {...props}
+        ref={setRef}
+        onPointerMove={handlePointerMove}
+        onPointerLeave={(event) => {
+          onPointerLeave?.(event);
+          reset();
+        }}
+        onPointerCancel={(event) => {
+          onPointerCancel?.(event);
+          reset();
+        }}
+        className={joinClasses("ml-motion-magnetic", className)}
+        style={{
+          transform: "translate3d(0, 0, 0)",
+          willChange: reducedMotion ? undefined : "transform",
+          ...style,
+        }}
+      >
+        {children}
+      </div>
+    );
+  }
+);
+Magnetic.displayName = "Magnetic";
+
+export interface OriginMorphProps extends React.HTMLAttributes<HTMLDivElement> {
+  isOpen: boolean;
+}
+
+export function OriginMorph({
+  isOpen,
+  children,
+  className,
+  style,
+  ...props
+}: OriginMorphProps) {
+  const reducedMotion = useReducedMotion();
+  if (!isOpen) return null;
+  return (
+    <div
+      {...props}
+      className={joinClasses("ml-motion-origin-morph", !reducedMotion && "ml-animate-pop", className)}
+      style={style}
+    >
+      {children}
+    </div>
+  );
+}

package/src/raf.ts

@@ -0,0 +1,52 @@
+export type FrameTask = (timestamp: number) => void;
+
+const queue = new Map<FrameTask, FrameTask>();
+let frameId: number | null = null;
+
+function flush(timestamp: number): void {
+  frameId = null;
+  const tasks = Array.from(queue.values());
+  queue.clear();
+  for (const task of tasks) task(timestamp);
+}
+
+export function scheduleFrame(task: FrameTask): () => void {
+  queue.set(task, task);
+  if (frameId === null) {
+    if (typeof requestAnimationFrame === "undefined") {
+      flush(typeof performance === "undefined" ? Date.now() : performance.now());
+    } else {
+      frameId = requestAnimationFrame(flush);
+    }
+  }
+  return () => {
+    queue.delete(task);
+    if (queue.size === 0 && frameId !== null && typeof cancelAnimationFrame !== "undefined") {
+      cancelAnimationFrame(frameId);
+      frameId = null;
+    }
+  };
+}
+
+export function createRafBatcher<T>(apply: (value: T, timestamp: number) => void) {
+  let latest: T;
+  let queued = false;
+  let cancel = () => {};
+
+  return {
+    schedule(value: T) {
+      latest = value;
+      if (queued) return;
+      queued = true;
+      const task = (timestamp: number) => {
+        queued = false;
+        apply(latest, timestamp);
+      };
+      cancel = scheduleFrame(task);
+    },
+    cancel() {
+      queued = false;
+      cancel();
+    },
+  };
+}

package/src/reduced-motion.ts

@@ -0,0 +1,20 @@
+"use client";
+
+import * as React from "react";
+
+const query = "(prefers-reduced-motion: reduce)";
+
+function subscribe(listener: () => void): () => void {
+  if (typeof window === "undefined") return () => {};
+  const media = window.matchMedia(query);
+  media.addEventListener("change", listener);
+  return () => media.removeEventListener("change", listener);
+}
+
+function snapshot(): boolean {
+  return typeof window !== "undefined" && window.matchMedia(query).matches;
+}
+
+export function useReducedMotion(): boolean {
+  return React.useSyncExternalStore(subscribe, snapshot, () => false);
+}

package/src/spring.ts

@@ -0,0 +1,134 @@
+export interface SpringOptions {
+  stiffness?: number;
+  damping?: number;
+  mass?: number;
+  restSpeed?: number;
+  restDelta?: number;
+  maxDelta?: number;
+}
+
+export interface SpringState {
+  value: number;
+  velocity: number;
+}
+
+export interface SpringStep extends SpringState {
+  done: boolean;
+}
+
+export const springPresets = {
+  gentle: { stiffness: 170, damping: 26, mass: 1 },
+  snappy: { stiffness: 320, damping: 28, mass: 0.9 },
+  bouncy: { stiffness: 260, damping: 18, mass: 1 },
+} as const satisfies Record<string, SpringOptions>;
+
+export function integrateSpring(
+  state: SpringState,
+  target: number,
+  deltaMs: number,
+  {
+    stiffness = 240,
+    damping = 26,
+    mass = 1,
+    restSpeed = 0.01,
+    restDelta = 0.01,
+    maxDelta = 32,
+  }: SpringOptions = {}
+): SpringStep {
+  const safeMass = Math.max(0.001, mass);
+  let remaining = Math.max(0, Math.min(maxDelta, deltaMs)) / 1000;
+  let value = state.value;
+  let velocity = state.velocity;
+
+  // Fixed substeps make the semi-implicit Euler integration stable after slow frames.
+  while (remaining > 0) {
+    const step = Math.min(remaining, 1 / 120);
+    const springForce = -stiffness * (value - target);
+    const dampingForce = -damping * velocity;
+    velocity += ((springForce + dampingForce) / safeMass) * step;
+    value += velocity * step;
+    remaining -= step;
+  }
+
+  const done = Math.abs(velocity) <= restSpeed && Math.abs(target - value) <= restDelta;
+  return done
+    ? { value: target, velocity: 0, done: true }
+    : { value, velocity, done: false };
+}
+
+export interface SpringAnimation {
+  setTarget(target: number): void;
+  set(value: number): void;
+  stop(): void;
+  get(): SpringState & { target: number; running: boolean };
+}
+
+export function createSpringAnimation({
+  from = 0,
+  to = from,
+  options,
+  onUpdate,
+  onComplete,
+}: {
+  from?: number;
+  to?: number;
+  options?: SpringOptions;
+  onUpdate: (value: number, state: SpringState) => void;
+  onComplete?: (value: number) => void;
+}): SpringAnimation {
+  let state: SpringState = { value: from, velocity: 0 };
+  let target = to;
+  let running = false;
+  let frame: number | null = null;
+  let previousTime = 0;
+
+  const stop = () => {
+    if (frame !== null && typeof cancelAnimationFrame !== "undefined") {
+      cancelAnimationFrame(frame);
+    }
+    frame = null;
+    running = false;
+    previousTime = 0;
+  };
+
+  const tick = (timestamp: number) => {
+    const delta = previousTime === 0 ? 1000 / 60 : timestamp - previousTime;
+    previousTime = timestamp;
+    const next = integrateSpring(state, target, delta, options);
+    state = { value: next.value, velocity: next.velocity };
+    onUpdate(state.value, state);
+    if (next.done) {
+      stop();
+      onComplete?.(state.value);
+    } else {
+      frame = requestAnimationFrame(tick);
+    }
+  };
+
+  const start = () => {
+    if (running || Object.is(state.value, target)) return;
+    running = true;
+    if (typeof requestAnimationFrame === "undefined") {
+      state = { value: target, velocity: 0 };
+      onUpdate(target, state);
+      running = false;
+      onComplete?.(target);
+      return;
+    }
+    frame = requestAnimationFrame(tick);
+  };
+
+  return {
+    setTarget(nextTarget) {
+      target = nextTarget;
+      start();
+    },
+    set(value) {
+      stop();
+      state = { value, velocity: 0 };
+      onUpdate(value, state);
+    },
+    stop,
+    get: () => ({ ...state, target, running }),
+  };
+}

package/src/tilt-3d.tsx

@@ -0,0 +1,139 @@
+"use client";
+
+import * as React from "react";
+import { createRafBatcher } from "./raf";
+import { useReducedMotion } from "./reduced-motion";
+
+export interface Tilt3DProps extends React.HTMLAttributes<HTMLDivElement> {
+  maxTilt?: number;
+  perspective?: number;
+  glare?: boolean;
+  scale?: number;
+}
+
+interface TiltFrame {
+  x: number;
+  y: number;
+  glareX: number;
+  glareY: number;
+  active: boolean;
+}
+
+export const Tilt3D = React.forwardRef<HTMLDivElement, Tilt3DProps>(
+  (
+    {
+      maxTilt = 12,
+      perspective = 900,
+      glare = true,
+      scale = 1.02,
+      className,
+      style,
+      children,
+      onPointerMove,
+      onPointerLeave,
+      onPointerCancel,
+      ...props
+    },
+    forwardedRef
+  ) => {
+    const cardRef = React.useRef<HTMLDivElement>(null);
+    const reducedMotion = useReducedMotion();
+    const setRef = React.useCallback(
+      (node: HTMLDivElement | null) => {
+        cardRef.current = node;
+        if (typeof forwardedRef === "function") forwardedRef(node);
+        else if (forwardedRef) forwardedRef.current = node;
+      },
+      [forwardedRef]
+    );
+
+    const batcher = React.useMemo(
+      () =>
+        createRafBatcher<TiltFrame>((frame) => {
+          const node = cardRef.current;
+          if (!node) return;
+          node.style.transform = frame.active
+            ? `perspective(${perspective}px) rotateX(${frame.x.toFixed(2)}deg) rotateY(${frame.y.toFixed(2)}deg) scale3d(${scale}, ${scale}, ${scale})`
+            : `perspective(${perspective}px) rotateX(0deg) rotateY(0deg) scale3d(1, 1, 1)`;
+          node.style.transition = frame.active
+            ? "transform 80ms linear"
+            : "transform 400ms cubic-bezier(0.16, 1, 0.3, 1)";
+          node.style.setProperty("--mlola-glare-x", `${frame.glareX}%`);
+          node.style.setProperty("--mlola-glare-y", `${frame.glareY}%`);
+          node.style.setProperty("--mlola-glare-opacity", frame.active && glare ? "1" : "0");
+        }),
+      [glare, perspective, scale]
+    );
+
+    React.useEffect(() => () => batcher.cancel(), [batcher]);
+
+    const reset = () => {
+      batcher.schedule({ x: 0, y: 0, glareX: 50, glareY: 50, active: false });
+    };
+
+    const handlePointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
+      onPointerMove?.(event);
+      const node = cardRef.current;
+      if (
+        event.defaultPrevented ||
+        reducedMotion ||
+        event.pointerType === "touch" ||
+        !node
+      ) return;
+      const rect = node.getBoundingClientRect();
+      if (rect.width <= 0 || rect.height <= 0) return;
+      const x = Math.max(0, Math.min(1, (event.clientX - rect.left) / rect.width));
+      const y = Math.max(0, Math.min(1, (event.clientY - rect.top) / rect.height));
+      batcher.schedule({
+        x: (y - 0.5) * -maxTilt,
+        y: (x - 0.5) * maxTilt,
+        glareX: x * 100,
+        glareY: y * 100,
+        active: true,
+      });
+    };
+
+    const handlePointerLeave = (event: React.PointerEvent<HTMLDivElement>) => {
+      onPointerLeave?.(event);
+      reset();
+    };
+
+    const handlePointerCancel = (event: React.PointerEvent<HTMLDivElement>) => {
+      onPointerCancel?.(event);
+      reset();
+    };
+
+    React.useEffect(() => {
+      if (reducedMotion) reset();
+    }, [reducedMotion]);
+
+    return (
+      <div
+        {...props}
+        ref={setRef}
+        onPointerMove={handlePointerMove}
+        onPointerLeave={handlePointerLeave}
+        onPointerCancel={handlePointerCancel}
+        className={className}
+        style={{
+          transform: `perspective(${perspective}px) rotateX(0deg) rotateY(0deg) scale3d(1, 1, 1)`,
+          transformStyle: "preserve-3d",
+          transition: "transform 400ms cubic-bezier(0.16, 1, 0.3, 1)",
+          willChange: reducedMotion ? undefined : "transform",
+          position: "relative",
+          ...style,
+        }}
+      >
+        {children}
+        {glare && (
+          <span
+            aria-hidden="true"
+            className="ml-motion-tilt-glare"
+            style={reducedMotion ? { transition: "none" } : undefined}
+          />
+        )}
+      </div>
+    );
+  }
+);
+Tilt3D.displayName = "Tilt3D";