@supermousejs/core 2.4.3 → 2.5.0-beta.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @supermousejs/core
 
+## 2.5.0-beta.0
+
+### Minor Changes
+
+- 0af4732: Architecture rewrite for v2.5. This is a beta, therefore expect API surface churn before the stable release.
+
+  **Scopes.** A single instance can now own multiple scopes. Pass them at construction or add them at runtime:
+
+  ```ts
+  const mouse = new Supermouse({
+    scopes: [{ name: "sidebar", container: sidebarEl, cursor: "native" }]
+  });
+
+  const handle = mouse.addScope({ container: modalEl, cursor: "custom" });
+  handle.setCursor("auto");
+  handle.remove();
+  ```
+
+  The innermost scope whose container contains the pointer is the active one. Plugin installation, cursor mode, hover selectors, and native-cursor state are all managed per scope.
+
+  **Cursor policy.** `NATIVE_TAGS` and the old `Stage.selectors` are unified into a single `CursorPolicy`. Pass a custom policy via `cursorPolicy` at the top level or per scope. `DEFAULT_CURSOR_POLICY` is exported for spreading.
+
+  **Ancestor-chain interaction.** `data-supermouse-*` attributes and `rules` now cascade from ancestors to the hovered element, ensuring the closest ancestor wins. This fixes the tag-inside-a-tag class of bugs. Disable with `inheritDataAttributes: false`.
+
+  **Lifecycle.** `onBeforeDisable` (and its `definePlugin` equivalent, `beforeDisable`) is now scope-aware: when a scope deactivates, each of its plugins runs `onBeforeDisable`, and the core waits for any returned Promise before hiding the element and calling `onDisable`.
+
+  **Changed.**
+  - `disable()` no longer resets physics. Call `disable({ reset: true })` for the old behavior.
+  - `suspend()` and `resume()` are removed. Use scopes.
+  - `registerHoverTarget` now mutates the active scope's selector set. It's still available for raw-object plugins, but `definePlugin`'s `selector` option is preferred.
+  - Stage no longer owns an individual `<style>` tag. All scopes share a single engine-level stylesheet.
+
+  **Removed.**
+  - `NATIVE_TAGS`, `SUPERMOUSE_CURSORS` internal constants (moved into policy).
+  - `Stage.addSelector` / `Stage.addSelectors` no-ops.
+
+### Patch Changes
+
+- 1325a9c: Reorganized Supermouse core for better tree-shaking and module isolation
+
 ## 2.4.3
 
 ### Patch Changes

package/README.md

@@ -1,158 +1,158 @@
-# Supermouse.js - TypeScript cursor engine
-
-[![npm version](https://img.shields.io/npm/v/@supermousejs/core.svg?style=flat-square)](https://www.npmjs.com/package/@supermousejs/core)
-[![npm downloads](https://img.shields.io/npm/dm/@supermousejs/core.svg?style=flat-square)](https://www.npmjs.com/package/@supermousejs/core)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40supermousejs%2Fcore?label=minzip)
-
-Supermouse is a headless, physics‑based cursor engine for the web written in TypeScript. It provides pointer tracking, state, physics, and a plugin lifecycle. You install plugins (or write your own) to render custom cursors and effects. The core is zero‑dependency and TypeScript‑first.
-
-**Documentation:** [supermouse.js.org](https://supermouse.js.org)
-
-## Installation
-
-```bash
-pnpm add @supermousejs/core
-npm install @supermousejs/core
-```
-
-Install plugins you need:
-
-```bash
-pnpm add @supermousejs/dot @supermousejs/ring
-npm install @supermousejs/dot @supermousejs/ring
-```
-
-## Quick Start
-
-```ts
-import { Supermouse } from "@supermousejs/core";
-import { Dot } from "@supermousejs/dot";
-
-const mouse = new Supermouse({
-  plugins: [Dot({ size: 8 })]
-});
-```
-
-Or use the plugin interface directly:
-
-```ts
-import { Supermouse } from "@supermousejs/core";
-
-const dot = document.createElement("div");
-// ... style dot ...
-
-const redDot = {
-  name: "red-dot",
-  install(app) {
-    app.stage.appendChild(dot);
-  },
-  update(app) {
-    const { smooth } = app.state;
-    dot.style.transform = `translate3d(${smooth.x}px, ${smooth.y}px, 0)`;
-  },
-  destroy() {
-    dot.remove();
-  }
-};
-
-const mouse = new Supermouse({ plugins: [redDot] });
-```
-
-## Options
-
-| Option                | Default                                                                 | Description                                   |
-| --------------------- | ----------------------------------------------------------------------- | --------------------------------------------- |
-| `smoothness`          | `0.15`                                                                  | Lower = smoother cursor follow                |
-| `hoverSelectors`      | `["a", "button", "input", "textarea", "[data-hover]", "[data-cursor]"]` | Selectors that set `state.isHover`            |
-| `enableTouch`         | `false`                                                                 | Allow touch events to move cursor             |
-| `autoDisableOnMobile` | `true`                                                                  | Disable on coarse‑pointer devices             |
-| `cursor`              | `"auto"`                                                                | `"auto"`, `"custom"`, `"native"`, or `"both"` |
-| `hideOnLeave`         | `true`                                                                  | Hide when pointer leaves window               |
-| `container`           | `document.body`                                                         | Scoping container                             |
-| `zIndex`              | `9999`                                                                  | Stage stacking order                          |
-| `dataPrefix`          | `"supermouse"`                                                          | Prefix for data attributes                    |
-| `rules`               | —                                                                       | Map of selectors to interaction data          |
-| `plugins`             | —                                                                       | Plugins to install at creation                |
-| `autoStart`           | `true`                                                                  | Set `false` and call `.start()` manually      |
-
-## Cursor Modes
-
-- `"auto"` – native cursor on interactive elements, custom elsewhere.
-- `"custom"` – always custom, hide native.
-- `"native"` – always native, hide custom.
-- `"both"` – show both native and custom together.
-
-Change at runtime with `mouse.setCursor("both")`.
-
-## Containers & Multiple Instances
-
-Scope an instance to a container:
-
-```ts
-const modal = document.getElementById("modal");
-const mouse = new Supermouse({ container: modal, cursor: "custom" });
-```
-
-Multiple instances can coexist; CSS rules are scoped automatically.
-
-## Native Cursor Fallback
-
-In `"auto"` mode, add `data-supermouse-ignore` to force the native cursor on an element and its descendants.
-
-```html
-<div data-supermouse-ignore>Native cursor here</div>
-```
-
-## Data Attributes
-
-Plugins can react to `data-*` attributes, e.g. `data-supermouse-color`. The prefix is configurable via `dataPrefix`.
-
-## Rules
-
-Define interaction data without writing many attributes:
-
-```ts
-const mouse = new Supermouse({
-  rules: {
-    ".primary-action": { magnetic: true, color: "red" }
-  }
-});
-```
-
-HTML `data-*` attributes override rule values per property.
-
-## API
-
-```ts
-mouse.state; // current MouseState
-mouse.options; // resolved options
-mouse.stage; // DOM element plugins render into
-mouse.isEnabled; // boolean
-
-mouse.enable(); // start input, hide native cursor
-mouse.disable(); // stop input, show native cursor, reset
-mouse.suspend(); // pause non‑destructively
-mouse.resume(); // resume from suspend
-
-mouse.setCursor(mode); // "auto" | "custom" | "native" | "both"
-
-mouse.use(plugin); // install plugin
-mouse.getPlugin(name); // retrieve plugin
-mouse.enablePlugin(name); // enable plugin
-mouse.disablePlugin(name); // disable plugin
-mouse.togglePlugin(name); // toggle plugin
-
-mouse.registerHoverTarget(sel); // add hover selector at runtime
-mouse.start(); // start animation loop
-mouse.step(time); // advance one frame manually
-mouse.destroy(); // destroy instance and plugins
-```
-
-## Browser Support
-
-All modern browsers.
-
-## License
-
-MIT
+# Supermouse.js - TypeScript cursor engine
+
+[![npm version](https://img.shields.io/npm/v/@supermousejs/core.svg?style=flat-square)](https://www.npmjs.com/package/@supermousejs/core)
+[![npm downloads](https://img.shields.io/npm/dm/@supermousejs/core.svg?style=flat-square)](https://www.npmjs.com/package/@supermousejs/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40supermousejs%2Fcore?label=minzip)
+
+Supermouse is a headless, physics‑based cursor engine for the web written in TypeScript. It provides pointer tracking, state, physics, and a plugin lifecycle. You install plugins (or write your own) to render custom cursors and effects. The core is zero‑dependency and TypeScript‑first.
+
+**Documentation:** [supermouse.js.org](https://supermouse.js.org)
+
+## Installation
+
+```bash
+pnpm add @supermousejs/core
+npm install @supermousejs/core
+```
+
+Install plugins you need:
+
+```bash
+pnpm add @supermousejs/dot @supermousejs/ring
+npm install @supermousejs/dot @supermousejs/ring
+```
+
+## Quick Start
+
+```ts
+import { Supermouse } from "@supermousejs/core";
+import { Dot } from "@supermousejs/dot";
+
+const mouse = new Supermouse({
+  plugins: [Dot({ size: 8 })]
+});
+```
+
+Or use the plugin interface directly:
+
+```ts
+import { Supermouse } from "@supermousejs/core";
+
+const dot = document.createElement("div");
+// ... style dot ...
+
+const redDot = {
+  name: "red-dot",
+  install(app) {
+    app.stage.appendChild(dot);
+  },
+  update(app) {
+    const { smooth } = app.state;
+    dot.style.transform = `translate3d(${smooth.x}px, ${smooth.y}px, 0)`;
+  },
+  destroy() {
+    dot.remove();
+  }
+};
+
+const mouse = new Supermouse({ plugins: [redDot] });
+```
+
+## Options
+
+| Option                | Default                                                                 | Description                                   |
+| --------------------- | ----------------------------------------------------------------------- | --------------------------------------------- |
+| `smoothness`          | `0.15`                                                                  | Lower = smoother cursor follow                |
+| `hoverSelectors`      | `["a", "button", "input", "textarea", "[data-hover]", "[data-cursor]"]` | Selectors that set `state.isHover`            |
+| `enableTouch`         | `false`                                                                 | Allow touch events to move cursor             |
+| `autoDisableOnMobile` | `true`                                                                  | Disable on coarse‑pointer devices             |
+| `cursor`              | `"auto"`                                                                | `"auto"`, `"custom"`, `"native"`, or `"both"` |
+| `hideOnLeave`         | `true`                                                                  | Hide when pointer leaves window               |
+| `container`           | `document.body`                                                         | Scoping container                             |
+| `zIndex`              | `9999`                                                                  | Stage stacking order                          |
+| `dataPrefix`          | `"supermouse"`                                                          | Prefix for data attributes                    |
+| `rules`               | —                                                                       | Map of selectors to interaction data          |
+| `plugins`             | —                                                                       | Plugins to install at creation                |
+| `autoStart`           | `true`                                                                  | Set `false` and call `.start()` manually      |
+
+## Cursor Modes
+
+- `"auto"` – native cursor on interactive elements, custom elsewhere.
+- `"custom"` – always custom, hide native.
+- `"native"` – always native, hide custom.
+- `"both"` – show both native and custom together.
+
+Change at runtime with `mouse.setCursor("both")`.
+
+## Containers & Multiple Instances
+
+Scope an instance to a container:
+
+```ts
+const modal = document.getElementById("modal");
+const mouse = new Supermouse({ container: modal, cursor: "custom" });
+```
+
+Multiple instances can coexist; CSS rules are scoped automatically.
+
+## Native Cursor Fallback
+
+In `"auto"` mode, add `data-supermouse-ignore` to force the native cursor on an element and its descendants.
+
+```html
+<div data-supermouse-ignore>Native cursor here</div>
+```
+
+## Data Attributes
+
+Plugins can react to `data-*` attributes, e.g. `data-supermouse-color`. The prefix is configurable via `dataPrefix`.
+
+## Rules
+
+Define interaction data without writing many attributes:
+
+```ts
+const mouse = new Supermouse({
+  rules: {
+    ".primary-action": { magnetic: true, color: "red" }
+  }
+});
+```
+
+HTML `data-*` attributes override rule values per property.
+
+## API
+
+```ts
+mouse.state; // current MouseState
+mouse.options; // resolved options
+mouse.stage; // DOM element plugins render into
+mouse.isEnabled; // boolean
+
+mouse.enable(); // start input, hide native cursor
+mouse.disable(); // stop input, show native cursor, reset
+mouse.suspend(); // pause non‑destructively
+mouse.resume(); // resume from suspend
+
+mouse.setCursor(mode); // "auto" | "custom" | "native" | "both"
+
+mouse.use(plugin); // install plugin
+mouse.getPlugin(name); // retrieve plugin
+mouse.enablePlugin(name); // enable plugin
+mouse.disablePlugin(name); // disable plugin
+mouse.togglePlugin(name); // toggle plugin
+
+mouse.registerHoverTarget(sel); // add hover selector at runtime
+mouse.start(); // start animation loop
+mouse.step(time); // advance one frame manually
+mouse.destroy(); // destroy instance and plugins
+```
+
+## Browser Support
+
+All modern browsers.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,7 +1,42 @@
-/** Default selectors that trigger `state.isHover`. Override with `hoverSelectors`. */
-export declare const DEFAULT_HOVER_SELECTORS: string[];
+/** Overall cursor mode. */
+export declare type CursorMode = "auto" | "custom" | "native" | "both";
+
+export declare interface CursorPolicy {
+    rules: CursorTargetRule[];
+}
+
+/** Shorthand form accepted at the public API boundary. */
+export declare type CursorPolicyInput = CursorPolicy | {
+    native?: string[];
+    hide?: string[];
+};
+
+/**
+ * A single rule that ties a CSS selector to native-cursor behaviour
+ * and/or native-cursor CSS suppression.
+ */
+export declare interface CursorTargetRule {
+    /** CSS selector to match. */
+    selector: string;
+    /**
+     * In `"auto"` cursor mode, an element matching this selector yields to the
+     * OS cursor.
+     * @default true
+     */
+    native?: boolean;
+    /**
+     * Generate a `cursor: none !important` rule for this selector when the
+     * custom cursor is active. Needed for elements whose UA stylesheet sets a
+     * cursor value (e.g. `a { cursor: pointer }`) that would otherwise override
+     * the container's inherited `cursor: none`.
+     * @default true
+     */
+    hide?: boolean;
+}
+
+export declare const DEFAULT_CURSOR_POLICY: CursorPolicy;
 
-/* Excluded from this release type: Input */
+export declare const DEFAULT_HOVER_SELECTORS: string[];
 
 /**
  * Interaction state consumed by plugins.
@@ -45,7 +80,7 @@ export declare interface MouseState {
     /** Native cursor temporarily restored due to native-input heuristics. */
     isNative: boolean;
     /** Current cursor mode: auto, custom, native, or both. */
-    cursorMode: "auto" | "custom" | "native" | "both";
+    cursorMode: CursorMode;
     /** Currently hovered DOM element, if any. */
     hoverTarget: HTMLElement | null;
     /** User has `prefers-reduced-motion` enabled. */
@@ -58,11 +93,7 @@ export declare interface MouseState {
     interaction: InteractionState;
 }
 
-/**
- * The subset of `SupermouseOptions` guaranteed to have a concrete value once
- * the constructor has merged user input over the defaults.
- */
-declare type ResolvedOptions = SupermouseOptions & Required<Pick<SupermouseOptions, "smoothness" | "enableTouch" | "autoDisableOnMobile" | "cursor" | "hideOnLeave" | "autoStart" | "container" | "dataPrefix" | "zIndex">>;
+declare type ResolvedOptions = SupermouseOptions & Required<Pick<SupermouseOptions, "smoothness" | "enableTouch" | "autoDisableOnMobile" | "cursor" | "hideOnLeave" | "autoStart" | "container" | "dataPrefix" | "zIndex" | "inheritDataAttributes">>;
 
 export declare type RuleDefinition = RuleSet | ((el: HTMLElement) => RuleSet);
 
@@ -70,71 +101,91 @@ export declare type RuleSet = Record<string, RuleValue | ((el: HTMLElement) => R
 
 export declare type RuleValue = string | boolean | number;
 
+/**
+ * Configuration for a single scope. A scope owns a container, its cursor
+ * mode, its hover selectors, and its plugin set. Scopes stack: the innermost
+ * scope whose container contains the pointer is the active one.
+ */
+export declare interface ScopeConfig {
+    /** Optional identifier for `getScope(name)` lookups. */
+    name?: string;
+    /** The element this scope is bound to. */
+    container: HTMLElement;
+    /** Cursor mode for this scope. Inherits from top-level if omitted. */
+    cursor?: CursorMode;
+    /** Hover selectors for this scope. Inherits from top-level if omitted. */
+    hoverSelectors?: string[];
+    /** Custom cursor policy for this scope. Inherits from top-level if omitted. */
+    cursorPolicy?: CursorPolicyInput;
+    /** Plugins installed when this scope activates. */
+    plugins?: SupermousePlugin[];
+    /**
+     * Whether data attributes and rules on ancestors cascade to the hovered
+     * element. Inherits from top-level if omitted.
+     * @default true
+     */
+    inheritDataAttributes?: boolean;
+    /** Stage z-index for this scope. Inherits from top-level if omitted. */
+    zIndex?: number;
+}
+
+export declare interface ScopeHandle {
+    readonly name: string | undefined;
+    readonly container: HTMLElement;
+    remove(): void;
+    setCursor(mode: CursorMode): void;
+}
+
 export declare interface ShapeState {
     width: number;
     height: number;
     borderRadius: number;
 }
 
-/* Excluded from this release type: Stage */
-
-/**
- * Orchestrates state, animation loop, and plugin lifecycle.
- */
 export declare class Supermouse {
     static readonly version: string;
     readonly version: string;
     state: MouseState;
-    /** Configuration options, fully resolved with defaults applied. */
     options: ResolvedOptions;
-    private plugins;
-    private _stage;
+    private _scopes;
+    private _activeScope;
+    private _installingScope;
+    private scopeByContainer;
     private input;
     private rafId;
     private lastTime;
-    private isRunning;
-    private isSuspended;
     private visibilityAbortController;
-    private hoverSelectors;
-    private hoverSelectorString;
     private crashedPlugins;
     constructor(options?: SupermouseOptions);
-    /** Look up a registered plugin by name. */
-    getPlugin(name: string): SupermousePlugin | undefined;
-    /** Whether the instance is not disabled/suspended and is processing input. */
+    get container(): HTMLElement;
+    get stage(): HTMLDivElement;
     get isEnabled(): boolean;
-    /** Enable a plugin by name. */
+    get isRunning(): boolean;
+    use(plugin: SupermousePlugin): this;
+    getPlugin(name: string): SupermousePlugin | undefined;
     enablePlugin(name: string): void;
-    /** Disable a plugin by name and hide its element. */
     disablePlugin(name: string): void;
-    /** Toggle a plugin's enabled state by name. */
     togglePlugin(name: string): void;
-    /** Add a selector to hover detection and cursor suppression. */
-    registerHoverTarget(selector: string): void;
-    /** The DOM element the instance is scoped to. */
-    get container(): HTMLElement;
-    /** The stage element that plugins append their visuals into. */
-    get stage(): HTMLDivElement;
-    /** Set the current cursor mode. */
-    setCursor(mode: "auto" | "custom" | "native" | "both"): void;
-    private init;
-    /** Re‑enable input processing and re‑apply cursor state. */
+    setCursor(mode: CursorMode): void;
+    addScope(config: ScopeConfig): ScopeHandle;
     enable(): void;
-    /** Disable input processing and restore native cursor. */
-    disable(): void;
-    /** Temporarily yield to a scoped instance. */
-    suspend(): void;
-    /** Resume from `suspend()`. */
-    resume(): void;
-    /** Register a new plugin. */
-    use(plugin: SupermousePlugin): this;
-    /** Reset physics; optionally clear all input state. */
-    private reset;
-    private startLoop;
-    /** Start the animation loop. */
+    disable(opts?: {
+        reset?: boolean;
+    }): void;
+    reset(): void;
     start(): void;
-    /** Manually step the animation loop. */
     step(time: number): void;
+    destroy(): void;
+    private _running;
+    private createScope;
+    private removeScope;
+    private setScopeCursor;
+    private installPlugins;
+    private installPlugin;
+    private handleActiveScopeChange;
+    private activatePlugin;
+    private deactivatePlugin;
+    private rebuildStylesheet;
     private runPluginSafe;
     private cleanupCrashedPlugins;
     private resolveStageVisibility;
@@ -142,10 +193,24 @@ export declare class Supermouse {
     private resetMotion;
     private update;
     private tick;
-    /** Pause rAF loop when tab hidden; resume on visible. */
     private bindVisibilityHandling;
-    /** Destroy the instance, freeing all resources. */
-    destroy(): void;
+    private startLoop;
+    /**
+     * @deprecated Prefer setting `hoverSelectors` at scope creation, or use
+     * `definePlugin`'s `selector` option. This method is kept for raw-object
+     * plugins and runtime extension; it mutates the active scope's selector set.
+     */
+    registerHoverTarget(selector: string): void;
+    /**
+     * @deprecated Read from the active scope instead. Exposed for tests and
+     * debugging only.
+     */
+    get hoverSelectors(): Set<string>;
+    /**
+     * @deprecated Read from the active scope instead. Exposed for tests and
+     * debugging only.
+     */
+    get plugins(): SupermousePlugin[];
 }
 
 export declare type SupermouseInstance = Supermouse;
@@ -180,7 +245,23 @@ export declare interface SupermouseOptions {
      * - `"both"`: always show custom cursor **and** native cursor together (no suppression).
      * @default "auto"
      */
-    cursor?: "auto" | "custom" | "native" | "both";
+    cursor?: CursorMode;
+    /**
+     * Custom cursor policy. Defaults to `DEFAULT_CURSOR_POLICY` from `./policy`.
+     */
+    cursorPolicy?: CursorPolicyInput;
+    /**
+     * Additional scopes registered at construction. The primary scope is
+     * created from the top-level `container` / `hoverSelectors` / `plugins`
+     * options; these are appended after it.
+     */
+    scopes?: ScopeConfig[];
+    /**
+     * Whether data attributes and rules on ancestors cascade to the hovered
+     * element. Applies to the primary scope; individual scopes can override.
+     * @default true
+     */
+    inheritDataAttributes?: boolean;
     /**
      * Whether to hide the custom cursor when the pointer leaves the browser viewport.
      * @default true
@@ -239,7 +320,8 @@ export declare interface SupermousePlugin {
     /** Called when plugin disabled via `.disablePlugin()`. */
     onDisable?: (instance: SupermouseInstance) => void;
     /**
-     * Called before the plugin is disabled.
+     * Called before the plugin is disabled. Return a Promise to delay hiding
+     * until an exit animation completes.
      */
     onBeforeDisable?(instance: SupermouseInstance): void | Promise<void>;
 }