@supermousejs/core 2.0.5 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @supermousejs/core
 
+## 2.2.0
+
+### Minor Changes
+
+- f6f44b2: Improved tree-shaking by consolidating subordinate files and helpers into the main module file
+
+## 2.1.0
+
+### Minor Changes
+
+- 2590af3: - Refactored engine by removing 200 lines of redundant comments and typedocs, with appropriate re-reference to canon web docs
+  - Fixed a framework reactivity cache trap by moving away from WeakMap (computations are light and relatively inexpensive)
+  - Fixed double crashing by implementing a `try {} catch {}` safety net for plugin installation
+  - Fixed the Input layer not refreshing plugin states (particularly on hover) when DOM content is detached in reactive frameworks with `Node.isConnected`
+
+### Patch Changes
+
+- 6d70c18: remove legacy package and update supermouse domain in readme
+- 14fb5b6: Updated tsconfig to be reference-compliant with core, utils and zoetrope when required
+
 ## 2.0.5
 
 ### Patch Changes

package/LICENSE.md

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Sijibomi Olusunmbola
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Sijibomi Olusunmbola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,31 +1,30 @@
-
-# @supermousejs/core
-
-The high-performance runtime engine for **Supermouse v2**.
-
-It separates cursor **intent** (input, physics, logic) from **rendering** (visuals), exposing a deterministic plugin pipeline.
-
-## Installation
-
-```bash
-pnpm add @supermousejs/core
-```
-
-## Basic Usage
-
-```ts
-import { Supermouse } from '@supermousejs/core';
-// Import visuals separately to keep bundle size low
-import { Dot } from '@supermousejs/dot';
-
-const app = new Supermouse({
-  smoothness: 0.15, // 0-1 (Physics damping)
-  hideCursor: true, // Auto-hide native cursor
-});
-
-app.use(Dot({ size: 8, color: '#f59e0b' }));
-```
-
-## Documentation
-
-Full documentation and interactive playground available at [supermouse](https://supermouse.vercel.app) or [check out the repo](https://github.com/Whitestar14/supermouse-js).
+# @supermousejs/core
+
+The high-performance runtime engine for **Supermouse v2**.
+
+It separates cursor **intent** (input, physics, logic) from **rendering** (visuals), exposing a deterministic plugin pipeline.
+
+## Installation
+
+```bash
+pnpm add @supermousejs/core
+```
+
+## Basic Usage
+
+```ts
+import { Supermouse } from "@supermousejs/core";
+// Import visuals separately to keep bundle size low
+import { Dot } from "@supermousejs/dot";
+
+const app = new Supermouse({
+  smoothness: 0.15, // 0-1 (Physics damping)
+  hideCursor: true // Auto-hide native cursor
+});
+
+app.use(Dot({ size: 8, color: "#f59e0b" }));
+```
+
+## Documentation
+
+Full documentation and interactive playground available at [supermouse](https://supermouse.js.org) or [check out the repo](https://github.com/Whitestar14/supermouse-js).

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 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.
@@ -48,7 +50,7 @@ export declare interface MouseState {
      * 'none' = Force Custom Cursor (Hide Native)
      * null = Let the Core decide based on isNative/isHover
      */
-    forcedCursor: 'auto' | 'none' | null;
+    forcedCursor: "auto" | "none" | null;
     /** The DOM element currently being hovered, if any. */
     hoverTarget: HTMLElement | null;
     /** Whether the user has `prefers-reduced-motion` enabled. */
@@ -61,7 +63,7 @@ export declare interface MouseState {
     interaction: InteractionState;
 }
 
-export declare type NativeIgnoreStrategy = 'auto' | 'tag' | 'css';
+export declare type NativeIgnoreStrategy = "auto" | "tag" | "css";
 
 export declare interface ShapeState {
     width: number;
@@ -69,42 +71,27 @@ export declare interface ShapeState {
     borderRadius: number;
 }
 
+/* Excluded from this release type: Stage */
+
 /**
- * The Central Conductor & Runtime Loop of Supermouse.
+ * Supermouse Runtime Loop
  *
- * This class orchestrates the application state, manages the animation loop (`requestAnimationFrame`),
- * and coordinates data flow between the Input system, the Stage system, and the Plugins.
+ * This class orchestrates the application state, manages the animation loop,
+ * and coordinates data flow between the internal systems, and the plugins.
  *
- * ## Architecture
- * 1. **Input System**: Captures raw events and writes to `state.pointer`.
- * 2. **Logic Plugins**: (Priority < 0) Read `pointer`, modify `state.target` (e.g. Magnetic, Stick).
- * 3. **Physics**: Core interpolates `state.smooth` towards `state.target`.
- * 4. **Visual Plugins**: (Priority >= 0) Read `state.smooth`, update DOM transforms.
- *
- * @example
- * ```ts
- * const app = new Supermouse({ smoothness: 0.15 });
- * app.use(Dot({ color: 'red' }));
- * ```
+ * @default
  */
 export declare class Supermouse {
-    /** The current version of Supermouse.js */
     static readonly version: string;
     readonly version: string;
-    /**
-     * The Single Source of Truth.
-     *
-     * This object is shared by reference. `Input` writes to it; `Supermouse` physics reads/writes to it;
-     * Plugins read/write to it.
-     */
     state: MouseState;
     /**
      * Configuration options.
      */
     options: SupermouseOptions;
-    /* Excluded from this release type: plugins */
-    /* Excluded from this release type: stage */
-    /* Excluded from this release type: input */
+    private plugins;
+    private stage;
+    private input;
     private rafId;
     private lastTime;
     private isRunning;
@@ -138,16 +125,6 @@ export declare class Supermouse {
      * Toggles the enabled state of a plugin.
      */
     togglePlugin(name: string): void;
-    /**
-     * Registers a CSS selector as an "Interactive Target".
-     *
-     * When the mouse hovers over an element matching this selector:
-     * 1. `state.isHover` becomes `true`.
-     * 2. `state.hoverTarget` is set to the element.
-     * 3. The `Stage` system injects CSS to hide the native cursor for this element (if `hideCursor: true`).
-     *
-     * @param selector - A valid CSS selector string (e.g., `.my-button`, `[data-trigger]`).
-     */
     registerHoverTarget(selector: string): void;
     /**
      * The fixed container element where plugins should append their DOM nodes.
@@ -155,52 +132,35 @@ export declare class Supermouse {
     get container(): HTMLDivElement;
     /**
      * Manually override the native cursor visibility.
-     * Useful for drag-and-drop operations, modals, or special UI states.
      *
      * @param type 'auto' (Show Native), 'none' (Hide Native), or null (Resume Auto-detection)
      */
-    setCursor(type: 'auto' | 'none' | null): void;
+    setCursor(type: "auto" | "none" | null): void;
     private init;
-    /**
-     * Starts the update loop and enables input listeners.
-     * Hides the native cursor if configured.
-     */
     enable(): void;
-    /**
-     * Stops the update loop, disables listeners, and restores the native cursor.
-     * Resets internal state positions to off-screen.
-     */
     disable(): void;
     /**
      * Registers a new plugin.
      *
-     * @remarks
-     * Plugins are sorted by `priority` immediately after registration.
-     * - **Negative Priority (< 0)**: Logic plugins (run before physics).
-     * - **Positive Priority (>= 0)**: Visual plugins (run after physics).
-     *
      * @param plugin - The plugin object to install.
      */
     use(plugin: SupermousePlugin): this;
+    private resetCoords;
     private resetPosition;
     private startLoop;
     /**
      * Manually steps the animation loop.
-     * Useful when integrating with external game loops (e.g., Three.js, PixiJS) where
-     * you want to disable the internal RAF and drive `Supermouse` from your own ticker.
      *
      * @param time Current timestamp in milliseconds.
      */
     step(time: number): void;
     private runPluginSafe;
     /**
-     * The Heartbeat.
      * Runs on every animation frame.
      */
     private tick;
     /**
      * Destroys the instance.
-     * Stops the loop, removes all DOM elements, removes all event listeners, and calls destroy on all plugins.
      */
     destroy(): void;
 }
@@ -297,7 +257,7 @@ export declare interface SupermousePlugin {
 }
 
 /**
- * Helper type: Allows a property to be a static value OR a function that returns the value based on state.
+ * Allows a property to be a static value or a function that returns the value based on state.
  */
 export declare type ValueOrGetter<T> = T | ((state: MouseState) => T);