@supermousejs/core 2.0.0

package/src/Supermouse.ts

@@ -0,0 +1,405 @@
+declare const __VERSION__: string;
+
+import { MouseState, SupermouseOptions, SupermousePlugin } from './types';
+import { Stage, Input } from './systems';
+import { damp, angle } from './utils/math';
+
+export const DEFAULT_HOVER_SELECTORS = [
+  'a', 'button', 'input', 'textarea', '[data-hover]', '[data-cursor]'
+];
+
+/**
+ * The Central Conductor & Runtime Loop of Supermouse.
+ * 
+ * This class orchestrates the application state, manages the animation loop (`requestAnimationFrame`),
+ * and coordinates data flow between the Input system, the Stage system, and the Plugins.
+ * 
+ * ## Architecture
+ * 1. **Input System**: Captures raw events and writes to `state.pointer`.
+ * 2. **Logic Plugins**: (Priority < 0) Read `pointer`, modify `state.target` (e.g. Magnetic, Stick).
+ * 3. **Physics**: Core interpolates `state.smooth` towards `state.target`.
+ * 4. **Visual Plugins**: (Priority >= 0) Read `state.smooth`, update DOM transforms.
+ * 
+ * @example
+ * ```ts
+ * const app = new Supermouse({ smoothness: 0.15 });
+ * app.use(Dot({ color: 'red' }));
+ * ```
+ */
+export class Supermouse {
+  /** The current version of Supermouse.js */
+  public static readonly version: string = __VERSION__;
+  public readonly version: string = __VERSION__;
+
+  /**
+   * The Single Source of Truth.
+   * 
+   * This object is shared by reference. `Input` writes to it; `Supermouse` physics reads/writes to it;
+   * Plugins read/write to it.
+   */
+  state: MouseState;
+
+  /**
+   * Configuration options.
+   */
+  options: SupermouseOptions;
+
+  /**
+   * Registry of active plugins.
+   * @internal Use `use()`, `enablePlugin()`, or `disablePlugin()` to interact with this.
+   */
+  private plugins: SupermousePlugin[] = [];
+  
+  /**
+   * The Stage System responsible for the DOM container and CSS injection.
+   * @internal
+   */
+  private stage: Stage;
+
+  /**
+   * The Input System responsible for event listeners.
+   * @internal
+   */
+  private input: Input;
+  
+  private rafId: number = 0;
+  private lastTime: number = 0;
+  private isRunning: boolean = false;
+  
+  private hoverSelectors: Set<string>;
+
+  /**
+   * Creates a new Supermouse instance.
+   * 
+   * @param options - Global configuration options.
+   * @throws Will throw if running in a non-browser environment (window/document undefined).
+   */
+  constructor(options: SupermouseOptions = {}) {
+    this.options = {
+      smoothness: 0.15,
+      enableTouch: false,
+      autoDisableOnMobile: true,
+      ignoreOnNative: 'auto',
+      hideCursor: true, 
+      hideOnLeave: true,
+      autoStart: true,
+      container: document.body,
+      ...options
+    };
+
+    // Ensure container is valid (fallback to body if null/undefined passed explicitly)
+    if (!this.options.container) {
+      this.options.container = document.body;
+    }
+
+    this.state = {
+      pointer: { x: -100, y: -100 },
+      target: { x: -100, y: -100 },
+      smooth: { x: -100, y: -100 },
+      velocity: { x: 0, y: 0 },
+      angle: 0,
+      isDown: false,
+      isHover: false,
+      isNative: false,
+      forcedCursor: null,
+      hoverTarget: null,
+      reducedMotion: false,
+      hasReceivedInput: false,
+      shape: null,
+      interaction: {}
+    };
+
+    // Initialize Selectors
+    if (this.options.hoverSelectors) {
+      this.hoverSelectors = new Set(this.options.hoverSelectors);
+    } else {
+      this.hoverSelectors = new Set(DEFAULT_HOVER_SELECTORS);
+    }
+
+    this.stage = new Stage(this.options.container, !!this.options.hideCursor);
+    this.hoverSelectors.forEach(s => this.stage.addSelector(s));
+
+    // Pass state by reference to Input. Input will mutate this state directly.
+    this.input = new Input(
+      this.state, 
+      this.options,
+      () => Array.from(this.hoverSelectors).join(', '), 
+      (enabled) => { if (!enabled) this.resetPosition(); }
+    );
+
+    if (this.options.plugins) {
+      this.options.plugins.forEach(p => this.use(p));
+    }
+
+    this.init();
+  }
+
+  /**
+   * Retrieves a registered plugin instance by its unique name.
+   */
+  public getPlugin(name: string) {
+    return this.plugins.find(p => p.name === name);
+  }
+
+  /**
+   * Returns whether the cursor system is currently enabled (processing input).
+   */
+  public get isEnabled(): boolean {
+    return this.input.isEnabled;
+  }
+
+  /**
+   * Enables a specific plugin by name.
+   * Triggers the `onEnable` lifecycle hook of the plugin.
+   */
+  public enablePlugin(name: string) {
+    const plugin = this.getPlugin(name);
+    if (plugin && plugin.isEnabled === false) {
+      plugin.isEnabled = true;
+      plugin.onEnable?.(this);
+    }
+  }
+
+  /**
+   * Disables a specific plugin by name.
+   * Triggers the `onDisable` lifecycle hook.
+   */
+  public disablePlugin(name: string) {
+    const plugin = this.getPlugin(name);
+    if (plugin && plugin.isEnabled !== false) {
+      plugin.isEnabled = false;
+      plugin.onDisable?.(this);
+    }
+  }
+
+  /**
+   * Toggles the enabled state of a plugin.
+   */
+  public togglePlugin(name: string) {
+    const plugin = this.getPlugin(name);
+    if (plugin) {
+      if (plugin.isEnabled === false) this.enablePlugin(name);
+      else this.disablePlugin(name);
+    }
+  }
+
+  /**
+   * Registers a CSS selector as an "Interactive Target".
+   * 
+   * When the mouse hovers over an element matching this selector:
+   * 1. `state.isHover` becomes `true`.
+   * 2. `state.hoverTarget` is set to the element.
+   * 3. The `Stage` system injects CSS to hide the native cursor for this element (if `hideCursor: true`).
+   * 
+   * @param selector - A valid CSS selector string (e.g., `.my-button`, `[data-trigger]`).
+   */
+  public registerHoverTarget(selector: string) {
+    if (!this.hoverSelectors.has(selector)) {
+      this.hoverSelectors.add(selector);
+      this.stage.addSelector(selector);
+    }
+  }
+
+  /** 
+   * The fixed container element where plugins should append their DOM nodes.
+   */
+  public get container(): HTMLDivElement { return this.stage.element; }
+  
+  /**
+   * Manually override the native cursor visibility.
+   * Useful for drag-and-drop operations, modals, or special UI states.
+   * 
+   * @param type 'auto' (Show Native), 'none' (Hide Native), or null (Resume Auto-detection)
+   */
+  public setCursor(type: 'auto' | 'none' | null) {
+    this.state.forcedCursor = type;
+  }
+
+  private init() { 
+    if (this.options.autoStart) {
+        this.startLoop(); 
+    }
+  }
+
+  /** 
+   * Starts the update loop and enables input listeners.
+   * Hides the native cursor if configured.
+   */
+  public enable() { this.input.isEnabled = true; this.stage.setNativeCursor('none'); }
+  
+  /** 
+   * Stops the update loop, disables listeners, and restores the native cursor. 
+   * Resets internal state positions to off-screen.
+   */
+  public disable() { this.input.isEnabled = false; this.stage.setNativeCursor('auto'); this.resetPosition(); }
+
+  /**
+   * Registers a new plugin.
+   * 
+   * @remarks
+   * Plugins are sorted by `priority` immediately after registration.
+   * - **Negative Priority (< 0)**: Logic plugins (run before physics).
+   * - **Positive Priority (>= 0)**: Visual plugins (run after physics).
+   * 
+   * @param plugin - The plugin object to install.
+   */
+  public use(plugin: SupermousePlugin) {
+    if (this.plugins.find(p => p.name === plugin.name)) {
+      console.warn(`[Supermouse] Plugin "${plugin.name}" already installed.`);
+      return this;
+    }
+    
+    if (plugin.isEnabled === undefined) {
+      plugin.isEnabled = true;
+    }
+
+    this.plugins.push(plugin);
+    this.plugins.sort((a, b) => (a.priority || 0) - (b.priority || 0));
+    
+    plugin.install?.(this);
+    return this;
+  }
+
+  private resetPosition() {
+    const off = { x: -100, y: -100 };
+    this.state.pointer = { ...off };
+    this.state.target = { ...off };
+    this.state.smooth = { ...off };
+    this.state.velocity = { x: 0, y: 0 };
+    this.state.angle = 0;
+    this.state.hasReceivedInput = false;
+    this.state.shape = null;
+    this.state.interaction = {};
+  }
+
+  private startLoop() {
+    if (this.isRunning) return;
+    this.isRunning = true;
+    this.lastTime = performance.now();
+    this.tick(this.lastTime);
+  }
+
+  /**
+   * Manually steps the animation loop.
+   * Useful when integrating with external game loops (e.g., Three.js, PixiJS) where
+   * you want to disable the internal RAF and drive `Supermouse` from your own ticker.
+   * 
+   * @param time Current timestamp in milliseconds.
+   */
+  public step(time: number) {
+    this.tick(time);
+  }
+
+  private runPluginSafe(plugin: SupermousePlugin, deltaTime: number) {
+    if (plugin.isEnabled === false) return;
+    try {
+      plugin.update?.(this, deltaTime);
+    } catch (e) {
+      console.error(`[Supermouse] Plugin '${plugin.name}' crashed and has been disabled.`, e);
+      plugin.isEnabled = false;
+      plugin.onDisable?.(this);
+    }
+  }
+
+  /**
+   * The Heartbeat.
+   * Runs on every animation frame.
+   */
+  private tick = (time: number) => {
+    // 1. Calculate Delta Time (in seconds)
+    // We cap dt at 0.1s (100ms) to prevent massive jumps if the tab is inactive for a while.
+    const dtMs = time - this.lastTime;
+    const dt = Math.min(dtMs / 1000, 0.1); 
+    this.lastTime = time;
+
+    // 2. Visibility Logic
+    // Stage is visible only if input is active, it's not a native-cursor override situation,
+    // and we have actually received mouse coordinates.
+    const shouldShowStage = this.input.isEnabled && !this.state.isNative && this.state.hasReceivedInput;
+    this.stage.setVisibility(shouldShowStage);
+
+    // 3. Native Cursor Hiding Logic
+    if (this.input.isEnabled && this.options.hideCursor) {
+       let targetState: 'none' | 'auto' = 'auto';
+
+       // PRIORITY 1: Manual Override (User/Plugin says so)
+       if (this.state.forcedCursor !== null) {
+         targetState = this.state.forcedCursor;
+       } 
+       // PRIORITY 2: Auto-Detection (Default behavior)
+       else {
+         // Show native if we are in a "Native Zone" (Input) OR if we haven't moved mouse yet
+         const showNative = this.state.isNative || !this.state.hasReceivedInput;
+         targetState = showNative ? 'auto' : 'none';
+       }
+
+       this.stage.setNativeCursor(targetState);
+    }
+
+    if (this.input.isEnabled) {
+      // 4. Sync Target
+      // By default, target = raw pointer. Logic plugins may override this in the next step.
+      this.state.target.x = this.state.pointer.x;
+      this.state.target.y = this.state.pointer.y;
+
+      // 5. Run Plugins
+      // This iterates through the priority-sorted list.
+      // - Logic Plugins (Magnetic) run first and modify this.state.target
+      // - Visual Plugins (Dot, Ring) run last and read this.state.smooth
+      for (let i = 0; i < this.plugins.length; i++) {
+        this.runPluginSafe(this.plugins[i], dtMs);
+      }
+
+      // 6. Physics Integration (Damping)
+      // Convert abstract smoothness (0-1) to damping factor (1-50 approx)
+      const userSmooth = this.options.smoothness!;
+      // Map 0.15 (floaty) -> ~10, 0.5 (snappy) -> ~25
+      const dampFactor = this.state.reducedMotion ? 1000 : (1 / userSmooth) * 2; 
+
+      this.state.smooth.x = damp(this.state.smooth.x, this.state.target.x, dampFactor, dt);
+      this.state.smooth.y = damp(this.state.smooth.y, this.state.target.y, dampFactor, dt);
+      
+      const vx = this.state.target.x - this.state.smooth.x;
+      const vy = this.state.target.y - this.state.smooth.y;
+      
+      this.state.velocity.x = vx;
+      this.state.velocity.y = vy;
+
+      // Only update angle if moving significantly (prevents jitter at rest)
+      if (Math.abs(vx) > 0.1 || Math.abs(vy) > 0.1) {
+        this.state.angle = angle(vx, vy);
+      }
+
+    } else {
+      // Inactive State: Force positions off-screen
+      this.state.smooth.x = -100;
+      this.state.smooth.y = -100;
+      this.state.pointer.x = -100;
+      this.state.pointer.y = -100;
+      this.state.velocity.x = 0;
+      this.state.velocity.y = 0;
+      
+      // Still run plugins (e.g. for exit animations)
+      for (let i = 0; i < this.plugins.length; i++) {
+        this.runPluginSafe(this.plugins[i], dtMs);
+      }
+    }
+
+    if (this.options.autoStart && this.isRunning) {
+      this.rafId = requestAnimationFrame(this.tick);
+    }
+  };
+  
+  /** 
+   * Destroys the instance.
+   * Stops the loop, removes all DOM elements, removes all event listeners, and calls destroy on all plugins.
+   */
+  public destroy() {
+    this.isRunning = false;
+    cancelAnimationFrame(this.rafId);
+    this.input.destroy();
+    this.stage.destroy();
+    this.plugins.forEach(p => p.destroy?.(this));
+    this.plugins = [];
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './Supermouse';
+export * from './types';

package/src/systems/Input.ts

@@ -0,0 +1,262 @@
+
+import { MouseState, SupermouseOptions, InteractionState } from '../types';
+
+/**
+ * The Sensor / State Writer.
+ * 
+ * This class listens to browser events (pointermove, pointerdown, hover) and mutates the shared `MouseState` object.
+ * It acts as the "Producer" of data for the Supermouse system.
+ * 
+ * @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;
+
+  /**
+   * Performance Optimization:
+   * We cache the resolved InteractionState for every element we encounter in a WeakMap.
+   */
+  private interactionCache = new WeakMap<HTMLElement, InteractionState>();
+
+  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 (e.g. phones/tablets).
+   * 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('(prefer-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);
+  }
+
+  // --- Interaction Parsing ---
+
+  /**
+   * Scrapes the DOM element for metadata to populate `state.interaction`.
+   * 
+   * **Strategy:**
+   * 1. Check WeakMap cache.
+   * 2. Apply config-based `rules`.
+   * 3. Scrape `dataset` (supermouse*).
+   * 4. Cache result.
+   */
+  private parseDOMInteraction(element: HTMLElement) {
+    // 0. Custom Strategy override
+    if (this.options.resolveInteraction) {
+      this.state.interaction = this.options.resolveInteraction(element);
+      return;
+    }
+
+    // 1. Check Cache
+    if (this.interactionCache.has(element)) {
+      this.state.interaction = this.interactionCache.get(element)!;
+      return;
+    }
+
+    const data: Record<string, any> = {};
+
+    // 2. Semantic Rules (Config-based)
+    if (this.options.rules) {
+      for (const [selector, rules] of Object.entries(this.options.rules)) {
+        if (element.matches(selector)) {
+          Object.assign(data, rules);
+        }
+      }
+    }
+
+    // 3. Dataset Scraping (Fast Native)
+    // Converts data-supermouse-my-val -> myVal
+    const dataset = element.dataset;
+    for (const key in dataset) {
+      if (key.startsWith('supermouse')) {
+        // 'supermouseColor' -> 'color'
+        // 'supermouseStick' -> 'stick'
+        const prop = key.slice(10);
+        if (prop) {
+          const cleanKey = prop.charAt(0).toLowerCase() + prop.slice(1);
+          const val = dataset[key];
+          // Treat empty string (bool attribute) as true
+          data[cleanKey] = val === '' ? true : val;
+        }
+      }
+    }
+
+    // 4. Cache and Set
+    this.interactionCache.set(element, data);
+    this.state.interaction = data;
+  }
+
+  // --- Handlers ---
+  
+  // Unified Pointer Event Handler
+  private handleMove = (e: PointerEvent) => {
+    if (!this.isEnabled) return;
+    
+    // Ignore non-mouse inputs if not on touch device (e.g. pen hovering but not touching)
+    // unless we strictly want to track everything. PointerType check is robust.
+    if (this.options.autoDisableOnMobile && e.pointerType === 'touch') return;
+
+    let x = e.clientX;
+    let y = e.clientY;
+
+    // Handle Custom Container Coordinates
+    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 = () => { if (this.isEnabled) this.state.isDown = true; };
+  private handleUp = () => { if (this.isEnabled) this.state.isDown = false; };
+
+  private handleMouseOver = (e: MouseEvent) => {
+    if (!this.isEnabled) return;
+    const target = e.target as HTMLElement;
+
+    // 0. THE VETO: Explicit Ignore
+    if (target.closest('[data-supermouse-ignore]')) {
+      this.state.isNative = true;
+      return;
+    }
+
+    // 1. Dynamic Hover Check
+    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);
+    }
+
+    // 2. Semantic Native Cursor Check (Configurable Strategy)
+    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;
+
+      // A. Tag Check (Fast, O(1))
+      if (checkTags) {
+        // Check localName for speed (always lowercase)
+        const tag = target.localName;
+        if (tag === 'input' || tag === 'textarea' || tag === 'select' || target.isContentEditable) {
+          isNative = true;
+        }
+      }
+
+      // B. CSS Check (Slow, causes Layout Reflow)
+      // Only run if not already detected and strategy allows it.
+      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 = () => {
+    if (this.options.hideOnLeave) {
+      this.state.hasReceivedInput = false;
+    }
+  };
+
+  private bindEvents() {
+    window.addEventListener('pointermove', this.handleMove, { passive: true });
+    window.addEventListener('pointerdown', this.handleDown, { passive: true });
+    window.addEventListener('pointerup', this.handleUp);
+    
+    document.addEventListener('mouseover', this.handleMouseOver);
+    document.addEventListener('mouseout', this.handleMouseOut);
+    document.addEventListener('mouseleave', this.handleWindowLeave);
+  }
+
+  public destroy() {
+    if (this.mediaQueryList && this.mediaQueryHandler) {
+      this.mediaQueryList.removeEventListener('change', this.mediaQueryHandler);
+    }
+    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);
+  }
+}