@supermousejs/labs 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @supermousejs/labs
+
+## 2.0.0
+
+### Major Changes
+
+- Initial v2.0.0 release
+
+### Patch Changes
+
+- Updated dependencies
+  - @supermousejs/zoetrope@2.0.0
+  - @supermousejs/utils@2.0.0
+  - @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,72 @@
+import { SupermousePlugin } from '../../core/src/index.ts';
+import { ValueOrGetter } from '../../core/src/index.ts';
+
+export declare const SmartIcon: (options: SmartIconOptions) => SupermousePlugin;
+
+export declare type SmartIconAnchor = "center" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+
+export declare interface SmartIconMap {
+    [key: string]: string;
+}
+
+export declare interface SmartIconOptions {
+    name?: string;
+    isEnabled?: boolean;
+    icons: SmartIconMap;
+    defaultState?: string;
+    useSemanticTags?: boolean;
+    transitionDuration?: number;
+    size?: ValueOrGetter<number>;
+    color?: ValueOrGetter<string>;
+    offset?: [number, number];
+    anchor?: ValueOrGetter<SmartIconAnchor>;
+    followStrategy?: ValueOrGetter<"smooth" | "raw">;
+    rotateWithVelocity?: ValueOrGetter<boolean>;
+}
+
+export declare const SmartRing: (options?: SmartRingOptions) => SupermousePlugin;
+
+export declare interface SmartRingOptions {
+    name?: string;
+    isEnabled?: boolean;
+    size?: ValueOrGetter<number>;
+    hoverSize?: ValueOrGetter<number>;
+    color?: ValueOrGetter<string>;
+    fill?: ValueOrGetter<string>;
+    borderWidth?: ValueOrGetter<number>;
+    mixBlendMode?: string;
+    enableSkew?: boolean;
+}
+
+export declare const Sparkles: (options?: SparklesOptions) => SupermousePlugin;
+
+export declare interface SparklesOptions {
+    name?: string;
+    isEnabled?: boolean;
+    color?: ValueOrGetter<string>;
+    /** Number of particles to keep in the pool. Default 30. */
+    count?: number;
+    /** How fast particles fade out (0.01 - 0.1). Default 0.05. */
+    decay?: number;
+    /** Pixels of movement required to spawn a particle. Lower = denser trail. Default 10. */
+    frequency?: number;
+    /** Random position offset for spawning. Default 5. */
+    scatter?: number;
+}
+
+export declare const TextRing: (options?: TextRingOptions) => SupermousePlugin;
+
+export declare interface TextRingOptions {
+    name?: string;
+    isEnabled?: boolean;
+    text?: ValueOrGetter<string>;
+    radius?: ValueOrGetter<number>;
+    fontSize?: ValueOrGetter<number>;
+    speed?: ValueOrGetter<number>;
+    color?: ValueOrGetter<string>;
+    opacity?: ValueOrGetter<number>;
+    className?: string;
+    spread?: boolean;
+}
+
+export { }

package/dist/index.mjs

@@ -0,0 +1,233 @@
+import { normalize as A, definePlugin as N, dom as n, math as w, Layers as k, effects as F } from "@supermousejs/utils";
+import { getCirclePath as H, getCircumference as X, formatLoopText as Y } from "@supermousejs/zoetrope";
+function U(t, l) {
+  const o = t.tagName.toLowerCase();
+  if (o === "input" || o === "textarea" || t.isContentEditable) {
+    const i = t.type;
+    if (["button", "submit", "checkbox", "radio", "range", "color"].includes(
+      i
+    )) {
+      if (l.pointer)
+        return "pointer";
+    } else if (l.text) return "text";
+  } else if ((o === "a" || o === "button" || t.closest("a") || t.closest("button")) && l.pointer)
+    return "pointer";
+  return null;
+}
+const q = (t) => {
+  let l, o = t.defaultState || "default", i = t.defaultState || "default", d = null, T = null, C = !1, x, h = 0, p = 0;
+  const E = A(t.size, 24), r = A(t.followStrategy, "smooth"), S = A(t.anchor, "center"), v = A(t.rotateWithVelocity, !1), y = t.useSemanticTags ?? !0, c = t.transitionDuration ?? 200, s = t.offset ? t.offset[0] : 0, R = t.offset ? t.offset[1] : 0;
+  return N(
+    {
+      name: t.name || "smart-icon",
+      selector: "[data-supermouse-icon]",
+      create: () => {
+        const a = n.createActor("div");
+        return a.style.zIndex = k.CURSOR, l = n.createActor("div"), n.applyStyles(l, {
+          width: "100%",
+          height: "100%",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          transformOrigin: "center center",
+          transform: "scale(1)",
+          // Pre-baked ease. Note: If duration changes dynamically, this won't update.
+          transition: `transform ${c / 2}ms cubic-bezier(0.16, 1, 0.3, 1)`
+        }), l.innerHTML = t.icons[o] || "", a.appendChild(l), a;
+      },
+      styles: {
+        color: "color"
+      },
+      update: (a, g) => {
+        const e = t.icons, m = a.state.hoverTarget;
+        let f = t.defaultState || "default";
+        if (m) {
+          m !== d && (d = m, T = y ? U(m, e) : null);
+          const L = a.state.interaction?.icon;
+          L && e[L] ? f = L : T && (f = T);
+        } else
+          d = null, T = null;
+        f !== o && !C && (e[f] || f === (t.defaultState || "default")) && (i = f, C = !0, clearTimeout(x), l.style.transform = "scale(0)", x = setTimeout(() => {
+          o = i, l.innerHTML = e[o] || "", l.style.transform = "scale(1)", x = setTimeout(() => {
+            C = !1;
+          }, c / 2);
+        }, c / 2));
+        const b = E(a.state);
+        n.setStyle(g, "width", `${b}px`), n.setStyle(g, "height", `${b}px`);
+        let u = 0, z = 0;
+        const $ = b / 2, O = S(a.state);
+        O !== "center" && (O.includes("left") && (u = $), O.includes("right") && (u = -$), O.includes("top") && (z = $), O.includes("bottom") && (z = -$));
+        const P = o === "pointer" || o === "text";
+        if (v(a.state) && !P && !a.state.reducedMotion) {
+          const { x: L, y: I } = a.state.velocity;
+          w.dist(L, I) > 1 && (p = w.angle(L, I)), h = w.lerpAngle(
+            h,
+            p,
+            0.15
+          );
+        } else
+          h = w.lerpAngle(h, 0, 0.15);
+        const M = r(a.state) === "raw" ? a.state.pointer : a.state.smooth;
+        n.setTransform(
+          g,
+          M.x + s + u,
+          M.y + R + z,
+          h
+        );
+      },
+      cleanup() {
+        clearTimeout(x);
+      }
+    },
+    t
+  );
+}, V = (t = {}) => {
+  const l = A(t.size, 20), o = A(t.hoverSize, 40), i = A(t.color, "#ffffff"), d = A(t.borderWidth, 2), T = A(t.fill, "transparent");
+  let C = 20, x = 20, h = 0, p = 1, E = 1;
+  return N(
+    {
+      name: t.name || "smart-ring",
+      selector: "[data-supermouse-color]",
+      create: (r) => {
+        const S = n.createCircle(l(r.state), T(r.state));
+        return n.applyStyles(S, {
+          zIndex: k.FOLLOWER,
+          mixBlendMode: t.mixBlendMode || "difference",
+          transition: "opacity 0.2s ease, border-radius 0.2s ease",
+          borderStyle: "solid"
+        }), S;
+      },
+      update: (r, S) => {
+        const v = l(r.state), y = r.state.shape;
+        let c = v, s = v, R = "50%", a = i(r.state);
+        y ? (c = y.width, s = y.height, R = `${y.borderRadius}px`) : (r.state.isHover && (c = o(r.state), s = o(r.state)), r.state.isDown && (c *= 0.9, s *= 0.9)), r.state.interaction.color && (a = r.state.interaction.color), C = w.lerp(C, c, 0.2), x = w.lerp(x, s, 0.2), n.setStyle(S, "width", `${C}px`), n.setStyle(S, "height", `${x}px`), n.setStyle(S, "borderRadius", R), n.setStyle(S, "borderColor", a), n.setStyle(S, "backgroundColor", T(r.state)), n.setStyle(S, "borderWidth", `${d(r.state)}px`);
+        let g = 0, e = 1, m = 1;
+        if (!y && t.enableSkew && !r.state.reducedMotion) {
+          const { velocity: u } = r.state, z = F.getVelocityDistortion(u.x, u.y);
+          g = z.rotation, e = z.scaleX, m = z.scaleY, h = w.lerpAngle(h, g, 0.15);
+        } else
+          h = 0;
+        p = w.lerp(p, e, 0.15), E = w.lerp(E, m, 0.15);
+        const { x: f, y: b } = r.state.smooth;
+        n.setTransform(S, f, b, h, p, E);
+      }
+    },
+    t
+  );
+}, G = (t = {}) => {
+  const l = t.count || 30, o = t.decay || 0.05, i = t.frequency || 10, d = t.scatter || 5, C = A(t.color, "#ff00ff"), x = [];
+  let h = 0, p = 0, E = !1, r = 0;
+  const S = (v, y, c) => {
+    const s = x.find((e) => !e.isActive);
+    if (!s) return;
+    s.isActive = !0, s.life = 1, s.x = v + w.random(-d, d), s.y = y + w.random(-d, d);
+    const R = w.random(0, Math.PI * 2), a = w.random(0.5, 1.5);
+    s.vx = Math.cos(R) * a, s.vy = Math.sin(R) * a, s.scale = w.random(0.5, 1.2), s.color = c;
+    const g = w.random(2, 5);
+    n.setStyle(s.el, "width", `${g}px`), n.setStyle(s.el, "height", `${g}px`), n.setStyle(s.el, "backgroundColor", c), n.setStyle(s.el, "opacity", "1"), n.setTransform(s.el, s.x, s.y, 0, s.scale, s.scale);
+  };
+  return N(
+    {
+      name: t.name || "sparkles",
+      install(v) {
+        for (let y = 0; y < l; y++) {
+          const c = n.createCircle(0, "transparent");
+          n.applyStyles(c, {
+            zIndex: k.TRACE,
+            opacity: "0",
+            willChange: "transform, opacity",
+            transition: "none"
+          }), v.container.appendChild(c), x.push({
+            el: c,
+            isActive: !1,
+            x: 0,
+            y: 0,
+            vx: 0,
+            vy: 0,
+            life: 0,
+            scale: 1,
+            color: ""
+          });
+        }
+      },
+      update(v) {
+        const { x: y, y: c } = v.state.pointer;
+        E || (h = y, p = c, E = !0);
+        const s = y - h, R = c - p, a = Math.hypot(s, R);
+        if (r += a, r > i) {
+          const g = C(v.state), e = Math.floor(r / i);
+          for (let m = 0; m < e; m++) {
+            const f = m / e, b = h + s * f, u = p + R * f;
+            S(b, u, g);
+          }
+          r = r % i;
+        }
+        h = y, p = c;
+        for (let g = 0; g < l; g++) {
+          const e = x[g];
+          if (e.isActive)
+            if (e.x += e.vx, e.y += e.vy, e.life -= o, e.life <= 0)
+              e.isActive = !1, e.el.style.opacity = "0";
+            else {
+              e.el.style.opacity = String(e.life);
+              const m = e.scale * e.life;
+              n.setTransform(e.el, e.x, e.y, 0, m, m);
+            }
+        }
+      },
+      destroy() {
+        x.forEach((v) => v.el.remove()), x.length = 0;
+      }
+    },
+    t
+  );
+};
+let j = 0;
+const J = (t = {}) => {
+  let l, o, i, d, T;
+  const C = `supermouse-text-ring-path-${j++}`, x = "SUPERMOUSE • SUPERMOUSE • ", h = 60, p = 12, E = 0.5, r = t.className || "", S = t.spread ?? !1, v = A(t.text, x), y = A(t.radius, h), c = A(t.fontSize, p), s = A(t.speed, E), R = A(t.opacity, 1);
+  let a = 0, g = "", e = 0, m = 0;
+  return N({
+    name: "text-ring",
+    selector: "[data-supermouse-text-ring]",
+    create: (f) => {
+      const b = n.createActor("div");
+      n.applyStyles(b, {
+        zIndex: k.FOLLOWER,
+        transition: "opacity 0.2s ease",
+        opacity: "1",
+        width: "0px",
+        height: "0px",
+        overflow: "visible",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center"
+      }), r && b.classList.add(...r.split(" ").filter(Boolean)), l = document.createElementNS("http://www.w3.org/2000/svg", "svg"), l.style.overflow = "visible", l.style.position = "absolute", l.style.left = "0", l.style.top = "0", o = document.createElementNS("http://www.w3.org/2000/svg", "path"), o.setAttribute("id", C), o.setAttribute("fill", "none"), d = document.createElementNS("http://www.w3.org/2000/svg", "text");
+      const u = c(f.state);
+      return d.setAttribute("font-size", `${u}px`), m = u, d.setAttribute("fill", "currentColor"), d.style.textTransform = "uppercase", d.style.letterSpacing = "2px", i = document.createElementNS("http://www.w3.org/2000/svg", "textPath"), i.setAttributeNS("http://www.w3.org/1999/xlink", "xlink:href", `#${C}`), i.setAttribute("href", `#${C}`), i.setAttribute("startOffset", "0%"), T = document.createTextNode(""), i.appendChild(T), d.appendChild(i), l.appendChild(o), l.appendChild(d), b.appendChild(l), b;
+    },
+    styles: {
+      color: "color"
+    },
+    update: (f, b) => {
+      let u = v(f.state);
+      const z = y(f.state), $ = c(f.state), O = s(f.state), P = R(f.state);
+      n.setStyle(b, "opacity", String(P));
+      const M = f.state.interaction;
+      if (M.textRing && typeof M.textRing == "string" ? u = M.textRing : M.text && typeof M.text == "string" && (u = M.text), z !== e && (o.setAttribute("d", H(z)), e = z), S) {
+        const W = X(z);
+        i.setAttribute("textLength", String(W)), i.setAttribute("lengthAdjust", "spacing"), u = Y(u, !0);
+      } else
+        i.removeAttribute("textLength"), i.removeAttribute("lengthAdjust");
+      $ !== m && (d.setAttribute("font-size", `${$}px`), m = $), u !== g && (T.textContent = u, g = u), a += O;
+      const { x: L, y: I } = f.state.smooth;
+      n.setTransform(b, L, I, a);
+    }
+  }, t);
+};
+export {
+  q as SmartIcon,
+  V as SmartRing,
+  G as Sparkles,
+  J as TextRing
+};

package/dist/index.umd.js

@@ -0,0 +1 @@
+(function(C,e){typeof exports=="object"&&typeof module<"u"?e(exports,require("@supermousejs/utils"),require("@supermousejs/zoetrope")):typeof define=="function"&&define.amd?define(["exports","@supermousejs/utils","@supermousejs/zoetrope"],e):(C=typeof globalThis<"u"?globalThis:C||self,e(C.SupermouseLabs={},C.SupermouseUtils,C.SupermouseZoetrope))})(this,(function(C,e,P){"use strict";function N(t,a){const c=t.tagName.toLowerCase();if(c==="input"||c==="textarea"||t.isContentEditable){const i=t.type;if(["button","submit","checkbox","radio","range","color"].includes(i)){if(a.pointer)return"pointer"}else if(a.text)return"text"}else if((c==="a"||c==="button"||t.closest("a")||t.closest("button"))&&a.pointer)return"pointer";return null}const k=t=>{let a,c=t.defaultState||"default",i=t.defaultState||"default",f=null,w=null,p=!1,S,g=0,z=0;const R=e.normalize(t.size,24),o=e.normalize(t.followStrategy,"smooth"),x=e.normalize(t.anchor,"center"),v=e.normalize(t.rotateWithVelocity,!1),h=t.useSemanticTags??!0,l=t.transitionDuration??200,n=t.offset?t.offset[0]:0,T=t.offset?t.offset[1]:0;return e.definePlugin({name:t.name||"smart-icon",selector:"[data-supermouse-icon]",create:()=>{const s=e.dom.createActor("div");return s.style.zIndex=e.Layers.CURSOR,a=e.dom.createActor("div"),e.dom.applyStyles(a,{width:"100%",height:"100%",display:"flex",alignItems:"center",justifyContent:"center",transformOrigin:"center center",transform:"scale(1)",transition:`transform ${l/2}ms cubic-bezier(0.16, 1, 0.3, 1)`}),a.innerHTML=t.icons[c]||"",s.appendChild(a),s},styles:{color:"color"},update:(s,y)=>{const r=t.icons,u=s.state.hoverTarget;let d=t.defaultState||"default";if(u){u!==f&&(f=u,w=h?N(u,r):null);const M=s.state.interaction?.icon;M&&r[M]?d=M:w&&(d=w)}else f=null,w=null;d!==c&&!p&&(r[d]||d===(t.defaultState||"default"))&&(i=d,p=!0,clearTimeout(S),a.style.transform="scale(0)",S=setTimeout(()=>{c=i,a.innerHTML=r[c]||"",a.style.transform="scale(1)",S=setTimeout(()=>{p=!1},l/2)},l/2));const b=R(s.state);e.dom.setStyle(y,"width",`${b}px`),e.dom.setStyle(y,"height",`${b}px`);let m=0,A=0;const L=b/2,$=x(s.state);$!=="center"&&($.includes("left")&&(m=L),$.includes("right")&&(m=-L),$.includes("top")&&(A=L),$.includes("bottom")&&(A=-L));const I=c==="pointer"||c==="text";if(v(s.state)&&!I&&!s.state.reducedMotion){const{x:M,y:O}=s.state.velocity;e.math.dist(M,O)>1&&(z=e.math.angle(M,O)),g=e.math.lerpAngle(g,z,.15)}else g=e.math.lerpAngle(g,0,.15);const E=o(s.state)==="raw"?s.state.pointer:s.state.smooth;e.dom.setTransform(y,E.x+n+m,E.y+T+A,g)},cleanup(){clearTimeout(S)}},t)},W=(t={})=>{const a=e.normalize(t.size,20),c=e.normalize(t.hoverSize,40),i=e.normalize(t.color,"#ffffff"),f=e.normalize(t.borderWidth,2),w=e.normalize(t.fill,"transparent");let p=20,S=20,g=0,z=1,R=1;return e.definePlugin({name:t.name||"smart-ring",selector:"[data-supermouse-color]",create:o=>{const x=e.dom.createCircle(a(o.state),w(o.state));return e.dom.applyStyles(x,{zIndex:e.Layers.FOLLOWER,mixBlendMode:t.mixBlendMode||"difference",transition:"opacity 0.2s ease, border-radius 0.2s ease",borderStyle:"solid"}),x},update:(o,x)=>{const v=a(o.state),h=o.state.shape;let l=v,n=v,T="50%",s=i(o.state);h?(l=h.width,n=h.height,T=`${h.borderRadius}px`):(o.state.isHover&&(l=c(o.state),n=c(o.state)),o.state.isDown&&(l*=.9,n*=.9)),o.state.interaction.color&&(s=o.state.interaction.color),p=e.math.lerp(p,l,.2),S=e.math.lerp(S,n,.2),e.dom.setStyle(x,"width",`${p}px`),e.dom.setStyle(x,"height",`${S}px`),e.dom.setStyle(x,"borderRadius",T),e.dom.setStyle(x,"borderColor",s),e.dom.setStyle(x,"backgroundColor",w(o.state)),e.dom.setStyle(x,"borderWidth",`${f(o.state)}px`);let y=0,r=1,u=1;if(!h&&t.enableSkew&&!o.state.reducedMotion){const{velocity:m}=o.state,A=e.effects.getVelocityDistortion(m.x,m.y);y=A.rotation,r=A.scaleX,u=A.scaleY,g=e.math.lerpAngle(g,y,.15)}else g=0;z=e.math.lerp(z,r,.15),R=e.math.lerp(R,u,.15);const{x:d,y:b}=o.state.smooth;e.dom.setTransform(x,d,b,g,z,R)}},t)},F=(t={})=>{const a=t.count||30,c=t.decay||.05,i=t.frequency||10,f=t.scatter||5,p=e.normalize(t.color,"#ff00ff"),S=[];let g=0,z=0,R=!1,o=0;const x=(v,h,l)=>{const n=S.find(r=>!r.isActive);if(!n)return;n.isActive=!0,n.life=1,n.x=v+e.math.random(-f,f),n.y=h+e.math.random(-f,f);const T=e.math.random(0,Math.PI*2),s=e.math.random(.5,1.5);n.vx=Math.cos(T)*s,n.vy=Math.sin(T)*s,n.scale=e.math.random(.5,1.2),n.color=l;const y=e.math.random(2,5);e.dom.setStyle(n.el,"width",`${y}px`),e.dom.setStyle(n.el,"height",`${y}px`),e.dom.setStyle(n.el,"backgroundColor",l),e.dom.setStyle(n.el,"opacity","1"),e.dom.setTransform(n.el,n.x,n.y,0,n.scale,n.scale)};return e.definePlugin({name:t.name||"sparkles",install(v){for(let h=0;h<a;h++){const l=e.dom.createCircle(0,"transparent");e.dom.applyStyles(l,{zIndex:e.Layers.TRACE,opacity:"0",willChange:"transform, opacity",transition:"none"}),v.container.appendChild(l),S.push({el:l,isActive:!1,x:0,y:0,vx:0,vy:0,life:0,scale:1,color:""})}},update(v){const{x:h,y:l}=v.state.pointer;R||(g=h,z=l,R=!0);const n=h-g,T=l-z,s=Math.hypot(n,T);if(o+=s,o>i){const y=p(v.state),r=Math.floor(o/i);for(let u=0;u<r;u++){const d=u/r,b=g+n*d,m=z+T*d;x(b,m,y)}o=o%i}g=h,z=l;for(let y=0;y<a;y++){const r=S[y];if(r.isActive)if(r.x+=r.vx,r.y+=r.vy,r.life-=c,r.life<=0)r.isActive=!1,r.el.style.opacity="0";else{r.el.style.opacity=String(r.life);const u=r.scale*r.life;e.dom.setTransform(r.el,r.x,r.y,0,u,u)}}},destroy(){S.forEach(v=>v.el.remove()),S.length=0}},t)};let H=0;const U=(t={})=>{let a,c,i,f,w;const p=`supermouse-text-ring-path-${H++}`,S="SUPERMOUSE • SUPERMOUSE • ",g=60,z=12,R=.5,o=t.className||"",x=t.spread??!1,v=e.normalize(t.text,S),h=e.normalize(t.radius,g),l=e.normalize(t.fontSize,z),n=e.normalize(t.speed,R),T=e.normalize(t.opacity,1);let s=0,y="",r=0,u=0;return e.definePlugin({name:"text-ring",selector:"[data-supermouse-text-ring]",create:d=>{const b=e.dom.createActor("div");e.dom.applyStyles(b,{zIndex:e.Layers.FOLLOWER,transition:"opacity 0.2s ease",opacity:"1",width:"0px",height:"0px",overflow:"visible",display:"flex",alignItems:"center",justifyContent:"center"}),o&&b.classList.add(...o.split(" ").filter(Boolean)),a=document.createElementNS("http://www.w3.org/2000/svg","svg"),a.style.overflow="visible",a.style.position="absolute",a.style.left="0",a.style.top="0",c=document.createElementNS("http://www.w3.org/2000/svg","path"),c.setAttribute("id",p),c.setAttribute("fill","none"),f=document.createElementNS("http://www.w3.org/2000/svg","text");const m=l(d.state);return f.setAttribute("font-size",`${m}px`),u=m,f.setAttribute("fill","currentColor"),f.style.textTransform="uppercase",f.style.letterSpacing="2px",i=document.createElementNS("http://www.w3.org/2000/svg","textPath"),i.setAttributeNS("http://www.w3.org/1999/xlink","xlink:href",`#${p}`),i.setAttribute("href",`#${p}`),i.setAttribute("startOffset","0%"),w=document.createTextNode(""),i.appendChild(w),f.appendChild(i),a.appendChild(c),a.appendChild(f),b.appendChild(a),b},styles:{color:"color"},update:(d,b)=>{let m=v(d.state);const A=h(d.state),L=l(d.state),$=n(d.state),I=T(d.state);e.dom.setStyle(b,"opacity",String(I));const E=d.state.interaction;if(E.textRing&&typeof E.textRing=="string"?m=E.textRing:E.text&&typeof E.text=="string"&&(m=E.text),A!==r&&(c.setAttribute("d",P.getCirclePath(A)),r=A),x){const j=P.getCircumference(A);i.setAttribute("textLength",String(j)),i.setAttribute("lengthAdjust","spacing"),m=P.formatLoopText(m,!0)}else i.removeAttribute("textLength"),i.removeAttribute("lengthAdjust");L!==u&&(f.setAttribute("font-size",`${L}px`),u=L),m!==y&&(w.textContent=m,y=m),s+=$;const{x:M,y:O}=d.state.smooth;e.dom.setTransform(b,M,O,s)}},t)};C.SmartIcon=k,C.SmartRing=W,C.Sparkles=F,C.TextRing=U,Object.defineProperty(C,Symbol.toStringTag,{value:"Module"})}));

package/meta.json

@@ -0,0 +1,59 @@
+
+[
+  {
+    "id": "smart-icon",
+    "name": "SmartIcon",
+    "package": "@supermousejs/labs",
+    "description": "Advanced state machine that morphs SVGs based on semantic context.",
+    "code": "import { SmartIcon } from '@supermousejs/labs';\n\napp.use(SmartIcon({ icons: { ... } }));",
+    "recipeId": "context-icon",
+    "icon": "labs",
+    "options": [
+      { "name": "icons", "type": "Record<string, string>", "default": "{}", "description": "Map of state names to SVG strings.", "reactive": false },
+      { "name": "size", "type": "number", "default": "24", "description": "Size of the icon container.", "reactive": true },
+      { "name": "color", "type": "string", "default": "'black'", "description": "Icon fill color (currentColor).", "reactive": true },
+      { "name": "anchor", "type": "string", "default": "'center'", "description": "Alignment (center, top-left, etc).", "reactive": true },
+      { "name": "offset", "type": "[number, number]", "default": "[0, 0]", "description": "Fixed offset.", "reactive": false },
+      { "name": "transitionDuration", "type": "number", "default": "200", "description": "Morph transition time in ms.", "reactive": false }
+    ]
+  },
+  {
+    "id": "smart-ring",
+    "name": "SmartRing",
+    "package": "@supermousejs/labs",
+    "description": "A reactive ring that distorts with velocity and adapts to stuck elements.",
+    "code": "import { SmartRing } from '@supermousejs/labs';\n\napp.use(SmartRing({ size: 24, color: '#f59e0b', enableSkew: true }));",
+    "icon": "ring",
+    "options": [
+        { "name": "size", "type": "number", "default": "20", "description": "Base diameter.", "reactive": true },
+        { "name": "hoverSize", "type": "number", "default": "40", "description": "Diameter on hover.", "reactive": true },
+        { "name": "enableSkew", "type": "boolean", "default": "false", "description": "Distort shape based on velocity.", "reactive": false }
+    ]
+  },
+  {
+    "id": "sparkles",
+    "name": "Sparkles",
+    "package": "@supermousejs/labs",
+    "description": "Emits particle trails based on movement velocity.",
+    "code": "import { Sparkles } from '@supermousejs/labs';\n\napp.use(Sparkles({ color: '#f59e0b', frequency: 10 }));",
+    "icon": "trail",
+    "options": [
+        { "name": "color", "type": "string", "default": "'#ff00ff'", "description": "Particle color.", "reactive": true },
+        { "name": "frequency", "type": "number", "default": "10", "description": "Pixels per spawn.", "reactive": false },
+        { "name": "decay", "type": "number", "default": "0.05", "description": "Fade rate.", "reactive": false }
+    ]
+  },
+  {
+    "id": "text-ring",
+    "name": "TextRing",
+    "package": "@supermousejs/labs",
+    "description": "Rotates text around the cursor position.",
+    "code": "import { TextRing } from '@supermousejs/labs';\n\napp.use(TextRing({ text: 'LOADING • ', radius: 40 }));",
+    "icon": "text",
+    "options": [
+        { "name": "text", "type": "string", "default": "'SUPERMOUSE • '", "description": "Text content.", "reactive": true },
+        { "name": "radius", "type": "number", "default": "60", "description": "Ring radius.", "reactive": true },
+        { "name": "speed", "type": "number", "default": "0.5", "description": "Rotation speed deg/frame.", "reactive": true }
+    ]
+  }
+]

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@supermousejs/labs",
+  "version": "2.0.0",
+  "main": "dist/index.umd.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@supermousejs/zoetrope": "2.0.0",
+    "@supermousejs/core": "2.0.0",
+    "@supermousejs/utils": "2.0.0"
+  },
+  "peerDependencies": {
+    "@supermousejs/core": "2.0.0"
+  },
+  "devDependencies": {
+    "@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/SmartIcon.ts

@@ -0,0 +1,239 @@
+import type { ValueOrGetter } from "@supermousejs/core";
+import { definePlugin, normalize, dom, math, Layers } from "@supermousejs/utils";
+
+export interface SmartIconMap {
+  [key: string]: string;
+}
+
+export type SmartIconAnchor =
+  | "center"
+  | "top-left"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-right";
+
+export interface SmartIconOptions {
+  name?: string;
+  isEnabled?: boolean;
+  icons: SmartIconMap;
+  defaultState?: string;
+  useSemanticTags?: boolean;
+  transitionDuration?: number;
+  size?: ValueOrGetter<number>;
+  color?: ValueOrGetter<string>;
+  offset?: [number, number];
+  anchor?: ValueOrGetter<SmartIconAnchor>;
+  followStrategy?: ValueOrGetter<"smooth" | "raw">;
+  rotateWithVelocity?: ValueOrGetter<boolean>;
+}
+
+function resolveSemanticState(
+  target: HTMLElement,
+  icons: SmartIconMap
+): string | null {
+  const tag = target.tagName.toLowerCase();
+
+  if (tag === "input" || tag === "textarea" || target.isContentEditable) {
+    const type = (target as HTMLInputElement).type;
+    if (
+      !["button", "submit", "checkbox", "radio", "range", "color"].includes(
+        type
+      )
+    ) {
+      if (icons["text"]) return "text";
+    } else if (icons["pointer"]) {
+      return "pointer";
+    }
+  } else if (
+    tag === "a" ||
+    tag === "button" ||
+    target.closest("a") ||
+    target.closest("button")
+  ) {
+    if (icons["pointer"]) return "pointer";
+  }
+  return null;
+}
+
+export const SmartIcon = (options: SmartIconOptions) => {
+  let contentWrapper: HTMLDivElement;
+
+  // State
+  let currentState = options.defaultState || "default";
+  let targetState = options.defaultState || "default";
+
+  let lastTarget: HTMLElement | null = null;
+  let cachedSemanticState: string | null = null;
+
+  let isTransitioning = false;
+  let transitionTimer: ReturnType<typeof setTimeout>;
+
+  // Rotation State
+  let currentRotation = 0;
+  let lastTargetRotation = 0;
+
+  // Normalized Getters (Pre-calculated)
+  const getSize = normalize(options.size, 24);
+  const getStrategy = normalize(options.followStrategy, "smooth");
+  const getAnchor = normalize(options.anchor, "center");
+  const getShouldRotate = normalize(options.rotateWithVelocity, false);
+
+  const useSemanticTags = options.useSemanticTags ?? true;
+  const duration = options.transitionDuration ?? 200;
+  const userOffX = options.offset ? options.offset[0] : 0;
+  const userOffY = options.offset ? options.offset[1] : 0;
+
+  return definePlugin<HTMLDivElement, SmartIconOptions>(
+    {
+      name: options.name || "smart-icon",
+      selector: "[data-supermouse-icon]",
+
+      create: () => {
+        const el = dom.createActor("div") as HTMLDivElement;
+        el.style.zIndex = Layers.CURSOR;
+
+        contentWrapper = dom.createActor("div") as HTMLDivElement;
+        dom.applyStyles(contentWrapper, {
+          width: "100%",
+          height: "100%",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          transformOrigin: "center center",
+          transform: "scale(1)",
+          // Pre-baked ease. Note: If duration changes dynamically, this won't update.
+          transition: `transform ${
+            duration / 2
+          }ms cubic-bezier(0.16, 1, 0.3, 1)`,
+        });
+
+        contentWrapper.innerHTML = options.icons[currentState] || "";
+
+        el.appendChild(contentWrapper);
+        return el;
+      },
+
+      styles: {
+        color: "color",
+      },
+
+      update: (app, el) => {
+        const icons = options.icons;
+        const target = app.state.hoverTarget;
+
+        // 1. Determine Next State
+        let nextState = options.defaultState || "default";
+
+        if (target) {
+          // A. Update Cache if target changed (Performance Fix)
+          if (target !== lastTarget) {
+            lastTarget = target;
+            cachedSemanticState = useSemanticTags
+              ? resolveSemanticState(target, icons)
+              : null;
+          }
+
+          // B. Resolve Logic
+          // Check Unified Interaction State (Attribute)
+          const attrSmartIcon = app.state.interaction?.icon; // Optional chaining safety
+
+          if (attrSmartIcon && icons[attrSmartIcon]) {
+            nextState = attrSmartIcon;
+          } else if (cachedSemanticState) {
+            nextState = cachedSemanticState;
+          }
+        } else {
+          lastTarget = null;
+          cachedSemanticState = null;
+        }
+
+        // 2. Handle State Transition
+        if (nextState !== currentState && !isTransitioning) {
+          if (
+            icons[nextState] ||
+            nextState === (options.defaultState || "default")
+          ) {
+            targetState = nextState;
+            isTransitioning = true;
+
+            // Clean up any pending timer to avoid race conditions
+            clearTimeout(transitionTimer);
+
+            // Scale Down
+            contentWrapper.style.transform = "scale(0)";
+
+            transitionTimer = setTimeout(() => {
+              currentState = targetState;
+              contentWrapper.innerHTML = icons[currentState] || "";
+              contentWrapper.style.transform = "scale(1)";
+
+              transitionTimer = setTimeout(() => {
+                isTransitioning = false;
+              }, duration / 2);
+            }, duration / 2);
+          }
+        }
+
+        // 3. Layout & Styling
+        const size = getSize(app.state);
+        dom.setStyle(el, "width", `${size}px`);
+        dom.setStyle(el, "height", `${size}px`);
+
+        // 4. Calculate Anchor
+        let anchorX = 0;
+        let anchorY = 0;
+        const half = size / 2;
+        const anchor = getAnchor(app.state);
+
+        if (anchor !== "center") {
+          if (anchor.includes("left")) anchorX = half;
+          if (anchor.includes("right")) anchorX = -half;
+          if (anchor.includes("top")) anchorY = half;
+          if (anchor.includes("bottom")) anchorY = -half;
+        }
+
+        // 5. Rotation
+        const isSemanticState =
+          currentState === "pointer" || currentState === "text";
+
+        if (
+          getShouldRotate(app.state) &&
+          !isSemanticState &&
+          !app.state.reducedMotion
+        ) {
+          const { x: vx, y: vy } = app.state.velocity;
+          const speed = math.dist(vx, vy);
+
+          if (speed > 1) {
+            lastTargetRotation = math.angle(vx, vy);
+          }
+          // Assuming math.lerpAngle handles the 360 wrap logic correctly
+          currentRotation = math.lerpAngle(
+            currentRotation,
+            lastTargetRotation,
+            0.15
+          );
+        } else {
+          currentRotation = math.lerpAngle(currentRotation, 0, 0.15);
+        }
+
+        // 6. Render
+        const pos =
+          getStrategy(app.state) === "raw"
+            ? app.state.pointer
+            : app.state.smooth;
+        dom.setTransform(
+          el,
+          pos.x + userOffX + anchorX,
+          pos.y + userOffY + anchorY,
+          currentRotation
+        );
+      },
+
+      cleanup() {
+        clearTimeout(transitionTimer);
+      },
+    },
+    options
+  );
+};

package/src/SmartRing.ts

@@ -0,0 +1,105 @@
+import type { ValueOrGetter } from "@supermousejs/core";
+import { definePlugin, normalize, dom, math, effects, Layers } from "@supermousejs/utils";
+
+export interface SmartRingOptions {
+  name?: string;
+  isEnabled?: boolean;
+  size?: ValueOrGetter<number>;
+  hoverSize?: ValueOrGetter<number>;
+  color?: ValueOrGetter<string>;
+  fill?: ValueOrGetter<string>;
+  borderWidth?: ValueOrGetter<number>;
+  mixBlendMode?: string;
+  enableSkew?: boolean;
+}
+
+export const SmartRing = (options: SmartRingOptions = {}) => {
+  const getSize = normalize(options.size, 20);
+  const getHoverSize = normalize(options.hoverSize, 40);
+  const getColor = normalize(options.color, "#ffffff");
+  const getBorder = normalize(options.borderWidth, 2);
+  const getFill = normalize(options.fill, "transparent");
+
+  let currentW = 20;
+  let currentH = 20;
+  let currentRot = 0;
+  let currentScaleX = 1;
+  let currentScaleY = 1;
+
+  return definePlugin<HTMLDivElement, SmartRingOptions>(
+    {
+      name: options.name || "smart-ring",
+      selector: "[data-supermouse-color]",
+
+      create: (app) => {
+        const el = dom.createCircle(getSize(app.state), getFill(app.state));
+        dom.applyStyles(el, {
+          zIndex: Layers.FOLLOWER,
+          mixBlendMode: options.mixBlendMode || "difference",
+          transition: "opacity 0.2s ease, border-radius 0.2s ease",
+          borderStyle: "solid",
+        });
+        return el;
+      },
+
+      update: (app, el) => {
+        const baseSize = getSize(app.state);
+        const shape = app.state.shape;
+
+        let targetW = baseSize;
+        let targetH = baseSize;
+        let targetRadius = "50%";
+        let color = getColor(app.state);
+
+        if (shape) {
+          targetW = shape.width;
+          targetH = shape.height;
+          targetRadius = `${shape.borderRadius}px`;
+        } else {
+          if (app.state.isHover) {
+            targetW = getHoverSize(app.state);
+            targetH = getHoverSize(app.state);
+          }
+          if (app.state.isDown) {
+            targetW *= 0.9;
+            targetH *= 0.9;
+          }
+        }
+
+        if (app.state.interaction.color) color = app.state.interaction.color;
+
+        currentW = math.lerp(currentW, targetW, 0.2);
+        currentH = math.lerp(currentH, targetH, 0.2);
+
+        dom.setStyle(el, "width", `${currentW}px`);
+        dom.setStyle(el, "height", `${currentH}px`);
+        dom.setStyle(el, "borderRadius", targetRadius);
+        dom.setStyle(el, "borderColor", color);
+        dom.setStyle(el, "backgroundColor", getFill(app.state));
+        dom.setStyle(el, "borderWidth", `${getBorder(app.state)}px`);
+
+        let targetRot = 0;
+        let targetScaleX = 1;
+        let targetScaleY = 1;
+
+        if (!shape && options.enableSkew && !app.state.reducedMotion) {
+          const { velocity } = app.state;
+          const dist = effects.getVelocityDistortion(velocity.x, velocity.y);
+          targetRot = dist.rotation;
+          targetScaleX = dist.scaleX;
+          targetScaleY = dist.scaleY;
+          currentRot = math.lerpAngle(currentRot, targetRot, 0.15);
+        } else {
+          currentRot = 0;
+        }
+
+        currentScaleX = math.lerp(currentScaleX, targetScaleX, 0.15);
+        currentScaleY = math.lerp(currentScaleY, targetScaleY, 0.15);
+
+        const { x, y } = app.state.smooth;
+        dom.setTransform(el, x, y, currentRot, currentScaleX, currentScaleY);
+      },
+    },
+    options
+  );
+};

package/src/Sparkles.ts

@@ -0,0 +1,168 @@
+import type { ValueOrGetter } from "@supermousejs/core";
+import { definePlugin, normalize, dom, math, Layers } from "@supermousejs/utils";
+
+export interface SparklesOptions {
+  name?: string;
+  isEnabled?: boolean;
+  color?: ValueOrGetter<string>;
+  /** Number of particles to keep in the pool. Default 30. */
+  count?: number;
+  /** How fast particles fade out (0.01 - 0.1). Default 0.05. */
+  decay?: number;
+  /** Pixels of movement required to spawn a particle. Lower = denser trail. Default 10. */
+  frequency?: number;
+  /** Random position offset for spawning. Default 5. */
+  scatter?: number;
+}
+
+interface Particle {
+  el: HTMLDivElement;
+  isActive: boolean;
+  x: number;
+  y: number;
+  vx: number;
+  vy: number;
+  life: number; // 0.0 to 1.0
+  scale: number;
+  color: string;
+}
+
+export const Sparkles = (options: SparklesOptions = {}) => {
+  const poolSize = options.count || 30;
+  const decayRate = options.decay || 0.05;
+  const frequency = options.frequency || 10;
+  const scatter = options.scatter || 5;
+
+  const defColor = "#ff00ff";
+  const getColor = normalize(options.color, defColor);
+
+  const pool: Particle[] = [];
+
+  // Track previous position for interpolation
+  let lx = 0;
+  let ly = 0;
+  let hasMoved = false;
+  let accumulatedDist = 0;
+
+  const activateParticle = (x: number, y: number, color: string) => {
+    const p = pool.find((item) => !item.isActive);
+    if (!p) return;
+
+    p.isActive = true;
+    p.life = 1.0;
+
+    // Spawn with slight scatter around the calculated point
+    p.x = x + math.random(-scatter, scatter);
+    p.y = y + math.random(-scatter, scatter);
+
+    // Pure radial burst
+    const angle = math.random(0, Math.PI * 2);
+    const speed = math.random(0.5, 1.5);
+    p.vx = Math.cos(angle) * speed;
+    p.vy = Math.sin(angle) * speed;
+
+    p.scale = math.random(0.5, 1.2);
+    p.color = color;
+
+    // Apply immediate visual updates
+    const size = math.random(2, 5);
+    dom.setStyle(p.el, "width", `${size}px`);
+    dom.setStyle(p.el, "height", `${size}px`);
+    dom.setStyle(p.el, "backgroundColor", color);
+    dom.setStyle(p.el, "opacity", "1");
+    dom.setTransform(p.el, p.x, p.y, 0, p.scale, p.scale);
+  };
+
+  return definePlugin(
+    {
+      name: options.name || "sparkles",
+
+      install(app) {
+        for (let i = 0; i < poolSize; i++) {
+          const el = dom.createCircle(0, "transparent");
+          dom.applyStyles(el, {
+            zIndex: Layers.TRACE,
+            opacity: "0",
+            willChange: "transform, opacity",
+            transition: "none",
+          });
+          app.container.appendChild(el);
+          pool.push({
+            el,
+            isActive: false,
+            x: 0,
+            y: 0,
+            vx: 0,
+            vy: 0,
+            life: 0,
+            scale: 1,
+            color: "",
+          });
+        }
+      },
+
+      update(app) {
+        const { x: cx, y: cy } = app.state.pointer;
+
+        // --- 1. SPAWN LOGIC (Interpolated) ---
+        if (!hasMoved) {
+          lx = cx;
+          ly = cy;
+          hasMoved = true;
+        }
+
+        const dx = cx - lx;
+        const dy = cy - ly;
+        const dist = Math.hypot(dx, dy);
+
+        accumulatedDist += dist;
+
+        // If we have moved enough to spawn one or more particles
+        if (accumulatedDist > frequency) {
+          const color = getColor(app.state);
+
+          // How many particles fit in this movement?
+          const steps = Math.floor(accumulatedDist / frequency);
+
+          // Interpolate backwards from current position
+          for (let i = 0; i < steps; i++) {
+            const t = i / steps;
+            const spawnX = lx + dx * t;
+            const spawnY = ly + dy * t;
+            activateParticle(spawnX, spawnY, color);
+          }
+
+          accumulatedDist = accumulatedDist % frequency;
+        }
+
+        lx = cx;
+        ly = cy;
+
+        // --- 2. PHYSICS LOOP ---
+        for (let i = 0; i < poolSize; i++) {
+          const p = pool[i];
+          if (!p.isActive) continue;
+
+          p.x += p.vx;
+          p.y += p.vy;
+          p.life -= decayRate;
+
+          if (p.life <= 0) {
+            p.isActive = false;
+            p.el.style.opacity = "0";
+          } else {
+            p.el.style.opacity = String(p.life);
+            const currentScale = p.scale * p.life;
+            dom.setTransform(p.el, p.x, p.y, 0, currentScale, currentScale);
+          }
+        }
+      },
+
+      destroy() {
+        pool.forEach((p) => p.el.remove());
+        pool.length = 0;
+      },
+    },
+    options
+  );
+};

package/src/TextRing.ts

@@ -0,0 +1,156 @@
+import type { ValueOrGetter } from '@supermousejs/core';
+import { definePlugin, normalize, dom, Layers } from '@supermousejs/utils';
+import { getCirclePath, getCircumference, formatLoopText } from '@supermousejs/zoetrope';
+
+export interface TextRingOptions {
+  name?: string;
+  isEnabled?: boolean;
+  text?: ValueOrGetter<string>;
+  radius?: ValueOrGetter<number>;
+  fontSize?: ValueOrGetter<number>;
+  speed?: ValueOrGetter<number>;
+  color?: ValueOrGetter<string>;
+  opacity?: ValueOrGetter<number>;
+  className?: string;
+  spread?: boolean;
+}
+
+let instanceCount = 0;
+
+export const TextRing = (options: TextRingOptions = {}) => {
+  let svg: SVGSVGElement;
+  let pathEl: SVGPathElement;
+  let textPathEl: SVGTextPathElement;
+  let textEl: SVGTextElement;
+  let textNode: Text;
+  
+  const pathId = `supermouse-text-ring-path-${instanceCount++}`;
+
+  const defText = 'SUPERMOUSE • SUPERMOUSE • ';
+  const defRadius = 60;
+  const defFontSize = 12;
+  const defSpeed = 0.5;
+  const className = options.className || '';
+  const spread = options.spread ?? false; 
+
+  const getText = normalize(options.text, defText);
+  const getRadius = normalize(options.radius, defRadius);
+  const getFontSize = normalize(options.fontSize, defFontSize);
+  const getSpeed = normalize(options.speed, defSpeed);
+  const getOpacity = normalize(options.opacity, 1);
+
+  let currentRotation = 0;
+  let lastText = '';
+  let lastRadius = 0;
+  let lastFontSize = 0;
+
+  return definePlugin<HTMLDivElement, TextRingOptions>({
+    name: 'text-ring',
+    selector: '[data-supermouse-text-ring]',
+
+    create: (app) => {
+      const container = dom.createActor('div') as HTMLDivElement;
+      dom.applyStyles(container, {
+        zIndex: Layers.FOLLOWER,
+        transition: 'opacity 0.2s ease',
+        opacity: '1',
+        width: '0px',
+        height: '0px',
+        overflow: 'visible',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      });
+      if (className) {
+        container.classList.add(...className.split(' ').filter(Boolean));
+      }
+
+      svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+      svg.style.overflow = 'visible';
+      svg.style.position = 'absolute';
+      svg.style.left = '0';
+      svg.style.top = '0';
+      
+      pathEl = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+      pathEl.setAttribute('id', pathId);
+      pathEl.setAttribute('fill', 'none');
+      
+      textEl = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+      
+      const fs = getFontSize(app.state);
+      textEl.setAttribute('font-size', `${fs}px`);
+      lastFontSize = fs;
+
+      textEl.setAttribute('fill', 'currentColor');
+      textEl.style.textTransform = 'uppercase';
+      textEl.style.letterSpacing = '2px';
+
+      textPathEl = document.createElementNS('http://www.w3.org/2000/svg', 'textPath');
+      textPathEl.setAttributeNS('http://www.w3.org/1999/xlink', 'xlink:href', `#${pathId}`);
+      textPathEl.setAttribute('href', `#${pathId}`);
+      textPathEl.setAttribute('startOffset', '0%');
+      
+      textNode = document.createTextNode('');
+      
+      textPathEl.appendChild(textNode);
+      textEl.appendChild(textPathEl);
+      svg.appendChild(pathEl);
+      svg.appendChild(textEl);
+      container.appendChild(svg);
+
+      return container;
+    },
+
+    styles: {
+      color: 'color'
+    },
+
+    update: (app, container) => {
+      let text = getText(app.state);
+      const radius = getRadius(app.state);
+      const fontSize = getFontSize(app.state);
+      const speed = getSpeed(app.state);
+      const opacity = getOpacity(app.state);
+
+      // Force update opacity
+      dom.setStyle(container, 'opacity', String(opacity));
+
+      const ia = app.state.interaction;
+      // Prefer specific "textRing" property, fallback to generic "text", then default option
+      if (ia.textRing && typeof ia.textRing === 'string') {
+        text = ia.textRing;
+      } else if (ia.text && typeof ia.text === 'string') {
+        text = ia.text;
+      }
+
+      if (radius !== lastRadius) {
+        pathEl.setAttribute('d', getCirclePath(radius));
+        lastRadius = radius;
+      }
+
+      if (spread) {
+        const circum = getCircumference(radius);
+        textPathEl.setAttribute('textLength', String(circum));
+        textPathEl.setAttribute('lengthAdjust', 'spacing');
+        text = formatLoopText(text, true);
+      } else {
+        textPathEl.removeAttribute('textLength');
+        textPathEl.removeAttribute('lengthAdjust');
+      }
+
+      if (fontSize !== lastFontSize) {
+        textEl.setAttribute('font-size', `${fontSize}px`);
+        lastFontSize = fontSize;
+      }
+
+      if (text !== lastText) {
+        textNode.textContent = text;
+        lastText = text;
+      }
+
+      currentRotation += speed;
+      const { x, y } = app.state.smooth;
+      dom.setTransform(container, x, y, currentRotation);
+    }
+  }, options);
+};

package/src/index.ts

@@ -0,0 +1,5 @@
+
+export * from './SmartIcon';
+export * from './SmartRing';
+export * from './Sparkles';
+export * from './TextRing';

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": [
+    "src"
+  ],
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {
+      "@supermousejs/core": [
+        "../core/src/index.ts"
+      ],
+      "@supermousejs/utils": [
+        "../utils/src/index.ts"
+      ],
+      "@supermousejs/zoetrope": [
+        "../zoetrope/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: 'SupermouseLabs',
+      fileName: (format) => format === 'es' ? 'index.mjs' : 'index.umd.js',
+    },
+    rollupOptions: {
+      external: ['@supermousejs/core', '@supermousejs/utils', '@supermousejs/zoetrope'],
+      output: {
+        globals: {
+          '@supermousejs/core': 'SupermouseCore'
+        , '@supermousejs/utils': 'SupermouseUtils', '@supermousejs/zoetrope': 'SupermouseZoetrope'}
+      }
+    }
+  },
+  plugins: [dts({ rollupTypes: true })]
+});