@supermousejs/core 2.5.0-beta.1 → 2.5.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @supermousejs/core
 
+## 2.5.0-beta.3
+
+### Patch Changes
+
+- 264bcbd: Beta.3 fixes and internal refactors.
+
+  **Fixed**
+  - Logic plugins (`priority < 0`) now correctly override `state.target` before physics. The update loop was reordering `target = pointer` after plugin execution, silently clobbering Magnetic, Stick, and any plugin that pins the cursor.
+  - Cursor state now applies synchronously on `mouseover`, `setCursor()`, and `handle.deactivate()`. Previously the cursor and stage visibility only updated on the next animation frame, causing a one-frame flash of the native cursor when entering a scope whose cursor mode differs from the previous one.
+  - Nested scope containers no longer inherit `cursor: none` from an outer scope. An engine-level `:where(.supermouse-scope .supermouse-scope) { cursor: auto }` rule cuts the inheritance without beating any authored cursor rule. Verified in Chromium and Firefox.
+  - `disablePlugin` on a plugin whose scope is inactive no longer re-fires `onBeforeDisable` and `onDisable`. Those hooks already ran when the scope went inactive. Semantics: `isEnabled` is user intent; lifecycle hooks fire on transitions of `(isEnabled && scopeIsActive)`.
+  - Deactivated eager scopes no longer orphan. The previous resolution model deleted the map entry on deactivation and never re-added it, so `handle.activate()` followed by a hover couldn't reactivate.
+  - Detached scope containers no longer pin stale bindings.
+  - `handle.activate()` is now eager when the pointer is already inside the container — fixes modals that mount under a stationary pointer.
+
+  **Changed**
+  - `ScopeHandle.remove()` renamed to `ScopeHandle.destroy()`.
+  - `ScopeHandle.disable()` / `ScopeHandle.enable()` renamed to `ScopeHandle.deactivate()` / `ScopeHandle.activate()`.
+  - `ScopeHandle.disabled` renamed to `ScopeHandle.active` (inverted).
+  - `CursorPolicy` is now `{ native: string[], hide: string[] }`. The previous `{ rules: CursorTargetRule[] }` shape is removed; `CursorTargetRule` is no longer exported.
+  - `ScopeConfig.container` accepts `HTMLElement | string`. A string is a CSS selector for lazy resolution. The scope stays dormant until an element matching the selector appears and the pointer enters it.
+  - `Stage.setNativeCursor` no longer writes inline `cursor` on the container. Cursor suppression is class-driven.
+
+  **Removed**
+  - `ViewportManager` module. Container rect reads are now direct `getBoundingClientRect()` calls in `Input.applyPointerToState`. Fixes stale-rect behavior after enter animations.
+  - Internal `scopeByContainer` map. Replaced with an ancestor walk using `Scope.match(el)`.
+
+  **Internal**
+  - Build target raised to `es2022`.
+  - `sideEffects: false` added to package.json.
+  - Size budget enforced at 6 kB gzip / 5.5 kB brotli via `size-limit`.
+
+- e9431a5: Renamed `disable` and `enable` to `deactivate` and `activate` for clarify of function and implement lazy loading of containers
+
+## 2.5.0-beta.2
+
+### Patch Changes
+
+- ff288b4: Fixed Logic Plugins not have effect from wrong ordering of target overwrite
+- 18b57de: Fixed CSS stylesheets being destroyed erroneously from a lack of a primary owner and plugins being activated all at once by the `States` plugin when re-entering previously exited scope
+
 ## 2.5.0-beta.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,39 +1,32 @@
 /** Overall cursor mode. */
 export declare type CursorMode = "auto" | "custom" | "native" | "both";
 
+/**
+ * A cursor policy maps two independent concerns to flat selector lists.
+ *
+ * - `native`: selectors whose elements yield to the OS cursor when the
+ *   cursor mode is `"auto"`. Hovering them temporarily shows the native
+ *   cursor and hides the custom one.
+ *
+ * - `hide`: selectors that receive `cursor: none !important` when the
+ *   custom cursor is active. Needed for elements whose UA stylesheet sets
+ *   a cursor (`a { cursor: pointer }`) that would otherwise override the
+ *   inherited suppression.
+ */
 export declare interface CursorPolicy {
-    rules: CursorTargetRule[];
+    native: string[];
+    hide: string[];
 }
 
-/** Shorthand form accepted at the public API boundary. */
+/**
+ * Shorthand accepted at the public API boundary. `{ native?: [...], hide?: [...] }`
+ * normalizes to the full `CursorPolicy` shape with missing keys defaulting to `[]`.
+ */
 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;
 
 export declare const DEFAULT_HOVER_SELECTORS: string[];
@@ -91,6 +84,11 @@ export declare interface MouseState {
     shape: ShapeState | null;
     /** Centralized store for hover metadata from data attributes and rules. */
     interaction: InteractionState;
+    /** The currently active scope's identity, or null when none is active. */
+    scope: {
+        name: string | undefined;
+        container: HTMLElement;
+    } | null;
 }
 
 declare type ResolvedOptions = SupermouseOptions & Required<Pick<SupermouseOptions, "smoothness" | "enableTouch" | "autoDisableOnMobile" | "cursor" | "hideOnLeave" | "autoStart" | "container" | "dataPrefix" | "zIndex" | "inheritDataAttributes">>;
@@ -109,8 +107,11 @@ export declare type RuleValue = string | boolean | number;
 export declare interface ScopeConfig {
     /** Optional identifier for `getScope(name)` lookups. */
     name?: string;
-    /** The element this scope is bound to. */
-    container: HTMLElement;
+    /**
+     * The container this scope is bound to. Pass an element reference for
+     * eager binding, or a CSS selector string for lazy resolution.
+     */
+    container: HTMLElement | string;
     /** Cursor mode for this scope. Inherits from top-level if omitted. */
     cursor?: CursorMode;
     /** Hover selectors for this scope. Inherits from top-level if omitted. */
@@ -119,6 +120,12 @@ export declare interface ScopeConfig {
     cursorPolicy?: CursorPolicyInput;
     /** Plugins installed when this scope activates. */
     plugins?: SupermousePlugin[];
+    /**
+     * Rules evaluated against hovered elements inside this scope. If omitted,
+     * the scope inherits the primary scope's rules. If provided, the scope
+     * uses only its own rules.
+     */
+    rules?: Record<string, RuleDefinition>;
     /**
      * Whether data attributes and rules on ancestors cascade to the hovered
      * element. Inherits from top-level if omitted.
@@ -131,9 +138,34 @@ export declare interface ScopeConfig {
 
 export declare interface ScopeHandle {
     readonly name: string | undefined;
-    readonly container: HTMLElement;
-    remove(): void;
+    /**
+     * The scope's container element, or `null` if the scope is
+     * selector-based and has not yet been resolved to a live element.
+     */
+    readonly container: HTMLElement | null;
+    readonly active: boolean;
+    /** True for eager scopes and for selector scopes that have resolved. */
+    readonly resolved: boolean;
+    destroy(): void;
     setCursor(mode: CursorMode): void;
+    /**
+     * Marks the scope as eligible for activation.
+     *
+     * Activation is lazy: the scope becomes active on the next `mouseover`
+     * inside its container, not immediately. If you need to force the scope
+     * active while the pointer is already inside it, this will not work
+     * until the pointer moves. Deactivation, by contrast, is eager.
+     */
+    activate(): void;
+    /**
+     * Marks the scope as ineligible. If it was the active scope, control
+     * yields immediately to the nearest active ancestor scope, or to
+     * nothing if none exists.
+     */
+    deactivate(): void;
+    use(plugin: SupermousePlugin): ScopeHandle;
+    removePlugin(name: string): void;
+    getPlugin(name: string): SupermousePlugin | undefined;
 }
 
 export declare interface ShapeState {
@@ -150,8 +182,10 @@ export declare class Supermouse {
     private _scopes;
     private _activeScope;
     private _installingScope;
-    private scopeByContainer;
+    private scopeByName;
+    private scopeHandles;
     private input;
+    private styleOwner;
     private rafId;
     private lastTime;
     private visibilityAbortController;
@@ -161,11 +195,42 @@ export declare class Supermouse {
     get stage(): HTMLDivElement;
     get isEnabled(): boolean;
     get isRunning(): boolean;
+    /**
+     * Installs a plugin into the primary scope.
+     *
+     * In multi-scope mode, prefer `handle.use(plugin)` to target a specific
+     * scope. This method always installs to the primary scope, regardless of
+     * which scope is currently active.
+     */
     use(plugin: SupermousePlugin): this;
+    /**
+     * Searches every scope and returns the first plugin matching `name`.
+     * Scopes are searched in registration order (primary first).
+     */
     getPlugin(name: string): SupermousePlugin | undefined;
+    getScope(name: string): ScopeHandle | undefined;
+    /**
+     * Enables a plugin by name, wherever it lives.
+     *
+     * If the plugin's scope is currently active, the activation lifecycle
+     * runs immediately. If the scope is inactive, `isEnabled` is set but
+     * hooks do not fire until the scope next activates.
+     */
     enablePlugin(name: string): void;
+    /**
+     * Disables a plugin by name, wherever it lives.
+     *
+     * If the plugin's scope is currently active, the deactivation lifecycle
+     * runs immediately. If the scope is inactive, `isEnabled` is set but
+     * hooks do not fire — they already ran when the scope went inactive.
+     */
     disablePlugin(name: string): void;
     togglePlugin(name: string): void;
+    /**
+     * Sets the cursor mode on the *active* scope.
+     *
+     * To set the mode on a specific scope, use `handle.setCursor(mode)`.
+     */
     setCursor(mode: CursorMode): void;
     addScope(config: ScopeConfig): ScopeHandle;
     enable(): void;
@@ -178,13 +243,55 @@ export declare class Supermouse {
     destroy(): void;
     private _running;
     private createScope;
-    private removeScope;
+    private buildScopeHandle;
+    private destroyScope;
     private setScopeCursor;
+    /**
+     * Marks the scope ineligible for activation and, if it was active, yields
+     * immediately to the nearest active ancestor scope (or nothing).
+     */
+    private deactivateScope;
+    /**
+     * Marks the scope eligible for activation.
+     *
+     * If the pointer is already inside the scope's container, the scope
+     * becomes active immediately. Otherwise it activates on the next
+     * `mouseover` inside the container. Deactivation is always eager.
+     */
+    private activateScope;
+    /**
+     * Called by `Input` on every `mouseover`, and internally when the active
+     * scope is removed or deactivated. Walks from `node` up the ancestor
+     * chain, returning the innermost active scope whose `match` succeeds
+     * for an ancestor. The matched scope is bound to that ancestor before
+     * return.
+     *
+     * The walk order is what enforces "innermost wins": the first ancestor
+     * matching any active scope is, by construction, the closest one to the
+     * event target. Detached containers can never be ancestors of a live
+     * event target, so no cleanup of stale bindings is required here.
+     */
+    private resolveScopeForNode;
+    /**
+     * Synchronously writes the current cursor and stage visibility for the
+     * active scope. Called after hover state settles, on cursor mode changes,
+     * and on programmatic scope transitions. The `update()` rAF path calls
+     * the same writers as a backstop.
+     */
+    private applyCursorNow;
+    private findScopeForPlugin;
     private installPlugins;
     private installPlugin;
+    private removePluginFromScope;
     private handleActiveScopeChange;
-    private activatePlugin;
     private deactivatePlugin;
+    /**
+     * Runs the deactivation lifecycle for a plugin whose owning scope just
+     * became inactive. Does NOT flip `plugin.isEnabled`, so user intent
+     * (e.g. States disabling a plugin) survives the scope round-trip.
+     */
+    private scopeDeactivatePlugin;
+    private scopeActivatePlugin;
     private rebuildStylesheet;
     private runPluginSafe;
     private cleanupCrashedPlugins;
@@ -196,21 +303,12 @@ export declare class Supermouse {
     private bindVisibilityHandling;
     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.
+     * Adds one or more hover selectors to the current scope. Intended for
+     * raw-object plugins during `install`. Plugins written with `definePlugin`
+     * should use the `selector` option instead, and consumers setting up a
+     * scope should prefer the `hoverSelectors` option at construction.
      */
     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;