@supermousejs/utils 2.3.1 → 2.4.1

package/src/doctor.ts

@@ -1,47 +1,300 @@
-/**
- * A diagnostic utility to find common CSS conflicts that cause cursor glitches.
- */
-export function doctor() {
-  console.group("🐭 Supermouse Doctor");
+export interface DoctorIssue {
+  severity: "error" | "warn" | "info";
+  code: string;
+  message: string;
+  hint?: string;
+}
+
+interface PluginLike {
+  readonly name?: string;
+  readonly priority?: number;
+  readonly element?: HTMLElement;
+  readonly update?: (...args: any[]) => void;
+  readonly [key: string]: unknown;
+}
+
+interface AppLike {
+  readonly plugins?: readonly PluginLike[];
+  readonly options?: Readonly<Record<string, unknown>>;
+  readonly state?: {
+    readonly cursorMode?: "auto" | "custom" | "native" | "both";
+    readonly hasReceivedInput?: boolean;
+  };
+  readonly input?: {
+    readonly isEnabled?: boolean;
+  };
+}
+
+const BRAND = "[supermouse] doctor";
+
+const S = {
+  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;"
+} as const;
+
+export function doctor(app?: any): void {
+  const issues = app ? audit(app) : scanDom();
+  printReport(issues);
+}
+
+function audit(app: any): readonly DoctorIssue[] {
+  const plugins = app.plugins ?? [];
+  const opts = app.options ?? {};
+
+  return [
+    ...checkPluginPriorities(plugins),
+    ...checkStatesPriority(plugins),
+    ...checkGhostElements(plugins),
+    ...checkMultiInstance(opts),
+    ...checkContainerPosition(opts),
+    ...checkCursorMode(opts, app.state),
+    ...scanDom(app)
+  ];
+}
+
+function isVisualPlugin(plugin: PluginLike): boolean {
+  if (plugin.element !== undefined) return true;
+  if (typeof plugin.update === "function" && plugin.update.length >= 3) return true;
+  return false;
+}
+
+function isLogicPlugin(plugin: PluginLike): boolean {
+  if (plugin.element !== undefined) return false;
+  if (typeof plugin.update === "function" && plugin.update.length === 2) return true;
+  return false;
+}
+
+function checkPluginPriorities(plugins: readonly PluginLike[]): readonly DoctorIssue[] {
+  const out: DoctorIssue[] = [];
+
+  for (const p of plugins) {
+    const name = p.name ?? "unknown";
+    const pri = p.priority ?? 0;
+
+    if (isLogicPlugin(p) && pri >= 0) {
+      out.push({
+        severity: "warn",
+        code: "PRIORITY_LOGIC",
+        message: `Plugin "${name}" has priority ${pri} but appears to be a logic plugin (should run before physics).`,
+        hint: `Set priority to a negative value (e.g. -10) on "${name}"`
+      });
+    }
+
+    if (isVisualPlugin(p) && pri < 0) {
+      out.push({
+        severity: "warn",
+        code: "PRIORITY_VISUAL",
+        message: `Plugin "${name}" has priority ${pri} but appears to be a visual plugin (should run after physics).`,
+        hint: "Remove priority or use a positive value"
+      });
+    }
+  }
+
+  return out;
+}
+
+function checkStatesPriority(plugins: readonly PluginLike[]): readonly DoctorIssue[] {
+  const states = plugins.find((p) => p.name === "states");
+  if (!states) return [];
+
+  const pri = states.priority ?? 0;
+  if (pri >= 0) {
+    return [
+      {
+        severity: "error",
+        code: "STATES_PRIORITY",
+        message: `States plugin has priority ${pri}. It must run before all visual plugins.`,
+        hint: "Set priority: -999 on the States plugin"
+      }
+    ];
+  }
+
+  return [];
+}
+
+function checkGhostElements(plugins: readonly PluginLike[]): readonly DoctorIssue[] {
+  const out: DoctorIssue[] = [];
+
+  for (const p of plugins) {
+    const name = p.name ?? "unknown";
+    if (isVisualPlugin(p) && !p.element) {
+      out.push({
+        severity: "warn",
+        code: "MISSING_ELEMENT",
+        message: `Plugin "${name}" has no 'element' property — disablePlugin() will not hide its DOM.`,
+        hint: "Assign plugin.element = el in install(), or use definePlugin()"
+      });
+    }
+  }
+
+  return out;
+}
+
+function checkMultiInstance(opts: Readonly<Record<string, unknown>>): readonly DoctorIssue[] {
+  const scopes = document.querySelectorAll('[class*="supermouse-scope-"]');
+  if (scopes.length <= 1) return [];
+  if (opts.container !== document.body) return [];
+
+  return [
+    {
+      severity: "warn",
+      code: "MULTI_INSTANCE",
+      message: `Detected ${scopes.length} Supermouse instances. The body instance may conflict with scoped ones.`,
+      hint: "Use suspend() / resume() or scope instances to different containers"
+    }
+  ];
+}
+
+function checkContainerPosition(opts: Readonly<Record<string, unknown>>): readonly DoctorIssue[] {
+  const container = opts.container as HTMLElement | undefined;
+  if (!container || container === document.body) return [];
+
+  const position = window.getComputedStyle(container).position;
+  if (position !== "static") return [];
+
+  return [
+    {
+      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 checkCursorMode(
+  opts: Readonly<Record<string, unknown>>,
+  state?: AppLike["state"]
+): readonly DoctorIssue[] {
+  const cursor = opts.cursor;
+  if (cursor === undefined) return [];
+
+  const validModes = ["auto", "custom", "native", "both"];
+  if (typeof cursor === "string" && !validModes.includes(cursor)) {
+    return [
+      {
+        severity: "error",
+        code: "INVALID_CURSOR_MODE",
+        message: `Invalid cursor mode "${cursor}". Expected one of: ${validModes.join(", ")}.`,
+        hint: `Set cursor to one of: ${validModes.join(", ")}`
+      }
+    ];
+  }
+
+  if (cursor === "both" && opts.container !== document.body && state?.cursorMode === "both") {
+    return [
+      {
+        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"
+      }
+    ];
+  }
+
+  return [];
+}
+
+function scanDom(app?: AppLike): readonly DoctorIssue[] {
+  const out: DoctorIssue[] = [];
 
-  const hasInitialized = Array.from(document.querySelectorAll("style")).some((s) =>
+  const isInitialized = Array.from(document.querySelectorAll("style")).some((s) =>
     s.id.startsWith("supermouse-style-")
   );
 
-  if (!hasInitialized) {
-    console.warn("[x] Supermouse has not been initialized yet.");
-    console.warn("   Please call doctor() after `new Supermouse()` has run.");
-    console.groupEnd();
-    return;
+  if (!isInitialized) {
+    return [
+      {
+        severity: "error",
+        code: "NOT_INITIALIZED",
+        message: "Supermouse has not been initialized yet.",
+        hint: "Call doctor() after new Supermouse() has run"
+      }
+    ];
   }
 
-  const issues: { el: Element; reason: string }[] = [];
-
-  const inlineCursor = document.querySelectorAll('[style*="cursor"]');
-  inlineCursor.forEach((el) => {
-    if (el.getAttribute("style")?.includes("cursor: none")) return;
+  document.querySelectorAll('[style*="cursor"]').forEach((el) => {
+    const style = el.getAttribute("style") ?? "";
+    if (style.includes("cursor: none")) return;
+    if (!style.includes("cursor")) return;
 
-    issues.push({
-      el,
-      reason: 'Element has inline "cursor" style. Remove it and let Supermouse handle state.'
+    out.push({
+      severity: "warn",
+      code: "INLINE_CURSOR",
+      message: "Element has an inline cursor style that may override Supermouse.",
+      hint: "Remove inline cursor styles"
     });
   });
 
-  if (document.body.style.cursor !== "none") {
-    console.warn(
-      '[Global] document.body.style.cursor is not "none". Ensure { hideCursor: true } is passed to Supermouse.'
-    );
+  const bodyInstance = document.querySelector(".supermouse-scope-0");
+  if (bodyInstance) {
+    const hasHideClass = bodyInstance.classList.contains("supermouse-hide-0");
+    const cursorMode = app?.state?.cursorMode ?? "auto";
+    const hasReceivedInput = app?.state?.hasReceivedInput ?? true;
+    const inputEnabled = app?.input?.isEnabled ?? true;
+
+    if (cursorMode === "custom" && inputEnabled && hasReceivedInput && !hasHideClass) {
+      out.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 out;
+}
+
+function printReport(issues: readonly DoctorIssue[]): void {
+  if (issues.length === 0) {
+    console.log(`%c${BRAND}%c No issues found`, S.brand, S.dim);
+    return;
   }
 
-  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("[ok] No obvious inline-style conflicts found.");
+  const summary = [
+    formatCount(issues, "error", "error"),
+    formatCount(issues, "warn", "warning"),
+    formatCount(issues, "info", "note")
+  ]
+    .filter((s): s is string => s !== null)
+    .join(" · ");
+
+  console.log(`%c${BRAND}%c ${summary}`, S.brand, S.dim);
+
+  for (const issue of issues) {
+    printIssue(issue);
   }
+}
+
+function formatCount(
+  issues: readonly DoctorIssue[],
+  severity: DoctorIssue["severity"],
+  label: string
+): string | null {
+  const n = issues.filter((i) => i.severity === severity).length;
+  return n > 0 ? `${n} ${label}${n > 1 ? "s" : ""}` : null;
+}
+
+function printIssue(issue: DoctorIssue): void {
+  console.log(
+    `%c${issue.severity.toUpperCase()}%c %c${issue.code}%c ${issue.message}`,
+    S[issue.severity],
+    S.dim,
+    S.code,
+    "color: inherit;"
+  );
 
-  console.groupEnd();
+  if (issue.hint) {
+    console.log(`  %c→%c ${issue.hint}`, S.hint, S.dim);
+  }
 }

package/src/dom.ts

@@ -5,7 +5,7 @@
  * @param id A unique identifier for this style block
  * @param css A string of CSS rules to inject.
  */
-export const injectStyles = (id: string, css: string) => {
+export const injectStyles = (id: string, css: string): void => {
   if (typeof document === "undefined") return;
   if (document.getElementById(id)) return;
 
@@ -15,16 +15,31 @@ export const injectStyles = (id: string, css: string) => {
   document.head.appendChild(style);
 };
 
-// WeakMap to store previous styles for elements to prevent DOM thrashing
-const styleCache = new WeakMap<HTMLElement, Record<string, string | number>>();
+const styleCache = new WeakMap<HTMLElement | SVGElement, Record<string, string | number>>();
+
+type CSSProperties = {
+  [K in keyof CSSStyleDeclaration as CSSStyleDeclaration[K] extends (...args: any) => any
+    ? never
+    : K]?: string | number;
+};
+
+function camelToKebab(str: string): string {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
 
 /**
- * Smart Style Setter (Batch).
- * Only writes to the DOM if the value has actually changed.
- * @param el The element to style
- * @param styles An object of CSS properties and values
+ * Applies CSS properties to an element. Only touches the DOM when a value
+ * has actually changed.
+ *
+ * @example
+ * css(el, {
+ *   width: `${size}px`,
+ *   height: `${size}px`,
+ *   opacity: state.isHover ? 1 : 0,
+ *   backgroundColor: state.interaction.color || "#000",
+ * });
  */
-export function applyStyles(el: HTMLElement, styles: Partial<CSSStyleDeclaration>) {
+export function css(el: HTMLElement | SVGElement, styles: CSSProperties): void {
   if (typeof document === "undefined" || !el) return;
 
   let cache = styleCache.get(el);
@@ -33,28 +48,32 @@ export function applyStyles(el: HTMLElement, styles: Partial<CSSStyleDeclaration
     styleCache.set(el, cache);
   }
 
-  for (const prop in styles) {
-    const value = (styles as any)[prop];
-    if (cache[prop] !== value) {
-      (el.style as any)[prop] = value;
-      cache[prop] = value;
+  for (const [prop, value] of Object.entries(styles)) {
+    if (value === undefined) continue;
+    const stringValue = String(value);
+    const kebabProp = camelToKebab(prop);
+    if (cache[kebabProp] !== stringValue) {
+      el.style.setProperty(kebabProp, stringValue);
+      cache[kebabProp] = stringValue;
     }
   }
 }
 
 /**
- * Smart Style Setter (Single).
- * Proxies to applyStyles for consistency.
- * @param el The element to style
- * @param property The CSS property to set
- * @param value The value to set for the property
+ * @deprecated Use `dom.css()` instead. This function will be removed in future versions.
+ */
+export function setStyle(el: HTMLElement | SVGElement, prop: string, value: string | number): void {
+  css(el, { [prop]: value });
+}
+
+/**
+ * @deprecated Use `dom.css()` instead. This function will be removed in future versions.
  */
-export function setStyle(
-  el: HTMLElement,
-  property: keyof CSSStyleDeclaration,
-  value: string | number
-) {
-  applyStyles(el, { [property]: value } as any);
+export function applyStyles(
+  el: HTMLElement | SVGElement,
+  styles: Record<string, string | number>
+): void {
+  css(el, styles);
 }
 
 /**
@@ -71,7 +90,7 @@ export function setStyle(
  * @param skewY Skew Y (deg) - Default 0
  */
 export function setTransform(
-  el: HTMLElement,
+  el: HTMLElement | SVGElement,
   x: number,
   y: number,
   rotation: number = 0,
@@ -79,16 +98,19 @@ export function setTransform(
   scaleY: number = 1,
   skewX: number = 0,
   skewY: number = 0
-) {
+): void {
   const transform = `translate3d(${x}px, ${y}px, 0) translate(-50%, -50%) rotate(${rotation}deg) skew(${skewX}deg, ${skewY}deg) scale(${scaleX}, ${scaleY})`;
 
-  setStyle(el, "transform", transform);
+  css(el, { transform });
 }
 
 /**
  * Calculates the bounding rectangle of an element relative to a container.
  */
-export function projectRect(element: HTMLElement, container: HTMLElement = document.body): DOMRect {
+export function projectRect(
+  element: HTMLElement | SVGSVGElement,
+  container: HTMLElement | SVGSVGElement = document.body
+): DOMRect {
   const rect = element.getBoundingClientRect();
 
   if (container !== document.body) {
@@ -108,9 +130,9 @@ export function projectRect(element: HTMLElement, container: HTMLElement = docum
  *
  * @param tagName The HTML tag to create (default: 'div')
  */
-export function createActor(tagName: string = "div"): HTMLElement {
+export function createActor(tagName: string = "div"): HTMLElement | SVGSVGElement {
   const el = document.createElement(tagName);
-  applyStyles(el, {
+  css(el, {
     position: "absolute",
     top: "0",
     left: "0",
@@ -127,7 +149,7 @@ export function createActor(tagName: string = "div"): HTMLElement {
  */
 export function createCircle(size: number, color: string): HTMLDivElement {
   const el = createActor("div") as HTMLDivElement;
-  applyStyles(el, {
+  css(el, {
     width: `${size}px`,
     height: `${size}px`,
     borderRadius: "50%",

package/src/index.ts

@@ -1,11 +1,15 @@
-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 { definePlugin } from "./plugin";
-export type { BasePluginOptions } from "./plugin";
-export { normalize } from "./options";
-export * from "./doctor";
+export * from "./math";
+export * from "./dom";
+export * from "./effects";
+export * from "./options";
+export * from "./doctor";
+export * from "./plugin";
+export * from "./svg";
+export * from "./css";
+
+import * as math from "./math";
+import * as dom from "./dom";
+import * as effects from "./effects";
+import * as svg from "./svg";
+
+export { math, dom, effects, svg };

package/src/math.ts

@@ -58,3 +58,7 @@ export function dist(x1: number, y1: number, x2: number = 0, y2: number = 0): nu
 export function angle(x: number, y: number): number {
   return Math.atan2(y, x) * (180 / Math.PI);
 }
+
+export function circumference(r: number): number {
+  return 2 * Math.PI * r;
+}

package/src/options.ts

@@ -1,22 +1,65 @@
-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;
-}
+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
+ * @returns A function that returns the resolved value of the option
+ */
+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;
+}
+
+/**
+ * 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 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] } {
+  const result = {} as { [K in keyof T]: (state: MouseState) => T[K] };
+
+  for (const key of Object.keys(defaults) as Array<keyof T>) {
+    result[key] = normalize(
+      options[key] as ValueOrGetter<T[typeof key]> | undefined,
+      defaults[key]
+    );
+  }
+
+  return result;
+}
+
+/**
+ * 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 const hasFinePointer = (): boolean =>
+  typeof window !== "undefined" && window.matchMedia("(pointer: fine)").matches;