@supermousejs/utils 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @supermousejs/utils
+
+## 2.0.0
+
+### Major Changes
+
+- Initial v2.0.0 release
+
+### Patch Changes
+
+- Updated dependencies
+  - @supermousejs/core@2.0.0

package/LICENSE.md

@@ -0,0 +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.

package/dist/index.d.ts

@@ -0,0 +1,227 @@
+import { MouseState } from '../../core/src/index.ts';
+import { Supermouse } from '../../core/src/index.ts';
+import { SupermousePlugin } from '../../core/src/index.ts';
+import { ValueOrGetter } from '../../core/src/index.ts';
+
+/**
+ * Calculates the angle in degrees between two points (or vector direction).
+ */
+declare function angle(x: number, y: number): number;
+
+/**
+ * Applies a dictionary of styles to an HTMLElement.
+ */
+declare function applyStyles(el: HTMLElement, styles: Partial<CSSStyleDeclaration>): void;
+
+export declare interface BasePluginOptions {
+    name?: string;
+    isEnabled?: boolean;
+}
+
+/**
+ * Constrains a value between a minimum and maximum.
+ */
+declare function clamp(value: number, min: number, max: number): number;
+
+/**
+ * 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')
+ */
+declare function createActor(tagName?: string): HTMLElement;
+
+/**
+ * Creates a circular HTML div using the standard actor base.
+ */
+declare function createCircle(size: number, color: string): HTMLDivElement;
+
+/**
+ * Legacy alias for createActor.
+ * @deprecated Use createActor() instead.
+ */
+declare function createDiv(): HTMLDivElement;
+
+/**
+ * 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)
+ */
+declare function damp(a: number, b: number, lambda: number, dt: number): number;
+
+export declare function definePlugin<E extends HTMLElement, O extends BasePluginOptions>(config: VisualConfig<E, O>, userOptions?: O): SupermousePlugin;
+
+export declare function definePlugin(config: LogicConfig, userOptions?: BasePluginOptions): SupermousePlugin;
+
+/**
+ * Calculates the distance (hypotenuse) between two points (or magnitude of a vector).
+ * If x2/y2 are omitted, calculates magnitude of vector x1/y1.
+ */
+declare function dist(x1: number, y1: number, x2?: number, y2?: number): number;
+
+/**
+ * Supermouse Doctor
+ * A diagnostic utility to find common CSS conflicts that cause "Double Cursor" glitches.
+ */
+export declare function doctor(): void;
+
+declare namespace dom {
+    export {
+        applyStyles,
+        setStyle,
+        setTransform,
+        projectRect,
+        createActor,
+        createCircle,
+        createDiv
+    }
+}
+export { dom }
+
+/**
+ * Common cubic-bezier easing strings for CSS transitions.
+ */
+export declare const Easings: {
+    /** Good for entrance animations (starts fast, slows down) */
+    readonly EASE_OUT_EXPO: "cubic-bezier(0.16, 1, 0.3, 1)";
+    /** Good for elastic/bouncy UI elements */
+    readonly ELASTIC_OUT: "cubic-bezier(0.34, 1.56, 0.64, 1)";
+    /** Standard smooth movement */
+    readonly SMOOTH: "ease-out";
+};
+
+declare namespace effects {
+    export {
+        getVelocityDistortion
+    }
+}
+export { effects }
+
+/**
+ * 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)
+ */
+declare function getVelocityDistortion(vx: number, vy: number, intensity?: number, maxStretch?: number): {
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+};
+
+/**
+ * Standard Z-Index layers for the Supermouse ecosystem.
+ * Relative to the Supermouse Container.
+ */
+export declare const Layers: {
+    /** The top-most layer. For text, tooltips, and crucial UI. */
+    readonly OVERLAY: "400";
+    /** The main cursor layer. For the primary Dot/Pointer. */
+    readonly CURSOR: "300";
+    /** The secondary layer. For Rings, brackets, or followers. */
+    readonly FOLLOWER: "200";
+    /** The background layer. For trails, sparkles, and particles. */
+    readonly TRACE: "100";
+};
+
+/**
+ * Linear Interpolation between two values.
+ */
+declare function lerp(start: number, end: number, factor: number): number;
+
+/**
+ * Linear Interpolation between two angles in degrees, taking the shortest path.
+ * Handles wrap-around at 360 degrees.
+ */
+declare function lerpAngle(start: number, end: number, factor: number): number;
+
+declare 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;
+    create?: never;
+}
+
+declare namespace math {
+    export {
+        lerp,
+        damp,
+        lerpAngle,
+        random,
+        clamp,
+        dist,
+        angle
+    }
+}
+export { math }
+
+/**
+ * Returns a function that always resolves the option value.
+ * Eliminates 'typeof' checks inside the render loop by normalizing
+ * static values into getter functions during initialization.
+ *
+ * @param option The option passed by the user
+ * @param defaultValue Fallback value
+ */
+export declare function normalize<T>(option: ValueOrGetter<T> | undefined, defaultValue: T): (state: MouseState) => T;
+
+/**
+ * Calculates the bounding rectangle of an element relative to a container.
+ * Useful for logic plugins when the cursor is confined to a specific div.
+ */
+declare function projectRect(element: HTMLElement, container?: HTMLElement): DOMRect;
+
+/**
+ * Returns a random number between min and max.
+ * Usage: math.random(10, 20) -> 14.5
+ */
+declare function random(min: number, max: number): number;
+
+/**
+ * Smart Style Setter.
+ * Only writes to the DOM if the value has actually changed.
+ */
+declare function setStyle(el: HTMLElement, property: keyof CSSStyleDeclaration, value: string | number): void;
+
+/**
+ * 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
+ */
+declare function setTransform(el: HTMLElement, x: number, y: number, rotation?: number, scaleX?: number, scaleY?: number, skewX?: number, skewY?: number): void;
+
+declare 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;
+}
+
+export { }

package/dist/index.mjs

@@ -0,0 +1,205 @@
+function y(e, t, n) {
+  return e + (t - e) * n;
+}
+function O(e, t, n, o) {
+  return y(e, t, 1 - Math.exp(-n * o));
+}
+function _(e, t, n) {
+  const o = ((t - e) % 360 + 540) % 360 - 180;
+  return e + o * n;
+}
+function C(e, t) {
+  return Math.random() * (t - e) + e;
+}
+function h(e, t, n) {
+  return Math.min(Math.max(e, t), n);
+}
+function b(e, t, n = 0, o = 0) {
+  const r = e - n, i = t - o;
+  return Math.sqrt(r * r + i * i);
+}
+function m(e, t) {
+  return Math.atan2(t, e) * (180 / Math.PI);
+}
+const x = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  angle: m,
+  clamp: h,
+  damp: O,
+  dist: b,
+  lerp: y,
+  lerpAngle: _,
+  random: C
+}, Symbol.toStringTag, { value: "Module" }));
+function a(e, t) {
+  Object.assign(e.style, t);
+}
+const p = /* @__PURE__ */ new WeakMap();
+function u(e, t, n) {
+  let o = p.get(e);
+  o || (o = {}, p.set(e, o)), o[t] !== n && (e.style[t] = n, o[t] = n);
+}
+function v(e, t, n, o = 0, r = 1, i = 1, s = 0, l = 0) {
+  e.style.transform = `
+    translate3d(${t}px, ${n}px, 0) 
+    translate(-50%, -50%) 
+    rotate(${o}deg) 
+    skew(${s}deg, ${l}deg)
+    scale(${r}, ${i})
+  `;
+}
+function w(e, t = document.body) {
+  const n = e.getBoundingClientRect();
+  if (t !== document.body) {
+    const o = t.getBoundingClientRect(), r = n.left - o.left, i = n.top - o.top;
+    return {
+      x: r,
+      y: i,
+      width: n.width,
+      height: n.height,
+      top: i,
+      left: r,
+      right: r + n.width,
+      bottom: i + n.height,
+      toJSON: () => ({})
+    };
+  }
+  return n;
+}
+function d(e = "div") {
+  const t = document.createElement(e);
+  return a(t, {
+    position: "absolute",
+    top: "0",
+    left: "0",
+    pointerEvents: "none",
+    boxSizing: "border-box",
+    display: "block",
+    willChange: "transform"
+  }), t;
+}
+function A(e, t) {
+  const n = d("div");
+  return a(n, {
+    width: `${e}px`,
+    height: `${e}px`,
+    borderRadius: "50%",
+    backgroundColor: t
+  }), n;
+}
+function M() {
+  return d("div");
+}
+const j = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  applyStyles: a,
+  createActor: d,
+  createCircle: A,
+  createDiv: M,
+  projectRect: w,
+  setStyle: u,
+  setTransform: v
+}, Symbol.toStringTag, { value: "Module" }));
+function R(e, t, n = 4e-3, o = 0.5) {
+  const r = b(e, t);
+  if (r < 0.1)
+    return { rotation: 0, scaleX: 1, scaleY: 1 };
+  const i = m(e, t), s = h(r * n, 0, o), l = 1 + s, c = 1 - s * 0.5;
+  return {
+    rotation: i,
+    scaleX: l,
+    scaleY: c
+  };
+}
+const z = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  getVelocityDistortion: R
+}, Symbol.toStringTag, { value: "Module" })), P = {
+  /** The top-most layer. For text, tooltips, and crucial UI. */
+  OVERLAY: "400",
+  /** The main cursor layer. For the primary Dot/Pointer. */
+  CURSOR: "300",
+  /** The secondary layer. For Rings, brackets, or followers. */
+  FOLLOWER: "200",
+  /** The background layer. For trails, sparkles, and particles. */
+  TRACE: "100"
+}, D = {
+  /** Good for entrance animations (starts fast, slows down) */
+  EASE_OUT_EXPO: "cubic-bezier(0.16, 1, 0.3, 1)",
+  /** Good for elastic/bouncy UI elements */
+  ELASTIC_OUT: "cubic-bezier(0.34, 1.56, 0.64, 1)",
+  /** Standard smooth movement */
+  SMOOTH: "ease-out"
+};
+function T(e, t) {
+  return e === void 0 ? () => t : typeof e == "function" ? e : () => e;
+}
+function $(e) {
+  return "create" in e && typeof e.create == "function";
+}
+function L(e, t = {}) {
+  const n = t.name || e.name, o = t.isEnabled ?? !0;
+  if ($(e)) {
+    let r;
+    const i = [];
+    if (e.styles)
+      for (const [s, l] of Object.entries(e.styles)) {
+        const c = T(t[s], void 0), g = l;
+        i.push((E, S) => {
+          const f = c(E.state);
+          f !== void 0 && u(S, g, f);
+        });
+      }
+    return {
+      name: n,
+      isEnabled: o,
+      install(s) {
+        r = e.create(s), e.selector && s.registerHoverTarget(e.selector), this.isEnabled === !1 && (r.style.opacity = "0"), s.container.appendChild(r);
+      },
+      update(s, l) {
+        if (r) {
+          for (let c = 0; c < i.length; c++)
+            i[c](s, r);
+          e.update?.(s, r, l);
+        }
+      },
+      onDisable(s) {
+        r && (u(r, "opacity", 0), e.onDisable?.(s, r));
+      },
+      onEnable(s) {
+        r && (u(r, "opacity", 1), e.onEnable?.(s, r));
+      },
+      destroy() {
+        r && (e.cleanup?.(r), r.remove());
+      }
+    };
+  } else
+    return {
+      ...e,
+      name: n,
+      isEnabled: o
+    };
+}
+function k() {
+  if (console.group("🐭 Supermouse Doctor"), !Array.from(document.querySelectorAll("style")).some((o) => o.id.startsWith("supermouse-style-"))) {
+    console.warn("❌ Supermouse has not been initialized yet."), console.warn('   Please call doctor() AFTER "new Supermouse()" has run.'), console.groupEnd();
+    return;
+  }
+  const t = [];
+  document.querySelectorAll('[style*="cursor"]').forEach((o) => {
+    o.getAttribute("style")?.includes("cursor: none") || t.push({
+      el: o,
+      reason: 'Element has inline "cursor" style. Remove it and let Supermouse handle state.'
+    });
+  }), document.body.style.cursor !== "none" && console.warn('[Global] document.body.style.cursor is not "none". Ensure { hideCursor: true } is passed to Supermouse.'), t.length > 0 ? (console.warn(`Found ${t.length} potential conflicts:`), t.forEach((o) => console.warn(`[${o.reason}]`, o.el)), console.info('Tip: Avoid setting "cursor: pointer" manually. Use plugins or "rules" config instead.')) : console.log("✅ No obvious inline-style conflicts found."), console.groupEnd();
+}
+export {
+  D as Easings,
+  P as Layers,
+  L as definePlugin,
+  k as doctor,
+  j as dom,
+  z as effects,
+  x as math,
+  T as normalize
+};

package/dist/index.umd.js

@@ -0,0 +1,7 @@
+(function(l,a){typeof exports=="object"&&typeof module<"u"?a(exports):typeof define=="function"&&define.amd?define(["exports"],a):(l=typeof globalThis<"u"?globalThis:l||self,a(l.SupermouseUtils={}))})(this,(function(l){"use strict";function a(e,t,n){return e+(t-e)*n}function S(e,t,n,o){return a(e,t,1-Math.exp(-n*o))}function O(e,t,n){const o=((t-e)%360+540)%360-180;return e+o*n}function T(e,t){return Math.random()*(t-e)+e}function h(e,t,n){return Math.min(Math.max(e,t),n)}function m(e,t,n=0,o=0){const r=e-n,i=t-o;return Math.sqrt(r*r+i*i)}function b(e,t){return Math.atan2(t,e)*(180/Math.PI)}const _=Object.freeze(Object.defineProperty({__proto__:null,angle:b,clamp:h,damp:S,dist:m,lerp:a,lerpAngle:O,random:T},Symbol.toStringTag,{value:"Module"}));function f(e,t){Object.assign(e.style,t)}const p=new WeakMap;function d(e,t,n){let o=p.get(e);o||(o={},p.set(e,o)),o[t]!==n&&(e.style[t]=n,o[t]=n)}function v(e,t,n,o=0,r=1,i=1,s=0,c=0){e.style.transform=`
+    translate3d(${t}px, ${n}px, 0) 
+    translate(-50%, -50%) 
+    rotate(${o}deg) 
+    skew(${s}deg, ${c}deg)
+    scale(${r}, ${i})
+  `}function C(e,t=document.body){const n=e.getBoundingClientRect();if(t!==document.body){const o=t.getBoundingClientRect(),r=n.left-o.left,i=n.top-o.top;return{x:r,y:i,width:n.width,height:n.height,top:i,left:r,right:r+n.width,bottom:i+n.height,toJSON:()=>({})}}return n}function y(e="div"){const t=document.createElement(e);return f(t,{position:"absolute",top:"0",left:"0",pointerEvents:"none",boxSizing:"border-box",display:"block",willChange:"transform"}),t}function w(e,t){const n=y("div");return f(n,{width:`${e}px`,height:`${e}px`,borderRadius:"50%",backgroundColor:t}),n}function M(){return y("div")}const A=Object.freeze(Object.defineProperty({__proto__:null,applyStyles:f,createActor:y,createCircle:w,createDiv:M,projectRect:C,setStyle:d,setTransform:v},Symbol.toStringTag,{value:"Module"}));function R(e,t,n=.004,o=.5){const r=m(e,t);if(r<.1)return{rotation:0,scaleX:1,scaleY:1};const i=b(e,t),s=h(r*n,0,o),c=1+s,u=1-s*.5;return{rotation:i,scaleX:c,scaleY:u}}const j=Object.freeze(Object.defineProperty({__proto__:null,getVelocityDistortion:R},Symbol.toStringTag,{value:"Module"})),$={OVERLAY:"400",CURSOR:"300",FOLLOWER:"200",TRACE:"100"},z={EASE_OUT_EXPO:"cubic-bezier(0.16, 1, 0.3, 1)",ELASTIC_OUT:"cubic-bezier(0.34, 1.56, 0.64, 1)",SMOOTH:"ease-out"};function g(e,t){return e===void 0?()=>t:typeof e=="function"?e:()=>e}function P(e){return"create"in e&&typeof e.create=="function"}function L(e,t={}){const n=t.name||e.name,o=t.isEnabled??!0;if(P(e)){let r;const i=[];if(e.styles)for(const[s,c]of Object.entries(e.styles)){const u=g(t[s],void 0),U=c;i.push((k,x)=>{const E=u(k.state);E!==void 0&&d(x,U,E)})}return{name:n,isEnabled:o,install(s){r=e.create(s),e.selector&&s.registerHoverTarget(e.selector),this.isEnabled===!1&&(r.style.opacity="0"),s.container.appendChild(r)},update(s,c){if(r){for(let u=0;u<i.length;u++)i[u](s,r);e.update?.(s,r,c)}},onDisable(s){r&&(d(r,"opacity",0),e.onDisable?.(s,r))},onEnable(s){r&&(d(r,"opacity",1),e.onEnable?.(s,r))},destroy(){r&&(e.cleanup?.(r),r.remove())}}}else return{...e,name:n,isEnabled:o}}function D(){if(console.group("🐭 Supermouse Doctor"),!Array.from(document.querySelectorAll("style")).some(o=>o.id.startsWith("supermouse-style-"))){console.warn("❌ Supermouse has not been initialized yet."),console.warn('   Please call doctor() AFTER "new Supermouse()" has run.'),console.groupEnd();return}const t=[];document.querySelectorAll('[style*="cursor"]').forEach(o=>{o.getAttribute("style")?.includes("cursor: none")||t.push({el:o,reason:'Element has inline "cursor" style. Remove it and let Supermouse handle state.'})}),document.body.style.cursor!=="none"&&console.warn('[Global] document.body.style.cursor is not "none". Ensure { hideCursor: true } is passed to Supermouse.'),t.length>0?(console.warn(`Found ${t.length} potential conflicts:`),t.forEach(o=>console.warn(`[${o.reason}]`,o.el)),console.info('Tip: Avoid setting "cursor: pointer" manually. Use plugins or "rules" config instead.')):console.log("✅ No obvious inline-style conflicts found."),console.groupEnd()}l.Easings=z,l.Layers=$,l.definePlugin=L,l.doctor=D,l.dom=A,l.effects=j,l.math=_,l.normalize=g,Object.defineProperty(l,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@supermousejs/utils",
+  "version": "2.0.0",
+  "main": "dist/index.umd.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@supermousejs/core": "2.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.umd.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build"
+  }
+}

package/src/css.ts

@@ -0,0 +1,11 @@
+/**
+ * Common cubic-bezier easing strings for CSS transitions.
+ */
+export const Easings = {
+  /** Good for entrance animations (starts fast, slows down) */
+  EASE_OUT_EXPO: 'cubic-bezier(0.16, 1, 0.3, 1)',
+  /** Good for elastic/bouncy UI elements */
+  ELASTIC_OUT: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+  /** Standard smooth movement */
+  SMOOTH: 'ease-out',
+} as const;

package/src/doctor.ts

@@ -0,0 +1,49 @@
+
+/**
+ * Supermouse Doctor
+ * A diagnostic utility to find common CSS conflicts that cause "Double Cursor" glitches.
+ */
+export function doctor() {
+  console.group('🐭 Supermouse Doctor');
+
+  // 0. Check Initialization
+  // Supermouse injects a style tag with an ID starting with 'supermouse-style-'
+  const hasInitialized = Array.from(document.querySelectorAll('style')).some(s => s.id.startsWith('supermouse-style-'));
+  
+  if (!hasInitialized) {
+    console.warn('❌ Supermouse has not been initialized yet.');
+    console.warn('   Please call doctor() AFTER "new Supermouse()" has run.');
+    console.groupEnd();
+    return;
+  }
+
+  const issues: { el: Element, reason: string }[] = [];
+
+  // 1. Check for Inline Styles (Hard Overrides)
+  const inlineCursor = document.querySelectorAll('[style*="cursor"]');
+  inlineCursor.forEach(el => {
+    // Ignore the supermouse container itself (usually has cursor: none)
+    if (el.getAttribute('style')?.includes('cursor: none')) return;
+    
+    issues.push({ 
+      el, 
+      reason: 'Element has inline "cursor" style. Remove it and let Supermouse handle state.' 
+    });
+  });
+
+  // 2. Check Global Body State
+  if (document.body.style.cursor !== 'none') {
+    console.warn('[Global] document.body.style.cursor is not "none". Ensure { hideCursor: true } is passed to Supermouse.');
+  }
+
+  // 3. Report
+  if (issues.length > 0) {
+    console.warn(`Found ${issues.length} potential conflicts:`);
+    issues.forEach(i => console.warn(`[${i.reason}]`, i.el));
+    console.info('Tip: Avoid setting "cursor: pointer" manually. Use plugins or "rules" config instead.');
+  } else {
+    console.log('✅ No obvious inline-style conflicts found.');
+  }
+
+  console.groupEnd();
+}

package/src/dom.ts

@@ -0,0 +1,131 @@
+
+/**
+ * Applies a dictionary of styles to an HTMLElement.
+ */
+export function applyStyles(el: HTMLElement, styles: Partial<CSSStyleDeclaration>) {
+  Object.assign(el.style, styles);
+}
+
+// WeakMap to store previous styles for elements to prevent DOM thrashing
+const styleCache = new WeakMap<HTMLElement, Record<string, string | number>>();
+
+/**
+ * Smart Style Setter.
+ * Only writes to the DOM if the value has actually changed.
+ */
+export function setStyle(el: HTMLElement, property: keyof CSSStyleDeclaration, value: string | number) {
+  let cache = styleCache.get(el);
+  if (!cache) {
+    cache = {};
+    styleCache.set(el, cache);
+  }
+
+  // Only write to DOM if value changed
+  if (cache[property as string] !== value) {
+    // @ts-ignore - Dynamic access
+    el.style[property] = value;
+    cache[property as string] = value;
+  }
+}
+
+/**
+ * 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
+) {
+  el.style.transform = `
+    translate3d(${x}px, ${y}px, 0) 
+    translate(-50%, -50%) 
+    rotate(${rotation}deg) 
+    skew(${skewX}deg, ${skewY}deg)
+    scale(${scaleX}, ${scaleY})
+  `;
+}
+
+/**
+ * Calculates the bounding rectangle of an element relative to a container.
+ * Useful for logic plugins when the cursor is confined to a specific div.
+ */
+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 {
+      x,
+      y,
+      width: rect.width,
+      height: rect.height,
+      top: y,
+      left: x,
+      right: x + rect.width,
+      bottom: y + rect.height,
+      toJSON: () => ({})
+    } as DOMRect;
+  }
+
+  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

@@ -0,0 +1,35 @@
+
+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/index.ts

@@ -0,0 +1,10 @@
+import * as math from './math';
+import * as dom from './dom';
+import * as effects from './effects';
+
+export { math, dom, effects };
+export * from './layers';
+export * from './css';
+export * from './plugin';
+export * from './options';
+export * from './doctor';

package/src/layers.ts

@@ -0,0 +1,17 @@
+/**
+ * Standard Z-Index layers for the Supermouse ecosystem.
+ * Relative to the Supermouse Container.
+ */
+export const Layers = {
+  /** The top-most layer. For text, tooltips, and crucial UI. */
+  OVERLAY: '400', 
+  
+  /** The main cursor layer. For the primary Dot/Pointer. */
+  CURSOR: '300',
+  
+  /** The secondary layer. For Rings, brackets, or followers. */
+  FOLLOWER: '200',
+  
+  /** The background layer. For trails, sparkles, and particles. */
+  TRACE: '100',
+} as const;

package/src/math.ts

@@ -0,0 +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);
+}

package/src/options.ts

@@ -0,0 +1,22 @@
+import type { MouseState, ValueOrGetter } from '@supermousejs/core';
+
+/**
+ * Returns a function that always resolves the option value.
+ * Eliminates 'typeof' checks inside the render loop by normalizing
+ * static values into getter functions during initialization.
+ * 
+ * @param option The option passed by the user
+ * @param defaultValue Fallback value
+ */
+export function normalize<T>(
+  option: ValueOrGetter<T> | undefined, 
+  defaultValue: T
+): (state: MouseState) => T {
+  if (option === undefined) {
+    return () => defaultValue;
+  }
+  if (typeof option === 'function') {
+    return option as (state: MouseState) => T;
+  }
+  return () => option;
+}

package/src/plugin.ts

@@ -0,0 +1,149 @@
+import type { Supermouse, SupermousePlugin } from '@supermousejs/core';
+import { normalize } from './options';
+import { setStyle } from './dom';
+
+// --- SHARED OPTIONS ---
+export interface BasePluginOptions {
+  name?: string;
+  isEnabled?: boolean;
+}
+
+// --- MODE A: LOGIC PLUGIN CONFIG ---
+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

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": [
+    "src"
+  ],
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {
+      "@supermousejs/core": [
+        "../core/src/index.ts"
+      ]
+    }
+  }
+}

package/vite.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+import path from 'path';
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: path.resolve(__dirname, 'src/index.ts'),
+      name: 'SupermouseUtils',
+      fileName: (format) => format === 'es' ? 'index.mjs' : 'index.umd.js',
+    },
+    rollupOptions: {
+      external: ['@supermousejs/core'],
+      output: {
+        globals: {
+          '@supermousejs/core': 'SupermouseCore'
+        }
+      }
+    }
+  },
+  plugins: [dts({ rollupTypes: true })]
+});