@supermousejs/core 2.3.0 → 2.4.1

package/src/__tests__/integration.spec.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { Supermouse } from "../Supermouse";
+
+describe("Supermouse integration", () => {
+  let app: Supermouse;
+  let container: HTMLElement;
+
+  afterEach(() => {
+    app?.destroy();
+    document.body.innerHTML = "";
+    document.head.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("disable() resets plugin-set cursorMode and restores native cursor", () => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    app = new Supermouse({ container, autoStart: false });
+
+    const smartIconLike = {
+      name: "fake-smart-icon",
+      install(instance: Supermouse) {
+        instance.setCursor("custom");
+      },
+      update() {}
+    };
+    app.use(smartIconLike);
+
+    expect(app.state.cursorMode).toBe("custom");
+
+    window.dispatchEvent(
+      new PointerEvent("pointermove", { clientX: 100, clientY: 100, pointerType: "mouse" })
+    );
+    app.start();
+    app.step(performance.now() + 16);
+
+    expect(app.stage.style.opacity).toBe("1"); // custom cursor visible
+
+    app.disable();
+
+    expect(app.state.cursorMode).toBe("custom");
+    expect(app.stage.style.opacity).toBe("0");
+    expect(container.style.cursor).toBe("");
+
+    app.step(performance.now() + 32);
+    expect(container.style.cursor).toBe("");
+    expect(app.stage.style.opacity).toBe("0");
+  });
+
+  it("disable() also works when plugin registers extra hover targets", () => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    app = new Supermouse({ container, autoStart: false });
+
+    const smartIconLike = {
+      name: "fake-smart-icon-2",
+      install(instance: Supermouse) {
+        instance.setCursor("custom");
+        instance.registerHoverTarget("p, h1, h2, h3, span");
+      },
+      update() {}
+    };
+    app.use(smartIconLike);
+
+    window.dispatchEvent(
+      new PointerEvent("pointermove", { clientX: 50, clientY: 50, pointerType: "mouse" })
+    );
+    app.start();
+    app.step(performance.now() + 16);
+
+    expect(app.state.cursorMode).toBe("custom");
+
+    app.disable();
+
+    expect(app.state.cursorMode).toBe("custom");
+    expect(app.stage.style.opacity).toBe("0");
+    expect(container.style.cursor).toBe("");
+
+    expect(container.classList.contains("supermouse-hide-0")).toBe(false);
+  });
+
+  it("nested instance with cursor 'both' does not inherit global inline cursor:none", () => {
+    // Global instance on body
+    const globalApp = new Supermouse({
+      container: document.body,
+      cursor: "auto",
+      autoStart: false
+    });
+
+    // Create nested preview container
+    const previewContainer = document.createElement("div");
+    document.body.appendChild(previewContainer);
+
+    // Preview instance with cursor 'both'
+    const previewApp = new Supermouse({
+      container: previewContainer,
+      cursor: "both",
+      autoStart: false
+    });
+
+    // Simulate entering preview: suspend global
+    globalApp.suspend();
+
+    // Global body must not have inline cursor:none
+    expect(document.body.style.cursor).toBe("");
+    expect(document.body.classList.contains("supermouse-hide-0")).toBe(false);
+
+    // Preview container must also not have inline cursor:none (its own 'both' mode shouldn't)
+    expect(previewContainer.style.cursor).toBe("");
+
+    // An empty div inside preview should inherit nothing from body
+    const emptyDiv = document.createElement("div");
+    previewContainer.appendChild(emptyDiv);
+    // In real browser, computed cursor would be 'auto', but we can at least check no inline
+    expect(emptyDiv.style.cursor).toBe("");
+
+    globalApp.destroy();
+    previewApp.destroy();
+    previewContainer.remove();
+  });
+});

package/src/__tests__/lifecycle.spec.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect, afterEach, beforeEach, vi } from "vitest";
+import { Supermouse } from "../Supermouse";
+
+describe("Supermouse lifecycle", () => {
+  let app: Supermouse;
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    app?.destroy();
+    document.body.innerHTML = "";
+    document.head.innerHTML = "";
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  function movePointer(x: number, y: number) {
+    window.dispatchEvent(
+      new PointerEvent("pointermove", {
+        clientX: x,
+        clientY: y,
+        pointerType: "mouse",
+        bubbles: true
+      })
+    );
+  }
+
+  const hasClassPrefix = (el: HTMLElement, prefix: string) =>
+    Array.from(el.classList).some((c) => c.startsWith(prefix));
+
+  it("auto-starts the loop when autoStart is true", () => {
+    const startLoopSpy = vi.spyOn(Supermouse.prototype as any, "startLoop");
+    app = new Supermouse({ autoStart: true, container });
+    expect(startLoopSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not auto-start when autoStart is false", () => {
+    const startLoopSpy = vi.spyOn(Supermouse.prototype as any, "startLoop");
+    app = new Supermouse({ autoStart: false, container });
+    expect(startLoopSpy).not.toHaveBeenCalled();
+  });
+
+  it("start() starts the loop and is idempotent", () => {
+    app = new Supermouse({ autoStart: false, container });
+    const rafSpy = vi.spyOn(window, "requestAnimationFrame").mockReturnValue(1);
+    app.start();
+    expect(rafSpy).toHaveBeenCalledTimes(1);
+    app.start();
+    expect(rafSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("disable() disables input, restores native cursor, and resets physics", () => {
+    app = new Supermouse({ autoStart: false, container });
+    movePointer(50, 60);
+    app.start();
+
+    app.disable();
+
+    expect(app.input.isEnabled).toBe(false);
+    expect(container.style.cursor).toBe(""); // original (empty)
+    expect(app.state.target).toEqual({ x: -100, y: -100 });
+    expect(app.state.smooth).toEqual({ x: -100, y: -100 });
+    expect(app.state.velocity).toEqual({ x: 0, y: 0 });
+    expect(app.state.displacement).toEqual({ x: 0, y: 0 });
+    expect(app.state.hasReceivedInput).toBe(false);
+  });
+
+  it("enable() re-enables input, snaps to current pointer, and hides native cursor", () => {
+    app = new Supermouse({ autoStart: false, container });
+    movePointer(200, 250);
+    app.start();
+    app.disable();
+    app.enable();
+
+    expect(app.input.isEnabled).toBe(true);
+    expect(app.state.hasReceivedInput).toBe(true);
+    expect(app.state.target).toEqual({ x: 200, y: 250 });
+    expect(app.state.smooth).toEqual({ x: 200, y: 250 });
+
+    expect(hasClassPrefix(container, "supermouse-hide-")).toBe(true);
+    expect(container.style.cursor).toBe("none");
+  });
+
+  it("suspend() disables input, clears hover, hides stage", () => {
+    app = new Supermouse({ autoStart: false, container });
+    // Simulate hovering an element
+    const link = document.createElement("a");
+    container.appendChild(link);
+    link.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
+    expect(app.state.isHover).toBe(true);
+
+    app.start();
+    app.suspend();
+
+    expect(app.input.isEnabled).toBe(false);
+    expect(app.state.isHover).toBe(false);
+    expect(app.state.hoverTarget).toBeNull();
+    expect(app.state.interaction).toEqual({});
+    expect(app.stage.style.opacity).toBe("0");
+  });
+
+  it("resume() re-enables input, snaps physics, and shows stage", () => {
+    app = new Supermouse({ autoStart: false, container });
+    movePointer(300, 400);
+    app.start();
+    app.suspend();
+
+    const updateSpy = vi.fn();
+    app.use({ name: "test", update: updateSpy });
+    app.resume();
+
+    expect(app.input.isEnabled).toBe(true);
+    expect(app.state.target).toEqual({ x: 300, y: 400 });
+    expect(app.state.smooth).toEqual({ x: 300, y: 400 });
+    expect(app.stage.style.opacity).toBe("1");
+    expect(updateSpy).toHaveBeenCalledWith(app, 0);
+  });
+
+  it("manual step advances physics and updates velocity/displacement", () => {
+    app = new Supermouse({ autoStart: false, container });
+    app.input.isEnabled = true;
+    app.state.hasReceivedInput = true;
+    app.state.pointer = { x: 100, y: 100 };
+    app.state.target = { x: 100, y: 100 };
+    app.state.smooth = { x: 0, y: 0 };
+    app.start();
+
+    const now = performance.now() + 16;
+    app.step(now);
+
+    expect(app.state.smooth.x).toBeGreaterThan(0);
+    expect(app.state.smooth.x).toBeLessThan(100);
+    expect(app.state.velocity.x).not.toBe(0);
+    expect(app.state.displacement.x).toBeCloseTo(100 - app.state.smooth.x);
+    expect(app.state.displacement.y).toBeCloseTo(100 - app.state.smooth.y);
+  });
+
+  it("pauses loop on document hidden and resumes on visible", () => {
+    app = new Supermouse({ autoStart: false, container });
+    const cancelSpy = vi.spyOn(window, "cancelAnimationFrame").mockImplementation(() => {});
+    const rafSpy = vi.spyOn(window, "requestAnimationFrame").mockReturnValue(1);
+    app.start();
+
+    Object.defineProperty(document, "hidden", { value: true, configurable: true });
+    Object.defineProperty(document, "visibilityState", { value: "hidden", configurable: true });
+    document.dispatchEvent(new Event("visibilitychange"));
+
+    expect(cancelSpy).toHaveBeenCalled();
+
+    Object.defineProperty(document, "hidden", { value: false, configurable: true });
+    Object.defineProperty(document, "visibilityState", { value: "visible", configurable: true });
+    document.dispatchEvent(new Event("visibilitychange"));
+
+    expect(rafSpy).toHaveBeenCalledTimes(2); // initial + resume
+  });
+
+  it("destroy() stops loop, removes event listeners, stage, and plugins", () => {
+    const destroyPluginSpy = vi.fn();
+
+    app = new Supermouse({ autoStart: false, container });
+    const stageEl = app.stage;
+    const styleTag = document.querySelector('style[id^="supermouse-style-"]');
+    app.use({ name: "plugin", destroy: destroyPluginSpy });
+
+    app.destroy();
+
+    expect(app.isRunning).toBe(false);
+    expect(document.body.contains(stageEl)).toBe(false);
+    expect(document.head.contains(styleTag)).toBe(false);
+    expect(destroyPluginSpy).toHaveBeenCalled();
+    expect(container.style.cursor).toBe("");
+    expect(container.classList.contains("supermouse-scope")).toBe(false);
+  });
+
+  it("disable() hides the custom cursor stage", () => {
+    app = new Supermouse({ autoStart: false });
+    // Simulate pointer presence
+    window.dispatchEvent(
+      new PointerEvent("pointermove", { clientX: 100, clientY: 100, pointerType: "mouse" })
+    );
+    expect(app.stage.style.opacity).toBe("1");
+
+    app.disable();
+
+    expect(app.stage.style.opacity).toBe("0");
+    expect(container.style.cursor).toBe("");
+  });
+
+  it("disable() preserves cursorMode", () => {
+    app = new Supermouse({ autoStart: false });
+    app.setCursor("custom");
+    app.disable();
+    expect(app.state.cursorMode).toBe("custom");
+  });
+});

package/src/__tests__/nested-instance.spec.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { Supermouse } from "../Supermouse";
+
+describe("Nested instances cursor inheritance", () => {
+  let globalApp: Supermouse;
+  let previewApp: Supermouse;
+  let body: HTMLElement;
+  let previewContainer: HTMLElement;
+
+  afterEach(() => {
+    globalApp?.destroy();
+    previewApp?.destroy();
+    document.body.innerHTML = "";
+    document.head.innerHTML = "";
+  });
+
+  it.fails(
+    "preview container should set inline cursor to auto when in 'both' mode to override inherited none",
+    () => {
+      body = document.body;
+      globalApp = new Supermouse({ container: body, cursor: "auto", autoStart: false });
+
+      // Force global instance to hide native cursor
+      globalApp.setCursor("custom");
+      globalApp.step(performance.now() + 16);
+      expect(body.style.cursor).toBe("none");
+
+      previewContainer = document.createElement("div");
+      body.appendChild(previewContainer);
+
+      previewApp = new Supermouse({
+        container: previewContainer,
+        cursor: "both",
+        autoStart: false
+      });
+      previewApp.step(performance.now() + 16);
+
+      // The preview container should have its own inline cursor set to 'auto'
+      // to override the inherited 'none' from body.
+      expect(previewContainer.style.cursor).toBe("auto");
+    }
+  );
+
+  it.fails("nested both mode should show native cursor", () => {
+    const global = new Supermouse({ container: document.body, cursor: "auto", autoStart: false });
+    global.setCursor("custom");
+    global.step(performance.now() + 16);
+    expect(document.body.style.cursor).toBe("none");
+
+    const preview = document.createElement("div");
+    document.body.appendChild(preview);
+    const local = new Supermouse({ container: preview, cursor: "both", autoStart: false });
+    local.step(performance.now() + 16);
+
+    // The preview container should have inline cursor 'auto', showing native cursor
+    expect(preview.style.cursor).toBe("auto");
+  });
+});

package/src/__tests__/plugin.spec.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { Supermouse } from "../Supermouse";
+
+describe("Supermouse plugin system", () => {
+  let app: Supermouse;
+
+  afterEach(() => {
+    app?.destroy();
+    document.body.innerHTML = "";
+    document.head.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("registers and looks up plugins by name", () => {
+    app = new Supermouse({ autoStart: false });
+    const plugin = { name: "test-plugin", install() {}, update() {} };
+    app.use(plugin);
+    expect(app.getPlugin("test-plugin")).toBe(plugin);
+    expect(app.getPlugin("missing-plugin")).toBeUndefined();
+  });
+
+  it("calls install hook when plugin is added", () => {
+    const install = vi.fn();
+    app = new Supermouse({ autoStart: false });
+    app.use({ name: "plugin", install });
+    expect(install).toHaveBeenCalledWith(app);
+  });
+
+  it("prevents duplicate plugin names and logs warning", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    app = new Supermouse({ autoStart: false });
+    const plugin = { name: "dupe", update() {} };
+    app.use(plugin);
+    app.use(plugin);
+    expect(warn).toHaveBeenCalled();
+    expect(app.plugins?.length).toBe(1); // private, but accessible in test
+  });
+
+  it("sorts plugins by priority (lower runs first)", async () => {
+    app = new Supermouse({ autoStart: false });
+    const order: number[] = [];
+    app.use({
+      name: "low",
+      priority: 10,
+      update: () => order.push(10)
+    });
+    app.use({
+      name: "high",
+      priority: 1,
+      update: () => order.push(1)
+    });
+
+    // Manually step once (simulate a frame)
+    app.start();
+    app.step(performance.now() + 16);
+    app.destroy(); // stop the loop
+
+    expect(order).toEqual([1, 10]);
+  });
+
+  it("enables and disables plugins via methods", () => {
+    app = new Supermouse({ autoStart: false });
+    const onEnable = vi.fn();
+    const onDisable = vi.fn();
+    const plugin = {
+      name: "toggle-plugin",
+      isEnabled: true,
+      onEnable,
+      onDisable,
+      element: document.createElement("div")
+    };
+    app.use(plugin);
+
+    app.disablePlugin("toggle-plugin");
+    expect(plugin.isEnabled).toBe(false);
+    expect(onDisable).toHaveBeenCalledWith(app);
+    expect(plugin.element.style.display).toBe("none");
+
+    app.enablePlugin("toggle-plugin");
+    expect(plugin.isEnabled).toBe(true);
+    expect(onEnable).toHaveBeenCalledWith(app);
+    expect(plugin.element.style.display).toBe("");
+  });
+
+  it("toggles plugin state", () => {
+    app = new Supermouse({ autoStart: false });
+    const plugin = { name: "toggle", isEnabled: true };
+    app.use(plugin);
+    app.togglePlugin("toggle");
+    expect(plugin.isEnabled).toBe(false);
+    app.togglePlugin("toggle");
+    expect(plugin.isEnabled).toBe(true);
+  });
+
+  it("disables and cleans up crashed plugins", () => {
+    app = new Supermouse({ autoStart: false });
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    const plugin = {
+      name: "crasher",
+      isEnabled: true,
+      update: () => {
+        throw new Error("boom");
+      },
+      element: document.createElement("div"),
+      onDisable: vi.fn(),
+      destroy: vi.fn()
+    };
+    app.use(plugin);
+
+    app.start();
+    app.step(performance.now() + 16);
+    app.destroy();
+
+    expect(error).toHaveBeenCalled();
+    expect(plugin.isEnabled).toBe(false);
+    expect(plugin.onDisable).toHaveBeenCalled();
+    expect(plugin.destroy).toHaveBeenCalled();
+  });
+
+  it("calls destroy hooks on all plugins when instance is destroyed", () => {
+    app = new Supermouse({ autoStart: false });
+    const destroy1 = vi.fn();
+    const destroy2 = vi.fn();
+    app.use({ name: "p1", destroy: destroy1 });
+    app.use({ name: "p2", destroy: destroy2 });
+    app.destroy();
+    expect(destroy1).toHaveBeenCalled();
+    expect(destroy2).toHaveBeenCalled();
+  });
+});

package/src/__tests__/setup.ts

@@ -1,7 +1,6 @@
-Object.defineProperty(window, "matchMedia", {
-  writable: true,
-  value: (query: string) => ({
-    matches: false,
+window.matchMedia = (query: string) => {
+  return {
+    matches: query === "(pointer: fine)",
     media: query,
     onchange: null,
     addListener: () => {},
@@ -9,5 +8,14 @@ Object.defineProperty(window, "matchMedia", {
     addEventListener: () => {},
     removeEventListener: () => {},
     dispatchEvent: () => false
-  })
-});
+  } as MediaQueryList;
+};
+
+if (!window.ResizeObserver) {
+  class ResizeObserverMock {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+  window.ResizeObserver = ResizeObserverMock as any;
+}