Architecture

# The DOM Firewall

The DOM Firewall is a core principle: all DOM‑scraping happens when a hover starts, never inside the animation loop. Calling getBoundingClientRect or reading computed styles during a requestAnimationFrame loop causes layout thrashing. Supermouse avoids this by caching element metadata the moment a hover begins.

# Registering Hover Targets

For the core to know when to scrape data, your plugin must declare what CSS selectors it cares about. You do this in your plugin's install method using registerHoverTarget.

export default {
  name: 'my-plugin',
  install(app) {
    // Tells the core to scrape data-my-plugin attributes on hover
    // and hides the native cursor for these elements.
    app.registerHoverTarget('[data-my-plugin]');
  },
  update(app) {
    if (app.state.interaction['my-plugin']) {
      // React to the scraped state
    }
  }
}

Calling registerHoverTarget does two critical things under the hood:

• It adds the selector to the internal list used for element.closest(selectors) detection to trigger hover states.
• It injects a global stylesheet (e.g., .supermouse-scope-0 [data-my-plugin] { cursor: none !important; }) to hide the native cursor.

# Hover Detection & closest()

Internally, all registered hover selectors are joined into a single string (e.g. "a, button, [data-supermouse-stick]"). This string is passed to element.closest(selectors), which finds the nearest ancestor (including self) that matches any of the selectors.

<!-- Register: '[data-hover] a' -->
<div data-hover>
  <a href="#">Hover me</a>  <!-- ✅ matched: <a> inside [data-hover] -->
</div>

<!-- Register: 'a [data-hover]' (WRONG mental model) -->
<a href="#">
  <span data-hover>text</span> <!-- ❗ closest('a [data-hover]') matches the <a>, not the <span> -->
</a>

# Interaction State Resolution

When the user hovers over a registered element, the engine evaluates properties in the following priority order (highest to lowest), merging them into a single flat object stored at state.interaction:

1. Custom resolveInteraction() function: User-provided custom logic.
2. Per-element data-[prefix]-* attributes: HTML overrides on specific nodes.
3. CSS selector rules: Global mappings defined in options.rules.

Parsing behavior: The prefix (configured via options.dataPrefix, defaults to "supermouse") is stripped, and keys are camelCased (data-[prefix]-my-key becomes interaction.myKey). Empty attributes like data-[prefix]-stick resolve to boolean true.

new Supermouse({
  resolveInteraction(el) {
    return {
      color: el.style.color,
      magnetic: el.hasAttribute("data-magnetic")
    };
  }
});

# State & Plugin Coordination

Plugins are isolated by design. They do not import or call methods on each other. Instead, they coordinate entirely by reading and writing to the central MouseState object.

# The Shape State Contract

state.shape is a read-mostly cache for the current cursor geometry (width, height, borderRadius). It is intended to be:

• Written by one logic plugin per context (e.g., a "stick" plugin that computes the element's rect) early in the pipeline.
• Read by visual plugins (ring, morph) to avoid redundant getBoundingClientRect calls.
• Set back to null when the condition that produced the shape ends.

# Velocity & Angle Semantics

It is a common misconception that state.velocity represents the true physical speed of the user's mouse. It does not. As seen in the loop pipeline above, velocity is derived directly from the mathematical difference between the target and the smooth position. state.angle is the direction (in degrees) of that same tracking error vector, computed via atan2(velocity.y, velocity.x).

velocity.x = target.x - smooth.x
velocity.y = target.y - smooth.y
angle = atan2(velocity.y, velocity.x) * (180 / PI)

This makes velocity a vector representing the spring tracking error (or distance to destination). This is highly useful for squishy, organic animations where you want the cursor to stretch based on how far behind it is.

If your plugin specifically requires the raw pixel delta per frame (true mouse speed), you must track it manually against the un-smoothed state.pointer:

// Inside your plugin
let lastPointer = { x: 0, y: 0 };

update(app) {
  // Calculate actual pixel movement per frame
  const dx = app.state.pointer.x - lastPointer.x;
  const dy = app.state.pointer.y - lastPointer.y;

  lastPointer = { ...app.state.pointer };
}

# Utilities & Helpers

# ValueOrGetter<T>

Many plugin options accept either a static value or a reactive function (state: MouseState) => T. The core library provides a normalize helper to easily evaluate these inside your update hooks:

import { normalize } from "@supermousejs/utils";

// In your plugin's install/update method:
const size = normalize(options.size, 16); // If options.size is undefined, defaults to 16
// 'size' is now guaranteed to be a resolved number,
// even if options.size was passed as (state) => number

# Lifecycle & Error Handling

# Native Cursor Visibility Control

Three layers control whether the real cursor is shown or hidden:

1. Global options.hideCursor: If false, the native cursor is never hidden.
2. Automatic detection: Based on state.isNative (e.g. hovering over native text inputs).
3. Forced override: Using app.setNativeCursor("hide" | "show" | "auto") to bypass automatic logic.

// ❌ BAD: selector starts with a combinator
'> .child'   → becomes '.supermouse-scope-0 > .child'
// ✅ GOOD: simple selectors only
'.child', '[data-my-plugin]'

# Execution Flags (enableTouch & autoStart)

• enableTouch (default: false): When true, touch events are processed instead of ignored. Experimental.
• autoStart (default: true): If false, the animation loop will not start until you explicitly call app.start(). Useful when waiting for additional setup.

# Plugin Error Handling

Supermouse wraps plugin execution so that one buggy plugin won't crash the entire cursor loop. If a plugin throws an error in its install() or update() hooks, the core catches it, logs the error to the console, disables the plugin (isEnabled = false), and attempts to safely run its onDisable hook.