@supermousejs/utils 2.3.1 → 2.4.0

package/dist/index.umd.js

@@ -1 +1,5 @@
-(function(i,a){typeof exports=="object"&&typeof module<"u"?a(exports):typeof define=="function"&&define.amd?define(["exports"],a):(i=typeof globalThis<"u"?globalThis:i||self,a(i.SupermouseUtils={}))})(this,(function(i){"use strict";function a(e,t,n){return e+(t-e)*n}function S(e,t,n,r){return a(e,t,1-Math.exp(-n*r))}function v(e,t,n){const r=((t-e)%360+540)%360-180;return e+r*n}function O(e,t){return Math.random()*(t-e)+e}function y(e,t,n){return Math.min(Math.max(e,t),n)}function p(e,t,n=0,r=0){const o=e-n,c=t-r;return Math.sqrt(o*o+c*c)}function b(e,t){return Math.atan2(t,e)*(180/Math.PI)}const C=Object.freeze(Object.defineProperty({__proto__:null,angle:b,clamp:y,damp:S,dist:p,lerp:a,lerpAngle:v,random:O},Symbol.toStringTag,{value:"Module"})),M=(e,t)=>{if(typeof document>"u"||document.getElementById(e))return;const n=document.createElement("style");n.id=e,n.innerHTML=t,document.head.appendChild(n)},h=new WeakMap;function f(e,t){if(typeof document>"u"||!e)return;let n=h.get(e);n||(n={},h.set(e,n));for(const r in t){const o=t[r];n[r]!==o&&(e.style[r]=o,n[r]=o)}}function d(e,t,n){f(e,{[t]:n})}function T(e,t,n,r=0,o=1,c=1,s=0,u=0){const l=`translate3d(${t}px, ${n}px, 0) translate(-50%, -50%) rotate(${r}deg) skew(${s}deg, ${u}deg) scale(${o}, ${c})`;d(e,"transform",l)}function _(e,t=document.body){const n=e.getBoundingClientRect();if(t!==document.body){const r=t.getBoundingClientRect(),o=n.left-r.left,c=n.top-r.top;return new DOMRect(o,c,n.width,n.height)}return n}function m(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=m("div");return f(n,{width:`${e}px`,height:`${e}px`,borderRadius:"50%",backgroundColor:t}),n}function R(){return m("div")}const j=Object.freeze(Object.defineProperty({__proto__:null,applyStyles:f,createActor:m,createCircle:w,createDiv:R,injectStyles:M,projectRect:_,setStyle:d,setTransform:T},Symbol.toStringTag,{value:"Module"}));function A(e,t,n=.004,r=.5){const o=p(e,t);if(o<.1)return{rotation:0,scaleX:1,scaleY:1};const c=b(e,t),s=y(o*n,0,r),u=1+s,l=1-s*.5;return{rotation:c,scaleX:u,scaleY:l}}const $=Object.freeze(Object.defineProperty({__proto__:null,getVelocityDistortion:A},Symbol.toStringTag,{value:"Module"})),z={OVERLAY:"400",CURSOR:"300",FOLLOWER:"200",TRACE:"100"},P={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 L(e){return"create"in e&&typeof e.create=="function"}function D(e,t={}){const n=t.name||e.name,r=t.isEnabled??!0;if(L(e)){let o;const c=[];if(e.styles)for(const[s,u]of Object.entries(e.styles)){const l=g(t[s],void 0),x=u;c.push((I,U)=>{const E=l(I.state);E!==void 0&&d(U,x,E)})}return{name:n,isEnabled:r,install(s){o=e.create(s),e.selector&&s.registerHoverTarget(e.selector),this.isEnabled===!1&&(o.style.opacity="0"),s.container.appendChild(o)},update(s,u){if(o){for(let l=0;l<c.length;l++)c[l](s,o);e.update?.(s,o,u)}},onDisable(s){o&&(d(o,"opacity",0),e.onDisable?.(s,o))},onEnable(s){o&&(d(o,"opacity",1),e.onEnable?.(s,o))},destroy(){o&&(e.cleanup?.(o),o.remove())}}}else return{...e,name:n,isEnabled:r}}function k(){if(console.group("🐭 Supermouse Doctor"),!Array.from(document.querySelectorAll("style")).some(r=>r.id.startsWith("supermouse-style-"))){console.warn("[x] 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(r=>{r.getAttribute("style")?.includes("cursor: none")||t.push({el:r,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(r=>console.warn(`[${r.reason}]`,r.el)),console.info('Tip: Avoid setting "cursor: pointer" manually. Use plugins or `rules` config instead.')):console.log("[ok] No obvious inline-style conflicts found."),console.groupEnd()}i.Easings=P,i.Layers=z,i.definePlugin=D,i.doctor=k,i.dom=j,i.effects=$,i.math=C,i.normalize=g,Object.defineProperty(i,Symbol.toStringTag,{value:"Module"})}));
+(function(r,f){typeof exports=="object"&&typeof module<"u"?f(exports):typeof define=="function"&&define.amd?define(["exports"],f):(r=typeof globalThis<"u"?globalThis:r||self,f(r.SupermouseUtils={}))})(this,(function(r){"use strict";function f(e,t,n){return e+(t-e)*n}function S(e,t,n,o){return f(e,t,1-Math.exp(-n*o))}function v(e,t,n){const o=((t-e)%360+540)%360-180;return e+o*n}function w(e,t){return Math.random()*(t-e)+e}function g(e,t,n){return Math.min(Math.max(e,t),n)}function p(e,t,n=0,o=0){const i=e-n,c=t-o;return Math.sqrt(i*i+c*c)}function y(e,t){return Math.atan2(t,e)*(180/Math.PI)}function E(e){return 2*Math.PI*e}const K=Object.freeze(Object.defineProperty({__proto__:null,angle:y,circumference:E,clamp:g,damp:S,dist:p,lerp:f,lerpAngle:v,random:w},Symbol.toStringTag,{value:"Module"})),$=(e,t)=>{if(typeof document>"u"||document.getElementById(e))return;const n=document.createElement("style");n.id=e,n.innerHTML=t,document.head.appendChild(n)},O=new WeakMap;function Z(e){return e.replace(/([a-z0-9])([A-Z])/g,"$1-$2").toLowerCase()}function d(e,t){if(typeof document>"u"||!e)return;let n=O.get(e);n||(n={},O.set(e,n));for(const[o,i]of Object.entries(t)){if(i===void 0)continue;const c=String(i),a=Z(o);n[a]!==c&&(e.style.setProperty(a,c),n[a]=c)}}function M(e,t,n){d(e,{[t]:n})}function I(e,t){d(e,t)}function P(e,t,n,o=0,i=1,c=1,a=0,s=0){const m=`translate3d(${t}px, ${n}px, 0) translate(-50%, -50%) rotate(${o}deg) skew(${a}deg, ${s}deg) scale(${i}, ${c})`;d(e,{transform:m})}function T(e,t=document.body){const n=e.getBoundingClientRect();if(t!==document.body){const o=t.getBoundingClientRect(),i=n.left-o.left,c=n.top-o.top;return new DOMRect(i,c,n.width,n.height)}return n}function h(e="div"){const t=document.createElement(e);return d(t,{position:"absolute",top:"0",left:"0",pointerEvents:"none",boxSizing:"border-box",display:"block",willChange:"transform"}),t}function C(e,t){const n=h("div");return d(n,{width:`${e}px`,height:`${e}px`,borderRadius:"50%",backgroundColor:t}),n}function _(){return h("div")}const J=Object.freeze(Object.defineProperty({__proto__:null,applyStyles:I,createActor:h,createCircle:C,createDiv:_,css:d,injectStyles:$,projectRect:T,setStyle:M,setTransform:P},Symbol.toStringTag,{value:"Module"}));function A(e,t,n=.004,o=.5){const i=p(e,t);if(i<.1)return{rotation:0,scaleX:1,scaleY:1};const c=y(e,t),a=g(i*n,0,o),s=1+a,m=1-a*.5;return{rotation:c,scaleX:s,scaleY:m}}const Q=Object.freeze(Object.defineProperty({__proto__:null,getVelocityDistortion:A},Symbol.toStringTag,{value:"Module"}));function R(e,t){return e===void 0?()=>t:typeof e=="function"?e:()=>e}function x(e,t){const n={};for(const o of Object.keys(t))n[o]=R(e[o],t[o]);return n}const ee=()=>typeof window<"u"&&window.matchMedia("(pointer: fine)").matches,k="[supermouse] doctor",l={brand:"color: #ffffff; background: #42b883; padding: 2px 4px; border-radius: 2px; font-weight: 700;",error:"color: #ffffff; background: #f43f5e; padding: 2px 4px; border-radius: 2px; font-weight: 700;",warn:"color: #1f2937; background: #f59e0b; padding: 2px 4px; border-radius: 2px; font-weight: 700;",info:"color: #ffffff; background: #3b82f6; padding: 2px 4px; border-radius: 2px; font-weight: 700;",dim:"color: #6b7280;",code:"color: #a1a1aa; font-weight: 500;",hint:"color: #10b981; font-weight: 600;"};function te(e){const t=e?ne(e):D();le(t)}function ne(e){const t=e.plugins??[],n=e.options??{};return[...oe(t),...ie(t),...se(t),...ce(n),...ue(n),...ae(n,e.state),...D(e)]}function j(e){return e.element!==void 0||typeof e.update=="function"&&e.update.length>=3}function re(e){return e.element!==void 0?!1:typeof e.update=="function"&&e.update.length===2}function oe(e){const t=[];for(const n of e){const o=n.name??"unknown",i=n.priority??0;re(n)&&i>=0&&t.push({severity:"warn",code:"PRIORITY_LOGIC",message:`Plugin "${o}" has priority ${i} but appears to be a logic plugin (should run before physics).`,hint:`Set priority to a negative value (e.g. -10) on "${o}"`}),j(n)&&i<0&&t.push({severity:"warn",code:"PRIORITY_VISUAL",message:`Plugin "${o}" has priority ${i} but appears to be a visual plugin (should run after physics).`,hint:"Remove priority or use a positive value"})}return t}function ie(e){const t=e.find(o=>o.name==="states");if(!t)return[];const n=t.priority??0;return n>=0?[{severity:"error",code:"STATES_PRIORITY",message:`States plugin has priority ${n}. It must run before all visual plugins.`,hint:"Set priority: -999 on the States plugin"}]:[]}function se(e){const t=[];for(const n of e){const o=n.name??"unknown";j(n)&&!n.element&&t.push({severity:"warn",code:"MISSING_ELEMENT",message:`Plugin "${o}" has no 'element' property — disablePlugin() will not hide its DOM.`,hint:"Assign plugin.element = el in install(), or use definePlugin()"})}return t}function ce(e){const t=document.querySelectorAll('[class*="supermouse-scope-"]');return t.length<=1?[]:e.container!==document.body?[]:[{severity:"warn",code:"MULTI_INSTANCE",message:`Detected ${t.length} Supermouse instances. The body instance may conflict with scoped ones.`,hint:"Use suspend() / resume() or scope instances to different containers"}]}function ue(e){const t=e.container;return!t||t===document.body?[]:window.getComputedStyle(t).position!=="static"?[]:[{severity:"info",code:"CONTAINER_POSITION",message:"Container has position:static. Supermouse will mutate it to relative.",hint:"Set position: relative in your CSS to avoid the mutation"}]}function ae(e,t){const n=e.cursor;if(n===void 0)return[];const o=["auto","custom","native","both"];return typeof n=="string"&&!o.includes(n)?[{severity:"error",code:"INVALID_CURSOR_MODE",message:`Invalid cursor mode "${n}". Expected one of: ${o.join(", ")}.`,hint:`Set cursor to one of: ${o.join(", ")}`}]:n==="both"&&e.container!==document.body&&t?.cursorMode==="both"?[{severity:"warn",code:"NESTED_BOTH_MODE",message:"Scoped instance uses cursor: 'both'. In nested scopes, the native cursor may be hidden by the outer instance's cursor suppression.",hint:"Offset the custom cursor when cursorMode === 'both' or consider a single-instance scope architecture"}]:[]}function D(e){const t=[];if(!Array.from(document.querySelectorAll("style")).some(i=>i.id.startsWith("supermouse-style-")))return[{severity:"error",code:"NOT_INITIALIZED",message:"Supermouse has not been initialized yet.",hint:"Call doctor() after new Supermouse() has run"}];document.querySelectorAll('[style*="cursor"]').forEach(i=>{const c=i.getAttribute("style")??"";c.includes("cursor: none")||c.includes("cursor")&&t.push({severity:"warn",code:"INLINE_CURSOR",message:"Element has an inline cursor style that may override Supermouse.",hint:"Remove inline cursor styles"})});const o=document.querySelector(".supermouse-scope-0");if(o){const i=o.classList.contains("supermouse-hide-0"),c=e?.state?.cursorMode??"auto",a=e?.state?.hasReceivedInput??!0,s=e?.input?.isEnabled??!0;c==="custom"&&s&&a&&!i&&t.push({severity:"warn",code:"BODY_CURSOR_LEAK",message:"Body instance has cursor: 'custom' but native cursor suppression class is not applied.",hint:"Check that the animation loop is running and setCursor('custom') was called"})}return t}function le(e){if(e.length===0){console.log(`%c${k}%c No issues found`,l.brand,l.dim);return}const t=[b(e,"error","error"),b(e,"warn","warning"),b(e,"info","note")].filter(n=>n!==null).join(" · ");console.log(`%c${k}%c ${t}`,l.brand,l.dim);for(const n of e)fe(n)}function b(e,t,n){const o=e.filter(i=>i.severity===t).length;return o>0?`${o} ${n}${o>1?"s":""}`:null}function fe(e){console.log(`%c${e.severity.toUpperCase()}%c %c${e.code}%c ${e.message}`,l[e.severity],l.dim,l.code,"color: inherit;"),e.hint&&console.log(`  %c→%c ${e.hint}`,l.hint,l.dim)}function de(e){return typeof e.create=="function"}function me(e,t={}){const n=t.name??e.name,o=t.isEnabled??!0;if(!de(e))return{...e,name:n,isEnabled:o};let i=null,c=!1;const a=s=>{if(i)return e.beforeDisable?.(s,i)};return{name:n,isEnabled:o,priority:e.priority,install(s){if(i=e.create(s),!(i instanceof HTMLElement)&&!(i instanceof SVGElement)){console.warn(`[supermouse] Plugin "${n}" create() did not return an HTMLElement or SVGElement.`);return}this.element=s.stage.appendChild(i),c=!0,e.selector&&s.registerHoverTarget(e.selector),o||(i.style.display="none"),e.install?.(s)},update(s,m){!i||!c||e.update?.(s,i,m)},onEnable(s){i&&(i.style.display="",e.onEnable?.(s,i))},async onBeforeDisable(s){await a(s)},onDisable(s){i&&e.onDisable?.(s,i)},destroy(s){i&&(e.cleanup?.(s,i),i.remove(),i=null,c=!1),e.destroy?.(s)}}}function u(e,t={}){const n=document.createElementNS("http://www.w3.org/2000/svg",e);for(const[o,i]of Object.entries(t))n.setAttribute(o,String(i));return n}function N(e,t){for(const[n,o]of Object.entries(t))e.setAttribute(n,String(o))}function L(e={}){return u("g",e)}function z(e={}){return u("circle",e)}function V(e={}){return u("rect",e)}function B(e,t={}){const n=u("path",t);return e!==void 0&&n.setAttribute("d",e),n}function U(e={},t){const n=u("text",e);return t!==void 0&&(n.textContent=t),n}function G(e,t={}){const n=u("textPath",{...t,href:e});return n.setAttributeNS("http://www.w3.org/1999/xlink","xlink:href",e),n}function H(e,t={},n=[]){const o=u("filter",{id:e,...t});return n.forEach(i=>o.appendChild(i)),o}function Y(e=0,t={}){return u("feGaussianBlur",{stdDeviation:String(e),...t})}function q(e=.1,t={}){return u("feTurbulence",{baseFrequency:String(e),...t})}function F(e){return u("feMergeNode",e?{in:e}:{})}function W(e=[]){const t=u("feMerge");return e.forEach(n=>t.appendChild(n)),t}function X(e){const t=Math.round(e*100)/100;return`
+    M 0, -${t}
+    A ${t},${t} 0 1,1 0,${t}
+    A ${t},${t} 0 1,1 0,-${t}
+  `.replace(/\s+/g," ").trim()}const he=Object.freeze(Object.defineProperty({__proto__:null,circle:z,circlePath:X,createSVGElement:u,filter:H,gaussianBlur:Y,group:L,merge:W,mergeNode:F,path:B,rect:V,setSVGAttrs:N,text:U,textPath:G,turbulence:q},Symbol.toStringTag,{value:"Module"})),ge={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"},pe={OVERLAY:"400",CURSOR:"300",FOLLOWER:"200",TRACE:"100"};r.Easings=ge,r.Layers=pe,r.angle=y,r.applyStyles=I,r.circle=z,r.circlePath=X,r.circumference=E,r.clamp=g,r.createActor=h,r.createCircle=C,r.createDiv=_,r.createSVGElement=u,r.css=d,r.damp=S,r.definePlugin=me,r.dist=p,r.doctor=te,r.dom=J,r.effects=Q,r.filter=H,r.gaussianBlur=Y,r.getVelocityDistortion=A,r.group=L,r.hasFinePointer=ee,r.injectStyles=$,r.lerp=f,r.lerpAngle=v,r.math=K,r.merge=W,r.mergeNode=F,r.normalize=R,r.normalizeAll=x,r.path=B,r.projectRect=T,r.random=w,r.rect=V,r.setSVGAttrs=N,r.setStyle=M,r.setTransform=P,r.svg=he,r.text=U,r.textPath=G,r.turbulence=q,Object.defineProperty(r,Symbol.toStringTag,{value:"Module"})}));

package/dist/math.d.ts

@@ -35,4 +35,5 @@ export declare function dist(x1: number, y1: number, x2?: number, y2?: number):
  * Calculates the angle in degrees between two points (or vector direction).
  */
 export declare function angle(x: number, y: number): number;
+export declare function circumference(r: number): number;
 //# sourceMappingURL=math.d.ts.map

package/dist/math.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../src/math.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG5E;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,GAAE,MAAU,EAAE,EAAE,GAAE,MAAU,GAAG,MAAM,CAInF;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD"}
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../src/math.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG5E;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,GAAE,MAAU,EAAE,EAAE,GAAE,MAAU,GAAG,MAAM,CAInF;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/options.d.ts

@@ -6,6 +6,36 @@ import { MouseState, ValueOrGetter } from '../packages/core/src';
  *
  * @param option The option passed by the user
  * @param defaultValue Fallback value
+ * @returns A function that returns the resolved value of the option
  */
 export declare function normalize<T>(option: ValueOrGetter<T> | undefined, defaultValue: T): (state: MouseState) => T;
+/**
+ * Normalizes multiple options in one call.
+ *
+ * @example
+ * const cfg = normalizeAll(options, {
+ *   size: 20,
+ *   color: "#fff",
+ *   opacity: 1,
+ * });
+ *
+ * // In update():
+ * const size = cfg.size(app.state);
+ *
+ * @param defaults Default values for the options
+ * @param options User-provided options to normalize
+ * @returns An object with normalized getter functions for each option
+ */
+export declare function normalizeAll<T extends Record<string, unknown>>(options: Partial<{
+    [K in keyof T]: ValueOrGetter<T[K]>;
+}>, defaults: T): {
+    [K in keyof T]: (state: MouseState) => T[K];
+};
+/**
+ * Checks if the current device has a fine pointer (e.g., mouse) or a coarse pointer (e.g., touch).
+ * This is useful for conditionally enabling or disabling cursor effects based on the input device.
+ *
+ * @returns True if the device has a fine pointer, false otherwise.
+ */
+export declare const hasFinePointer: () => boolean;
 //# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,EACpC,YAAY,EAAE,CAAC,GACd,CAAC,KAAK,EAAE,UAAU,KAAK,CAAC,CAQ1B"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,EACpC,YAAY,EAAE,CAAC,GACd,CAAC,KAAK,EAAE,UAAU,KAAK,CAAC,CAQ1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,OAAO,EAAE,OAAO,CAAC;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC,EACzD,QAAQ,EAAE,CAAC,GACV;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC;CAAE,CAWjD;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAO,OAC6C,CAAC"}

package/dist/plugin.d.ts

@@ -1,34 +1,111 @@
-import { Supermouse, SupermousePlugin } from '../packages/core/src';
+import { SupermouseInstance, SupermousePlugin } from '../packages/core/src';
+/** Options that can be passed to any plugin factory. */
 export interface BasePluginOptions {
+    /** Overrides the plugin's internal name. */
     name?: string;
+    /** Whether the plugin starts enabled. Defaults to `true`. */
     isEnabled?: boolean;
 }
-interface LogicConfig {
+interface CoreConfig {
+    /** Unique identifier. Used by `getPlugin()`, `enablePlugin()`, etc. */
     name: string;
+    /** Execution order in the frame loop. Lower values are executed earlier */
     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;
+    /** Whether the plugin starts enabled. Defaults to `true`. */
+    isEnabled?: boolean;
+    /** Called once when the plugin is registered via `app.use()`. */
+    install?(app: SupermouseInstance): void;
 }
-interface VisualConfig<E extends HTMLElement, O extends object> {
-    name: string;
-    /** Automatically register this attribute selector */
+/**
+ * Declarative config for a logic plugin.
+ *
+ * Logic plugins modify cursor intent (e.g. magnetism, snapping, gravity).
+ */
+export interface LogicConfig extends CoreConfig {
+    /**
+     * Called every frame while the plugin is enabled.
+     * @param app       The Supermouse instance.
+     * @param deltaTime Elapsed time since last frame, in milliseconds.
+     */
+    update?(app: SupermouseInstance, deltaTime: number): void;
+    /** Called when the plugin is removed or the app is destroyed. */
+    destroy?(app: SupermouseInstance): void;
+    /** Called when `app.enablePlugin(name)` is invoked. */
+    onEnable?(app: SupermouseInstance): void;
+    /** Called when `app.disablePlugin(name)` is invoked. */
+    onDisable?(app: SupermouseInstance): void;
+    /**
+     * Called before the plugin is disabled. Can return a Promise to delay
+     * hiding until an exit animation finishes. This is the declarative
+     * equivalent of `SupermousePlugin.onBeforeDisable`.
+     */
+    beforeDisable?(app: SupermouseInstance): void | Promise<void>;
+}
+/**
+ * Declarative config for a visual plugin.
+ *
+ * @typeParam E - The specific element subtype returned by `create`.
+ *   Can be an `HTMLElement` (e.g. `HTMLDivElement`) or an `SVGElement`
+ *   (e.g. `SVGSVGElement`).
+ */
+export interface VisualConfig<E extends HTMLElement | SVGElement = HTMLElement | SVGElement> extends CoreConfig {
+    /**
+     * Factory that creates the plugin's root DOM element.
+     * Called once during `install()`. The returned element is automatically
+     * appended to the **stage** (not `app.container`).
+     */
+    create: (app: SupermouseInstance) => E;
+    /**
+     * Called every frame while the plugin is enabled.
+     * Use `css()` from `@supermousejs/utils` for style writes,
+     * and `setTransform()` for positioning.
+     */
+    update?(app: SupermouseInstance, element: E, deltaTime: number): void;
+    /** Called when the plugin is enabled. The element is already visible. */
+    onEnable?(app: SupermouseInstance, element: E): void;
+    /**
+     * Called when the plugin is disabled.
+     * The element is still in the DOM when this runs, so you can start
+     * CSS transitions. If `beforeDisable` is defined and returns a Promise,
+     * the core will wait for it to resolve before hiding the element.
+     */
+    onDisable?(app: SupermouseInstance, element: E): void;
+    /**
+     * Called during `destroy()`, before the element is removed from the DOM.
+     * Use this to tear down external listeners or GSAP timelines.
+     */
+    cleanup?(app: SupermouseInstance, element: E): void;
+    /** General teardown hook, called after cleanup and element removal. */
+    destroy?(app: SupermouseInstance): void;
+    /**
+     * Auto-registers this selector as a hover target on install.
+     * Equivalent to `app.registerHoverTarget(selector)` inside `install()`.
+     */
     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;
+    /**
+     * Called before the plugin is disabled. Can return a Promise to delay
+     * hiding until an exit animation finishes.
+     * Receives the element as the second argument.
+     */
+    beforeDisable?(app: SupermouseInstance, element: E): void | Promise<void>;
 }
-export declare function definePlugin<E extends HTMLElement, O extends BasePluginOptions>(config: VisualConfig<E, O>, userOptions?: O): SupermousePlugin;
+/**
+ * Creates a visual plugin with automatic DOM mounting and lifecycle management.
+ *
+ * @param config        Visual plugin definition.
+ * @param userOptions   Optional overrides for `name` and `isEnabled`.
+ * @returns A `SupermousePlugin` whose `element` property is typed as `E`.
+ */
+export declare function definePlugin<E extends HTMLElement | SVGElement>(config: VisualConfig<E>, userOptions?: BasePluginOptions): SupermousePlugin & {
+    element?: E;
+};
+/**
+ * Creates a logic plugin that is passed through directly.
+ *
+ * @param config        Logic plugin definition.
+ * @param userOptions   Optional overrides for `name` and `isEnabled`.
+ * @returns A `SupermousePlugin`.
+ */
 export declare function definePlugin(config: LogicConfig, userOptions?: BasePluginOptions): SupermousePlugin;
 export {};
 //# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAIvE,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;IACpC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;IACpC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;IAEtC,MAAM,CAAC,EAAE,KAAK,CAAC;CAChB;AAGD,UAAU,YAAY,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,MAAM;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,CAAC,CAAC;IAC/B,wCAAwC;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,mBAAmB,CAAC,CAAC,CAAC;IAC7D,6CAA6C;IAC7C,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAClE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IACjD,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAClD,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAC/B,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB;AAYD,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,iBAAiB,EAC7E,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,WAAW,CAAC,EAAE,CAAC,GACd,gBAAgB,CAAC;AAGpB,wBAAgB,YAAY,CAC1B,MAAM,EAAE,WAAW,EACnB,WAAW,CAAC,EAAE,iBAAiB,GAC9B,gBAAgB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE/E,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,UAAU;IAClB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iEAAiE;IACjE,OAAO,CAAC,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C;;;;OAIG;IACH,MAAM,CAAC,CAAC,GAAG,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1D,iEAAiE;IACjE,OAAO,CAAC,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACxC,uDAAuD;IACvD,QAAQ,CAAC,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACzC,wDAAwD;IACxD,SAAS,CAAC,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C;;;;OAIG;IACH,aAAa,CAAC,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY,CAC3B,CAAC,SAAS,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAC7D,SAAQ,UAAU;IAClB;;;;OAIG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,CAAC,CAAC;IAEvC;;;;OAIG;IACH,MAAM,CAAC,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtE,yEAAyE;IACzE,QAAQ,CAAC,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IACrD;;;;;OAKG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IAEtD;;;OAGG;IACH,OAAO,CAAC,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IACpD,uEAAuE;IACvE,OAAO,CAAC,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,aAAa,CAAC,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3E;AAQD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,UAAU,EAC7D,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,WAAW,CAAC,EAAE,iBAAiB,GAC9B,gBAAgB,GAAG;IAAE,OAAO,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC;AAEtC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,WAAW,EACnB,WAAW,CAAC,EAAE,iBAAiB,GAC9B,gBAAgB,CAAC"}

package/dist/svg.d.ts

@@ -0,0 +1,36 @@
+type SVGAttrs = Record<string, string | number | boolean>;
+/** Create any SVG element by tag name with attributes. */
+export declare function createSVGElement<K extends keyof SVGElementTagNameMap>(tag: K, attrs?: SVGAttrs): SVGElementTagNameMap[K];
+/** Set multiple attributes on an SVG element. */
+export declare function setSVGAttrs(el: SVGElement, attrs: SVGAttrs): void;
+/** Create a `<g>` group. */
+export declare function group(attrs?: SVGAttrs): SVGGElement;
+/** Create a `<circle>`. */
+export declare function circle(attrs?: SVGAttrs): SVGCircleElement;
+/** Create a `<rect>`. */
+export declare function rect(attrs?: SVGAttrs): SVGRectElement;
+/** Create a `<path>` with optional `d` attribute. */
+export declare function path(d?: string, attrs?: SVGAttrs): SVGPathElement;
+/** Create a `<text>` element. */
+export declare function text(attrs?: SVGAttrs, content?: string): SVGTextElement;
+/** Create a `<textPath>` with proper `href` and `xlink:href`. */
+export declare function textPath(href: string, attrs?: SVGAttrs): SVGTextPathElement;
+/** Create a `<filter>` with region attributes and children. */
+export declare function filter(id: string, attrs?: SVGAttrs, children?: SVGElement[]): SVGFilterElement;
+/** Create a `<feGaussianBlur>` primitive. */
+export declare function gaussianBlur(stdDeviation?: string | number, attrs?: SVGAttrs): SVGFEGaussianBlurElement;
+/** Create a `<feTurbulence>` primitive. */
+export declare function turbulence(baseFrequency?: string | number, attrs?: SVGAttrs): SVGFETurbulenceElement;
+/** Create a `<feMergeNode>` primitive. */
+export declare function mergeNode(inAttr?: string): SVGFEMergeNodeElement;
+/** Create a `<feMerge>` container with merge node children. */
+export declare function merge(nodes?: SVGFEMergeNodeElement[]): SVGFEMergeElement;
+/**
+ * Calculates the SVG Path data for a perfect circle starting at the top center (12 o'clock).
+ *
+ * Path moves to (0, -r), then draws two semi-circles.
+ * @param r Radius in pixels
+ */
+export declare function circlePath(r: number): string;
+export {};
+//# sourceMappingURL=svg.d.ts.map

package/dist/svg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"svg.d.ts","sourceRoot":"","sources":["../src/svg.ts"],"names":[],"mappings":"AAAA,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAE1D,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,oBAAoB,EACnE,GAAG,EAAE,CAAC,EACN,KAAK,GAAE,QAAa,GACnB,oBAAoB,CAAC,CAAC,CAAC,CAMzB;AAED,iDAAiD;AACjD,wBAAgB,WAAW,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAIjE;AAED,4BAA4B;AAC5B,wBAAgB,KAAK,CAAC,KAAK,GAAE,QAAa,GAAG,WAAW,CAEvD;AAED,2BAA2B;AAC3B,wBAAgB,MAAM,CAAC,KAAK,GAAE,QAAa,GAAG,gBAAgB,CAE7D;AAED,yBAAyB;AACzB,wBAAgB,IAAI,CAAC,KAAK,GAAE,QAAa,GAAG,cAAc,CAEzD;AAED,qDAAqD;AACrD,wBAAgB,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,QAAa,GAAG,cAAc,CAIrE;AAED,iCAAiC;AACjC,wBAAgB,IAAI,CAAC,KAAK,GAAE,QAAa,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,cAAc,CAI3E;AAED,iEAAiE;AACjE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,QAAa,GAAG,kBAAkB,CAI/E;AAED,+DAA+D;AAC/D,wBAAgB,MAAM,CACpB,EAAE,EAAE,MAAM,EACV,KAAK,GAAE,QAAa,EACpB,QAAQ,GAAE,UAAU,EAAO,GAC1B,gBAAgB,CAIlB;AAED,6CAA6C;AAC7C,wBAAgB,YAAY,CAC1B,YAAY,GAAE,MAAM,GAAG,MAAU,EACjC,KAAK,GAAE,QAAa,GACnB,wBAAwB,CAK1B;AAED,2CAA2C;AAC3C,wBAAgB,UAAU,CACxB,aAAa,GAAE,MAAM,GAAG,MAAY,EACpC,KAAK,GAAE,QAAa,GACnB,sBAAsB,CAKxB;AAED,0CAA0C;AAC1C,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,qBAAqB,CAEhE;AAED,+DAA+D;AAC/D,wBAAgB,KAAK,CAAC,KAAK,GAAE,qBAAqB,EAAO,GAAG,iBAAiB,CAI5E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAU5C"}

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@supermousejs/utils",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "main": "dist/index.umd.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "author": "O.S David",
+  "description": "Shared utilities and helpers for writing Supermouse plugins",
   "url": "https://github.com/Whitestar14/supermouse-js",
+  "sideEffects": false,
   "license": "MIT",
   "exports": {
     ".": {
@@ -27,10 +29,10 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@supermousejs/core": "2.3.0"
+    "@supermousejs/core": "2.4.0"
   },
   "devDependencies": {
-    "@supermousejs/core": "2.3.0"
+    "@supermousejs/core": "2.4.0"
   },
   "scripts": {
     "build": "vite build"

package/src/css.ts

@@ -9,3 +9,21 @@ export const Easings = {
   /** Standard smooth movement */
   SMOOTH: "ease-out"
 } as const;
+
+/**
+ * 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;