@supermousejs/core 2.3.0 → 2.4.0

package/src/Supermouse.ts

@@ -1,37 +1,85 @@
 declare const __VERSION__: string | undefined;
 const VERSION: string = typeof __VERSION__ !== "undefined" ? __VERSION__ : "0.0.0";
 
-import type { MouseState, SupermouseOptions, SupermousePlugin } from "./types";
+import type { MouseState, SupermouseOptions, SupermousePlugin, RuleDefinition } from "./types";
 
+/** Standard linear interpolation */
 function lerp(start: number, end: number, factor: number): number {
   return start + (end - start) * factor;
 }
 
+/**
+ * Framerate-independent exponential smoothing by Freya Holmér.
+ * @param lambda  Response rate.
+ * @param dt Delta time in seconds.
+ *
+ * https://www.youtube.com/watch?v=LSNQuFEDOyQ
+ */
 function damp(a: number, b: number, lambda: number, dt: number): number {
   return lerp(a, b, 1 - Math.exp(-lambda * dt));
 }
 
+/** Off-screen park position before input arrives or after pointer leaves viewport. */
+const OFFSCREEN = { x: -100, y: -100 } as const;
+
+/** HTML tags that always warrant native cursor fallback. */
+const NATIVE_TAGS = new Set(["input", "textarea", "select"]);
+
 /**
- * Input.ts
- *
- * This class listens to browser events and mutates the shared `MouseState` object.
+ * Computed `cursor` values treated as "author didn't explicitly choose one."
+ * Anything else wins over custom cursor.
+ */
+const SUPERMOUSE_CURSORS = new Set([
+  "default",
+  "auto",
+  "pointer",
+  "none",
+  "inherit",
+  "grab",
+  "grabbing"
+]);
+
+/** Default selectors that trigger `state.isHover`. Override with `hoverSelectors`. */
+export const DEFAULT_HOVER_SELECTORS = [
+  "a",
+  "button",
+  "input",
+  "textarea",
+  "[data-hover]",
+  "[data-cursor]"
+];
+
+/**
+ * Owns all browser-event listening and is the only class allowed to write
+ * to these `MouseState` fields: `pointer`, `isDown`, `isHover`, `isNative`,
+ * `hoverTarget`, `interaction`, `reducedMotion`.
  *
- * @internal This is an internal system class instantiated by `Supermouse`.
+ * @internal Instantiated by `Supermouse`.
  */
 export class Input {
   private mediaQueryList?: MediaQueryList;
-  private mediaQueryHandler?: (e: MediaQueryListEvent) => void;
   private motionQuery?: MediaQueryList;
   private dataPrefix: string;
   private normalizedDataPrefix: string;
   private ignoreAttribute: string;
-
-  /**
-   * Master switch for input processing.
-   * Toggled by `Supermouse.enable()`/`disable()` or automatically by device capability checks.
-   */
+  private abortController = new AbortController();
+  private nativeTarget: HTMLElement | null = null;
+  public hasSeenPointer: boolean = false;
   public isEnabled: boolean = true;
 
+  private containerRect: DOMRect | null = null;
+  private resizeObserver?: ResizeObserver;
+
+  /** Cached matched rules for the current interaction element. */
+  private matchedRules: Array<{ selector: string; rules: RuleDefinition }> = [];
+  private lastParsedTarget: HTMLElement | null = null;
+
+  /** Precomputed list of rule entries for faster iteration. */
+  private ruleEntries: Array<[string, RuleDefinition]>;
+
+  /** The actual element currently under the pointer (regardless of hover selectors). */
+  private currentTarget: HTMLElement | null = null;
+
   constructor(
     private state: MouseState,
     private options: SupermouseOptions,
@@ -42,38 +90,26 @@ export class Input {
     this.normalizedDataPrefix = this.dataPrefix.toLowerCase();
     this.ignoreAttribute = `data-${this.dataPrefix}-ignore`;
 
+    this.ruleEntries = this.options.rules ? Object.entries(this.options.rules) : [];
+
     this.checkDeviceCapability();
     this.checkMotionPreference();
+    this.setupContainerRectTracking();
     this.bindEvents();
   }
 
-  private abortController = new AbortController();
-
-  /**
-   * Automatically disables the custom cursor on devices without fine pointer control.
-   */
   private checkDeviceCapability(): void {
     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, {
+    this.mediaQueryList.addEventListener("change", (e) => this.updateEnabledState(e.matches), {
       signal: this.abortController.signal
     });
   }
 
-  /**
-   * Checks for `prefers-reduced-motion`.
-   * If true, the core physics engine will switch to instant snapping (high damping) to avoid motion sickness.
-   */
   private checkMotionPreference(): void {
     this.motionQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
     this.state.reducedMotion = this.motionQuery.matches;
-
     this.motionQuery.addEventListener(
       "change",
       (e) => {
@@ -88,175 +124,282 @@ export class Input {
     this.onEnableChange(enabled);
   }
 
-  private parseDOMInteraction(element: HTMLElement): void {
-    if (this.options.resolveInteraction) {
-      this.state.interaction = this.options.resolveInteraction(element) || {};
-      return;
+  /** Caches container rect; updates on resize/scroll/ResizeObserver. */
+  private setupContainerRectTracking(): void {
+    const container = this.options.container;
+    if (!container || container === document.body) return;
+
+    const updateRect = (): void => {
+      this.containerRect = container.getBoundingClientRect();
+    };
+    updateRect();
+
+    window.addEventListener("resize", updateRect, { signal: this.abortController.signal });
+    window.addEventListener("scroll", updateRect, {
+      passive: true,
+      signal: this.abortController.signal
+    });
+
+    if (typeof ResizeObserver !== "undefined") {
+      this.resizeObserver = new ResizeObserver(updateRect);
+      this.resizeObserver.observe(container);
+    }
+  }
+
+  /**
+   * Evaluates rules against the given element.
+   * Selector matching is cached per element; only function values re-evaluated each frame.
+   */
+  public parseDOMInteraction(element: HTMLElement): void {
+    if (element !== this.lastParsedTarget) {
+      this.lastParsedTarget = element;
+      this.matchedRules = [];
+
+      for (const [selector, rules] of this.ruleEntries) {
+        if (this.matchesSelector(element, selector)) {
+          this.matchedRules.push({ selector, rules });
+        }
+      }
     }
-    const data: Record<string, string | boolean> = {};
-    if (this.options.rules) {
-      for (const [sel, rules] of Object.entries(this.options.rules)) {
-        if (element.matches(sel)) Object.assign(data, rules);
+
+    const data: Record<string, string | boolean | number> = {};
+    for (const { rules } of this.matchedRules) {
+      try {
+        const resolved = typeof rules === "function" ? rules(element) : rules;
+        if (!resolved || typeof resolved !== "object") continue;
+
+        for (const [key, val] of Object.entries(resolved)) {
+          data[key] = typeof val === "function" ? val(element) : val;
+        }
+      } catch (e) {
+        console.error(`[Supermouse] Rule threw during evaluation:`, e);
       }
     }
-    const pre = this.normalizedDataPrefix,
-      len = this.dataPrefix.length;
+
+    const pre = this.normalizedDataPrefix;
     for (const key in element.dataset) {
       if (!key.toLowerCase().startsWith(pre)) continue;
-      const prop = key.slice(len);
+      const prop = key.slice(pre.length);
       if (!prop) continue;
       const val = element.dataset[key];
       data[prop[0].toLowerCase() + prop.slice(1)] = val === "" ? true : val!;
     }
+
     this.state.interaction = data;
   }
 
-  private handleMove(e: PointerEvent): void {
-    if (!this.isEnabled) return;
+  /**
+   * Optimized selector matching:
+   * - For simple selectors (no spaces), just call `element.matches`.
+   * - For complex selectors with descendant combinators, fallback to splitting.
+   */
+  private matchesSelector(element: HTMLElement, selector: string): boolean {
+    try {
+      // Fast path: simple selector
+      if (!/\s/.test(selector.trim())) {
+        return element.matches(selector);
+      }
+    } catch {
+      // If matches fails, fall through to ancestor-based matching
+    }
+
+    const parts = selector.trim().split(/\s+/);
+    if (parts.length < 2) return false;
+
+    const self = parts.pop()!;
+    const ancestor = parts.join(" ");
+    if (!self || !ancestor) return false;
+
+    try {
+      return element.matches(self) && !!element.closest(ancestor);
+    } catch {
+      return false;
+    }
+  }
 
+  private isOutsideContainer(target: Node): boolean {
+    const { container } = this.options;
+    return !!container && container !== document.body && !container.contains(target);
+  }
+
+  private resolveComputedCursor(target: HTMLElement): string {
+    return window.getComputedStyle(target).cursor;
+  }
+
+  private handleMove = (e: PointerEvent): void => {
     if (this.options.autoDisableOnMobile && e.pointerType === "touch" && !this.options.enableTouch)
       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;
+    const container = this.options.container;
+    if (container && this.containerRect && container !== document.body) {
+      x -= this.containerRect.left;
+      y -= this.containerRect.top;
     }
 
     this.state.pointer.x = x;
     this.state.pointer.y = y;
+    this.hasSeenPointer = true;
+
+    if (!this.isEnabled) return;
 
     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 {
+  private handleDown = (): void => {
     if (this.isEnabled) this.state.isDown = true;
-  }
+  };
 
-  private handleUp(): void {
+  private handleUp = (): void => {
     if (this.isEnabled) this.state.isDown = false;
-  }
+  };
 
-  private handleMouseOver(e: MouseEvent): void {
+  private handleMouseOver = (e: Event): void => {
     if (!this.isEnabled) return;
     const target = e.target as HTMLElement;
 
-    if (target.closest(`[${this.ignoreAttribute}]`)) {
+    if (this.isOutsideContainer(target)) return;
+
+    if (this.state.cursorMode === "auto" && target.closest(`[${this.ignoreAttribute}]`)) {
+      this.state.isHover = false;
+      this.state.hoverTarget = null;
+      this.state.interaction = {};
+      this.currentTarget = null;
+      this.lastParsedTarget = null;
+      this.matchedRules = [];
+
       this.state.isNative = true;
+      this.nativeTarget = target;
       return;
     }
 
-    const selector = this.getHoverSelector();
-    const hoverable = target.closest(selector);
+    this.state.isNative = false;
+    this.nativeTarget = null;
 
+    this.currentTarget = target;
+    this.parseDOMInteraction(target);
+
+    if (this.state.cursorMode !== "auto") {
+      const hoverable = target.closest(this.getHoverSelector());
+      if (hoverable) {
+        this.state.isHover = true;
+        this.state.hoverTarget = hoverable as HTMLElement;
+      }
+      return;
+    }
+
+    const hoverable = target.closest(this.getHoverSelector());
     if (hoverable) {
       this.state.isHover = true;
       this.state.hoverTarget = hoverable as HTMLElement;
-      this.parseDOMInteraction(this.state.hoverTarget);
     }
 
-    const strategy = this.options.ignoreOnNative;
-
-    if (strategy && strategy !== null) {
-      const checkTags = strategy === "auto" || strategy === "tag";
-      const checkCSS = 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;
-      }
+    // Built-in native detection: tags + CSS
+    const checkTags = NATIVE_TAGS.has(target.localName) || target.isContentEditable;
+    const checkCSS = !SUPERMOUSE_CURSORS.has(this.resolveComputedCursor(target));
+    if (checkTags || checkCSS) {
+      this.state.isNative = true;
+      this.nativeTarget = target;
     }
-  }
+  };
 
-  private handleMouseOut(e: MouseEvent): void {
+  private handleMouseOut = (e: Event): void => {
     if (!this.isEnabled) return;
     const target = e.target as HTMLElement;
+    const related = (e as MouseEvent).relatedTarget as Node | null;
+
+    if (this.isOutsideContainer(target)) return;
 
     if (target === this.state.hoverTarget || target.contains(this.state.hoverTarget)) {
-      if (!e.relatedTarget || !this.state.hoverTarget?.contains(e.relatedTarget as Node)) {
+      if (!related || !this.state.hoverTarget?.contains(related)) {
         this.state.isHover = false;
         this.state.hoverTarget = null;
-        this.state.interaction = {};
       }
     }
 
-    if (this.state.isNative) {
-      this.state.isNative = false;
+    if (this.nativeTarget && (target === this.nativeTarget || target.contains(this.nativeTarget))) {
+      if (!related || !this.nativeTarget.contains(related)) {
+        this.state.isNative = false;
+        this.nativeTarget = null;
+      }
     }
-  }
 
-  private handleWindowLeave(): void {
+    // Clear current target when pointer leaves it
+    if (target === this.currentTarget) {
+      this.currentTarget = null;
+      this.lastParsedTarget = null;
+      this.matchedRules = [];
+    }
+  };
+
+  private handleWindowLeave = (): void => {
     if (this.options.hideOnLeave) {
       this.state.hasReceivedInput = false;
       this.state.pointer = { ...OFFSCREEN };
     }
-  }
+  };
 
   public clearHover(): void {
     this.state.isHover = false;
     this.state.hoverTarget = null;
     this.state.isNative = false;
+    this.nativeTarget = null;
     this.state.interaction = {};
+    this.currentTarget = null;
+    this.lastParsedTarget = null;
+    this.matchedRules = [];
+  }
+
+  /** Returns the raw element currently under the pointer. */
+  public getCurrentTarget(): HTMLElement | null {
+    return this.currentTarget;
   }
 
   private bindEvents(): void {
     const { signal } = this.abortController;
-    window.addEventListener("pointermove", this.handleMove.bind(this), { passive: true, signal });
-    window.addEventListener("pointerdown", this.handleDown.bind(this), { passive: true, signal });
-    window.addEventListener("pointerup", this.handleUp.bind(this), { signal });
+    window.addEventListener("pointermove", this.handleMove, { passive: true, signal });
+    window.addEventListener("pointerdown", this.handleDown, { passive: true, signal });
+    window.addEventListener("pointerup", this.handleUp, { signal });
 
-    document.addEventListener("mouseover", this.handleMouseOver.bind(this), { signal });
-    document.addEventListener("mouseout", this.handleMouseOut.bind(this), { signal });
-    document.addEventListener("mouseleave", this.handleWindowLeave.bind(this), { signal });
+    const isBody = !this.options.container || this.options.container === document.body;
+    const hoverRoot = isBody ? document : this.options.container!;
+    hoverRoot.addEventListener("mouseover", this.handleMouseOver, { signal });
+    hoverRoot.addEventListener("mouseout", this.handleMouseOut, { signal });
+    document.addEventListener("mouseleave", this.handleWindowLeave, { signal });
   }
 
   public destroy(): void {
     this.abortController.abort();
+    this.resizeObserver?.disconnect();
   }
 }
 
 let stageCount = 0;
 
 /**
- * Stage.ts
- *
- * This class manages the DOM container for the custom cursor and handles native cursor visibility.
- * It is instantiated by the `Supermouse` class and is not intended for direct use by plugins.
+ * Owns the stage container and manages native-cursor suppression via injected styles.
+ * The stylesheet is rebuilt only when selectors change, not per frame.
  *
- * @internal
+ * @internal Instantiated by `Supermouse`.
  */
 export class Stage {
-  /** The container element appended to the document. */
   public readonly element: HTMLDivElement;
   private styleTag: HTMLStyleElement;
-  private id: string;
-  private scopeClass: string;
+  private readonly id: string;
+  private readonly scopeClass: string;
+  private readonly hideClass: string;
 
-  private currentCursorState: "none" | "auto" | "" | null = null;
+  private currentCursorState: "none" | "auto" | null = null;
   private originalContainerPosition: string = "";
   private originalContainerCursor: string = "";
+
+  /** Selectors that need explicit `cursor: none !important` to override UA styles. */
   private selectors: Set<string> = new Set([
     "a",
     "button",
@@ -269,24 +412,30 @@ export class Stage {
 
   constructor(
     private container: HTMLElement = document.body,
-    private hideNativeCursor: boolean
+    private zIndex: number = 9999
   ) {
     if (!container || !(container instanceof HTMLElement)) {
       throw new Error(`[Supermouse] Invalid container: ${container}. Must be an HTMLElement.`);
     }
+    if (!container.isConnected) {
+      console.warn(
+        "[Supermouse] container is not attached to the document — " +
+          "stage sizing/positioning will be wrong until it is."
+      );
+    }
 
     const instanceId = stageCount++;
     this.id = `supermouse-style-${instanceId}`;
     this.scopeClass = `supermouse-scope-${instanceId}`;
+    this.hideClass = `supermouse-hide-${instanceId}`;
 
     const isBody = container === document.body;
-
     this.element = document.createElement("div");
     Object.assign(this.element.style, {
       position: isBody ? "fixed" : "absolute",
       inset: "0px",
       pointerEvents: "none",
-      zIndex: "9999",
+      zIndex: String(this.zIndex),
       opacity: "1",
       transition: "opacity 0.15s ease"
     });
@@ -294,59 +443,50 @@ export class Stage {
     if (!isBody) {
       const computed = window.getComputedStyle(container);
       this.originalContainerPosition = computed.position;
-      if (computed.position === "static") {
-        container.style.position = "relative";
-      }
+      if (computed.position === "static") container.style.position = "relative";
     }
 
     this.originalContainerCursor = container.style.cursor;
-
     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);
+    this.container.classList.add("supermouse-scope", this.scopeClass);
+    this.updateCursorCSS();
+  }
 
-    if (this.hideNativeCursor) {
-      this.setNativeCursor("none");
+  /** Batch add selectors. Comma‑separated groups are split and scoped individually. */
+  public addSelectors(selectors: Iterable<string>): void {
+    let changed = false;
+    for (const selector of selectors) {
+      selector.split(",").forEach((s) => {
+        const trimmed = s.trim();
+        if (trimmed && !this.selectors.has(trimmed)) {
+          this.selectors.add(trimmed);
+          changed = true;
+        }
+      });
     }
+    if (changed) this.updateCursorCSS();
   }
 
-  /**
-   * Adds a new CSS selector to the `selectors` set.
-   * Called by `Supermouse` and subsequently plugins during install to ensure
-   * the native cursor is hidden on their specific interactive targets.
-   */
+  /** Add a single selector (or comma‑separated group). */
   public addSelector(selector: string): void {
-    this.selectors.add(selector);
-    if (this.hideNativeCursor) {
-      this.updateCursorCSS();
-    }
+    this.addSelectors([selector]);
   }
 
   public setVisibility(visible: boolean): void {
     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.
-   */
+  /** Toggle native cursor visibility. */
   public setNativeCursor(type: "none" | "auto"): void {
-    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 = "";
-    }
+    this.container.classList.toggle(this.hideClass, type === "none");
+    this.container.style.cursor = type === "none" ? "none" : this.originalContainerCursor;
   }
 
   private updateCursorCSS(): void {
@@ -356,45 +496,59 @@ export class Stage {
       return;
     }
 
-    const scopedSelectors = rawSelectors.map((s) => `.${this.scopeClass} ${s}`).join(", ");
+    const exclusion = `:not(.${this.scopeClass} .supermouse-scope):not(.${this.scopeClass} .supermouse-scope *)`;
+    const scopeRule = (s: string) =>
+      `.${this.scopeClass}.${this.hideClass} ${s}${exclusion} { cursor: none !important; }`;
+
+    const scopedRules = rawSelectors.map(scopeRule).join("\n");
+
+    const broadRule = `.${this.scopeClass}.${this.hideClass} *${exclusion} { cursor: none !important; }`;
+    const containerRule = `.${this.scopeClass}.${this.hideClass} { cursor: none !important; }`;
 
     this.styleTag.innerText = `
-      ${scopedSelectors} {
-        cursor: none !important;
-      }
-    `;
+    ${containerRule}
+    ${broadRule}
+    ${scopedRules}
+    ${scopeRule("label")}
+    ${scopeRule("select")}
+    ${scopeRule('input[type="range"]::-webkit-slider-thumb')}
+    ${scopeRule('input[type="range"]::-moz-range-thumb')}
+  `;
   }
 
   public destroy(): void {
     this.element.remove();
     this.styleTag.remove();
-
     this.container.style.cursor = this.originalContainerCursor;
-    this.container.classList.remove(this.scopeClass);
-
+    this.container.classList.remove("supermouse-scope", this.scopeClass, this.hideClass);
     if (this.container !== document.body && this.originalContainerPosition === "static") {
       this.container.style.position = "";
     }
   }
 }
 
-const OFFSCREEN = { x: -100, y: -100 } as const;
-export const DEFAULT_HOVER_SELECTORS = [
-  "a",
-  "button",
-  "input",
-  "textarea",
-  "[data-hover]",
-  "[data-cursor]"
-];
+/**
+ * The subset of `SupermouseOptions` guaranteed to have a concrete value once
+ * the constructor has merged user input over the defaults.
+ */
+type ResolvedOptions = SupermouseOptions &
+  Required<
+    Pick<
+      SupermouseOptions,
+      | "smoothness"
+      | "enableTouch"
+      | "autoDisableOnMobile"
+      | "cursor"
+      | "hideOnLeave"
+      | "autoStart"
+      | "container"
+      | "dataPrefix"
+      | "zIndex"
+    >
+  >;
 
 /**
- * Supermouse Runtime Loop
- *
- * This class orchestrates the application state, manages the animation loop,
- * and coordinates data flow between the internal systems, and the plugins.
- *
- * @default
+ * Orchestrates state, animation loop, and plugin lifecycle.
  */
 export class Supermouse {
   public static readonly version: string = VERSION;
@@ -402,51 +556,48 @@ export class Supermouse {
 
   state: MouseState;
 
-  /**
-   * Configuration options.
-   */
-  options: SupermouseOptions;
+  /** Configuration options, fully resolved with defaults applied. */
+  options: ResolvedOptions;
 
   private plugins: SupermousePlugin[] = [];
-  private stage: Stage;
+  private _stage: Stage;
   private input: Input;
 
   private rafId: number = 0;
   private lastTime: number = 0;
   private isRunning: boolean = false;
+  private isSuspended: boolean = false;
+  private visibilityAbortController = new AbortController();
 
   private hoverSelectors: Set<string>;
+  private hoverSelectorString: string;
+  private crashedPlugins: SupermousePlugin[] = [];
 
-  /**
-   * 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,
+      cursor: "auto",
       hideOnLeave: true,
       autoStart: true,
       container: document.body,
       dataPrefix: "supermouse",
+      zIndex: 9999,
       ...options
-    };
+    } as ResolvedOptions;
 
     this.state = {
-      pointer: { x: -100, y: -100 },
-      target: { x: -100, y: -100 },
-      smooth: { x: -100, y: -100 },
+      pointer: { ...OFFSCREEN },
+      target: { ...OFFSCREEN },
+      smooth: { ...OFFSCREEN },
       velocity: { x: 0, y: 0 },
+      displacement: { x: 0, y: 0 },
       angle: 0,
       isDown: false,
       isHover: false,
       isNative: false,
-      forcedCursor: null,
+      cursorMode: this.options.cursor,
       hoverTarget: null,
       reducedMotion: false,
       hasReceivedInput: false,
@@ -454,154 +605,184 @@ export class Supermouse {
       interaction: {}
     };
 
-    if (this.options.hoverSelectors) {
-      this.hoverSelectors = new Set(this.options.hoverSelectors);
-    } else {
-      this.hoverSelectors = new Set(DEFAULT_HOVER_SELECTORS);
-    }
+    this.hoverSelectors = new Set(this.options.hoverSelectors ?? DEFAULT_HOVER_SELECTORS);
+    this.hoverSelectorString = Array.from(this.hoverSelectors).join(", ");
 
-    this.stage = new Stage(this.options.container, !!this.options.hideCursor);
-    this.hoverSelectors.forEach((s) => this.stage.addSelector(s));
+    this._stage = new Stage(this.options.container, this.options.zIndex);
+    this._stage.addSelectors(this.hoverSelectors);
 
     this.input = new Input(
       this.state,
       this.options,
-      () => Array.from(this.hoverSelectors).join(", "),
+      () => this.hoverSelectorString,
       (enabled) => {
         if (!enabled) this.reset(true);
       }
     );
 
-    if (this.options.plugins) {
-      this.options.plugins.forEach((p) => this.use(p));
-    }
-
+    this.options.plugins?.forEach((p) => this.use(p));
+    this.bindVisibilityHandling();
     this.init();
   }
 
-  /**
-   * Retrieves a registered plugin instance by its unique name.
-   */
+  /** Look up a registered plugin by name. */
   public getPlugin(name: string): SupermousePlugin | undefined {
     return this.plugins.find((p) => p.name === name);
   }
 
-  /**
-   * Returns whether the cursor system is currently enabled (processing input).
-   */
+  /** Whether the instance is not disabled/suspended and is processing input. */
   public get isEnabled(): boolean {
     return this.input.isEnabled;
   }
 
-  /**
-   * Enables a specific plugin by name.
-   * Triggers the `onEnable` lifecycle hook of the plugin.
-   */
+  /** Enable a plugin by name. */
   public enablePlugin(name: string): void {
     const plugin = this.getPlugin(name);
     if (plugin && plugin.isEnabled === false) {
       plugin.isEnabled = true;
+      if (plugin.element) plugin.element.style.display = "";
       plugin.onEnable?.(this);
     }
   }
 
-  /**
-   * Disables a specific plugin by name.
-   * Triggers the `onDisable` lifecycle hook.
-   */
+  /** Disable a plugin by name and hide its element. */
   public disablePlugin(name: string): void {
     const plugin = this.getPlugin(name);
     if (plugin && plugin.isEnabled !== false) {
       plugin.isEnabled = false;
-      plugin.onDisable?.(this);
+
+      const finishDisable = () => {
+        if (plugin.element) plugin.element.style.display = "none";
+        plugin.onDisable?.(this);
+      };
+
+      const result = plugin.onBeforeDisable?.(this);
+      if (result && typeof result.then === "function") {
+        void Promise.resolve(result)
+          .then(finishDisable)
+          .catch((err) => {
+            console.error(`[Supermouse] Plugin '${plugin.name}' onBeforeDisable threw:`, err);
+            finishDisable();
+          });
+      } else {
+        finishDisable();
+      }
     }
   }
 
-  /**
-   * Toggles the enabled state of a plugin.
-   */
+  /** Toggle a plugin's enabled state by name. */
   public togglePlugin(name: string): void {
     const plugin = this.getPlugin(name);
-    if (plugin) {
-      if (plugin.isEnabled === false) this.enablePlugin(name);
-      else this.disablePlugin(name);
-    }
+    if (!plugin) return;
+    if (plugin.isEnabled === false) this.enablePlugin(name);
+    else this.disablePlugin(name);
   }
 
+  /** Add a selector to hover detection and cursor suppression. */
   public registerHoverTarget(selector: string): void {
     if (!this.hoverSelectors.has(selector)) {
       this.hoverSelectors.add(selector);
-      this.stage.addSelector(selector);
+      this.hoverSelectorString = Array.from(this.hoverSelectors).join(", ");
+      this._stage.addSelector(selector);
     }
   }
 
-  /**
-   * The fixed container element where plugins should append their DOM nodes.
-   */
-  public get container(): HTMLDivElement {
-    return this.stage.element;
+  /** The DOM element the instance is scoped to. */
+  public get container(): HTMLElement {
+    return this.options.container;
   }
 
-  /**
-   * Sets the native cursor visibility.
-   *
-   * @param mode
-   */
-  public setNativeCursor(mode: "hide" | "show" | "auto"): void {
-    this.state.forcedCursor = mode === "auto" ? null : mode === "hide" ? "none" : "auto";
+  /** The stage element that plugins append their visuals into. */
+  public get stage(): HTMLDivElement {
+    return this._stage.element;
+  }
+
+  /** Set the current cursor mode. */
+  public setCursor(mode: "auto" | "custom" | "native" | "both"): void {
+    this.state.cursorMode = mode;
   }
 
   private init(): void {
-    if (this.options.autoStart) {
-      this.startLoop();
-    }
+    if (this.options.autoStart) this.startLoop();
   }
 
+  /** Re‑enable input processing and re‑apply cursor state. */
   public enable(): void {
     this.input.isEnabled = true;
-    this.stage.setNativeCursor("none");
+
+    if (this.input.hasSeenPointer) {
+      this.state.target.x = this.state.smooth.x = this.state.pointer.x;
+      this.state.target.y = this.state.smooth.y = this.state.pointer.y;
+      this.resetMotion();
+      this.state.hasReceivedInput = true;
+    }
+
+    this._stage.setNativeCursor(this.resolveCursorState());
   }
+
+  /** Disable input processing and restore native cursor. */
   public disable(): void {
     this.input.isEnabled = false;
-    this.stage.setNativeCursor("auto");
+    this._stage.setNativeCursor("auto");
+    this._stage.setVisibility(false);
     this.reset(true);
   }
 
-  /**
-   * Registers a new plugin.
-   *
-   * @param plugin - The plugin object to install.
-   */
-  public use(plugin: SupermousePlugin): this {
-    const exists = this.plugins.some((p) => p.name === plugin.name);
+  /** Temporarily yield to a scoped instance. */
+  public suspend(): void {
+    if (!this.input.isEnabled) return;
+    this.isSuspended = true;
+    this.input.isEnabled = false;
+    this.input.clearHover();
+    /** Current limitations with multi-scoped containers identified.
+     * setting native cursor here suppresses cursor css so aggressively
+     * that cursor: "both" will not work on scoped instances.
+     * proposed fix by v2.5+ */
+    // this._stage.setNativeCursor("auto");
+    this._stage.setVisibility(false);
+  }
+
+  /** Resume from `suspend()`. */
+  public resume(): void {
+    if (!this.isSuspended) return;
+    this.isSuspended = false;
+    this.input.isEnabled = true;
 
-    if (exists) {
-      console.warn(`[Supermouse] Plugin "${plugin.name}" already installed.`);
-      return this;
+    if (this.state.hasReceivedInput) {
+      this.state.target.x = this.state.smooth.x = this.state.pointer.x;
+      this.state.target.y = this.state.smooth.y = this.state.pointer.y;
+      this.resetMotion();
     }
-
-    if (plugin.isEnabled === undefined) {
-      plugin.isEnabled = true;
+    // Update plugins before showing stage to avoid stale visuals.
+    for (let i = this.plugins.length - 1; i >= 0; i--) {
+      this.runPluginSafe(this.plugins[i], 0);
     }
+    this._stage.setVisibility(true);
+  }
 
+  /** Register a new plugin. */
+  public use(plugin: SupermousePlugin): this {
+    if (this.plugins.some((p) => p.name === plugin.name)) {
+      console.warn(`[Supermouse] Plugin "${plugin.name}" already installed.`);
+      return this;
+    }
+    plugin.isEnabled ??= true;
     try {
       plugin.install?.(this);
     } catch (e) {
       console.error(`[Supermouse] Failed to install plugin '${plugin.name}'.`, e);
       return this;
     }
-
     this.plugins.push(plugin);
-    this.plugins.sort((a, b) => (a.priority || 0) - (b.priority || 0));
-
+    this.plugins.sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
     return this;
   }
 
+  /** Reset physics; optionally clear all input state. */
   private reset(hard = false): void {
-    this.state.pointer = { ...OFFSCREEN };
     this.state.target = { ...OFFSCREEN };
     this.state.smooth = { ...OFFSCREEN };
-    this.state.velocity = { x: 0, y: 0 };
+    this.resetMotion();
     this.state.angle = 0;
     if (hard) {
       this.state.hasReceivedInput = false;
@@ -613,26 +794,19 @@ export class Supermouse {
   private startLoop(): void {
     if (this.isRunning) return;
     this.isRunning = true;
-
+    if (document.hidden) return;
     this.lastTime = performance.now();
-    this.tick(this.lastTime);
+    this.rafId = requestAnimationFrame(this.tick);
   }
 
-  /**
-   * Starts the animation loop. This is automatically called if `autoStart` is true.
-   * Plugins can call this method to resume the loop if it has been stopped.
-   */
+  /** Start the animation loop. */
   public start(): void {
     this.startLoop();
   }
 
-  /**
-   * Manually steps the animation loop.
-   *
-   * @param time Current timestamp in milliseconds.
-   */
+  /** Manually step the animation loop. */
   public step(time: number): void {
-    this.tick(time);
+    this.update(time);
   }
 
   private runPluginSafe(plugin: SupermousePlugin, deltaTime: number): void {
@@ -641,91 +815,139 @@ export class Supermouse {
       plugin.update?.(this, deltaTime);
     } catch (e) {
       console.error(`[Supermouse] Plugin '${plugin.name}' crashed and has been disabled.`, e);
-
-      // Remove from active array immediately so it doesn't iterate again
-      const index = this.plugins.indexOf(plugin);
-      if (index > -1) {
-        this.plugins.splice(index, 1);
-      }
-
       plugin.isEnabled = false;
+      this.crashedPlugins.push(plugin);
+    }
+  }
 
-      // Attempt cleanup
+  private cleanupCrashedPlugins(): void {
+    if (this.crashedPlugins.length === 0) return;
+    for (const plugin of this.crashedPlugins) {
+      const index = this.plugins.indexOf(plugin);
+      if (index > -1) this.plugins.splice(index, 1);
       try {
-        plugin.destroy?.(this);
         plugin.onDisable?.(this);
+        plugin.destroy?.(this);
       } catch (err) {
         console.error(`[Supermouse] Failed to cleanup crashed plugin '${plugin.name}'.`, err);
       }
+      plugin.element?.remove();
     }
+    this.crashedPlugins = [];
   }
 
-  /**
-   * Runs on every animation frame.
-   */
-  private tick = (time: number): void => {
+  private resolveStageVisibility(): boolean {
+    if (this.state.cursorMode === "native") return false;
+    if (this.state.cursorMode === "both")
+      return this.input.isEnabled && this.state.hasReceivedInput;
+    if (this.state.cursorMode === "custom")
+      return this.input.isEnabled && this.state.hasReceivedInput;
+
+    return this.input.isEnabled && !this.state.isNative && this.state.hasReceivedInput;
+  }
+
+  private resolveCursorState(): "none" | "auto" {
+    if (!this.input.isEnabled) return "auto";
+
+    if (this.state.cursorMode === "both") return "auto";
+    if (this.state.cursorMode === "native") return "auto";
+    if (this.state.cursorMode === "custom") return "none";
+    return this.state.isNative || !this.state.hasReceivedInput ? "auto" : "none";
+  }
+
+  private resetMotion(): void {
+    this.state.velocity = { x: 0, y: 0 };
+    this.state.displacement = { x: 0, y: 0 };
+  }
+
+  private update(time: number): void {
     const dtMs = time - this.lastTime;
     const dt = Math.min(dtMs / 1000, 0.1);
     this.lastTime = time;
 
-    if (this.state.hoverTarget && !this.state.hoverTarget.isConnected) {
+    const currentTarget = this.input.getCurrentTarget();
+    if (currentTarget && !currentTarget.isConnected) {
       this.input.clearHover();
+    } else if (currentTarget) {
+      this.input.parseDOMInteraction(currentTarget);
     }
 
-    const shouldShowStage =
-      this.input.isEnabled && !this.state.isNative && this.state.hasReceivedInput;
-    this.stage.setVisibility(shouldShowStage);
-
-    if (this.input.isEnabled && this.options.hideCursor) {
-      let targetState: "none" | "auto" = "auto";
-      if (this.state.forcedCursor !== null) {
-        targetState = this.state.forcedCursor;
-      } else {
-        const showNative = this.state.isNative || !this.state.hasReceivedInput;
-        targetState = showNative ? "auto" : "none";
-      }
-      this.stage.setNativeCursor(targetState);
+    this._stage.setVisibility(this.resolveStageVisibility());
+    if (this.input.isEnabled) {
+      this._stage.setNativeCursor(this.resolveCursorState());
     }
 
     if (this.input.isEnabled && this.state.hasReceivedInput) {
       this.state.target.x = this.state.pointer.x;
       this.state.target.y = this.state.pointer.y;
-    } else {
-      this.state.target = { ...OFFSCREEN };
     }
 
     for (let i = 0; i < this.plugins.length; i++) {
       this.runPluginSafe(this.plugins[i], dtMs);
     }
+    this.cleanupCrashedPlugins();
 
     if (this.input.isEnabled) {
-      const factor = this.state.reducedMotion ? 1000 : (1 / this.options.smoothness!) * 2;
+      const factor = this.state.reducedMotion ? 1000 : (1 / this.options.smoothness) * 2;
+
+      const previousX = this.state.smooth.x;
+      const previousY = this.state.smooth.y;
 
       this.state.smooth.x = damp(this.state.smooth.x, this.state.target.x, factor, dt);
       this.state.smooth.y = damp(this.state.smooth.y, this.state.target.y, factor, dt);
 
-      this.state.velocity.x = this.state.target.x - this.state.smooth.x;
-      this.state.velocity.y = this.state.target.y - this.state.smooth.y;
+      this.state.displacement.x = this.state.target.x - this.state.smooth.x;
+      this.state.displacement.y = this.state.target.y - this.state.smooth.y;
+
+      if (dt > 0) {
+        this.state.velocity.x = (this.state.smooth.x - previousX) / dt;
+        this.state.velocity.y = (this.state.smooth.y - previousY) / dt;
+      } else {
+        this.state.velocity.x = 0;
+        this.state.velocity.y = 0;
+      }
+
       const { x: vx, y: vy } = this.state.velocity;
       if (Math.abs(vx) > 0.1 || Math.abs(vy) > 0.1) {
         this.state.angle = Math.atan2(vy, vx) * (180 / Math.PI);
       }
     }
+  }
 
+  private tick = (time: number): void => {
+    this.update(time);
     if (this.isRunning) {
       this.rafId = requestAnimationFrame(this.tick);
     }
   };
 
-  /**
-   * Destroys the instance.
-   */
+  /** Pause rAF loop when tab hidden; resume on visible. */
+  private bindVisibilityHandling(): void {
+    document.addEventListener(
+      "visibilitychange",
+      () => {
+        if (!this.isRunning) return;
+        if (document.hidden) {
+          cancelAnimationFrame(this.rafId);
+        } else {
+          this.lastTime = performance.now();
+          this.rafId = requestAnimationFrame(this.tick);
+        }
+      },
+      { signal: this.visibilityAbortController.signal }
+    );
+  }
+
+  /** Destroy the instance, freeing all resources. */
   public destroy(): void {
     this.isRunning = false;
     cancelAnimationFrame(this.rafId);
+    this.visibilityAbortController.abort();
     this.input.destroy();
-    this.stage.destroy();
+    this._stage.destroy();
     this.plugins.forEach((p) => p.destroy?.(this));
     this.plugins = [];
   }
 }
+
+export type SupermouseInstance = Supermouse;