@supermousejs/core 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @supermousejs/core
 
+## 2.4.0
+
+### Minor Changes
+
+- 53b7276: This release stabilises the core after experimental work, keeping the best improvements while reverting the approach that caused cursor flickering.
+  - `zIndex` option – customise the stage’s z‑index (default `9999`).
+  - `cacheCursorStyle` option – opt‑in per‑element caching of computed `cursor` values, with `clearStyleCache()` to invalidate.
+  - `suspend()` / `resume()` – temporarily yield to another Supermouse instance without tearing down the current one.
+  - `hasSeenPointer` flag – enables `enable()` to snap the cursor to the live pointer instantly, no more off‑screen sweep.
+  - Nested‑instance CSS exclusion – scoped stylesheets now automatically prevent outer instance cursor rules from leaking into nested containers.
+  - `enable()` now respects any active `forcedCursor` override.
+  - `disable()` always restores the native cursor.
+  - `clearHover()` now resets `isNative` and `nativeTarget` to prevent stale state.
+  - Plugin crash handling: crashing plugins are removed after the frame with full cleanup (`onDisable` → `destroy` → element removal).
+  - `enablePlugin` / `disablePlugin` now hide/show the plugin’s DOM element (if it exposes an `element` property) and call lifecycle hooks.
+  - `reset()` no longer wipes `state.pointer`, so `enable()` can always snap to the last known position.
+  - Native‑cursor suppression now uses a class‑toggled CSS approach with additional rules for `<label>`, `<select>`, and range slider thumbs.
+  - `handleMouseOut` clears `isNative` only when truly leaving the native element, preventing flicker when moving within native controls.
+  - Animation loop pauses when the tab is hidden and resumes on focus.
+  - `Stage` warns if the container is not attached to the DOM yet.
+  - Original container `cursor` style is restored on destroy.
+  - Various other stability and edge‑case fixes.
+
+- 0cd6a04: - Unified cursor modes to reduce api surface by replacing cursor and hideCursor with single cursor option, decouple interaction parsing causing bugs
+  - Cache rule entries and hover selector string to reduce per-frame work.
+  - Suspend/resume no longer toggle native cursor state. this is an identified multi-scope limitation.
+- ab3cad2: Enhanced supermouse containerization and added options for caching computed cursor styles
+
+### Patch Changes
+
+- 36d5366: Added proper description messages to package meta
+- 4fc5aed: Added forward-compatible `onBeforeDisable` hook for plugins in preparation for architecture rewrite in v2.5
+
 ## 2.3.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,10 +1,11 @@
+/** Default selectors that trigger `state.isHover`. Override with `hoverSelectors`. */
 export declare const DEFAULT_HOVER_SELECTORS: string[];
 
 /* Excluded from this release type: Input */
 
 /**
- * The Interface for interaction state.
- * Plugins should use Module Augmentation to add their specific properties to this interface.
+ * Interaction state consumed by plugins.
+ * Extend via module augmentation for type safety.
  *
  * @example
  * declare module '@supermousejs/core' {
@@ -15,10 +16,7 @@ export declare const DEFAULT_HOVER_SELECTORS: string[];
  * }
  */
 export declare interface InteractionState {
-    /**
-     * Allow arbitrary keys for rapid prototyping.
-     * For type safety, use module augmentation to define expected keys.
-     */
+    /** Arbitrary keys allowed for quick prototyping. */
     [key: string]: any;
 }
 
@@ -28,42 +26,49 @@ export declare interface MousePosition {
 }
 
 export declare interface MouseState {
-    /** The raw position from the latest pointer event, before smoothing is applied. */
+    /** Raw pointer position from the latest event (before smoothing). */
     pointer: MousePosition;
-    /** The current goal position that the core loop is driving toward. */
+    /** Goal position the core loop drives toward. */
     target: MousePosition;
-    /** The smoothed/interpolated position used for rendering. */
+    /** Smoothed position used for rendering. */
     smooth: MousePosition;
-    /** The current movement vector derived from the smoothed state. */
+    /** Movement vector derived from smoothed state. */
     velocity: MousePosition;
-    /** The current movement angle in degrees, derived from velocity. */
+    /** Remaining distance to target. */
+    displacement: MousePosition;
+    /** Movement angle in degrees. */
     angle: number;
-    /** Whether the pointer is currently pressed down. */
+    /** Pointer is pressed down. */
     isDown: boolean;
-    /** Whether the pointer is currently hovering over a registered interactive element. */
+    /** Hovering over a registered interactive element. */
     isHover: boolean;
-    /** Whether the runtime has temporarily restored the native cursor due to native-input heuristics. */
+    /** Native cursor temporarily restored due to native-input heuristics. */
     isNative: boolean;
-    /**
-     * If set, this overrides all auto-detection logic.
-     * 'auto' = Force Native Cursor (Show)
-     * 'none' = Force Custom Cursor (Hide Native)
-     * null = Let the Core decide based on isNative/isHover
-     */
-    forcedCursor: "auto" | "none" | null;
-    /** The DOM element currently being hovered, if any. */
+    /** Current cursor mode: auto, custom, native, or both. */
+    cursorMode: "auto" | "custom" | "native" | "both";
+    /** Currently hovered DOM element, if any. */
     hoverTarget: HTMLElement | null;
-    /** Whether the user has `prefers-reduced-motion` enabled. */
+    /** User has `prefers-reduced-motion` enabled. */
     reducedMotion: boolean;
-    /** Whether the system has received valid input coordinates at least once. */
+    /** At least one valid input coordinate received. */
     hasReceivedInput: boolean;
-    /** Defines a specific geometric shape the cursor should conform to. */
+    /** Geometric shape the cursor should conform to. */
     shape: ShapeState | null;
-    /** Centralized store for hover metadata from data attributes. */
+    /** Centralized store for hover metadata from data attributes and rules. */
     interaction: InteractionState;
 }
 
-export declare type NativeIgnoreStrategy = "auto" | "tag" | "css";
+/**
+ * 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">>;
+
+export declare type RuleDefinition = RuleSet | ((el: HTMLElement) => RuleSet);
+
+export declare type RuleSet = Record<string, RuleValue | ((el: HTMLElement) => RuleValue)>;
+
+export declare type RuleValue = string | boolean | number;
 
 export declare interface ShapeState {
     width: number;
@@ -74,104 +79,78 @@ export declare interface ShapeState {
 /* Excluded from this release type: Stage */
 
 /**
- * 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 declare class Supermouse {
     static readonly version: string;
     readonly version: string;
     state: MouseState;
-    /**
-     * Configuration options.
-     */
-    options: SupermouseOptions;
+    /** Configuration options, fully resolved with defaults applied. */
+    options: ResolvedOptions;
     private plugins;
-    private stage;
+    private _stage;
     private input;
     private rafId;
     private lastTime;
     private isRunning;
+    private isSuspended;
+    private visibilityAbortController;
     private hoverSelectors;
-    /**
-     * Creates a new Supermouse instance.
-     *
-     * @param options - Global configuration options.
-     * @throws Will throw if running in a non-browser environment (window/document undefined).
-     */
+    private hoverSelectorString;
+    private crashedPlugins;
     constructor(options?: SupermouseOptions);
-    /**
-     * Retrieves a registered plugin instance by its unique name.
-     */
+    /** Look up a registered plugin by name. */
     getPlugin(name: string): SupermousePlugin | undefined;
-    /**
-     * Returns whether the cursor system is currently enabled (processing input).
-     */
+    /** Whether the instance is not disabled/suspended and is processing input. */
     get isEnabled(): boolean;
-    /**
-     * Enables a specific plugin by name.
-     * Triggers the `onEnable` lifecycle hook of the plugin.
-     */
+    /** Enable a plugin by name. */
     enablePlugin(name: string): void;
-    /**
-     * Disables a specific plugin by name.
-     * Triggers the `onDisable` lifecycle hook.
-     */
+    /** Disable a plugin by name and hide its element. */
     disablePlugin(name: string): void;
-    /**
-     * Toggles the enabled state of a plugin.
-     */
+    /** 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 fixed container element where plugins should append their DOM nodes.
-     */
-    get container(): HTMLDivElement;
-    /**
-     * Sets the native cursor visibility.
-     *
-     * @param mode
-     */
-    setNativeCursor(mode: "hide" | "show" | "auto"): 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. */
     enable(): void;
+    /** Disable input processing and restore native cursor. */
     disable(): void;
-    /**
-     * Registers a new plugin.
-     *
-     * @param plugin - The plugin object to install.
-     */
+    /** 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;
-    /**
-     * 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(): void;
-    /**
-     * Manually steps the animation loop.
-     *
-     * @param time Current timestamp in milliseconds.
-     */
+    /** Manually step the animation loop. */
     step(time: number): void;
     private runPluginSafe;
-    /**
-     * Runs on every animation frame.
-     */
+    private cleanupCrashedPlugins;
+    private resolveStageVisibility;
+    private resolveCursorState;
+    private resetMotion;
+    private update;
     private tick;
-    /**
-     * Destroys the instance.
-     */
+    /** Pause rAF loop when tab hidden; resume on visible. */
+    private bindVisibilityHandling;
+    /** Destroy the instance, freeing all resources. */
     destroy(): void;
 }
 
-/**
- * Configuration options passed to the Supermouse constructor.
- */
+export declare type SupermouseInstance = Supermouse;
+
+/** Configuration options for the Supermouse constructor. */
 export declare interface SupermouseOptions {
     /**
      * The interpolation factor (0 to 1). Lower is smoother/slower.
@@ -194,25 +173,16 @@ export declare interface SupermouseOptions {
      */
     autoDisableOnMobile?: boolean;
     /**
-     * Strategy for detecting when to fallback to the native cursor.
-     * - `'auto'`: Checks both HTML tags and CSS cursor styles (Accurate but slower).
-     * - `'tag'`: Checks only semantic tags like <input>, <textarea> (Fastest, prevents layout thrashing).
-     * - `'css'`: Checks only computed CSS cursor styles (Slow, triggers reflow).
-     * - `null`: Never fallback to native cursor.
-     *
-     * @default 'auto'
+     * Overall cursor mode.
+     * - `"auto"`: use built-in heuristic to decide per element.
+     * - `"custom"`: always show custom cursor, hide native.
+     * - `"native"`: always show native cursor, hide custom.
+     * - `"both"`: always show custom cursor **and** native cursor together (no suppression).
+     * @default "auto"
      */
-    ignoreOnNative?: NativeIgnoreStrategy | null;
-    /**
-     * Whether to hide the native cursor via scoped CSS injection on the container.
-     * When enabled, the stage toggles `cursor: none` on the configured container and
-     * on registered hover targets.
-     * @default true
-     */
-    hideCursor?: boolean;
+    cursor?: "auto" | "custom" | "native" | "both";
     /**
      * Whether to hide the custom cursor when the pointer leaves the browser viewport.
-     * When enabled the runtime clears the cursor back to an off-screen position to avoid stale hover state.
      * @default true
      */
     hideOnLeave?: boolean;
@@ -233,51 +203,48 @@ export declare interface SupermouseOptions {
     /**
      * Semantic rules mapping CSS selectors to interaction state.
      * Rules are evaluated against hovered elements and merged into `state.interaction`.
-     * Matching data attributes on the same element are also read and can override or enrich the final object.
      * @example { 'button': { icon: 'pointer' } }
      */
-    rules?: Record<string, InteractionState>;
-    /**
-     * Custom strategy to resolve interaction state from a hovered element.
-     * When provided, this callback bypasses the default `rules` + `data-[prefix]-*` scraping and
-     * returns the interaction payload directly for the current hover target.
-     */
-    resolveInteraction?: (target: HTMLElement) => InteractionState;
+    rules?: Record<string, RuleDefinition>;
     /**
      * The prefix used for data attributes to store hover metadata.
-     * For example, if dataPrefix is "supermouse", then the attribute would be "data-supermouse-*".
-     * This allows for multiple instances of Supermouse to coexist without conflicting data attributes.
      * @default "supermouse"
      */
     dataPrefix?: string;
+    /**
+     * The `z-index` applied to the cursor stage element.
+     * @default 9999
+     */
+    zIndex?: number;
 }
 
-/**
- * Interface for defining a Supermouse Plugin.
- */
+/** Interface for defining a Supermouse plugin. */
 export declare interface SupermousePlugin {
-    /** Unique name for the plugin. Used for toggling/retrieval. */
+    /** Unique plugin name. */
     name: string;
-    /** Execution priority. Lower numbers run first. */
+    /** Execution priority; lower runs first. */
     priority?: number;
-    /** If false, update() will not be called. */
+    /** If false, `update()` will not be called. */
     isEnabled?: boolean;
+    /** Root DOM element, if any. Hidden when plugin disabled. */
+    element?: HTMLElement | SVGElement;
     /** Called when `app.use()` is executed. */
-    install?: (instance: Supermouse) => void;
-    /** Called on every animation frame with the frame delta time in milliseconds. */
-    update?: (instance: Supermouse, deltaTime: number) => void;
-    /** Called when the plugin is removed or the app is destroyed. */
-    destroy?: (instance: Supermouse) => void;
-    /** Called when the plugin is enabled via .enablePlugin() */
-    onEnable?: (instance: Supermouse) => void;
-    /** Called when the plugin is disabled via .disablePlugin() */
-    onDisable?: (instance: Supermouse) => void;
+    install?: (instance: SupermouseInstance) => void;
+    /** Called every animation frame with delta time in ms. */
+    update?: (instance: SupermouseInstance, deltaTime: number) => void;
+    /** Called when plugin removed or instance destroyed. */
+    destroy?: (instance: SupermouseInstance) => void;
+    /** Called when plugin enabled via `.enablePlugin()`. */
+    onEnable?: (instance: SupermouseInstance) => void;
+    /** Called when plugin disabled via `.disablePlugin()`. */
+    onDisable?: (instance: SupermouseInstance) => void;
+    /**
+     * Called before the plugin is disabled.
+     */
+    onBeforeDisable?(instance: SupermouseInstance): void | Promise<void>;
 }
 
-/**
- * Allows a property to be a static value or a function that returns the value based on state.
- * This is primarily useful for plugin option definitions that should react to the current runtime state.
- */
+/** Static value or function that returns a value based on state. */
 export declare type ValueOrGetter<T> = T | ((state: MouseState) => T);
 
 export { }