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

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @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

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[];
@@ -114,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. */
@@ -142,12 +138,31 @@ export declare interface ScopeConfig {
 
 export declare interface ScopeHandle {
     readonly name: string | undefined;
-    readonly container: HTMLElement;
-    readonly disabled: boolean;
-    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;
-    disable(): void;
-    enable(): 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;
@@ -167,7 +182,6 @@ export declare class Supermouse {
     private _scopes;
     private _activeScope;
     private _installingScope;
-    private scopeByContainer;
     private scopeByName;
     private scopeHandles;
     private input;
@@ -181,12 +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;
@@ -200,11 +244,42 @@ export declare class Supermouse {
     private _running;
     private createScope;
     private buildScopeHandle;
-    private removeScope;
+    private destroyScope;
     private setScopeCursor;
-    private disableScope;
-    private enableScope;
-    private findScopeAbove;
+    /**
+     * 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;
@@ -227,16 +302,6 @@ export declare class Supermouse {
     private tick;
     private bindVisibilityHandling;
     private startLoop;
-    /**
-     * @deprecated Read from the active scope instead.
-     * Exposed for tests and debugging.
-     */
-    get hoverSelectors(): Set<string>;
-    /**
-     * @deprecated Read from the active scope instead.
-     * Exposed for tests and debugging.
-     */
-    get plugins(): SupermousePlugin[];
     /**
      * Adds one or more hover selectors to the current scope. Intended for
      * raw-object plugins during `install`. Plugins written with `definePlugin`