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

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @supermousejs/core
 
+## 2.5.0-beta.4
+
+### Patch Changes
+
+- cb9bf9a: Beta.4
+
+  **Added**
+  - `state.authoredCursor` — the cursor value the page intends at the element under the pointer, resolved as if Supermouse's suppression were not active. Populated on every pointerTarget change, in all cursor modes. Read this to know what the page wants (`canvas { cursor: crosshair }`, `.drag-handle { cursor: grab }`, `[disabled] { cursor: not-allowed }`) rather than just whether the OS cursor should be shown (`state.isNative`).
+  - `state.pointerTarget` — the raw element under the pointer, regardless of hover selectors. Distinct from `state.hoverTarget`, which reports the nearest ancestor matching a hover selector.
+
+  **Fixed**
+  - Cursor detection in `auto` mode no longer reads its own suppression output. The previous implementation called `getComputedStyle(target).cursor` while the scope's hide class was active, so it always saw `"none"` and never triggered native fallback for authored exotic cursors. A probe attribute (`data-sm-probe`) is now excluded from every generated suppression rule, so the read sees the page's intended value.
+
+  **Changed**
+  - `@supermousejs/labs`: `SmartIcon` now reads `state.pointerTarget` and `state.authoredCursor` instead of relying on a broad hover-selector sweep. Hovering a `<p>` no longer sets `state.isHover` on the primary scope.
+  - `@supermousejs/labs`: `SmartIconOptions.useSemanticTags` renamed to `useSemanticDetection`. The old name referred to a `registerHoverTarget` sweep that no longer runs.
+
+  **Internal**
+  - Size budget raised to 6.5 kB gzip / 5.75 kB brotli to accommodate the beta.4 surface. Will be re-tightened once the shape settles.
+
+## 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[];
@@ -81,6 +74,16 @@ export declare interface MouseState {
     isNative: boolean;
     /** Current cursor mode: auto, custom, native, or both. */
     cursorMode: CursorMode;
+    /**
+     * The raw element currently under the pointer, regardless of whether it
+     * matches any hover selector.
+     */
+    pointerTarget: HTMLElement | null;
+    /**
+     * The authored cursor value at `pointerTarget`, resolved as if
+     * Supermouse's suppression were not active.
+     */
+    authoredCursor: string | null;
     /** Currently hovered DOM element, if any. */
     hoverTarget: HTMLElement | null;
     /** User has `prefers-reduced-motion` enabled. */
@@ -114,8 +117,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 +148,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 +192,6 @@ export declare class Supermouse {
     private _scopes;
     private _activeScope;
     private _installingScope;
-    private scopeByContainer;
     private scopeByName;
     private scopeHandles;
     private input;
@@ -181,12 +205,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 +254,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 +312,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`