@supermousejs/utils 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -1,74 +1,81 @@
-# @supermousejs/utils
-
-## 2.2.0
-
-### Minor Changes
-
-- 9fe1a7b: - Implemented idiomatic approach to using supermouse/utils
-  - Rewrote `applyStyles`, `setTransform` and `setStyles` to share a global cache registry
-- 9fa6ece: Add `injectStyles` to safely handle injecting global CSS styles into the document head
-
-### 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
-- Updated dependencies [6d70c18]
-- Updated dependencies [2590af3]
-- Updated dependencies [14fb5b6]
-  - @supermousejs/core@2.1.0
-
-## 2.1.1
-
-### Patch Changes
-
-- 67f771b: Add relevant npm metadata to package.json file
-- Updated dependencies [67f771b]
-  - @supermousejs/core@2.0.5
-
-## 2.1.0
-
-### Minor Changes
-
-- 0a1652d: fixed build architecture and updated plugin metadata
-
-## 2.0.4
-
-### Patch Changes
-
-- 993dc67: Updated supemousejs packages with proper author, license and url descriptors to repo
-- Updated dependencies [993dc67]
-  - @supermousejs/core@2.0.4
-
-## 2.0.3
-
-### Patch Changes
-
-- Updated dependencies
-  - @supermousejs/core@2.0.3
-
-## 2.0.2
-
-### Patch Changes
-
-- ae219a0: Update READMEs with correct link to documentation
-- Updated dependencies [ae219a0]
-  - @supermousejs/core@2.0.2
-
-## 2.0.1
-
-### Patch Changes
-
-- Add minimal README.md files to packages
-- Updated dependencies
-  - @supermousejs/core@2.0.1
-
-## 2.0.0
-
-### Major Changes
-
-- Initial v2.0.0 release
-
-### Patch Changes
-
-- Updated dependencies
-  - @supermousejs/core@2.0.0
+# @supermousejs/utils
+
+## 2.3.0
+
+### Patch Changes
+
+- Updated dependencies [f6f44b2]
+  - @supermousejs/core@2.2.0
+
+## 2.2.0
+
+### Minor Changes
+
+- 9fe1a7b: - Implemented idiomatic approach to using supermouse/utils
+  - Rewrote `applyStyles`, `setTransform` and `setStyles` to share a global cache registry
+- 9fa6ece: Add `injectStyles` to safely handle injecting global CSS styles into the document head
+
+### 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
+- Updated dependencies [6d70c18]
+- Updated dependencies [2590af3]
+- Updated dependencies [14fb5b6]
+  - @supermousejs/core@2.1.0
+
+## 2.1.1
+
+### Patch Changes
+
+- 67f771b: Add relevant npm metadata to package.json file
+- Updated dependencies [67f771b]
+  - @supermousejs/core@2.0.5
+
+## 2.1.0
+
+### Minor Changes
+
+- 0a1652d: fixed build architecture and updated plugin metadata
+
+## 2.0.4
+
+### Patch Changes
+
+- 993dc67: Updated supemousejs packages with proper author, license and url descriptors to repo
+- Updated dependencies [993dc67]
+  - @supermousejs/core@2.0.4
+
+## 2.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @supermousejs/core@2.0.3
+
+## 2.0.2
+
+### Patch Changes
+
+- ae219a0: Update READMEs with correct link to documentation
+- Updated dependencies [ae219a0]
+  - @supermousejs/core@2.0.2
+
+## 2.0.1
+
+### Patch Changes
+
+- Add minimal README.md files to packages
+- Updated dependencies
+  - @supermousejs/core@2.0.1
+
+## 2.0.0
+
+### Major Changes
+
+- Initial v2.0.0 release
+
+### Patch Changes
+
+- Updated dependencies
+  - @supermousejs/core@2.0.0

package/dist/options.d.ts

@@ -1,4 +1,4 @@
-import { MouseState, ValueOrGetter } from '../../core/src';
+import { MouseState, ValueOrGetter } from '../packages/core/src';
 /**
  * Returns a function that always resolves the option value.
  * Eliminates 'typeof' checks inside the render loop by normalizing

package/dist/plugin.d.ts

@@ -1,4 +1,4 @@
-import { Supermouse, SupermousePlugin } from '../../core/src';
+import { Supermouse, SupermousePlugin } from '../packages/core/src';
 export interface BasePluginOptions {
     name?: string;
     isEnabled?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supermousejs/utils",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "main": "dist/index.umd.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -27,10 +27,10 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@supermousejs/core": "2.1.0"
+    "@supermousejs/core": "2.2.0"
   },
   "devDependencies": {
-    "@supermousejs/core": "2.1.0"
+    "@supermousejs/core": "2.2.0"
   },
   "scripts": {
     "build": "vite build"

package/src/dom.ts

@@ -1,145 +1,145 @@
-/**
- * Injects global CSS styles into the document head safely.
- * Checks for existing IDs to prevent duplication during SPA routing or HMR.
- *
- * @param id A unique identifier for this style block
- * @param css A string of CSS rules to inject.
- */
-export const injectStyles = (id: string, css: string) => {
-  if (typeof document === "undefined") return;
-  if (document.getElementById(id)) return;
-
-  const style = document.createElement("style");
-  style.id = id;
-  style.innerHTML = css;
-  document.head.appendChild(style);
-};
-
-// WeakMap to store previous styles for elements to prevent DOM thrashing
-const styleCache = new WeakMap<HTMLElement, Record<string, string | number>>();
-
-/**
- * Smart Style Setter (Batch).
- * Only writes to the DOM if the value has actually changed.
- * @param el The element to style
- * @param styles An object of CSS properties and values
- */
-export function applyStyles(el: HTMLElement, styles: Partial<CSSStyleDeclaration>) {
-  if (typeof document === "undefined" || !el) return;
-
-  let cache = styleCache.get(el);
-  if (!cache) {
-    cache = {};
-    styleCache.set(el, cache);
-  }
-
-  for (const prop in styles) {
-    const value = (styles as any)[prop];
-    if (cache[prop] !== value) {
-      (el.style as any)[prop] = value;
-      cache[prop] = value;
-    }
-  }
-}
-
-/**
- * Smart Style Setter (Single).
- * Proxies to applyStyles for consistency.
- * @param el The element to style
- * @param property The CSS property to set
- * @param value The value to set for the property
- */
-export function setStyle(
-  el: HTMLElement,
-  property: keyof CSSStyleDeclaration,
-  value: string | number
-) {
-  applyStyles(el, { [property]: value } as any);
-}
-
-/**
- * Universal Transform Setter.
- * Handles centering (-50%) automatically.
- *
- * @param el The element
- * @param x X Position (px)
- * @param y Y Position (px)
- * @param rotation Rotation (deg) - Default 0
- * @param scaleX Scale X - Default 1
- * @param scaleY Scale Y - Default 1
- * @param skewX Skew X (deg) - Default 0
- * @param skewY Skew Y (deg) - Default 0
- */
-export function setTransform(
-  el: HTMLElement,
-  x: number,
-  y: number,
-  rotation: number = 0,
-  scaleX: number = 1,
-  scaleY: number = 1,
-  skewX: number = 0,
-  skewY: number = 0
-) {
-  const transform = `translate3d(${x}px, ${y}px, 0) translate(-50%, -50%) rotate(${rotation}deg) skew(${skewX}deg, ${skewY}deg) scale(${scaleX}, ${scaleY})`;
-
-  setStyle(el, "transform", transform);
-}
-
-/**
- * Calculates the bounding rectangle of an element relative to a container.
- */
-export function projectRect(element: HTMLElement, container: HTMLElement = document.body): DOMRect {
-  const rect = element.getBoundingClientRect();
-
-  if (container !== document.body) {
-    const containerRect = container.getBoundingClientRect();
-    const x = rect.left - containerRect.left;
-    const y = rect.top - containerRect.top;
-
-    return new DOMRect(x, y, rect.width, rect.height);
-  }
-
-  return rect;
-}
-
-/**
- * Creates a standard Supermouse actor element with optimal performance settings.
- * Includes absolute positioning, pointer-events: none, and will-change: transform.
- *
- * @param tagName The HTML tag to create (default: 'div')
- */
-export function createActor(tagName: string = "div"): HTMLElement {
-  const el = document.createElement(tagName);
-  applyStyles(el, {
-    position: "absolute",
-    top: "0",
-    left: "0",
-    pointerEvents: "none",
-    boxSizing: "border-box",
-    display: "block",
-    willChange: "transform"
-  });
-  return el;
-}
-
-/**
- * Creates a circular HTML div using the standard actor base.
- */
-export function createCircle(size: number, color: string): HTMLDivElement {
-  const el = createActor("div") as HTMLDivElement;
-  applyStyles(el, {
-    width: `${size}px`,
-    height: `${size}px`,
-    borderRadius: "50%",
-    backgroundColor: color
-  });
-  return el;
-}
-
-/**
- * Legacy alias for createActor.
- * @deprecated Use createActor() instead.
- */
-export function createDiv(): HTMLDivElement {
-  return createActor("div") as HTMLDivElement;
-}
+/**
+ * Injects global CSS styles into the document head safely.
+ * Checks for existing IDs to prevent duplication during SPA routing or HMR.
+ *
+ * @param id A unique identifier for this style block
+ * @param css A string of CSS rules to inject.
+ */
+export const injectStyles = (id: string, css: string) => {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(id)) return;
+
+  const style = document.createElement("style");
+  style.id = id;
+  style.innerHTML = css;
+  document.head.appendChild(style);
+};
+
+// WeakMap to store previous styles for elements to prevent DOM thrashing
+const styleCache = new WeakMap<HTMLElement, Record<string, string | number>>();
+
+/**
+ * Smart Style Setter (Batch).
+ * Only writes to the DOM if the value has actually changed.
+ * @param el The element to style
+ * @param styles An object of CSS properties and values
+ */
+export function applyStyles(el: HTMLElement, styles: Partial<CSSStyleDeclaration>) {
+  if (typeof document === "undefined" || !el) return;
+
+  let cache = styleCache.get(el);
+  if (!cache) {
+    cache = {};
+    styleCache.set(el, cache);
+  }
+
+  for (const prop in styles) {
+    const value = (styles as any)[prop];
+    if (cache[prop] !== value) {
+      (el.style as any)[prop] = value;
+      cache[prop] = value;
+    }
+  }
+}
+
+/**
+ * Smart Style Setter (Single).
+ * Proxies to applyStyles for consistency.
+ * @param el The element to style
+ * @param property The CSS property to set
+ * @param value The value to set for the property
+ */
+export function setStyle(
+  el: HTMLElement,
+  property: keyof CSSStyleDeclaration,
+  value: string | number
+) {
+  applyStyles(el, { [property]: value } as any);
+}
+
+/**
+ * Universal Transform Setter.
+ * Handles centering (-50%) automatically.
+ *
+ * @param el The element
+ * @param x X Position (px)
+ * @param y Y Position (px)
+ * @param rotation Rotation (deg) - Default 0
+ * @param scaleX Scale X - Default 1
+ * @param scaleY Scale Y - Default 1
+ * @param skewX Skew X (deg) - Default 0
+ * @param skewY Skew Y (deg) - Default 0
+ */
+export function setTransform(
+  el: HTMLElement,
+  x: number,
+  y: number,
+  rotation: number = 0,
+  scaleX: number = 1,
+  scaleY: number = 1,
+  skewX: number = 0,
+  skewY: number = 0
+) {
+  const transform = `translate3d(${x}px, ${y}px, 0) translate(-50%, -50%) rotate(${rotation}deg) skew(${skewX}deg, ${skewY}deg) scale(${scaleX}, ${scaleY})`;
+
+  setStyle(el, "transform", transform);
+}
+
+/**
+ * Calculates the bounding rectangle of an element relative to a container.
+ */
+export function projectRect(element: HTMLElement, container: HTMLElement = document.body): DOMRect {
+  const rect = element.getBoundingClientRect();
+
+  if (container !== document.body) {
+    const containerRect = container.getBoundingClientRect();
+    const x = rect.left - containerRect.left;
+    const y = rect.top - containerRect.top;
+
+    return new DOMRect(x, y, rect.width, rect.height);
+  }
+
+  return rect;
+}
+
+/**
+ * Creates a standard Supermouse actor element with optimal performance settings.
+ * Includes absolute positioning, pointer-events: none, and will-change: transform.
+ *
+ * @param tagName The HTML tag to create (default: 'div')
+ */
+export function createActor(tagName: string = "div"): HTMLElement {
+  const el = document.createElement(tagName);
+  applyStyles(el, {
+    position: "absolute",
+    top: "0",
+    left: "0",
+    pointerEvents: "none",
+    boxSizing: "border-box",
+    display: "block",
+    willChange: "transform"
+  });
+  return el;
+}
+
+/**
+ * Creates a circular HTML div using the standard actor base.
+ */
+export function createCircle(size: number, color: string): HTMLDivElement {
+  const el = createActor("div") as HTMLDivElement;
+  applyStyles(el, {
+    width: `${size}px`,
+    height: `${size}px`,
+    borderRadius: "50%",
+    backgroundColor: color
+  });
+  return el;
+}
+
+/**
+ * Legacy alias for createActor.
+ * @deprecated Use createActor() instead.
+ */
+export function createDiv(): HTMLDivElement {
+  return createActor("div") as HTMLDivElement;
+}

package/src/effects.ts

@@ -1,34 +1,34 @@
-import { dist, angle, clamp } from "./math";
-
-/**
- * Calculates Rotation and Scale based on velocity to create a "Squash and Stretch" effect.
- *
- * @param vx Velocity X
- * @param vy Velocity Y
- * @param intensity Stretch factor (default: 0.004)
- * @param maxStretch Max stretch percentage (default: 0.5 = 150% length)
- */
-export function getVelocityDistortion(vx: number, vy: number, intensity = 0.004, maxStretch = 0.5) {
-  const speed = dist(vx, vy);
-
-  // Deadzone: If moving too slow, don't rotate (prevents jittering at rest)
-  if (speed < 0.1) {
-    return { rotation: 0, scaleX: 1, scaleY: 1 };
-  }
-
-  // 1. Point towards movement
-  const rotation = angle(vx, vy);
-
-  // 2. Stretch based on speed
-  const stretch = clamp(speed * intensity, 0, maxStretch);
-
-  // 3. Scale X grows, Scale Y shrinks (to preserve volume-ish)
-  const scaleX = 1 + stretch;
-  const scaleY = 1 - stretch * 0.5; // Squash factor
-
-  return {
-    rotation,
-    scaleX,
-    scaleY
-  };
-}
+import { dist, angle, clamp } from "./math";
+
+/**
+ * Calculates Rotation and Scale based on velocity to create a "Squash and Stretch" effect.
+ *
+ * @param vx Velocity X
+ * @param vy Velocity Y
+ * @param intensity Stretch factor (default: 0.004)
+ * @param maxStretch Max stretch percentage (default: 0.5 = 150% length)
+ */
+export function getVelocityDistortion(vx: number, vy: number, intensity = 0.004, maxStretch = 0.5) {
+  const speed = dist(vx, vy);
+
+  // Deadzone: If moving too slow, don't rotate (prevents jittering at rest)
+  if (speed < 0.1) {
+    return { rotation: 0, scaleX: 1, scaleY: 1 };
+  }
+
+  // 1. Point towards movement
+  const rotation = angle(vx, vy);
+
+  // 2. Stretch based on speed
+  const stretch = clamp(speed * intensity, 0, maxStretch);
+
+  // 3. Scale X grows, Scale Y shrinks (to preserve volume-ish)
+  const scaleX = 1 + stretch;
+  const scaleY = 1 - stretch * 0.5; // Squash factor
+
+  return {
+    rotation,
+    scaleX,
+    scaleY
+  };
+}

package/src/math.ts

@@ -1,60 +1,60 @@
-/**
- * Linear Interpolation between two values.
- */
-export function lerp(start: number, end: number, factor: number): number {
-  return start + (end - start) * factor;
-}
-
-/**
- * Frame-rate independent damping (Time-based Lerp).
- * Ensures smooth animation consistent across 60hz, 120hz, etc.
- *
- * @param a Current value
- * @param b Target value
- * @param lambda Smoothing factor (approx 1-20). Higher is faster.
- * @param dt Delta time in seconds (not milliseconds)
- */
-export function damp(a: number, b: number, lambda: number, dt: number): number {
-  return lerp(a, b, 1 - Math.exp(-lambda * dt));
-}
-
-/**
- * Linear Interpolation between two angles in degrees, taking the shortest path.
- * Handles wrap-around at 360 degrees.
- */
-export function lerpAngle(start: number, end: number, factor: number): number {
-  const diff = ((((end - start) % 360) + 540) % 360) - 180;
-  return start + diff * factor;
-}
-
-/**
- * Returns a random number between min and max.
- * Usage: math.random(10, 20) -> 14.5
- */
-export function random(min: number, max: number): number {
-  return Math.random() * (max - min) + min;
-}
-
-/**
- * Constrains a value between a minimum and maximum.
- */
-export function clamp(value: number, min: number, max: number): number {
-  return Math.min(Math.max(value, min), max);
-}
-
-/**
- * Calculates the distance (hypotenuse) between two points (or magnitude of a vector).
- * If x2/y2 are omitted, calculates magnitude of vector x1/y1.
- */
-export function dist(x1: number, y1: number, x2: number = 0, y2: number = 0): number {
-  const dx = x1 - x2;
-  const dy = y1 - y2;
-  return Math.sqrt(dx * dx + dy * dy);
-}
-
-/**
- * Calculates the angle in degrees between two points (or vector direction).
- */
-export function angle(x: number, y: number): number {
-  return Math.atan2(y, x) * (180 / Math.PI);
-}
+/**
+ * Linear Interpolation between two values.
+ */
+export function lerp(start: number, end: number, factor: number): number {
+  return start + (end - start) * factor;
+}
+
+/**
+ * Frame-rate independent damping (Time-based Lerp).
+ * Ensures smooth animation consistent across 60hz, 120hz, etc.
+ *
+ * @param a Current value
+ * @param b Target value
+ * @param lambda Smoothing factor (approx 1-20). Higher is faster.
+ * @param dt Delta time in seconds (not milliseconds)
+ */
+export function damp(a: number, b: number, lambda: number, dt: number): number {
+  return lerp(a, b, 1 - Math.exp(-lambda * dt));
+}
+
+/**
+ * Linear Interpolation between two angles in degrees, taking the shortest path.
+ * Handles wrap-around at 360 degrees.
+ */
+export function lerpAngle(start: number, end: number, factor: number): number {
+  const diff = ((((end - start) % 360) + 540) % 360) - 180;
+  return start + diff * factor;
+}
+
+/**
+ * Returns a random number between min and max.
+ * Usage: math.random(10, 20) -> 14.5
+ */
+export function random(min: number, max: number): number {
+  return Math.random() * (max - min) + min;
+}
+
+/**
+ * Constrains a value between a minimum and maximum.
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Calculates the distance (hypotenuse) between two points (or magnitude of a vector).
+ * If x2/y2 are omitted, calculates magnitude of vector x1/y1.
+ */
+export function dist(x1: number, y1: number, x2: number = 0, y2: number = 0): number {
+  const dx = x1 - x2;
+  const dy = y1 - y2;
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+/**
+ * Calculates the angle in degrees between two points (or vector direction).
+ */
+export function angle(x: number, y: number): number {
+  return Math.atan2(y, x) * (180 / Math.PI);
+}

package/src/plugin.ts

@@ -1,147 +1,147 @@
-import type { Supermouse, SupermousePlugin } from "@supermousejs/core";
-import { normalize } from "./options";
-import { setStyle } from "./dom";
-
-export interface BasePluginOptions {
-  name?: string;
-  isEnabled?: boolean;
-}
-
-interface LogicConfig {
-  name: string;
-  priority?: number;
-  install?: (app: Supermouse) => void;
-  update?: (app: Supermouse, deltaTime: number) => void;
-  destroy?: (app: Supermouse) => void;
-  onEnable?: (app: Supermouse) => void;
-  onDisable?: (app: Supermouse) => void;
-  // Explicitly disallow 'create' here to ensure type separation
-  create?: never;
-}
-
-// --- MODE B: VISUAL PLUGIN CONFIG ---
-interface VisualConfig<E extends HTMLElement, O extends object> {
-  name: string;
-  /** Automatically register this attribute selector */
-  selector?: string;
-  /** Create and return the DOM Element */
-  create: (app: Supermouse) => E;
-  /** Map option keys to CSS properties */
-  styles?: Partial<Record<keyof O, keyof CSSStyleDeclaration>>;
-  /** Update loop with access to the element */
-  update?: (app: Supermouse, element: E, deltaTime: number) => void;
-  onEnable?: (app: Supermouse, element: E) => void;
-  onDisable?: (app: Supermouse, element: E) => void;
-  cleanup?: (element: E) => void;
-  destroy?: never; // Visual plugins use cleanup(), not destroy()
-}
-
-// Helper Type Guard to safely distinguish VisualConfig at runtime
-function isVisualConfig<E extends HTMLElement, O extends object>(
-  config: LogicConfig | VisualConfig<E, O>
-): config is VisualConfig<E, O> {
-  return "create" in config && typeof (config as any).create === "function";
-}
-
-// --- THE OVERLOADS ---
-
-// Overload 1: Visual Plugin (Infer Element E and Options O)
-export function definePlugin<E extends HTMLElement, O extends BasePluginOptions>(
-  config: VisualConfig<E, O>,
-  userOptions?: O
-): SupermousePlugin;
-
-// Overload 2: Logic Plugin
-export function definePlugin(
-  config: LogicConfig,
-  userOptions?: BasePluginOptions
-): SupermousePlugin;
-
-// --- THE IMPLEMENTATION ---
-
-export function definePlugin(
-  config: LogicConfig | VisualConfig<HTMLElement, any>,
-  userOptions: any = {}
-): SupermousePlugin {
-  const name = userOptions.name || config.name;
-  const initialEnabled = userOptions.isEnabled ?? true;
-
-  // MODE A: VISUAL
-  if (isVisualConfig(config)) {
-    let element: HTMLElement;
-
-    // PRE-COMPILE STYLE SETTERS
-    const styleSetters: ((app: Supermouse, el: HTMLElement) => void)[] = [];
-
-    if (config.styles) {
-      for (const [optKey, cssProp] of Object.entries(config.styles)) {
-        const getter = normalize(userOptions[optKey], undefined);
-        const prop = cssProp as any;
-
-        styleSetters.push((app, el) => {
-          const val = getter(app.state);
-          if (val !== undefined) {
-            setStyle(el, prop, val);
-          }
-        });
-      }
-    }
-
-    return {
-      name,
-      isEnabled: initialEnabled,
-
-      install(app) {
-        // 1. Create & Append
-        element = config.create(app);
-        if (config.selector) app.registerHoverTarget(config.selector);
-
-        // 2. Handle Initial State
-        if (this.isEnabled === false) {
-          element.style.opacity = "0";
-        }
-        app.container.appendChild(element);
-      },
-
-      update(app, dt) {
-        if (!element) return;
-
-        // 3. Run Pre-compiled Style Setters
-        for (let i = 0; i < styleSetters.length; i++) {
-          styleSetters[i](app, element);
-        }
-
-        // 4. Run Custom Update
-        config.update?.(app, element, dt);
-      },
-
-      onDisable(app) {
-        if (!element) return;
-        // Use setStyle to ensure cache remains in sync (0)
-        setStyle(element, "opacity", 0);
-        config.onDisable?.(app, element);
-      },
-
-      onEnable(app) {
-        if (!element) return;
-        setStyle(element, "opacity", 1);
-        config.onEnable?.(app, element);
-      },
-
-      destroy() {
-        if (!element) return;
-        config.cleanup?.(element);
-        element.remove();
-      }
-    };
-  }
-
-  // MODE B: LOGIC (Standard Pass-through)
-  else {
-    return {
-      ...config,
-      name,
-      isEnabled: initialEnabled
-    };
-  }
-}
+import type { Supermouse, SupermousePlugin } from "@supermousejs/core";
+import { normalize } from "./options";
+import { setStyle } from "./dom";
+
+export interface BasePluginOptions {
+  name?: string;
+  isEnabled?: boolean;
+}
+
+interface LogicConfig {
+  name: string;
+  priority?: number;
+  install?: (app: Supermouse) => void;
+  update?: (app: Supermouse, deltaTime: number) => void;
+  destroy?: (app: Supermouse) => void;
+  onEnable?: (app: Supermouse) => void;
+  onDisable?: (app: Supermouse) => void;
+  // Explicitly disallow 'create' here to ensure type separation
+  create?: never;
+}
+
+// --- MODE B: VISUAL PLUGIN CONFIG ---
+interface VisualConfig<E extends HTMLElement, O extends object> {
+  name: string;
+  /** Automatically register this attribute selector */
+  selector?: string;
+  /** Create and return the DOM Element */
+  create: (app: Supermouse) => E;
+  /** Map option keys to CSS properties */
+  styles?: Partial<Record<keyof O, keyof CSSStyleDeclaration>>;
+  /** Update loop with access to the element */
+  update?: (app: Supermouse, element: E, deltaTime: number) => void;
+  onEnable?: (app: Supermouse, element: E) => void;
+  onDisable?: (app: Supermouse, element: E) => void;
+  cleanup?: (element: E) => void;
+  destroy?: never; // Visual plugins use cleanup(), not destroy()
+}
+
+// Helper Type Guard to safely distinguish VisualConfig at runtime
+function isVisualConfig<E extends HTMLElement, O extends object>(
+  config: LogicConfig | VisualConfig<E, O>
+): config is VisualConfig<E, O> {
+  return "create" in config && typeof (config as any).create === "function";
+}
+
+// --- THE OVERLOADS ---
+
+// Overload 1: Visual Plugin (Infer Element E and Options O)
+export function definePlugin<E extends HTMLElement, O extends BasePluginOptions>(
+  config: VisualConfig<E, O>,
+  userOptions?: O
+): SupermousePlugin;
+
+// Overload 2: Logic Plugin
+export function definePlugin(
+  config: LogicConfig,
+  userOptions?: BasePluginOptions
+): SupermousePlugin;
+
+// --- THE IMPLEMENTATION ---
+
+export function definePlugin(
+  config: LogicConfig | VisualConfig<HTMLElement, any>,
+  userOptions: any = {}
+): SupermousePlugin {
+  const name = userOptions.name || config.name;
+  const initialEnabled = userOptions.isEnabled ?? true;
+
+  // MODE A: VISUAL
+  if (isVisualConfig(config)) {
+    let element: HTMLElement;
+
+    // PRE-COMPILE STYLE SETTERS
+    const styleSetters: ((app: Supermouse, el: HTMLElement) => void)[] = [];
+
+    if (config.styles) {
+      for (const [optKey, cssProp] of Object.entries(config.styles)) {
+        const getter = normalize(userOptions[optKey], undefined);
+        const prop = cssProp as any;
+
+        styleSetters.push((app, el) => {
+          const val = getter(app.state);
+          if (val !== undefined) {
+            setStyle(el, prop, val);
+          }
+        });
+      }
+    }
+
+    return {
+      name,
+      isEnabled: initialEnabled,
+
+      install(app) {
+        // 1. Create & Append
+        element = config.create(app);
+        if (config.selector) app.registerHoverTarget(config.selector);
+
+        // 2. Handle Initial State
+        if (this.isEnabled === false) {
+          element.style.opacity = "0";
+        }
+        app.container.appendChild(element);
+      },
+
+      update(app, dt) {
+        if (!element) return;
+
+        // 3. Run Pre-compiled Style Setters
+        for (let i = 0; i < styleSetters.length; i++) {
+          styleSetters[i](app, element);
+        }
+
+        // 4. Run Custom Update
+        config.update?.(app, element, dt);
+      },
+
+      onDisable(app) {
+        if (!element) return;
+        // Use setStyle to ensure cache remains in sync (0)
+        setStyle(element, "opacity", 0);
+        config.onDisable?.(app, element);
+      },
+
+      onEnable(app) {
+        if (!element) return;
+        setStyle(element, "opacity", 1);
+        config.onEnable?.(app, element);
+      },
+
+      destroy() {
+        if (!element) return;
+        config.cleanup?.(element);
+        element.remove();
+      }
+    };
+  }
+
+  // MODE B: LOGIC (Standard Pass-through)
+  else {
+    return {
+      ...config,
+      name,
+      isEnabled: initialEnabled
+    };
+  }
+}

package/tsconfig.json

@@ -1,11 +1,9 @@
-{
-  "extends": "../../tsconfig.composite-lib.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist"
-  },
-  "include": ["src"],
-  "references": [
-    { "path": "../core" }
-  ]
-}
+{
+  "extends": "../../tsconfig.composite-lib.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": [{ "path": "../core" }]
+}