@supermousejs/core 2.0.0

package/src/systems/Stage.ts

@@ -0,0 +1,156 @@
+
+let stageCount = 0;
+
+/**
+ * The Environment / DOM Manager.
+ * 
+ * This class handles the DOM container where the cursor lives and manages the global CSS 
+ * required to hide the default OS cursor without flickering.
+ * 
+ * ## Why CSS Injection?
+ * Simply adding `cursor: none` to the body isn't enough. Interactive elements like `<input>` 
+ * or `<a>` often have their own user-agent styles that force `cursor: text` or `cursor: pointer`.
+ * This results in the "double cursor" glitch.
+ * 
+ * The Stage system generates a scoped stylesheet that aggressively targets registered selectors
+ * with `cursor: none !important` to ensure a seamless experience.
+ * 
+ * @internal This is an internal system class instantiated by `Supermouse`.
+ */
+export class Stage {
+  /** The container element appended to the document. Plugins must append here. */
+  public readonly element: HTMLDivElement;
+  
+  private styleTag: HTMLStyleElement;
+  private id: string;
+  private scopeClass: string;
+  
+  // Cache to prevent redundant DOM updates
+  private currentCursorState: 'none' | 'auto' | '' | null = null;
+
+  // Defaults for CSS hiding. We must override user-agent styles on these elements
+  // to prevent the native cursor from popping through.
+  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;
+
+    // 1. Create Container
+    // If attached to body, use fixed positioning to cover viewport.
+    // If attached to a specific div, use absolute positioning to cover that div.
+    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'
+    });
+    
+    // Ensure parent is relative if we are using absolute positioning
+    if (!isBody) {
+        const computed = window.getComputedStyle(container);
+        if (computed.position === 'static') {
+            container.style.position = 'relative';
+        }
+    }
+    
+    container.appendChild(this.element);
+
+    // 2. Create Dynamic Style Tag
+    this.styleTag = document.createElement('style');
+    this.styleTag.id = this.id;
+    document.head.appendChild(this.styleTag);
+
+    // 3. Apply Scope Class to Container
+    // This allows us to target CSS purely within this container (or body)
+    // preventing styles from leaking if multiple Supermouse instances exist.
+    this.container.classList.add(this.scopeClass);
+
+    // 4. Apply Initial Cursor State
+    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();
+    }
+  }
+
+  /**
+   * Controls the opacity of the entire stage (all custom cursor elements).
+   */
+  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 global hiding is disabled via options, do nothing (unless specifically forcing auto)
+    if (!this.hideNativeCursor && type === 'none') return;
+
+    // PERFORMANCE FIX: Don't touch DOM if state hasn't changed
+    if (type === this.currentCursorState) return;
+    this.currentCursorState = type;
+
+    if (type === 'none') {
+      // 1. Hide on container directly (covers background/empty space)
+      this.container.style.cursor = 'none';
+      // 2. Hide on interactive elements (overrides UA stylesheet)
+      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;
+    }
+    
+    // Scoped Selector Logic:
+    // We prepend the scope class to every selector to ensure we don't bleed into
+    // other parts of the page if the user is using a specific container.
+    // e.g. .supermouse-scope-0 a, .supermouse-scope-0 button { ... }
+    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

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

package/src/types.ts

@@ -0,0 +1,169 @@
+
+import { Supermouse } from './Supermouse';
+
+export interface MousePosition {
+  x: number;
+  y: number;
+}
+
+export interface ShapeState {
+  width: number;
+  height: number;
+  borderRadius: number;
+}
+
+/**
+ * The Interface for interaction state.
+ * Plugins should use Module Augmentation to add their specific properties to this interface.
+ * 
+ * @example
+ * declare module '@supermousejs/core' {
+ *   interface InteractionState {
+ *     magnetic: boolean | number;
+ *     text: string;
+ *   }
+ * }
+ */
+export interface InteractionState {
+  /** 
+   * Allow arbitrary keys for rapid prototyping. 
+   * For type safety, use module augmentation to define expected keys.
+   */
+  [key: string]: any;
+}
+
+export interface MouseState {
+  /** The raw position of the input pointer (mouse/touch). */
+  pointer: MousePosition;
+  /** The target position the cursor logic wants to reach. */
+  target: MousePosition;
+  /** The smoothed/interpolated position used for rendering. */
+  smooth: MousePosition;
+  /** The current velocity vector of the smooth position. */
+  velocity: MousePosition;
+  /** The angle of movement in degrees. Calculated 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). */
+  isNative: boolean;
+  /** 
+   * If set, this overrides all auto-detection logic. 
+   * 'auto' = Force Native Cursor (Show)
+   * 'none' = Force Custom Cursor (Hide Native)
+   * null = Let the Core decide based on isNative/isHover
+   */
+  forcedCursor: 'auto' | 'none' | null;
+  /** The DOM element currently being hovered, if any. */
+  hoverTarget: HTMLElement | null;
+  /** Whether the user has `prefers-reduced-motion` enabled. */
+  reducedMotion: boolean;
+  /** Whether the system has received valid input coordinates at least once. */
+  hasReceivedInput: boolean;
+  /** Defines a specific geometric shape the cursor should conform to. */
+  shape: ShapeState | null;
+  /** Centralized store for hover metadata from data attributes. */
+  interaction: InteractionState;
+}
+
+export type NativeIgnoreStrategy = 'auto' | 'tag' | 'css';
+
+/**
+ * Configuration options passed to the Supermouse constructor.
+ */
+export interface SupermouseOptions {
+  /** 
+   * The interpolation factor (0 to 1). Lower is smoother/slower. 
+   * @default 0.15
+   */
+  smoothness?: number;
+  /**
+   * List of CSS selectors that trigger the "Hover" state.
+   * Overrides the default set if provided.
+   */
+  hoverSelectors?: string[];
+  /**
+   * Whether to enable custom cursor effects on touch devices.
+   * @default false
+   */
+  enableTouch?: boolean;
+  /**
+   * Whether to automatically disable the custom cursor on devices with coarse pointers.
+   * @default true
+   */
+  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).
+   * - `'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.
+   * @default 'auto'
+   */
+  ignoreOnNative?: boolean | NativeIgnoreStrategy;
+  /**
+   * Whether to hide the native cursor via global CSS injection.
+   * @default true
+   */
+  hideCursor?: boolean;
+  /**
+   * Whether to hide the custom cursor when the mouse leaves the browser window.
+   * @default true
+   */
+  hideOnLeave?: boolean;
+  /**
+   * List of plugins to initialize with the instance.
+   */
+  plugins?: SupermousePlugin[];
+  /**
+   * The DOM element to append the cursor stage to.
+   * @default document.body
+   */
+  container?: HTMLElement;
+  /**
+   * Whether to start the internal animation loop automatically.
+   * @default true
+   */
+  autoStart?: boolean;
+  /**
+   * Semantic rules mapping CSS selectors to interaction state.
+   * @example { 'button': { icon: 'pointer' } }
+   */
+  rules?: Record<string, InteractionState>;
+  /**
+   * Custom strategy to resolve interaction state from a hovered element.
+   * Overrides the default data-attribute scraping.
+   */
+  resolveInteraction?: (target: HTMLElement) => InteractionState;
+}
+
+/**
+ * Helper type: Allows a property to be a static value OR a function that returns the value based on state.
+ */
+export type ValueOrGetter<T> = T | ((state: MouseState) => T);
+
+/**
+ * Interface for defining a Supermouse Plugin.
+ */
+export interface SupermousePlugin {
+  /** Unique name for the plugin. Used for toggling/retrieval. */
+  name: string;
+  /** Execution priority. Lower numbers run first. */
+  priority?: number;
+  /** If false, update() will not be called. */
+  isEnabled?: boolean;
+
+  /** Called when `app.use()` is executed. */
+  install?: (instance: Supermouse) => void;
+  /** Called on every animation frame. */
+  update?: (instance: Supermouse, deltaTime: number) => void;
+  /** Called when the plugin is removed or the app is destroyed. */
+  destroy?: (instance: Supermouse) => void;
+
+  /** Called when the plugin is enabled via .enablePlugin() */
+  onEnable?: (instance: Supermouse) => void;
+  /** Called when the plugin is disabled via .disablePlugin() */
+  onDisable?: (instance: Supermouse) => void;
+}

package/src/utils/math.ts

@@ -0,0 +1,20 @@
+/**
+ * Linear Interpolation between two values.
+ */
+export function lerp(start: number, end: number, factor: number): number {
+  return start + (end - start) * factor;
+}
+
+/**
+ * Frame-rate independent damping (Time-based Lerp).
+ */
+export function damp(a: number, b: number, lambda: number, dt: number): number {
+  return lerp(a, b, 1 - Math.exp(-lambda * dt));
+}
+
+/**
+ * Calculates the angle in degrees between two points.
+ */
+export function angle(x: number, y: number): number {
+  return Math.atan2(y, x) * (180 / Math.PI);
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": [
+    "src"
+  ],
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "noUnusedLocals": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "paths": {}
+  }
+}

package/vite.config.ts

@@ -0,0 +1,32 @@
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { readFileSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const pkg = JSON.parse(readFileSync(path.resolve(__dirname, 'package.json'), 'utf-8'));
+
+export default defineConfig({
+  define: {
+    __VERSION__: JSON.stringify(pkg.version)
+  },
+  build: {
+    lib: {
+      entry: path.resolve(__dirname, 'src/index.ts'),
+      name: 'SupermouseCore',
+      fileName: (format) => format === 'es' ? 'index.mjs' : 'index.umd.js',
+    },
+    rollupOptions: {
+      external: [],
+      output: {
+        globals: {
+          '@supermousejs/core': 'SupermouseCore'
+        }
+      }
+    }
+  },
+  plugins: [dts({ rollupTypes: true })]
+});