feat: configurable activation key and click blocking

src/index.ts

@@ -135,6 +135,15 @@ function onMouseDown(e: MouseEvent) {
   overlay.clearHighlight();
 }
 
+function onClick(e: MouseEvent) {
+  if (!keyHeld) return;
+
+  // Block clicks on the underlying page while grabbing
+  e.preventDefault();
+  e.stopPropagation();
+  e.stopImmediatePropagation();
+}
+
 // ── Clipboard ────────────────────────────────────────────────────────
 
 async function copyToClipboard(text: string) {
@@ -200,6 +209,7 @@ function bootstrap() {
   document.addEventListener("keyup", onKeyUp, true);
   document.addEventListener("mousemove", onMouseMove, true);
   document.addEventListener("mousedown", onMouseDown, true);
+  document.addEventListener("click", onClick, true);
   window.addEventListener("blur", onBlur);
 
   // Connect agent bridge if URL provided
@@ -226,6 +236,7 @@ export function destroySolidGrab() {
   document.removeEventListener("keyup", onKeyUp, true);
   document.removeEventListener("mousemove", onMouseMove, true);
   document.removeEventListener("mousedown", onMouseDown, true);
+  document.removeEventListener("click", onClick, true);
   window.removeEventListener("blur", onBlur);
 
   overlay.unmount();
@@ -235,10 +246,13 @@ export function destroySolidGrab() {
 }
 
 // ── Auto-init on import ──────────────────────────────────────────────
-// When imported as a side-effect (`import "solid-grab"`), auto-initialize
-// with defaults. Users who want custom options should use initSolidGrab().
+// Deferred to a microtask so that named importers can call
+// initSolidGrab({ key: ... }) synchronously before the default init.
+// This lets the Vite plugin pass options through the virtual module.
 
-initSolidGrab();
+queueMicrotask(() => {
+  if (!initialized) initSolidGrab();
+});
 
 // ── Expose global API for extensibility (like React Grab) ────────────
 

src/types.ts

@@ -77,6 +77,13 @@ export interface SolidGrabPluginOptions {
    * @default true
    */
   autoImport?: boolean;
+
+  /**
+   * Activation key to hold while hovering to grab elements.
+   * Passed through to the runtime via the virtual module.
+   * @default "Alt"
+   */
+  key?: "Alt" | "Control" | "Meta";
 }
 
 // ── Data attribute names ─────────────────────────────────────────────

src/vite.ts

@@ -180,6 +180,7 @@ export default function solidGrab(
     jsxLocation = true,
     componentLocation = true,
     autoImport = true,
+    key = "Alt",
   } = options;
 
   let projectRoot = "";
@@ -201,7 +202,7 @@ export default function solidGrab(
 
     load(id) {
       if (id === RESOLVED_VIRTUAL_INIT) {
-        return `import "solid-grab";`;
+        return `import { initSolidGrab } from "solid-grab";\ninitSolidGrab({ key: "${key}" });`;
       }
     },
 

tests/vite-plugin.test.ts

@@ -207,6 +207,36 @@ describe("transform", () => {
   });
 });
 
+describe("virtual module (key config)", () => {
+  test("emits initSolidGrab with default Alt key", () => {
+    const plugin = createPlugin();
+    const result = (plugin as any).load("\0virtual:solid-grab-init");
+
+    expect(result).toContain('import { initSolidGrab } from "solid-grab"');
+    expect(result).toContain('initSolidGrab({ key: "Alt" })');
+  });
+
+  test("emits initSolidGrab with Meta key", () => {
+    const plugin = createPlugin({ key: "Meta" });
+    const result = (plugin as any).load("\0virtual:solid-grab-init");
+
+    expect(result).toContain('initSolidGrab({ key: "Meta" })');
+  });
+
+  test("emits initSolidGrab with Control key", () => {
+    const plugin = createPlugin({ key: "Control" });
+    const result = (plugin as any).load("\0virtual:solid-grab-init");
+
+    expect(result).toContain('initSolidGrab({ key: "Control" })');
+  });
+
+  test("returns undefined for non-virtual module ids", () => {
+    const plugin = createPlugin();
+    const result = (plugin as any).load("/project/src/App.tsx");
+    expect(result).toBeUndefined();
+  });
+});
+
 describe("transformIndexHtml", () => {
   test("returns tag descriptors in dev mode", () => {
     const plugin = createPlugin();