@supermousejs/core 2.3.0 → 2.4.1

package/dist/index.mjs

@@ -1,44 +1,57 @@
-const d = "2.3.0";
-function p(n, t, e) {
-  return n + (t - n) * e;
+const c = "2.4.1";
+function p(o, t, e) {
+  return o + (t - o) * e;
 }
-function c(n, t, e, i) {
-  return p(n, t, 1 - Math.exp(-e * i));
+function d(o, t, e, s) {
+  return p(o, t, 1 - Math.exp(-e * s));
 }
-class f {
-  constructor(t, e, i, a) {
-    this.state = t, this.options = e, this.getHoverSelector = i, this.onEnableChange = a, this.dataPrefix = this.options.dataPrefix ?? "supermouse", this.normalizedDataPrefix = this.dataPrefix.toLowerCase(), this.ignoreAttribute = `data-${this.dataPrefix}-ignore`, this.checkDeviceCapability(), this.checkMotionPreference(), this.bindEvents();
+const h = { x: -100, y: -100 }, g = /* @__PURE__ */ new Set(["input", "textarea", "select"]), f = /* @__PURE__ */ new Set([
+  "default",
+  "auto",
+  "pointer",
+  "none",
+  "inherit",
+  "grab",
+  "grabbing"
+]), m = [
+  "a",
+  "button",
+  "input",
+  "textarea",
+  "[data-hover]",
+  "[data-cursor]"
+];
+class v {
+  constructor(t, e, s, i) {
+    this.state = t, this.options = e, this.getHoverSelector = s, this.onEnableChange = i, this.dataPrefix = this.options.dataPrefix ?? "supermouse", 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();
   }
   state;
   options;
   getHoverSelector;
   onEnableChange;
   mediaQueryList;
-  mediaQueryHandler;
   motionQuery;
   dataPrefix;
   normalizedDataPrefix;
   ignoreAttribute;
-  /**
-   * Master switch for input processing.
-   * Toggled by `Supermouse.enable()`/`disable()` or automatically by device capability checks.
-   */
-  isEnabled = !0;
   abortController = new AbortController();
-  /**
-   * Automatically disables the custom cursor on devices without fine pointer control.
-   */
+  nativeTarget = null;
+  hasSeenPointer = !1;
+  isEnabled = !0;
+  containerRect = null;
+  resizeObserver;
+  /** Cached matched rules for the current interaction element. */
+  matchedRules = [];
+  lastParsedTarget = null;
+  /** Precomputed list of rule entries for faster iteration. */
+  ruleEntries;
+  /** The actual element currently under the pointer (regardless of hover selectors). */
+  currentTarget = null;
   checkDeviceCapability() {
-    this.options.autoDisableOnMobile && (this.mediaQueryList = window.matchMedia("(pointer: fine)"), this.updateEnabledState(this.mediaQueryList.matches), this.mediaQueryHandler = (t) => {
-      this.updateEnabledState(t.matches);
-    }, this.mediaQueryList.addEventListener("change", this.mediaQueryHandler, {
+    this.options.autoDisableOnMobile && (this.mediaQueryList = window.matchMedia("(pointer: fine)"), this.updateEnabledState(this.mediaQueryList.matches), this.mediaQueryList.addEventListener("change", (t) => this.updateEnabledState(t.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.
-   */
   checkMotionPreference() {
     this.motionQuery = window.matchMedia("(prefers-reduced-motion: reduce)"), this.state.reducedMotion = this.motionQuery.matches, this.motionQuery.addEventListener(
       "change",
@@ -51,115 +64,174 @@ class f {
   updateEnabledState(t) {
     this.isEnabled = t, this.onEnableChange(t);
   }
+  /** Caches container rect; updates on resize/scroll/ResizeObserver. */
+  setupContainerRectTracking() {
+    const t = this.options.container;
+    if (!t || t === document.body) return;
+    const e = () => {
+      this.containerRect = t.getBoundingClientRect();
+    };
+    e(), window.addEventListener("resize", e, { signal: this.abortController.signal }), window.addEventListener("scroll", e, {
+      passive: !0,
+      signal: this.abortController.signal
+    }), typeof ResizeObserver < "u" && (this.resizeObserver = new ResizeObserver(e), this.resizeObserver.observe(t));
+  }
+  /**
+   * Evaluates rules against the given element.
+   * Selector matching is cached per element; only function values re-evaluated each frame.
+   */
   parseDOMInteraction(t) {
-    if (this.options.resolveInteraction) {
-      this.state.interaction = this.options.resolveInteraction(t) || {};
-      return;
+    if (t !== this.lastParsedTarget) {
+      this.lastParsedTarget = t, this.matchedRules = [];
+      for (const [i, n] of this.ruleEntries)
+        this.matchesSelector(t, i) && this.matchedRules.push({ selector: i, rules: n });
     }
     const e = {};
-    if (this.options.rules)
-      for (const [s, o] of Object.entries(this.options.rules))
-        t.matches(s) && Object.assign(e, o);
-    const i = this.normalizedDataPrefix, a = this.dataPrefix.length;
-    for (const s in t.dataset) {
-      if (!s.toLowerCase().startsWith(i)) continue;
-      const o = s.slice(a);
-      if (!o) continue;
-      const r = t.dataset[s];
-      e[o[0].toLowerCase() + o.slice(1)] = r === "" ? !0 : r;
+    for (const { rules: i } of this.matchedRules)
+      try {
+        const n = typeof i == "function" ? i(t) : i;
+        if (!n || typeof n != "object") continue;
+        for (const [r, a] of Object.entries(n))
+          e[r] = typeof a == "function" ? a(t) : a;
+      } catch (n) {
+        console.error("[Supermouse] Rule threw during evaluation:", n);
+      }
+    const s = this.normalizedDataPrefix;
+    for (const i in t.dataset) {
+      if (!i.toLowerCase().startsWith(s)) continue;
+      const n = i.slice(s.length);
+      if (!n) continue;
+      const r = t.dataset[i];
+      e[n[0].toLowerCase() + n.slice(1)] = r === "" ? !0 : r;
     }
     this.state.interaction = e;
   }
-  handleMove(t) {
-    if (!this.isEnabled || this.options.autoDisableOnMobile && t.pointerType === "touch" && !this.options.enableTouch)
-      return;
-    let e = t.clientX, i = t.clientY;
-    if (this.options.container && this.options.container !== document.body) {
-      const a = this.options.container.getBoundingClientRect();
-      e -= a.left, i -= a.top;
+  /**
+   * Optimized selector matching:
+   * - For simple selectors (no spaces), just call `element.matches`.
+   * - For complex selectors with descendant combinators, fallback to splitting.
+   */
+  matchesSelector(t, e) {
+    try {
+      if (!/\s/.test(e.trim()))
+        return t.matches(e);
+    } catch {
+    }
+    const s = e.trim().split(/\s+/);
+    if (s.length < 2) return !1;
+    const i = s.pop(), n = s.join(" ");
+    if (!i || !n) return !1;
+    try {
+      return t.matches(i) && !!t.closest(n);
+    } catch {
+      return !1;
     }
-    this.state.pointer.x = e, this.state.pointer.y = i, this.state.hasReceivedInput || (this.state.hasReceivedInput = !0, this.state.target.x = this.state.smooth.x = e, this.state.target.y = this.state.smooth.y = i);
   }
-  handleDown() {
-    this.isEnabled && (this.state.isDown = !0);
+  isOutsideContainer(t) {
+    const { container: e } = this.options;
+    return !!e && e !== document.body && !e.contains(t);
   }
-  handleUp() {
-    this.isEnabled && (this.state.isDown = !1);
+  resolveComputedCursor(t) {
+    return window.getComputedStyle(t).cursor;
   }
-  handleMouseOver(t) {
+  handleMove = (t) => {
+    if (this.options.autoDisableOnMobile && t.pointerType === "touch" && !this.options.enableTouch)
+      return;
+    let e = t.clientX, s = t.clientY;
+    const i = this.options.container;
+    i && this.containerRect && i !== document.body && (e -= this.containerRect.left, s -= this.containerRect.top), this.state.pointer.x = e, this.state.pointer.y = s, this.hasSeenPointer = !0, this.isEnabled && (this.state.hasReceivedInput || (this.state.hasReceivedInput = !0, this.state.target.x = this.state.smooth.x = e, this.state.target.y = this.state.smooth.y = s));
+  };
+  handleDown = () => {
+    this.isEnabled && (this.state.isDown = !0);
+  };
+  handleUp = () => {
+    this.isEnabled && (this.state.isDown = !1);
+  };
+  handleMouseOver = (t) => {
     if (!this.isEnabled) return;
     const e = t.target;
-    if (e.closest(`[${this.ignoreAttribute}]`)) {
-      this.state.isNative = !0;
+    if (this.isOutsideContainer(e)) return;
+    if (this.state.cursorMode === "auto" && e.closest(`[${this.ignoreAttribute}]`)) {
+      this.state.isHover = !1, this.state.hoverTarget = null, this.state.interaction = {}, this.currentTarget = null, this.lastParsedTarget = null, this.matchedRules = [], this.state.isNative = !0, this.nativeTarget = e;
       return;
     }
-    const i = this.getHoverSelector(), a = e.closest(i);
-    a && (this.state.isHover = !0, this.state.hoverTarget = a, this.parseDOMInteraction(this.state.hoverTarget));
-    const s = this.options.ignoreOnNative;
-    if (s && s !== null) {
-      const o = s === "auto" || s === "tag", r = s === "auto" || s === "css";
-      let u = !1;
-      if (o) {
-        const h = e.localName;
-        (h === "input" || h === "textarea" || h === "select" || e.isContentEditable) && (u = !0);
-      }
-      if (!u && r) {
-        const h = window.getComputedStyle(e).cursor;
-        ["default", "auto", "pointer", "none", "inherit"].includes(h) || (u = !0);
-      }
-      u && (this.state.isNative = !0);
+    if (this.state.isNative = !1, this.nativeTarget = null, this.currentTarget = e, this.parseDOMInteraction(e), this.state.cursorMode !== "auto") {
+      const r = e.closest(this.getHoverSelector());
+      r && (this.state.isHover = !0, this.state.hoverTarget = r);
+      return;
     }
-  }
-  handleMouseOut(t) {
+    const s = e.closest(this.getHoverSelector());
+    s && (this.state.isHover = !0, this.state.hoverTarget = s);
+    const i = g.has(e.localName) || e.isContentEditable, n = !f.has(this.resolveComputedCursor(e));
+    (i || n) && (this.state.isNative = !0, this.nativeTarget = e);
+  };
+  handleMouseOut = (t) => {
     if (!this.isEnabled) return;
-    const e = t.target;
-    (e === this.state.hoverTarget || e.contains(this.state.hoverTarget)) && (!t.relatedTarget || !this.state.hoverTarget?.contains(t.relatedTarget)) && (this.state.isHover = !1, this.state.hoverTarget = null, this.state.interaction = {}), this.state.isNative && (this.state.isNative = !1);
-  }
-  handleWindowLeave() {
-    this.options.hideOnLeave && (this.state.hasReceivedInput = !1, this.state.pointer = { ...l });
-  }
+    const e = t.target, s = t.relatedTarget;
+    this.isOutsideContainer(e) || ((e === this.state.hoverTarget || e.contains(this.state.hoverTarget)) && (!s || !this.state.hoverTarget?.contains(s)) && (this.state.isHover = !1, this.state.hoverTarget = null), this.nativeTarget && (e === this.nativeTarget || e.contains(this.nativeTarget)) && (!s || !this.nativeTarget.contains(s)) && (this.state.isNative = !1, this.nativeTarget = null), e === this.currentTarget && (this.currentTarget = null, this.lastParsedTarget = null, this.matchedRules = []));
+  };
+  /**
+   * Handles the case where the pointer leaves the entire document.
+   * This is more reliable than the `mouseleave` event on `document`.
+   */
+  handleDocumentMouseOut = (t) => {
+    this.isEnabled && t.relatedTarget === null && this.options.hideOnLeave && this.handleWindowLeave();
+  };
+  handleWindowLeave = () => {
+    this.options.hideOnLeave && (this.state.hasReceivedInput = !1, this.state.pointer = { ...h });
+  };
   clearHover() {
-    this.state.isHover = !1, this.state.hoverTarget = null, this.state.isNative = !1, this.state.interaction = {};
+    this.state.isHover = !1, this.state.hoverTarget = null, this.state.isNative = !1, this.nativeTarget = null, this.state.interaction = {}, this.currentTarget = null, this.lastParsedTarget = null, this.matchedRules = [];
+  }
+  /** Returns the raw element currently under the pointer. */
+  getCurrentTarget() {
+    return this.currentTarget;
   }
   bindEvents() {
     const { signal: t } = this.abortController;
-    window.addEventListener("pointermove", this.handleMove.bind(this), { passive: !0, signal: t }), window.addEventListener("pointerdown", this.handleDown.bind(this), { passive: !0, signal: t }), window.addEventListener("pointerup", this.handleUp.bind(this), { signal: t }), document.addEventListener("mouseover", this.handleMouseOver.bind(this), { signal: t }), document.addEventListener("mouseout", this.handleMouseOut.bind(this), { signal: t }), document.addEventListener("mouseleave", this.handleWindowLeave.bind(this), { signal: t });
+    window.addEventListener("pointermove", this.handleMove, { passive: !0, signal: t }), window.addEventListener("pointerdown", this.handleDown, { passive: !0, signal: t }), window.addEventListener("pointerup", this.handleUp, { signal: t });
+    const s = !this.options.container || this.options.container === document.body ? document : this.options.container;
+    s.addEventListener("mouseover", this.handleMouseOver, { signal: t }), s.addEventListener("mouseout", this.handleMouseOut, { signal: t }), document.addEventListener("mouseout", this.handleDocumentMouseOut, { signal: t });
   }
   destroy() {
-    this.abortController.abort();
+    this.abortController.abort(), this.resizeObserver?.disconnect();
   }
 }
-let g = 0;
-class v {
-  constructor(t = document.body, e) {
-    if (this.container = t, this.hideNativeCursor = e, !t || !(t instanceof HTMLElement))
+let b = 0;
+class y {
+  constructor(t = document.body, e = 9999) {
+    if (this.container = t, this.zIndex = e, !t || !(t instanceof HTMLElement))
       throw new Error(`[Supermouse] Invalid container: ${t}. Must be an HTMLElement.`);
-    const i = g++;
-    this.id = `supermouse-style-${i}`, this.scopeClass = `supermouse-scope-${i}`;
-    const a = t === document.body;
+    t.isConnected || console.warn(
+      "[Supermouse] container is not attached to the document — stage sizing/positioning will be wrong until it is."
+    );
+    const s = b++;
+    this.id = `supermouse-style-${s}`, this.scopeClass = `supermouse-scope-${s}`, this.hideClass = `supermouse-hide-${s}`;
+    const i = t === document.body;
     if (this.element = document.createElement("div"), Object.assign(this.element.style, {
-      position: a ? "fixed" : "absolute",
+      position: i ? "fixed" : "absolute",
       inset: "0px",
       pointerEvents: "none",
-      zIndex: "9999",
+      zIndex: String(this.zIndex),
       opacity: "1",
       transition: "opacity 0.15s ease"
-    }), !a) {
-      const s = window.getComputedStyle(t);
-      this.originalContainerPosition = s.position, s.position === "static" && (t.style.position = "relative");
+    }), !i) {
+      const n = window.getComputedStyle(t);
+      this.originalContainerPosition = n.position, n.position === "static" && (t.style.position = "relative");
     }
-    this.originalContainerCursor = t.style.cursor, t.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.hideNativeCursor && this.setNativeCursor("none");
+    this.originalContainerCursor = t.style.cursor, t.appendChild(this.element), this.styleTag = document.createElement("style"), this.styleTag.id = this.id, document.head.appendChild(this.styleTag), this.container.classList.add("supermouse-scope", this.scopeClass), this.updateCursorCSS();
   }
   container;
-  hideNativeCursor;
-  /** The container element appended to the document. */
+  zIndex;
   element;
   styleTag;
   id;
   scopeClass;
+  hideClass;
   currentCursorState = null;
   originalContainerPosition = "";
   originalContainerCursor = "";
+  /** Selectors that need explicit `cursor: none !important` to override UA styles. */
   selectors = /* @__PURE__ */ new Set([
     "a",
     "button",
@@ -169,23 +241,26 @@ class v {
     '[role="button"]',
     "[tabindex]"
   ]);
-  /**
-   * 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.
-   */
+  /** Batch add selectors. Comma‑separated groups are split and scoped individually. */
+  addSelectors(t) {
+    let e = !1;
+    for (const s of t)
+      s.split(",").forEach((i) => {
+        const n = i.trim();
+        n && !this.selectors.has(n) && (this.selectors.add(n), e = !0);
+      });
+    e && this.updateCursorCSS();
+  }
+  /** Add a single selector (or comma‑separated group). */
   addSelector(t) {
-    this.selectors.add(t), this.hideNativeCursor && this.updateCursorCSS();
+    this.addSelectors([t]);
   }
   setVisibility(t) {
     this.element.style.opacity = t ? "1" : "0";
   }
-  /**
-   * Toggles the visibility of the native cursor via CSS injection.
-   * @param type 'none' to hide, 'auto' to show.
-   */
+  /** Toggle native cursor visibility. */
   setNativeCursor(t) {
-    !this.hideNativeCursor && t === "none" || t !== this.currentCursorState && (this.currentCursorState = t, t === "none" ? (this.container.style.cursor = "none", this.updateCursorCSS()) : (this.container.style.cursor = "", this.styleTag.innerText = ""));
+    t !== this.currentCursorState && (this.currentCursorState = t, this.container.classList.toggle(this.hideClass, t === "none"), this.container.style.cursor = t === "none" ? "none" : this.originalContainerCursor);
   }
   updateCursorCSS() {
     const t = Array.from(this.selectors);
@@ -193,227 +268,241 @@ class v {
       this.styleTag.innerText = "";
       return;
     }
-    const e = t.map((i) => `.${this.scopeClass} ${i}`).join(", ");
+    const e = `:not(.${this.scopeClass} .supermouse-scope):not(.${this.scopeClass} .supermouse-scope *)`, s = (a) => `.${this.scopeClass}.${this.hideClass} ${a}${e} { cursor: none !important; }`, i = t.map(s).join(`
+`), n = `.${this.scopeClass}.${this.hideClass} *${e} { cursor: none !important; }`, r = `.${this.scopeClass}.${this.hideClass} { cursor: none !important; }`;
     this.styleTag.innerText = `
-      ${e} {
-        cursor: none !important;
-      }
-    `;
+    ${r}
+    ${n}
+    ${i}
+    ${s("label")}
+    ${s("select")}
+    ${s('input[type="range"]::-webkit-slider-thumb')}
+    ${s('input[type="range"]::-moz-range-thumb')}
+  `;
   }
   destroy() {
-    this.element.remove(), this.styleTag.remove(), this.container.style.cursor = this.originalContainerCursor, this.container.classList.remove(this.scopeClass), this.container !== document.body && this.originalContainerPosition === "static" && (this.container.style.position = "");
+    this.element.remove(), this.styleTag.remove(), this.container.style.cursor = this.originalContainerCursor, this.container.classList.remove("supermouse-scope", this.scopeClass, this.hideClass), this.container !== document.body && this.originalContainerPosition === "static" && (this.container.style.position = "");
   }
 }
-const l = { x: -100, y: -100 }, m = [
-  "a",
-  "button",
-  "input",
-  "textarea",
-  "[data-hover]",
-  "[data-cursor]"
-];
-class y {
-  static version = d;
-  version = d;
+class C {
+  static version = c;
+  version = c;
   state;
-  /**
-   * Configuration options.
-   */
+  /** Configuration options, fully resolved with defaults applied. */
   options;
   plugins = [];
-  stage;
+  _stage;
   input;
   rafId = 0;
   lastTime = 0;
   isRunning = !1;
+  isSuspended = !1;
+  visibilityAbortController = new AbortController();
   hoverSelectors;
-  /**
-   * Creates a new Supermouse instance.
-   *
-   * @param options - Global configuration options.
-   * @throws Will throw if running in a non-browser environment (window/document undefined).
-   */
+  hoverSelectorString;
+  crashedPlugins = [];
   constructor(t = {}) {
     this.options = {
       smoothness: 0.15,
       enableTouch: !1,
       autoDisableOnMobile: !0,
-      ignoreOnNative: "auto",
-      hideCursor: !0,
+      cursor: "auto",
       hideOnLeave: !0,
       autoStart: !0,
       container: document.body,
       dataPrefix: "supermouse",
+      zIndex: 9999,
       ...t
     }, this.state = {
-      pointer: { x: -100, y: -100 },
-      target: { x: -100, y: -100 },
-      smooth: { x: -100, y: -100 },
+      pointer: { ...h },
+      target: { ...h },
+      smooth: { ...h },
       velocity: { x: 0, y: 0 },
+      displacement: { x: 0, y: 0 },
       angle: 0,
       isDown: !1,
       isHover: !1,
       isNative: !1,
-      forcedCursor: null,
+      cursorMode: this.options.cursor,
       hoverTarget: null,
       reducedMotion: !1,
       hasReceivedInput: !1,
       shape: null,
       interaction: {}
-    }, this.options.hoverSelectors ? this.hoverSelectors = new Set(this.options.hoverSelectors) : this.hoverSelectors = new Set(m), this.stage = new v(this.options.container, !!this.options.hideCursor), this.hoverSelectors.forEach((e) => this.stage.addSelector(e)), this.input = new f(
+    }, this.hoverSelectors = new Set(this.options.hoverSelectors ?? m), this.hoverSelectorString = Array.from(this.hoverSelectors).join(", "), this._stage = new y(this.options.container, this.options.zIndex), this._stage.addSelectors(this.hoverSelectors), this.input = new v(
       this.state,
       this.options,
-      () => Array.from(this.hoverSelectors).join(", "),
+      () => this.hoverSelectorString,
       (e) => {
         e || this.reset(!0);
       }
-    ), this.options.plugins && this.options.plugins.forEach((e) => this.use(e)), this.init();
+    ), this.options.plugins?.forEach((e) => this.use(e)), this.bindVisibilityHandling(), this.init();
   }
-  /**
-   * Retrieves a registered plugin instance by its unique name.
-   */
+  /** Look up a registered plugin by name. */
   getPlugin(t) {
     return this.plugins.find((e) => e.name === t);
   }
-  /**
-   * Returns whether the cursor system is currently enabled (processing input).
-   */
+  /** Whether the instance is not disabled/suspended and is processing input. */
   get isEnabled() {
     return this.input.isEnabled;
   }
-  /**
-   * Enables a specific plugin by name.
-   * Triggers the `onEnable` lifecycle hook of the plugin.
-   */
+  /** Enable a plugin by name. */
   enablePlugin(t) {
     const e = this.getPlugin(t);
-    e && e.isEnabled === !1 && (e.isEnabled = !0, e.onEnable?.(this));
+    e && e.isEnabled === !1 && (e.isEnabled = !0, e.element && (e.element.style.display = ""), e.onEnable?.(this));
   }
-  /**
-   * Disables a specific plugin by name.
-   * Triggers the `onDisable` lifecycle hook.
-   */
+  /** Disable a plugin by name and hide its element. */
   disablePlugin(t) {
     const e = this.getPlugin(t);
-    e && e.isEnabled !== !1 && (e.isEnabled = !1, e.onDisable?.(this));
+    if (e && e.isEnabled !== !1) {
+      e.isEnabled = !1;
+      const s = () => {
+        e.element && (e.element.style.display = "none"), e.onDisable?.(this);
+      }, i = e.onBeforeDisable?.(this);
+      i && typeof i.then == "function" ? Promise.resolve(i).then(s).catch((n) => {
+        console.error(`[Supermouse] Plugin '${e.name}' onBeforeDisable threw:`, n), s();
+      }) : s();
+    }
   }
-  /**
-   * Toggles the enabled state of a plugin.
-   */
+  /** Toggle a plugin's enabled state by name. */
   togglePlugin(t) {
     const e = this.getPlugin(t);
     e && (e.isEnabled === !1 ? this.enablePlugin(t) : this.disablePlugin(t));
   }
+  /** Add a selector to hover detection and cursor suppression. */
   registerHoverTarget(t) {
-    this.hoverSelectors.has(t) || (this.hoverSelectors.add(t), this.stage.addSelector(t));
+    this.hoverSelectors.has(t) || (this.hoverSelectors.add(t), this.hoverSelectorString = Array.from(this.hoverSelectors).join(", "), this._stage.addSelector(t));
   }
-  /**
-   * The fixed container element where plugins should append their DOM nodes.
-   */
+  /** The DOM element the instance is scoped to. */
   get container() {
-    return this.stage.element;
+    return this.options.container;
   }
-  /**
-   * Sets the native cursor visibility.
-   *
-   * @param mode
-   */
-  setNativeCursor(t) {
-    this.state.forcedCursor = t === "auto" ? null : t === "hide" ? "none" : "auto";
+  /** The stage element that plugins append their visuals into. */
+  get stage() {
+    return this._stage.element;
+  }
+  /** Set the current cursor mode. */
+  setCursor(t) {
+    this.state.cursorMode = t;
   }
   init() {
     this.options.autoStart && this.startLoop();
   }
+  /** Re‑enable input processing and re‑apply cursor state. */
   enable() {
-    this.input.isEnabled = !0, this.stage.setNativeCursor("none");
+    this.input.isEnabled = !0, 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 = !0), this._stage.setNativeCursor(this.resolveCursorState());
   }
+  /** Disable input processing and restore native cursor. */
   disable() {
-    this.input.isEnabled = !1, this.stage.setNativeCursor("auto"), this.reset(!0);
+    this.input.isEnabled = !1, this._stage.setNativeCursor("auto"), this._stage.setVisibility(!1), this.reset(!0);
+  }
+  /** Temporarily yield to a scoped instance. */
+  suspend() {
+    this.input.isEnabled && (this.isSuspended = !0, this.input.isEnabled = !1, this.input.clearHover(), this._stage.setVisibility(!1));
+  }
+  /** Resume from `suspend()`. */
+  resume() {
+    if (this.isSuspended) {
+      this.isSuspended = !1, this.input.isEnabled = !0, 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());
+      for (let t = this.plugins.length - 1; t >= 0; t--)
+        this.runPluginSafe(this.plugins[t], 0);
+      this._stage.setVisibility(!0);
+    }
   }
-  /**
-   * Registers a new plugin.
-   *
-   * @param plugin - The plugin object to install.
-   */
+  /** Register a new plugin. */
   use(t) {
-    if (this.plugins.some((i) => i.name === t.name))
+    if (this.plugins.some((e) => e.name === t.name))
       return console.warn(`[Supermouse] Plugin "${t.name}" already installed.`), this;
-    t.isEnabled === void 0 && (t.isEnabled = !0);
+    t.isEnabled ??= !0;
     try {
       t.install?.(this);
-    } catch (i) {
-      return console.error(`[Supermouse] Failed to install plugin '${t.name}'.`, i), this;
+    } catch (e) {
+      return console.error(`[Supermouse] Failed to install plugin '${t.name}'.`, e), this;
     }
-    return this.plugins.push(t), this.plugins.sort((i, a) => (i.priority || 0) - (a.priority || 0)), this;
+    return this.plugins.push(t), this.plugins.sort((e, s) => (e.priority ?? 0) - (s.priority ?? 0)), this;
   }
+  /** Reset physics; optionally clear all input state. */
   reset(t = !1) {
-    this.state.pointer = { ...l }, this.state.target = { ...l }, this.state.smooth = { ...l }, this.state.velocity = { x: 0, y: 0 }, this.state.angle = 0, t && (this.state.hasReceivedInput = !1, this.state.shape = null, this.state.interaction = {});
+    this.state.target = { ...h }, this.state.smooth = { ...h }, this.resetMotion(), this.state.angle = 0, t && (this.state.hasReceivedInput = !1, this.state.shape = null, this.state.interaction = {});
   }
   startLoop() {
-    this.isRunning || (this.isRunning = !0, this.lastTime = performance.now(), this.tick(this.lastTime));
+    this.isRunning || (this.isRunning = !0, !document.hidden && (this.lastTime = performance.now(), 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. */
   start() {
     this.startLoop();
   }
-  /**
-   * Manually steps the animation loop.
-   *
-   * @param time Current timestamp in milliseconds.
-   */
+  /** Manually step the animation loop. */
   step(t) {
-    this.tick(t);
+    this.update(t);
   }
   runPluginSafe(t, e) {
     if (t.isEnabled !== !1)
       try {
         t.update?.(this, e);
-      } catch (i) {
-        console.error(`[Supermouse] Plugin '${t.name}' crashed and has been disabled.`, i);
-        const a = this.plugins.indexOf(t);
-        a > -1 && this.plugins.splice(a, 1), t.isEnabled = !1;
+      } catch (s) {
+        console.error(`[Supermouse] Plugin '${t.name}' crashed and has been disabled.`, s), t.isEnabled = !1, this.crashedPlugins.push(t);
+      }
+  }
+  cleanupCrashedPlugins() {
+    if (this.crashedPlugins.length !== 0) {
+      for (const t of this.crashedPlugins) {
+        const e = this.plugins.indexOf(t);
+        e > -1 && this.plugins.splice(e, 1);
         try {
-          t.destroy?.(this), t.onDisable?.(this);
+          t.onDisable?.(this), t.destroy?.(this);
         } catch (s) {
           console.error(`[Supermouse] Failed to cleanup crashed plugin '${t.name}'.`, s);
         }
+        t.element?.remove();
       }
-  }
-  /**
-   * Runs on every animation frame.
-   */
-  tick = (t) => {
-    const e = t - this.lastTime, i = Math.min(e / 1e3, 0.1);
-    this.lastTime = t, this.state.hoverTarget && !this.state.hoverTarget.isConnected && this.input.clearHover();
-    const a = this.input.isEnabled && !this.state.isNative && this.state.hasReceivedInput;
-    if (this.stage.setVisibility(a), this.input.isEnabled && this.options.hideCursor) {
-      let s = "auto";
-      this.state.forcedCursor !== null ? s = this.state.forcedCursor : s = this.state.isNative || !this.state.hasReceivedInput ? "auto" : "none", this.stage.setNativeCursor(s);
+      this.crashedPlugins = [];
     }
-    this.input.isEnabled && this.state.hasReceivedInput ? (this.state.target.x = this.state.pointer.x, this.state.target.y = this.state.pointer.y) : this.state.target = { ...l };
-    for (let s = 0; s < this.plugins.length; s++)
-      this.runPluginSafe(this.plugins[s], e);
-    if (this.input.isEnabled) {
-      const s = this.state.reducedMotion ? 1e3 : 1 / this.options.smoothness * 2;
-      this.state.smooth.x = c(this.state.smooth.x, this.state.target.x, s, i), this.state.smooth.y = c(this.state.smooth.y, this.state.target.y, s, i), this.state.velocity.x = this.state.target.x - this.state.smooth.x, this.state.velocity.y = this.state.target.y - this.state.smooth.y;
-      const { x: o, y: r } = this.state.velocity;
-      (Math.abs(o) > 0.1 || Math.abs(r) > 0.1) && (this.state.angle = Math.atan2(r, o) * (180 / Math.PI));
+  }
+  resolveStageVisibility() {
+    return this.state.cursorMode === "native" ? !1 : this.state.cursorMode === "both" ? this.input.isEnabled && this.state.hasReceivedInput : this.state.cursorMode === "custom" ? this.input.isEnabled && this.state.hasReceivedInput : this.input.isEnabled && !this.state.isNative && this.state.hasReceivedInput;
+  }
+  resolveCursorState() {
+    return !this.input.isEnabled || this.state.cursorMode === "both" || this.state.cursorMode === "native" ? "auto" : this.state.cursorMode === "custom" ? "none" : this.state.isNative || !this.state.hasReceivedInput ? "auto" : "none";
+  }
+  resetMotion() {
+    this.state.velocity = { x: 0, y: 0 }, this.state.displacement = { x: 0, y: 0 };
+  }
+  update(t) {
+    const e = t - this.lastTime, s = Math.min(e / 1e3, 0.1);
+    this.lastTime = t;
+    const i = this.input.getCurrentTarget();
+    i && !i.isConnected ? this.input.clearHover() : i && this.input.parseDOMInteraction(i), this._stage.setVisibility(this.resolveStageVisibility()), this.input.isEnabled && this._stage.setNativeCursor(this.resolveCursorState()), this.input.isEnabled && this.state.hasReceivedInput && (this.state.target.x = this.state.pointer.x, this.state.target.y = this.state.pointer.y);
+    for (let n = 0; n < this.plugins.length; n++)
+      this.runPluginSafe(this.plugins[n], e);
+    if (this.cleanupCrashedPlugins(), this.input.isEnabled) {
+      const n = this.state.reducedMotion ? 1e3 : 1 / this.options.smoothness * 2, r = this.state.smooth.x, a = this.state.smooth.y;
+      this.state.smooth.x = d(this.state.smooth.x, this.state.target.x, n, s), this.state.smooth.y = d(this.state.smooth.y, this.state.target.y, n, s), this.state.displacement.x = this.state.target.x - this.state.smooth.x, this.state.displacement.y = this.state.target.y - this.state.smooth.y, s > 0 ? (this.state.velocity.x = (this.state.smooth.x - r) / s, this.state.velocity.y = (this.state.smooth.y - a) / s) : (this.state.velocity.x = 0, this.state.velocity.y = 0);
+      const { x: l, y: u } = this.state.velocity;
+      (Math.abs(l) > 0.1 || Math.abs(u) > 0.1) && (this.state.angle = Math.atan2(u, l) * (180 / Math.PI));
     }
-    this.isRunning && (this.rafId = requestAnimationFrame(this.tick));
+  }
+  tick = (t) => {
+    this.update(t), this.isRunning && (this.rafId = requestAnimationFrame(this.tick));
   };
-  /**
-   * Destroys the instance.
-   */
+  /** Pause rAF loop when tab hidden; resume on visible. */
+  bindVisibilityHandling() {
+    document.addEventListener(
+      "visibilitychange",
+      () => {
+        this.isRunning && (document.hidden ? cancelAnimationFrame(this.rafId) : (this.lastTime = performance.now(), this.rafId = requestAnimationFrame(this.tick)));
+      },
+      { signal: this.visibilityAbortController.signal }
+    );
+  }
+  /** Destroy the instance, freeing all resources. */
   destroy() {
-    this.isRunning = !1, cancelAnimationFrame(this.rafId), this.input.destroy(), this.stage.destroy(), this.plugins.forEach((t) => t.destroy?.(this)), this.plugins = [];
+    this.isRunning = !1, cancelAnimationFrame(this.rafId), this.visibilityAbortController.abort(), this.input.destroy(), this._stage.destroy(), this.plugins.forEach((t) => t.destroy?.(this)), this.plugins = [];
   }
 }
 export {
   m as DEFAULT_HOVER_SELECTORS,
-  f as Input,
-  v as Stage,
-  y as Supermouse
+  v as Input,
+  y as Stage,
+  C as Supermouse
 };