@supermousejs/core 2.1.0 → 2.3.0

package/src/__tests__/setup.ts

@@ -0,0 +1,13 @@
+Object.defineProperty(window, "matchMedia", {
+  writable: true,
+  value: (query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false
+  })
+});

package/src/__tests__/supermouse.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { Supermouse } from "../Supermouse";
+
+describe("Supermouse core", () => {
+  it("registers and looks up plugins by name", () => {
+    const app = new Supermouse();
+
+    const plugin = {
+      name: "test-plugin",
+      install() {},
+      update() {}
+    };
+
+    app.use(plugin);
+
+    expect(app.getPlugin("test-plugin")).toBe(plugin);
+    expect(app.getPlugin("missing-plugin")).toBeUndefined();
+  });
+});

package/src/types.ts

@@ -32,21 +32,21 @@ export interface InteractionState {
 }
 
 export interface MouseState {
-  /** The raw position of the input pointer (mouse/touch). */
+  /** The raw position from the latest pointer event, before smoothing is applied. */
   pointer: MousePosition;
-  /** The target position the cursor logic wants to reach. */
+  /** The current goal position that the core loop is driving toward. */
   target: MousePosition;
   /** The smoothed/interpolated position used for rendering. */
   smooth: MousePosition;
-  /** The current velocity vector of the smooth position. */
+  /** The current movement vector derived from the smoothed state. */
   velocity: MousePosition;
-  /** The angle of movement in degrees. Calculated from velocity. */
+  /** The current movement angle in degrees, derived from velocity. */
   angle: number;
   /** Whether the pointer is currently pressed down. */
   isDown: boolean;
   /** Whether the pointer is currently hovering over a registered interactive element. */
   isHover: boolean;
-  /** Whether the native cursor is currently forced visible by internal logic (e.g. input elements). */
+  /** Whether the runtime has temporarily restored the native cursor due to native-input heuristics. */
   isNative: boolean;
   /**
    * If set, this overrides all auto-detection logic.
@@ -95,20 +95,24 @@ export interface SupermouseOptions {
   autoDisableOnMobile?: boolean;
   /**
    * Strategy for detecting when to fallback to the native cursor.
-   * - `true` / `'auto'`: Checks both HTML tags and CSS cursor styles (Accurate but slower).
+   * - `'auto'`: Checks both HTML tags and CSS cursor styles (Accurate but slower).
    * - `'tag'`: Checks only semantic tags like <input>, <textarea> (Fastest, prevents layout thrashing).
    * - `'css'`: Checks only computed CSS cursor styles (Slow, triggers reflow).
-   * - `false`: Never fallback to native cursor.
+   * - `null`: Never fallback to native cursor.
+   *
    * @default 'auto'
    */
-  ignoreOnNative?: boolean | NativeIgnoreStrategy;
+  ignoreOnNative?: NativeIgnoreStrategy | null;
   /**
-   * Whether to hide the native cursor via global CSS injection.
+   * Whether to hide the native cursor via scoped CSS injection on the container.
+   * When enabled, the stage toggles `cursor: none` on the configured container and
+   * on registered hover targets.
    * @default true
    */
   hideCursor?: boolean;
   /**
-   * Whether to hide the custom cursor when the mouse leaves the browser window.
+   * Whether to hide the custom cursor when the pointer leaves the browser viewport.
+   * When enabled the runtime clears the cursor back to an off-screen position to avoid stale hover state.
    * @default true
    */
   hideOnLeave?: boolean;
@@ -128,18 +132,29 @@ export interface SupermouseOptions {
   autoStart?: boolean;
   /**
    * Semantic rules mapping CSS selectors to interaction state.
+   * Rules are evaluated against hovered elements and merged into `state.interaction`.
+   * Matching data attributes on the same element are also read and can override or enrich the final object.
    * @example { 'button': { icon: 'pointer' } }
    */
   rules?: Record<string, InteractionState>;
   /**
    * Custom strategy to resolve interaction state from a hovered element.
-   * Overrides the default data-attribute scraping.
+   * When provided, this callback bypasses the default `rules` + `data-[prefix]-*` scraping and
+   * returns the interaction payload directly for the current hover target.
    */
   resolveInteraction?: (target: HTMLElement) => InteractionState;
+  /**
+   * The prefix used for data attributes to store hover metadata.
+   * For example, if dataPrefix is "supermouse", then the attribute would be "data-supermouse-*".
+   * This allows for multiple instances of Supermouse to coexist without conflicting data attributes.
+   * @default "supermouse"
+   */
+  dataPrefix?: string;
 }
 
 /**
  * Allows a property to be a static value or a function that returns the value based on state.
+ * This is primarily useful for plugin option definitions that should react to the current runtime state.
  */
 export type ValueOrGetter<T> = T | ((state: MouseState) => T);
 
@@ -156,7 +171,7 @@ export interface SupermousePlugin {
 
   /** Called when `app.use()` is executed. */
   install?: (instance: Supermouse) => void;
-  /** Called on every animation frame. */
+  /** Called on every animation frame with the frame delta time in milliseconds. */
   update?: (instance: Supermouse, deltaTime: number) => void;
   /** Called when the plugin is removed or the app is destroyed. */
   destroy?: (instance: Supermouse) => void;

package/tsconfig.json

@@ -1,9 +1,9 @@
-{
-  "extends": "../../tsconfig.composite-lib.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist"
-  },
-  "include": ["src"],
-  "references": []
-}
+{
+  "extends": "../../tsconfig.composite-lib.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": []
+}

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    globals: true,
+    setupFiles: ["src/__tests__/setup.ts"],
+    include: ["src/**/*.test.ts"]
+  }
+});

package/src/systems/Input.ts

@@ -1,231 +0,0 @@
-import type { MouseState, SupermouseOptions } from "../types";
-
-/**
- * This class listens to browser events and mutates the shared `MouseState` object.
- *
- * @internal This is an internal system class instantiated by `Supermouse`.
- */
-export class Input {
-  private mediaQueryList?: MediaQueryList;
-  private mediaQueryHandler?: (e: MediaQueryListEvent) => void;
-  private motionQuery?: MediaQueryList;
-
-  /**
-   * Master switch for input processing.
-   * Toggled by `Supermouse.enable()`/`disable()` or automatically by device capability checks.
-   */
-  public isEnabled: boolean = true;
-
-  constructor(
-    private state: MouseState,
-    private options: SupermouseOptions,
-    private getHoverSelector: () => string,
-    private onEnableChange: (enabled: boolean) => void
-  ) {
-    this.checkDeviceCapability();
-    this.checkMotionPreference();
-    this.bindEvents();
-  }
-
-  /**
-   * Automatically disables the custom cursor on devices without fine pointer control.
-   * Relies on `matchMedia('(pointer: fine)')`.
-   */
-  private checkDeviceCapability() {
-    if (!this.options.autoDisableOnMobile) return;
-
-    this.mediaQueryList = window.matchMedia("(pointer: fine)");
-    this.updateEnabledState(this.mediaQueryList.matches);
-
-    this.mediaQueryHandler = (e: MediaQueryListEvent) => {
-      this.updateEnabledState(e.matches);
-    };
-    this.mediaQueryList.addEventListener("change", this.mediaQueryHandler);
-  }
-
-  /**
-   * Checks for `prefers-reduced-motion`.
-   * If true, the core physics engine will switch to instant snapping (high damping) to avoid motion sickness.
-   */
-  private checkMotionPreference() {
-    this.motionQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
-    this.state.reducedMotion = this.motionQuery.matches;
-
-    this.motionQuery.addEventListener("change", (e) => {
-      this.state.reducedMotion = e.matches;
-    });
-  }
-
-  private updateEnabledState(enabled: boolean) {
-    this.isEnabled = enabled;
-    this.onEnableChange(enabled);
-  }
-
-  private parseDOMInteraction(element: HTMLElement) {
-    if (this.options.resolveInteraction) {
-      this.state.interaction = this.options.resolveInteraction(element);
-      return;
-    }
-
-    const data: Record<string, string | boolean> = {};
-
-    if (this.options.rules) {
-      for (const [selector, rules] of Object.entries(this.options.rules)) {
-        if (element.matches(selector)) {
-          Object.assign(data, rules);
-        }
-      }
-    }
-
-    const dataset = element.dataset;
-    for (const key in dataset) {
-      if (key.startsWith("supermouse")) {
-        const prop = key.slice(10);
-        if (prop) {
-          const cleanKey = prop.charAt(0).toLowerCase() + prop.slice(1);
-          const val = dataset[key];
-          if (val !== undefined) {
-            data[cleanKey] = val === "" ? true : val;
-          }
-        }
-      }
-    }
-
-    this.state.interaction = data;
-  }
-
-  private handleMove(e: PointerEvent) {
-    if (!this.isEnabled) return;
-
-    if (this.options.autoDisableOnMobile && e.pointerType === "touch") return;
-
-    let x = e.clientX;
-    let y = e.clientY;
-
-    if (this.options.container && this.options.container !== document.body) {
-      const rect = this.options.container.getBoundingClientRect();
-      x -= rect.left;
-      y -= rect.top;
-    }
-
-    this.state.pointer.x = x;
-    this.state.pointer.y = y;
-
-    if (!this.state.hasReceivedInput) {
-      this.state.hasReceivedInput = true;
-      this.state.target.x = this.state.smooth.x = x;
-      this.state.target.y = this.state.smooth.y = y;
-    }
-  }
-
-  private handleDown(): void {
-    if (this.isEnabled) this.state.isDown = true;
-  }
-
-  private handleUp(): void {
-    if (this.isEnabled) this.state.isDown = false;
-  }
-
-  private handleMouseOver(e: MouseEvent) {
-    if (!this.isEnabled) return;
-    const target = e.target as HTMLElement;
-
-    if (target.closest("[data-supermouse-ignore]")) {
-      this.state.isNative = true;
-      return;
-    }
-
-    const selector = this.getHoverSelector();
-    const hoverable = target.closest(selector);
-
-    if (hoverable) {
-      this.state.isHover = true;
-      this.state.hoverTarget = hoverable as HTMLElement;
-      this.parseDOMInteraction(this.state.hoverTarget);
-    }
-
-    const strategy = this.options.ignoreOnNative;
-
-    if (strategy) {
-      const checkTags = strategy === true || strategy === "auto" || strategy === "tag";
-      const checkCSS = strategy === true || strategy === "auto" || strategy === "css";
-      let isNative = false;
-
-      if (checkTags) {
-        const tag = target.localName;
-        if (tag === "input" || tag === "textarea" || tag === "select" || target.isContentEditable) {
-          isNative = true;
-        }
-      }
-
-      if (!isNative && checkCSS) {
-        const style = window.getComputedStyle(target).cursor;
-        const supermouseAllowed = ["default", "auto", "pointer", "none", "inherit"];
-        if (!supermouseAllowed.includes(style)) {
-          isNative = true;
-        }
-      }
-
-      if (isNative) {
-        this.state.isNative = true;
-      }
-    }
-  }
-
-  private handleMouseOut(e: MouseEvent) {
-    if (!this.isEnabled) return;
-    const target = e.target as HTMLElement;
-
-    if (target === this.state.hoverTarget || target.contains(this.state.hoverTarget)) {
-      if (!e.relatedTarget || !this.state.hoverTarget?.contains(e.relatedTarget as Node)) {
-        this.state.isHover = false;
-        this.state.hoverTarget = null;
-        this.state.interaction = {};
-      }
-    }
-
-    if (this.state.isNative) {
-      this.state.isNative = false;
-    }
-  }
-
-  private handleWindowLeave(): void {
-    if (this.options.hideOnLeave) {
-      this.state.hasReceivedInput = false;
-    }
-  }
-
-  public clearHover() {
-    this.state.isHover = false;
-    this.state.hoverTarget = null;
-    this.state.isNative = false;
-  }
-
-  private bindEvents() {
-    window.addEventListener("pointermove", this.handleMove.bind(this), { passive: true });
-    window.addEventListener("pointerdown", this.handleDown.bind(this), { passive: true });
-    window.addEventListener("pointerup", this.handleUp.bind(this));
-
-    document.addEventListener("mouseover", this.handleMouseOver.bind(this));
-    document.addEventListener("mouseout", this.handleMouseOut.bind(this));
-    document.addEventListener("mouseleave", this.handleWindowLeave.bind(this));
-  }
-
-  public destroy() {
-    if (this.mediaQueryList && this.mediaQueryHandler) {
-      this.mediaQueryList.removeEventListener("change", this.mediaQueryHandler);
-    }
-    if (this.motionQuery) {
-      // Modern browsers support removeEventListener on MediaQueryList
-      this.motionQuery.onchange = null;
-    }
-
-    window.removeEventListener("pointermove", this.handleMove);
-    window.removeEventListener("pointerdown", this.handleDown);
-    window.removeEventListener("pointerup", this.handleUp);
-
-    document.removeEventListener("mouseover", this.handleMouseOver);
-    document.removeEventListener("mouseout", this.handleMouseOut);
-    document.removeEventListener("mouseleave", this.handleWindowLeave);
-  }
-}

package/src/systems/Stage.ts

@@ -1,126 +0,0 @@
-let stageCount = 0;
-
-export class Stage {
-  /** The container element appended to the document. */
-  public readonly element: HTMLDivElement;
-  private styleTag: HTMLStyleElement;
-  private id: string;
-  private scopeClass: string;
-
-  private currentCursorState: "none" | "auto" | "" | null = null;
-
-  private selectors: Set<string> = new Set([
-    "a",
-    "button",
-    "input",
-    "textarea",
-    "select",
-    '[role="button"]',
-    "[tabindex]"
-  ]);
-
-  constructor(
-    private container: HTMLElement = document.body,
-    private hideNativeCursor: boolean
-  ) {
-    if (!container || !(container instanceof HTMLElement)) {
-      throw new Error(`[Supermouse] Invalid container: ${container}. Must be an HTMLElement.`);
-    }
-
-    const instanceId = stageCount++;
-    this.id = `supermouse-style-${instanceId}`;
-    this.scopeClass = `supermouse-scope-${instanceId}`;
-
-    const isBody = container === document.body;
-
-    this.element = document.createElement("div");
-    Object.assign(this.element.style, {
-      position: isBody ? "fixed" : "absolute",
-      top: "0",
-      left: "0",
-      width: "100%",
-      height: "100%",
-      pointerEvents: "none",
-      zIndex: "9999",
-      opacity: "1",
-      transition: "opacity 0.15s ease"
-    });
-
-    if (!isBody) {
-      const computed = window.getComputedStyle(container);
-      if (computed.position === "static") {
-        container.style.position = "relative";
-      }
-    }
-
-    container.appendChild(this.element);
-
-    this.styleTag = document.createElement("style");
-    this.styleTag.id = this.id;
-    document.head.appendChild(this.styleTag);
-
-    this.container.classList.add(this.scopeClass);
-
-    if (this.hideNativeCursor) {
-      this.setNativeCursor("none");
-    }
-  }
-
-  /**
-   * Adds a new CSS selector to the Hide Native Cursor list.
-   * Called by `Supermouse` (and subsequently plugins) during install to ensure
-   * the native cursor is hidden on their specific interactive targets.
-   */
-  public addSelector(selector: string) {
-    this.selectors.add(selector);
-    if (this.hideNativeCursor) {
-      this.updateCursorCSS();
-    }
-  }
-
-  public setVisibility(visible: boolean) {
-    this.element.style.opacity = visible ? "1" : "0";
-  }
-
-  /**
-   * Toggles the visibility of the native cursor via CSS injection.
-   * @param type 'none' to hide, 'auto' to show.
-   */
-  public setNativeCursor(type: "none" | "auto" | "") {
-    if (!this.hideNativeCursor && type === "none") return;
-
-    if (type === this.currentCursorState) return;
-    this.currentCursorState = type;
-
-    if (type === "none") {
-      this.container.style.cursor = "none";
-      this.updateCursorCSS();
-    } else {
-      this.container.style.cursor = "";
-      this.styleTag.innerText = "";
-    }
-  }
-
-  private updateCursorCSS() {
-    const rawSelectors = Array.from(this.selectors);
-    if (rawSelectors.length === 0) {
-      this.styleTag.innerText = "";
-      return;
-    }
-
-    const scopedSelectors = rawSelectors.map((s) => `.${this.scopeClass} ${s}`).join(", ");
-
-    this.styleTag.innerText = `
-      ${scopedSelectors} {
-        cursor: none !important;
-      }
-    `;
-  }
-
-  public destroy() {
-    this.element.remove();
-    this.styleTag.remove();
-    this.container.style.cursor = "";
-    this.container.classList.remove(this.scopeClass);
-  }
-}

package/src/systems/index.ts

@@ -1,2 +0,0 @@
-export * from "./Stage";
-export * from "./Input";

package/src/utils/math.ts

@@ -1,11 +0,0 @@
-export function lerp(start: number, end: number, factor: number): number {
-  return start + (end - start) * factor;
-}
-
-export function damp(a: number, b: number, lambda: number, dt: number): number {
-  return lerp(a, b, 1 - Math.exp(-lambda * dt));
-}
-
-export function angle(x: number, y: number): number {
-  return Math.atan2(y, x) * (180 / Math.PI);
-}