Introduction
Supermouse is a high-performance cursor engine for the modern web, designed to isolate cursor intent from cursor rendering.
Conventional cursor libraries treat cursors as standard UI elements, tying their coordinates to framework reactive state (React, Vue) or relying on heavy animation wrappers (like GSAP) that operate on CPU layout properties. This coupling introduces input lag and rendering delays. Supermouse runs a standalone, deterministic animation loop (60–120Hz) managed directly via requestAnimationFrame.
By separating physics interpolation from paint routines and enforcing a strict DOM Firewall, Supermouse enables fluid pointer dynamics without layout thrashing.
The Traditional Problems
- 01.
The Double Cursor Glitch. Hiding the OS cursor via standard CSS is fragile; inputs, dynamic targets, and user-agent stylesheets regularly force it back, creating flickering.
- 02.
Input Lag. Framework state updates are asynchronous. Driving coordinates through a virtual DOM deferment trails the native pointer by 1–2 frames.
- 03.
Coupled Architectures. Mixing physical tracking bounds with visual render elements limits layout composability and stops developer modifications.
The Supermouse Solution
- 01.
The Stage Controller. Supermouse injects a scoped, high-specificity stylesheet to suppress native pointers over registered regions, utilizing granularity controls to show or hide the OS pointer.
- 02.
Direct GPU Transforms. By bypassing the virtual DOM, updates apply hardware-accelerated CSS translation vectors directly onto target layers.
- 03.
Decoupled Pipeline. Logic layers compute coordinates, physics smooths movement, and visuals render. Plugins hook into specific stages without side-effects.
Core Philosophy
Physics models track coordinate intent on state.target, while visual plugins read from the interpolated state.smooth values. This decoupling lets plugins modify tracking bounds dynamically.
The core engine registers plugins on a chainable stack via app.use(), coordinating execution priority. You can swap, enable, or disable layers at runtime.
Coarse pointers (touch devices) trigger automatic hibernation via autoDisableOnMobile. Operating system preferences for state.reducedMotion instantly skip floaty physics to prevent motion sickness.