feat: initial commit for standalone click-to-component tool

2 weeks ago · e340d55f7e
7 changed files with 1156 additions and 0 deletions
--- a/.babelrc.example
+++ b/.babelrc.example
@ -0,0 +1,10 @@
+{
+  "presets": ["next/babel"],
+  "env": {
+    "development": {
+      "plugins": [
+        "./add-data-locator.cjs"
+      ]
+    }
+  }
+}
--- a/README.md
+++ b/README.md
@ -0,0 +1,221 @@
+# ⚡ Click-to-Component
+
+A zero-config, high-precision component inspector and **Click-to-Component** developer tool for Next.js and React applications.
+
+Hover over any UI element on your web page while holding <kbd>Alt</kbd> (or <kbd>Option</kbd>) to highlight component boundaries in real time, and **click to instantly jump to the exact file, line, and column in your IDE** (Antigravity IDE, VS Code, Cursor, WebStorm, Sublime Text, etc.).
+
+---
+
+## ✨ Features
+
+- 🎯 **Direct IDE Jump**: Opens your active IDE and focuses the exact file and cursor position (`file.tsx:line:col`).
+- 🔍 **Live Hover Highlighting**: Holding <kbd>Alt</kbd> outlines the component under your mouse with dynamic bounding box tracking and smooth scroll support.
+- 🔀 **Dual Hierarchy Modes**:
+  - **Outer Component Mode (<kbd>Alt</kbd>)**: Selects the outer component or section container.
+  - **Inner Leaf Mode (<kbd>Alt</kbd> + <kbd>Ctrl</kbd> / <kbd>Cmd</kbd>)**: Drills down directly to the exact innermost child element (e.g. `<svg>`, `<button>`, `<span>`).
+  - **Live Dynamic Toggle**: Press or release <kbd>Ctrl</kbd> while hovering to switch between Outer and Inner mode in real time!
+- 🏷️ **Smart Component Badge**: Displays the JSX tag name (e.g. `<section>`, `<button>`), short relative file path, line number, and active inspection mode pill (`OUTER` / `INNER`).
+- 📱 **Mobile & Tablet Ready**: Floating draggable inspector button with tap-to-inspect on touch devices.
+- 🛡️ **Zero Production Overhead**: Completely disabled, tree-shaken, and stripped out in production builds.
+
+---
+
+## 🏗️ Architecture & How It Works
+
+The system operates across three interconnected layers:
+
+```mermaid
+flowchart TD
+    subgraph BuildTime["1. Build-Time AST Transform"]
+        A[Babel / Compiler] -->|add-data-locator.cjs| B[Injects data-locator attribute on JSX elements]
+    end
+
+    subgraph ClientSide["2. Client Runtime"]
+        B --> C[DevClickToComponent]
+        C -->|Alt + Hover| D[Draws Emerald Bounding Box for Outer Component]
+        C -->|Alt + Ctrl + Hover| E[Draws Cyan Bounding Box for Inner Element]
+        C -->|Alt + Click| F[Sends locator to API]
+    end
+
+    subgraph ServerSide["3. Local Server API"]
+        F -->|POST /api/open-in-ide| G[route.ts]
+        G -->|CLI Command Execution| H[antigravity-ide / code -r -g filepath:line:col]
+        H --> I[IDE Opens & Focuses Line]
+    end
+```
+
+---
+
+## 📁 Repository Structure
+
+```
+click-to-component/
+├── add-data-locator.cjs         # Babel AST plugin to inject data-locator attributes
+├── .babelrc.example             # Babel configuration example
+├── client/
+│   └── dev-click-to-component.tsx  # React Client Component (Inspector UI & Listeners)
+├── server/
+│   └── route.ts                 # Next.js App Router API Route (/api/open-in-ide)
+├── package.json                 # Standalone package metadata
+└── README.md                    # Documentation
+```
+
+---
+
+## 🚀 Quick Setup & Installation
+
+### Step 1: Install Babel Plugin
+
+Copy `add-data-locator.cjs` to your project root.
+
+Create or update `.babelrc` in your project root:
+
+```json
+{
+  "presets": ["next/babel"],
+  "env": {
+    "development": {
+      "plugins": [
+        "./add-data-locator.cjs"
+      ]
+    }
+  }
+}
+```
+
+> **Note**: Scoping the plugin inside `"env": { "development": ... }` guarantees that no `data-locator` attributes will be added to your production builds.
+
+---
+
+### Step 2: Add the Server API Route
+
+Create the file `app/api/open-in-ide/route.ts` and copy `server/route.ts` into it:
+
+```ts
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import os from "os";
+
+export async function POST(req: Request) {
+  if (process.env.NODE_ENV !== "development") {
+    return NextResponse.json(
+      { message: "Not available in production" },
+      { status: 404 }
+    );
+  }
+
+  try {
+    const { locator } = await req.json();
+    if (!locator) {
+      return NextResponse.json({ message: "Locator is required" }, { status: 400 });
+    }
+
+    const isWindows = os.platform() === "win32";
+    const bin = isWindows ? "antigravity-ide.cmd" : "antigravity-ide";
+    const cmd = `${bin} -r -g "${locator}"`;
+
+    return new Promise<Response>((resolve) => {
+      exec(cmd, (error) => {
+        if (error) {
+          const fallbackBin = isWindows ? "code.cmd" : "code";
+          const fallbackCmd = `${fallbackBin} -r -g "${locator}"`;
+
+          exec(fallbackCmd, (fallbackError) => {
+            if (fallbackError) {
+              resolve(
+                NextResponse.json(
+                  { message: "Failed to open file in IDE", error: error.message },
+                  { status: 500 }
+                )
+              );
+            } else {
+              resolve(NextResponse.json({ success: true, via: "code" }));
+            }
+          });
+          return;
+        }
+        resolve(NextResponse.json({ success: true, via: "antigravity" }));
+      });
+    });
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return NextResponse.json(
+      { message: "Internal server error", error: message },
+      { status: 500 }
+    );
+  }
+}
+```
+
+---
+
+### Step 3: Add the Client Component
+
+Copy `client/dev-click-to-component.tsx` to `app/components/dev-click-to-component.tsx` (or `components/dev-click-to-component.tsx`).
+
+Include it in your root layout (`app/layout.tsx`):
+
+```tsx
+import { DevClickToComponent } from "./components/dev-click-to-component";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        {process.env.NODE_ENV === "development" && <DevClickToComponent />}
+      </body>
+    </html>
+  );
+}
+```
+
+---
+
+## 🎮 How to Use
+
+### Desktop Shortcuts
+
+| Shortcut | Mode | Highlight Color | Target |
+| :--- | :--- | :--- | :--- |
+| **<kbd>Alt</kbd> + Hover** | **`OUTER`** | 🟩 Emerald Green (`#2dd9a4`) | Outer Component / Section Container |
+| **<kbd>Alt</kbd> + <kbd>Ctrl</kbd> + Hover** *(or <kbd>Alt</kbd>+<kbd>Cmd</kbd> on Mac)* | **`INNER`** | 🟦 Electric Cyan (`#38bdf8`) | Innermost leaf element under mouse cursor |
+| **<kbd>Alt</kbd> + Click** | **Open** | ⚡ Flash Pulse | Opens the currently highlighted element in your IDE |
+
+### Mobile / Touch Devices
+- A floating draggable button appears on screens $\le 768\text{px}$.
+- Tap the button to toggle **Inspect Mode**.
+- Tap any element on screen to highlight it and open its source code in the IDE.
+
+---
+
+## 💻 Supported IDEs & Protocol Fallbacks
+
+When the local CLI is invoked, the system opens your existing active IDE window using `-r -g <filepath>:<line>:<col>`:
+
+- **Antigravity IDE** (`antigravity-ide -r -g`)
+- **VS Code / VS Code Insiders** (`code -r -g`)
+- **Cursor** (`cursor -r -g`)
+
+If the API route is unreachable (e.g. running inside certain sandboxed iframe environments), the client automatically falls back to browser URL protocol schemes:
+- `antigravity://file/<locator>`
+- `cursor://file/<locator>`
+- `vscode://file/<locator>`
+- `webstorm://open?file=<locator>`
+- `subl://open?url=file://<locator>`
+- `atom://open?url=file://<locator>`
+
+---
+
+## 🛡️ Production Safety & Performance
+
+1. **Compiler Level**: In `NODE_ENV === "production"`, `add-data-locator.cjs` returns early without modifying the AST.
+2. **Bundle Level**: In `app/layout.tsx`, `{process.env.NODE_ENV === "development" && <DevClickToComponent />}` evaluates to `false` during `next build`, allowing bundlers to completely tree-shake the client component out of the production bundle.
+3. **Runtime Level**: Event listeners and rendering are guarded with `process.env.NODE_ENV !== "development"`.
+4. **Security Level**: The `/api/open-in-ide` route returns a `404` in production environments, preventing arbitrary command execution.
+
+---
+
+## 📄 License
+
+MIT
--- a/add-data-locator.cjs
+++ b/add-data-locator.cjs
@ -0,0 +1,40 @@
+module.exports = function addDataLocator({ types: t }) {
+  return {
+    name: "add-data-locator",
+    visitor: {
+      JSXOpeningElement(path, state) {
+        if (process.env.NODE_ENV !== "development") {
+          return;
+        }
+
+        const filePath = state.file.opts.filename;
+
+        if (!filePath || filePath.includes("node_modules")) {
+          return;
+        }
+
+        const attributeExists = path.node.attributes.some(
+          (attribute) =>
+            t.isJSXAttribute(attribute) &&
+            t.isJSXIdentifier(attribute.name) &&
+            attribute.name.name === "data-locator",
+        );
+
+        if (attributeExists) {
+          return;
+        }
+
+        const lineNumber = path.node.loc?.start.line ?? "unknown";
+        const columnNumber = path.node.loc?.start.column ?? "unknown";
+        const locatorValue = `${filePath}:${lineNumber}:${columnNumber}`;
+
+        path.node.attributes.push(
+          t.jsxAttribute(
+            t.jsxIdentifier("data-locator"),
+            t.stringLiteral(locatorValue),
+          ),
+        );
+      },
+    },
+  };
+};
--- a/client/dev-click-to-component.tsx
+++ b/client/dev-click-to-component.tsx
@ -0,0 +1,577 @@
+"use client";
+
+import { useEffect, useState, useRef, useCallback } from "react";
+
+const IDE_SCHEMES = [
+  {
+    matches: ["antigravity"],
+    createUrl: (locator: string) => `antigravity://file/${locator}`,
+  },
+  {
+    matches: ["cursor"],
+    createUrl: (locator: string) => `cursor://file/${locator}`,
+  },
+  {
+    matches: ["vscode", "code"],
+    createUrl: (locator: string) => `vscode://file/${locator}`,
+  },
+  {
+    matches: ["webstorm", "intellij"],
+    createUrl: (locator: string) => `webstorm://open?file=${locator}`,
+  },
+  {
+    matches: ["sublime"],
+    createUrl: (locator: string) => `subl://open?url=file://${locator}`,
+  },
+  {
+    matches: ["atom", "nova"],
+    createUrl: (locator: string) => `atom://open?url=file://${locator}`,
+  },
+] as const;
+
+function parseLocator(locator: string) {
+  const match = locator.match(/^(.*):(\d+|unknown):(\d+|unknown)$/);
+
+  if (!match) {
+    return { filePath: locator, line: null, column: null };
+  }
+
+  const [, filePath, line, column] = match;
+
+  return {
+    filePath,
+    line: line === "unknown" ? null : Number(line),
+    column: column === "unknown" ? null : Number(column),
+  };
+}
+
+function formatLocatorLabel(locator: string) {
+  const { filePath, line } = parseLocator(locator);
+  const parts = filePath.split(/[/\\]/);
+  const shortPath = parts.slice(-2).join("/");
+  const lineInfo = line !== null ? `:${line}` : "";
+  return `${shortPath}${lineInfo}`;
+}
+
+function getHierarchy(startEl: HTMLElement | null): HTMLElement[] {
+  const list: HTMLElement[] = [];
+  let curr: HTMLElement | null = startEl;
+  while (curr && curr !== document.body && curr !== document.documentElement) {
+    if (curr.hasAttribute("data-locator")) {
+      list.push(curr);
+    }
+    curr = curr.parentElement;
+  }
+  return list; // [0: innermost, ..., N-1: outermost]
+}
+
+function selectTargetElement(
+  hierarchy: HTMLElement[],
+  isInnerMode: boolean
+): HTMLElement | null {
+  if (hierarchy.length === 0) return null;
+  if (hierarchy.length === 1) return hierarchy[0];
+
+  if (isInnerMode) {
+    // Inner Mode (Alt + Ctrl): target the deep inner leaf element
+    return hierarchy[0];
+  }
+
+  // Outer Mode (Alt): target the outermost component/section container
+  const nonRootPage = hierarchy.filter((el) => {
+    const loc = el.getAttribute("data-locator") || "";
+    return !loc.includes("app/layout.") && !loc.includes("app/page.");
+  });
+
+  if (nonRootPage.length > 0) {
+    return nonRootPage[nonRootPage.length - 1];
+  }
+
+  return hierarchy[hierarchy.length - 1];
+}
+
+interface HoveredTargetState {
+  rect: DOMRect;
+  locator: string;
+  borderRadius: string;
+  tagName: string;
+  isInner: boolean;
+  hasMultipleLevels: boolean;
+}
+
+export function DevClickToComponent() {
+  const [isInspecting, setIsInspecting] = useState(false);
+  const [isMobile, setIsMobile] = useState(false);
+  const [position, setPosition] = useState<{ x: number; y: number } | null>(null);
+  const [isDragging, setIsDragging] = useState(false);
+  const [hoveredTarget, setHoveredTarget] = useState<HoveredTargetState | null>(null);
+  const [isOpening, setIsOpening] = useState(false);
+
+  const currentElementRef = useRef<HTMLElement | null>(null);
+  const lastPointerPos = useRef<{ x: number; y: number } | null>(null);
+  const dragStart = useRef({ x: 0, y: 0, buttonX: 0, buttonY: 0, hasMoved: false });
+
+  // Detect mobile / small screen size
+  useEffect(() => {
+    const checkSize = () => {
+      setIsMobile(window.innerWidth <= 768);
+    };
+    checkSize();
+    window.addEventListener("resize", checkSize);
+    return () => window.removeEventListener("resize", checkSize);
+  }, []);
+
+  // Keep button in bounds on resize
+  useEffect(() => {
+    const handleResize = () => {
+      if (!isMobile) return;
+      setPosition((prev) => {
+        if (!prev) return null;
+        return {
+          x: Math.max(16, Math.min(window.innerWidth - 66, prev.x)),
+          y: Math.max(16, Math.min(window.innerHeight - 66, prev.y)),
+        };
+      });
+    };
+    window.addEventListener("resize", handleResize);
+    return () => window.removeEventListener("resize", handleResize);
+  }, [isMobile]);
+
+  const openInIde = useCallback(async (locator: string) => {
+    const userAgent = navigator.userAgent.toLowerCase();
+    const { filePath, line, column } = parseLocator(locator);
+    const positionSuffix =
+      line === null ? "" : `:${line}${column === null ? "" : `:${column}`}`;
+    const locatorString = `${filePath}${positionSuffix}`;
+
+    setIsOpening(true);
+    setTimeout(() => setIsOpening(false), 600);
+
+    try {
+      await fetch("/api/open-in-ide", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ locator: locatorString, userAgent }),
+      });
+    } catch (err) {
+      console.error("[DevClickToComponent] Error sending API request:", err);
+
+      // Fallback to URL scheme
+      const ideUrl =
+        IDE_SCHEMES.find(({ matches }) =>
+          matches.some((match) => userAgent.includes(match))
+        )?.createUrl(locatorString) ?? `antigravity://file/${locatorString}`;
+
+      try {
+        window.location.href = ideUrl;
+      } catch {
+        window.open(`file://${filePath}`, "_blank", "noopener,noreferrer");
+      }
+    }
+  }, []);
+
+  // Desktop: Alt (Outer) vs Alt + Ctrl (Inner) inspection & Click handler
+  useEffect(() => {
+    if (process.env.NODE_ENV !== "development") {
+      return;
+    }
+
+    const updateHoverTarget = (el: HTMLElement | null, isInnerMode: boolean) => {
+      const hierarchy = getHierarchy(el);
+      const targetEl = selectTargetElement(hierarchy, isInnerMode);
+
+      if (targetEl) {
+        currentElementRef.current = targetEl;
+        const rect = targetEl.getBoundingClientRect();
+        const computed = window.getComputedStyle(targetEl);
+        setHoveredTarget({
+          rect,
+          locator: targetEl.getAttribute("data-locator") || "",
+          borderRadius: computed.borderRadius,
+          tagName: targetEl.tagName.toLowerCase(),
+          isInner: isInnerMode || hierarchy.length === 1,
+          hasMultipleLevels: hierarchy.length > 1,
+        });
+      } else {
+        currentElementRef.current = null;
+        setHoveredTarget(null);
+      }
+    };
+
+    const handlePointerMove = (e: PointerEvent) => {
+      lastPointerPos.current = { x: e.clientX, y: e.clientY };
+
+      if (e.altKey) {
+        const target = e.target instanceof HTMLElement ? e.target : null;
+        const isInnerMode = Boolean(e.ctrlKey || e.metaKey);
+        updateHoverTarget(target, isInnerMode);
+      } else if (currentElementRef.current) {
+        currentElementRef.current = null;
+        setHoveredTarget(null);
+      }
+    };
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      const isAlt = e.altKey || e.key === "Alt";
+      const isInnerMode = Boolean(
+        e.ctrlKey || e.metaKey || e.key === "Control" || e.key === "Meta"
+      );
+
+      if (isAlt && lastPointerPos.current) {
+        const el = document.elementFromPoint(
+          lastPointerPos.current.x,
+          lastPointerPos.current.y
+        ) as HTMLElement | null;
+        updateHoverTarget(el, isInnerMode);
+      }
+    };
+
+    const handleKeyUp = (e: KeyboardEvent) => {
+      if (e.key === "Alt" || !e.altKey) {
+        currentElementRef.current = null;
+        setHoveredTarget(null);
+      } else if (e.altKey && (e.key === "Control" || e.key === "Meta")) {
+        // Released Ctrl while keeping Alt pressed -> switch back to Outer Mode
+        if (lastPointerPos.current) {
+          const el = document.elementFromPoint(
+            lastPointerPos.current.x,
+            lastPointerPos.current.y
+          ) as HTMLElement | null;
+          updateHoverTarget(el, false);
+        }
+      }
+    };
+
+    const handleWindowBlur = () => {
+      currentElementRef.current = null;
+      setHoveredTarget(null);
+    };
+
+    const handleScrollOrResize = () => {
+      if (currentElementRef.current) {
+        const rect = currentElementRef.current.getBoundingClientRect();
+        const computed = window.getComputedStyle(currentElementRef.current);
+        setHoveredTarget((prev) =>
+          prev
+            ? {
+                ...prev,
+                rect,
+                borderRadius: computed.borderRadius,
+              }
+            : null
+        );
+      }
+    };
+
+    const handleDesktopClick = (event: MouseEvent) => {
+      if (!event.altKey) {
+        return;
+      }
+
+      const target = event.target instanceof HTMLElement ? event.target : null;
+      const isInnerMode = Boolean(event.ctrlKey || event.metaKey);
+      const hierarchy = getHierarchy(target);
+      const targetEl = selectTargetElement(hierarchy, isInnerMode);
+      const locator = targetEl?.getAttribute("data-locator");
+
+      if (!locator) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+
+      openInIde(locator);
+    };
+
+    window.addEventListener("pointermove", handlePointerMove, true);
+    window.addEventListener("keydown", handleKeyDown, true);
+    window.addEventListener("keyup", handleKeyUp, true);
+    window.addEventListener("blur", handleWindowBlur);
+    document.addEventListener("mouseleave", handleWindowBlur);
+    window.addEventListener("scroll", handleScrollOrResize, true);
+    window.addEventListener("resize", handleScrollOrResize, true);
+    document.addEventListener("click", handleDesktopClick, true);
+
+    return () => {
+      window.removeEventListener("pointermove", handlePointerMove, true);
+      window.removeEventListener("keydown", handleKeyDown, true);
+      window.removeEventListener("keyup", handleKeyUp, true);
+      window.removeEventListener("blur", handleWindowBlur);
+      document.removeEventListener("mouseleave", handleWindowBlur);
+      window.removeEventListener("scroll", handleScrollOrResize, true);
+      window.removeEventListener("resize", handleScrollOrResize, true);
+      document.removeEventListener("click", handleDesktopClick, true);
+    };
+  }, [openInIde]);
+
+  // Mobile: Inspect Mode click interception
+  useEffect(() => {
+    if (process.env.NODE_ENV !== "development" || !isMobile || !isInspecting) return;
+
+    const handleInspectClick = async (event: MouseEvent) => {
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+
+      // Ignore clicks on the inspect button itself
+      if (target.closest(".dev-inspect-btn")) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+
+      const element = target.closest<HTMLElement>("[data-locator]");
+      const locator = element?.getAttribute("data-locator");
+
+      if (locator && element) {
+        console.log(`[DevClickToComponent] Inspect Mode matched element. Opening in IDE:`, locator);
+
+        // Flash target element outline briefly as visual feedback
+        const originalOutline = element.style.outline;
+        element.style.outline = "3px solid #2dd9a4";
+        setTimeout(() => {
+          element.style.outline = originalOutline;
+        }, 400);
+
+        openInIde(locator);
+      }
+
+      setIsInspecting(false);
+    };
+
+    document.addEventListener("click", handleInspectClick, true);
+
+    return () => {
+      document.removeEventListener("click", handleInspectClick, true);
+    };
+  }, [isMobile, isInspecting, openInIde]);
+
+  // Dragging event handlers for mobile floating button
+  const handlePointerDown = (e: React.PointerEvent<HTMLButtonElement>) => {
+    e.currentTarget.setPointerCapture(e.pointerId);
+    setIsDragging(true);
+    const startX = position?.x ?? window.innerWidth - 66;
+    const startY = position?.y ?? window.innerHeight - 66;
+    dragStart.current = {
+      x: e.clientX,
+      y: e.clientY,
+      buttonX: startX,
+      buttonY: startY,
+      hasMoved: false,
+    };
+  };
+
+  const handlePointerMoveButton = (e: React.PointerEvent<HTMLButtonElement>) => {
+    if (!isDragging) return;
+    const dx = e.clientX - dragStart.current.x;
+    const dy = e.clientY - dragStart.current.y;
+
+    if (Math.abs(dx) > 5 || Math.abs(dy) > 5) {
+      dragStart.current.hasMoved = true;
+    }
+
+    const newX = Math.max(16, Math.min(window.innerWidth - 66, dragStart.current.buttonX + dx));
+    const newY = Math.max(16, Math.min(window.innerHeight - 66, dragStart.current.buttonY + dy));
+
+    setPosition({ x: newX, y: newY });
+  };
+
+  const handlePointerUpButton = (e: React.PointerEvent<HTMLButtonElement>) => {
+    if (!isDragging) return;
+    e.currentTarget.releasePointerCapture(e.pointerId);
+    setIsDragging(false);
+  };
+
+  const handleToggleInspect = () => {
+    if (!dragStart.current.hasMoved) {
+      setIsInspecting(!isInspecting);
+    }
+  };
+
+  // Color scheme: Emerald (#2dd9a4) for Outer, Cyan (#38bdf8) for Inner
+  const accentColor = hoveredTarget?.isInner ? "#38bdf8" : "#2dd9a4";
+  const accentBg = hoveredTarget?.isInner
+    ? "rgba(56, 189, 248, 0.08)"
+    : "rgba(45, 217, 164, 0.08)";
+  const accentShadow = hoveredTarget?.isInner
+    ? "0 0 14px rgba(56, 189, 248, 0.5), inset 0 0 6px rgba(56, 189, 248, 0.2)"
+    : "0 0 14px rgba(45, 217, 164, 0.45), inset 0 0 6px rgba(45, 217, 164, 0.15)";
+
+  if (process.env.NODE_ENV !== "development") {
+    return null;
+  }
+
+  return (
+    <>
+      {/* Alt (Outer) / Alt + Ctrl (Inner) Highlight Overlay Box */}
+      {hoveredTarget && (
+        <div
+          style={{
+            position: "fixed",
+            top: `${hoveredTarget.rect.top}px`,
+            left: `${hoveredTarget.rect.left}px`,
+            width: `${hoveredTarget.rect.width}px`,
+            height: `${hoveredTarget.rect.height}px`,
+            borderRadius: hoveredTarget.borderRadius || "4px",
+            border: isOpening ? "2px solid #ffffff" : `2px solid ${accentColor}`,
+            backgroundColor: isOpening ? "rgba(255, 255, 255, 0.2)" : accentBg,
+            boxShadow: isOpening
+              ? `0 0 22px ${accentColor}, inset 0 0 12px ${accentColor}`
+              : accentShadow,
+            pointerEvents: "none",
+            zIndex: 999999,
+            transition:
+              "top 0.06s ease-out, left 0.06s ease-out, width 0.06s ease-out, height 0.06s ease-out, border 0.15s, background-color 0.15s, box-shadow 0.15s",
+          }}
+        >
+          {/* Component Info Tag */}
+          <div
+            style={{
+              position: "absolute",
+              top: hoveredTarget.rect.top < 30 ? "6px" : "-28px",
+              left: Math.max(0, -hoveredTarget.rect.left),
+              display: "inline-flex",
+              alignItems: "center",
+              gap: "6px",
+              backgroundColor: "#020d09",
+              color: accentColor,
+              fontSize: "11px",
+              fontWeight: 600,
+              fontFamily:
+                "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
+              padding: "3px 8px",
+              borderRadius: "5px",
+              whiteSpace: "nowrap",
+              boxShadow: "0 4px 14px rgba(0,0,0,0.6)",
+              border: `1px solid ${accentColor}66`,
+              pointerEvents: "none",
+            }}
+          >
+            {/* Outer / Inner Mode Pill */}
+            <span
+              style={{
+                backgroundColor: hoveredTarget.isInner
+                  ? "rgba(56, 189, 248, 0.25)"
+                  : "rgba(45, 217, 164, 0.2)",
+                color: accentColor,
+                padding: "1px 5px",
+                borderRadius: "3px",
+                fontSize: "10px",
+                fontWeight: 700,
+                letterSpacing: "0.03em",
+              }}
+            >
+              {hoveredTarget.isInner ? "INNER" : "OUTER"}
+            </span>
+
+            <span style={{ color: "#ffffff", opacity: 0.65 }}>
+              &lt;{hoveredTarget.tagName}&gt;
+            </span>
+            <span>{formatLocatorLabel(hoveredTarget.locator)}</span>
+
+            <span
+              style={{
+                color: "#ffffff",
+                opacity: 0.5,
+                fontSize: "10px",
+                fontWeight: 400,
+              }}
+            >
+              {isOpening
+                ? "⚡ Opening IDE..."
+                : hoveredTarget.hasMultipleLevels
+                ? hoveredTarget.isInner
+                  ? "⌥+Click | Release Ctrl for Outer"
+                  : "⌥+Click | Hold Ctrl for Inner"
+                : "⌥+Click to open"}
+            </span>
+          </div>
+        </div>
+      )}
+
+      {/* Floating Action Draggable Button (Inspect Mode for Mobile/Tablet) */}
+      {isMobile && (
+        <div
+          style={{
+            position: "fixed",
+            left: position ? `${position.x}px` : "auto",
+            top: position ? `${position.y}px` : "auto",
+            bottom: position ? "auto" : "16px",
+            right: position ? "auto" : "16px",
+            display: "flex",
+            flexDirection: "column",
+            gap: "10px",
+            zIndex: 99998,
+            touchAction: "none",
+          }}
+        >
+          <button
+            className="dev-inspect-btn"
+            onPointerDown={handlePointerDown}
+            onPointerMove={handlePointerMoveButton}
+            onPointerUp={handlePointerUpButton}
+            onClick={handleToggleInspect}
+            style={{
+              width: "50px",
+              height: "50px",
+              borderRadius: "25px",
+              backgroundColor: isInspecting ? "#2dd9a4" : "#020d09",
+              color: isInspecting ? "#020d09" : "#ffffff",
+              border: isInspecting
+                ? "2px solid #2dd9a4"
+                : "1px solid rgba(255,255,255,0.15)",
+              boxShadow: isInspecting
+                ? "0 0 16px rgba(45, 217, 164, 0.7)"
+                : "0 4px 14px rgba(0,0,0,0.4)",
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              cursor: isDragging ? "grabbing" : "pointer",
+              transition: isDragging
+                ? "none"
+                : "background-color 0.25s, transform 0.25s, box-shadow 0.25s",
+              outline: "none",
+              transform: isInspecting ? "scale(1.1)" : "scale(1)",
+            }}
+            title="Toggle Dev Inspect Mode (Drag to move, tap to activate)"
+          >
+            {isInspecting ? (
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                fill="none"
+                viewBox="0 0 24 24"
+                strokeWidth={2.5}
+                stroke="currentColor"
+                style={{ width: "22px", height: "22px", pointerEvents: "none" }}
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  d="M6 18 18 6M6 6l12 12"
+                />
+              </svg>
+            ) : (
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                fill="none"
+                viewBox="0 0 24 24"
+                strokeWidth={2}
+                stroke="currentColor"
+                style={{ width: "22px", height: "22px", pointerEvents: "none" }}
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  d="m15.75 15.75-2.489-2.489m0 0a3.375 3.375 0 1 0-4.773-4.773 3.375 3.375 0 0 0 4.774 4.774ZM21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z"
+                />
+              </svg>
+            )}
+          </button>
+        </div>
+      )}
+    </>
+  );
+}
+
+export default DevClickToComponent;
--- a/package.json
+++ b/package.json
@ -0,0 +1,20 @@
+{
+  "name": "click-to-component",
+  "version": "1.0.0",
+  "description": "Seamless click-to-component and hover inspector for Next.js & React to open source code directly in your IDE.",
+  "main": "client/dev-click-to-component.tsx",
+  "keywords": [
+    "click-to-component",
+    "react",
+    "nextjs",
+    "inspector",
+    "devtools",
+    "developer-experience",
+    "ide",
+    "antigravity",
+    "vscode",
+    "cursor"
+  ],
+  "author": "",
+  "license": "MIT"
+}
--- a/read.md
+++ b/read.md
@ -0,0 +1,221 @@
+# ⚡ Click-to-Component
+
+A zero-config, high-precision component inspector and **Click-to-Component** developer tool for Next.js and React applications.
+
+Hover over any UI element on your web page while holding <kbd>Alt</kbd> (or <kbd>Option</kbd>) to highlight component boundaries in real time, and **click to instantly jump to the exact file, line, and column in your IDE** (Antigravity IDE, VS Code, Cursor, WebStorm, Sublime Text, etc.).
+
+---
+
+## ✨ Features
+
+- 🎯 **Direct IDE Jump**: Opens your active IDE and focuses the exact file and cursor position (`file.tsx:line:col`).
+- 🔍 **Live Hover Highlighting**: Holding <kbd>Alt</kbd> outlines the component under your mouse with dynamic bounding box tracking and smooth scroll support.
+- 🔀 **Dual Hierarchy Modes**:
+  - **Outer Component Mode (<kbd>Alt</kbd>)**: Selects the outer component or section container.
+  - **Inner Leaf Mode (<kbd>Alt</kbd> + <kbd>Ctrl</kbd> / <kbd>Cmd</kbd>)**: Drills down directly to the exact innermost child element (e.g. `<svg>`, `<button>`, `<span>`).
+  - **Live Dynamic Toggle**: Press or release <kbd>Ctrl</kbd> while hovering to switch between Outer and Inner mode in real time!
+- 🏷️ **Smart Component Badge**: Displays the JSX tag name (e.g. `<section>`, `<button>`), short relative file path, line number, and active inspection mode pill (`OUTER` / `INNER`).
+- 📱 **Mobile & Tablet Ready**: Floating draggable inspector button with tap-to-inspect on touch devices.
+- 🛡️ **Zero Production Overhead**: Completely disabled, tree-shaken, and stripped out in production builds.
+
+---
+
+## 🏗️ Architecture & How It Works
+
+The system operates across three interconnected layers:
+
+```mermaid
+flowchart TD
+    subgraph BuildTime["1. Build-Time AST Transform"]
+        A[Babel / Compiler] -->|add-data-locator.cjs| B[Injects data-locator attribute on JSX elements]
+    end
+
+    subgraph ClientSide["2. Client Runtime"]
+        B --> C[DevClickToComponent]
+        C -->|Alt + Hover| D[Draws Emerald Bounding Box for Outer Component]
+        C -->|Alt + Ctrl + Hover| E[Draws Cyan Bounding Box for Inner Element]
+        C -->|Alt + Click| F[Sends locator to API]
+    end
+
+    subgraph ServerSide["3. Local Server API"]
+        F -->|POST /api/open-in-ide| G[route.ts]
+        G -->|CLI Command Execution| H[antigravity-ide / code -r -g filepath:line:col]
+        H --> I[IDE Opens & Focuses Line]
+    end
+```
+
+---
+
+## 📁 Repository Structure
+
+```
+click-to-component/
+├── add-data-locator.cjs         # Babel AST plugin to inject data-locator attributes
+├── .babelrc.example             # Babel configuration example
+├── client/
+│   └── dev-click-to-component.tsx  # React Client Component (Inspector UI & Listeners)
+├── server/
+│   └── route.ts                 # Next.js App Router API Route (/api/open-in-ide)
+├── package.json                 # Standalone package metadata
+└── README.md                    # Documentation
+```
+
+---
+
+## 🚀 Quick Setup & Installation
+
+### Step 1: Install Babel Plugin
+
+Copy `add-data-locator.cjs` to your project root.
+
+Create or update `.babelrc` in your project root:
+
+```json
+{
+  "presets": ["next/babel"],
+  "env": {
+    "development": {
+      "plugins": [
+        "./add-data-locator.cjs"
+      ]
+    }
+  }
+}
+```
+
+> **Note**: Scoping the plugin inside `"env": { "development": ... }` guarantees that no `data-locator` attributes will be added to your production builds.
+
+---
+
+### Step 2: Add the Server API Route
+
+Create the file `app/api/open-in-ide/route.ts` and copy `server/route.ts` into it:
+
+```ts
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import os from "os";
+
+export async function POST(req: Request) {
+  if (process.env.NODE_ENV !== "development") {
+    return NextResponse.json(
+      { message: "Not available in production" },
+      { status: 404 }
+    );
+  }
+
+  try {
+    const { locator } = await req.json();
+    if (!locator) {
+      return NextResponse.json({ message: "Locator is required" }, { status: 400 });
+    }
+
+    const isWindows = os.platform() === "win32";
+    const bin = isWindows ? "antigravity-ide.cmd" : "antigravity-ide";
+    const cmd = `${bin} -r -g "${locator}"`;
+
+    return new Promise<Response>((resolve) => {
+      exec(cmd, (error) => {
+        if (error) {
+          const fallbackBin = isWindows ? "code.cmd" : "code";
+          const fallbackCmd = `${fallbackBin} -r -g "${locator}"`;
+
+          exec(fallbackCmd, (fallbackError) => {
+            if (fallbackError) {
+              resolve(
+                NextResponse.json(
+                  { message: "Failed to open file in IDE", error: error.message },
+                  { status: 500 }
+                )
+              );
+            } else {
+              resolve(NextResponse.json({ success: true, via: "code" }));
+            }
+          });
+          return;
+        }
+        resolve(NextResponse.json({ success: true, via: "antigravity" }));
+      });
+    });
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return NextResponse.json(
+      { message: "Internal server error", error: message },
+      { status: 500 }
+    );
+  }
+}
+```
+
+---
+
+### Step 3: Add the Client Component
+
+Copy `client/dev-click-to-component.tsx` to `app/components/dev-click-to-component.tsx` (or `components/dev-click-to-component.tsx`).
+
+Include it in your root layout (`app/layout.tsx`):
+
+```tsx
+import { DevClickToComponent } from "./components/dev-click-to-component";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        {process.env.NODE_ENV === "development" && <DevClickToComponent />}
+      </body>
+    </html>
+  );
+}
+```
+
+---
+
+## 🎮 How to Use
+
+### Desktop Shortcuts
+
+| Shortcut | Mode | Highlight Color | Target |
+| :--- | :--- | :--- | :--- |
+| **<kbd>Alt</kbd> + Hover** | **`OUTER`** | 🟩 Emerald Green (`#2dd9a4`) | Outer Component / Section Container |
+| **<kbd>Alt</kbd> + <kbd>Ctrl</kbd> + Hover** *(or <kbd>Alt</kbd>+<kbd>Cmd</kbd> on Mac)* | **`INNER`** | 🟦 Electric Cyan (`#38bdf8`) | Innermost leaf element under mouse cursor |
+| **<kbd>Alt</kbd> + Click** | **Open** | ⚡ Flash Pulse | Opens the currently highlighted element in your IDE |
+
+### Mobile / Touch Devices
+- A floating draggable button appears on screens $\le 768\text{px}$.
+- Tap the button to toggle **Inspect Mode**.
+- Tap any element on screen to highlight it and open its source code in the IDE.
+
+---
+
+## 💻 Supported IDEs & Protocol Fallbacks
+
+When the local CLI is invoked, the system opens your existing active IDE window using `-r -g <filepath>:<line>:<col>`:
+
+- **Antigravity IDE** (`antigravity-ide -r -g`)
+- **VS Code / VS Code Insiders** (`code -r -g`)
+- **Cursor** (`cursor -r -g`)
+
+If the API route is unreachable (e.g. running inside certain sandboxed iframe environments), the client automatically falls back to browser URL protocol schemes:
+- `antigravity://file/<locator>`
+- `cursor://file/<locator>`
+- `vscode://file/<locator>`
+- `webstorm://open?file=<locator>`
+- `subl://open?url=file://<locator>`
+- `atom://open?url=file://<locator>`
+
+---
+
+## 🛡️ Production Safety & Performance
+
+1. **Compiler Level**: In `NODE_ENV === "production"`, `add-data-locator.cjs` returns early without modifying the AST.
+2. **Bundle Level**: In `app/layout.tsx`, `{process.env.NODE_ENV === "development" && <DevClickToComponent />}` evaluates to `false` during `next build`, allowing bundlers to completely tree-shake the client component out of the production bundle.
+3. **Runtime Level**: Event listeners and rendering are guarded with `process.env.NODE_ENV !== "development"`.
+4. **Security Level**: The `/api/open-in-ide` route returns a `404` in production environments, preventing arbitrary command execution.
+
+---
+
+## 📄 License
+
+MIT
--- a/server/route.ts
+++ b/server/route.ts
@ -0,0 +1,67 @@
+import { NextResponse } from "next/server";
+import { exec } from "child_process";
+import os from "os";
+
+export async function POST(req: Request) {
+  // Never run in production
+  if (process.env.NODE_ENV !== "development") {
+    return NextResponse.json(
+      { message: "Not available in production" },
+      { status: 404 }
+    );
+  }
+
+  try {
+    const { locator } = await req.json();
+
+    if (!locator) {
+      return NextResponse.json(
+        { message: "Locator is required" },
+        { status: 400 }
+      );
+    }
+
+    const isWindows = os.platform() === "win32";
+    const bin = isWindows ? "antigravity-ide.cmd" : "antigravity-ide";
+    const cmd = `${bin} -r -g "${locator}"`;
+
+    return new Promise<Response>((resolve) => {
+      exec(cmd, (error) => {
+        if (error) {
+          // If primary IDE launcher isn't available, try fallback to code/cursor
+          const fallbackBin = isWindows ? "code.cmd" : "code";
+          const fallbackCmd = `${fallbackBin} -r -g "${locator}"`;
+
+          exec(fallbackCmd, (fallbackError) => {
+            if (fallbackError) {
+              console.error(
+                `[open-in-ide] Error opening file: ${error.message} / Fallback error: ${fallbackError.message}`
+              );
+              resolve(
+                NextResponse.json(
+                  {
+                    message: "Failed to open file in IDE",
+                    error: error.message,
+                  },
+                  { status: 500 }
+                )
+              );
+            } else {
+              resolve(NextResponse.json({ success: true, via: "code" }));
+            }
+          });
+          return;
+        }
+
+        resolve(NextResponse.json({ success: true, via: "antigravity" }));
+      });
+    });
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error("[open-in-ide] Handler error:", err);
+    return NextResponse.json(
+      { message: "Internal server error", error: message },
+      { status: 500 }
+    );
+  }
+}