@supermousejs/core 2.0.5 → 2.1.0

package/CHANGELOG.md

@@ -1,37 +1,51 @@
-# @supermousejs/core
-
-## 2.0.5
-
-### Patch Changes
-
-- 67f771b: Add relevant npm metadata to package.json file
-
-## 2.0.4
-
-### Patch Changes
-
-- 993dc67: Updated supemousejs packages with proper author, license and url descriptors to repo
-
-## 2.0.3
-
-### Patch Changes
-
-- Add keywords to core package
-
-## 2.0.2
-
-### Patch Changes
-
-- ae219a0: Update READMEs with correct link to documentation
-
-## 2.0.1
-
-### Patch Changes
-
-- Add minimal README.md files to packages
-
-## 2.0.0
-
-### Major Changes
-
-- Initial v2.0.0 release
+# @supermousejs/core
+
+## 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
+
+- 67f771b: Add relevant npm metadata to package.json file
+
+## 2.0.4
+
+### Patch Changes
+
+- 993dc67: Updated supemousejs packages with proper author, license and url descriptors to repo
+
+## 2.0.3
+
+### Patch Changes
+
+- Add keywords to core package
+
+## 2.0.2
+
+### Patch Changes
+
+- ae219a0: Update READMEs with correct link to documentation
+
+## 2.0.1
+
+### Patch Changes
+
+- Add minimal README.md files to packages
+
+## 2.0.0
+
+### Major Changes
+
+- Initial v2.0.0 release

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

@@ -48,7 +48,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 +61,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;
@@ -70,41 +70,22 @@ export declare interface ShapeState {
 }
 
 /**
- * The Central Conductor & Runtime Loop of Supermouse.
+ * Runtime Loop of Supermouse.
  *
  * 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.
- *
- * ## 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' }));
- * ```
  */
 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 +119,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,30 +126,16 @@ 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;
@@ -186,21 +143,17 @@ export declare class Supermouse {
     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 +250,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);