@seithr/motion

Closed-form analytical spring ODE physics, zero-allocation gesture recognition, and 120fps hardware-accelerated animations.

Overview

@seithr/motion implements closed-form analytical mass-spring-damper Ordinary Differential Equation (ODE) solvers. Unlike numerical approximations (such as Euler or Verlet integration), closed-form solutions guarantee zero numerical drift and absolute stability regardless of frame timing jitter. All animations execute via compositor transforms (translate3d), avoiding expensive browser layout reflows.

Installation

bun add seithr
# or using npm
npm install seithr

Features

• Closed-Form Analytical ODE Physics:
  • createSpring: 1D analytical spring controller responding with physical mass, stiffness, and damping.
  • createSpringVec2: 2D coupled spring physics for coordinates, pointers, and spatial elements.
• Inertia & Momentum Engine:
  • createInertia: Smooth deceleration momentum decay with customizable friction coefficient.
• Zero-Allocation Gesture Decoders:
  • createDraggable: Pointer gesture tracker with boundary resistance, momentum fling, and zero allocations on steady-state drag frames.
• Hardware-Accelerated: Direct GPU compositor updates with automatic prefers-reduced-motion compliance.

Usage

import { createSignal } from "seithr"
import { createDraggable, createSpring } from "seithr/motion"

function SpringCard() {
  const [cardEl, setCardEl] = createSignal<HTMLDivElement | null>(null)

  const spring = createSpring(0, {
    stiffness: 170,
    damping: 26,
    mass: 1,
  })

  // Dragging gesture with boundary restorative physics
  const draggable = createDraggable(cardEl, {
    bounds: { left: 0, right: 300, top: 0, bottom: 0, mode: "rubberband" },
    onDrag: (e) => {
      console.log("Current position:", e.x, e.y)
    },
  })

  return (
    <div
      ref={setCardEl}
      style={{
        transform: `translate3d(${spring.value() + draggable.x()}px, ${draggable.y()}px, 0px)`,
        cursor: "grab",
      }}
    >
      Interactive Draggable Card
    </div>
  )
}