@zargaryanvh/react-component-inspector 1.0.3 → 1.0.4

package/README.md

@@ -23,13 +23,19 @@ When working with AI assistants to fix or modify frontend code, you often need t
 
 ### The Solution
 React Component Inspector provides:
-- **One-click component identification** - Just hold CTRL and hover
+- **One-click component identification** - Hold CTRL and hover over any element
+- **Margin, padding & gap inspection** - Hold CTRL+ALT to see spacing (margin, padding, flex/grid gap) and copy it for Cursor
 - **Rich metadata extraction** - Component name, props, file path, usage context
-- **AI-optimized format** - Copy-paste ready metadata for AI assistants
+- **AI-optimized format** - Copy-paste ready metadata for AI assistants (Component, Margin, Padding, Gap)
+- **How to find in code** - Tooltip shows DOM path, target element, and step-by-step how to find and modify in Cursor
 - **Zero production overhead** - Completely disabled in production builds
 
 ## 📊 What Data Does It Provide?
 
+When you hold **CTRL** and hover over an element, a tooltip appears showing component metadata, copy buttons (Component / Margin / Padding / Gap), and the "How to find in code" section:
+
+![Inspector tooltip showing component data, copy buttons, and how to find in code](docs/screenshots/tooltip-preview.png)
+
 When you inspect a component, you get:
 
 ### Element Identification
@@ -50,27 +56,44 @@ When you inspect a component, you get:
 - Props signature (key props affecting behavior)
 - Source file path
 
-### Example Output
+### Example Output (Copy Component)
 ```
+=== TYPE: COMPONENT ===
+
 === ELEMENT IDENTIFICATION ===
 Element Type: button
 Element Text/Label: "Save Transaction"
-Element ID: save-button
-Element Classes: MuiButton-root, primary-button
-CSS Selector: button#save-button
-Position: (450, 320)
-Size: 120x36px
+...
+DOM Path: body > div#root > div.MuiBox-root > button.MuiButton-root
+Parent: div.MuiBox-root
+Role in tree: leaf element; parent: div.MuiBox-root
+
+=== TARGET (use this to instruct Cursor) ===
+TARGET: The SaveButton with class MuiButton-root - position (450, 320), size 120x36px. It is the element in the DOM path above, NOT a child.
+
+=== HOW TO FIND AND MODIFY THIS COMPONENT IN CODE ===
+1. Use the DOM Path to locate the correct element...
+2. Open src/components/buttons/SaveButton.tsx and find the component...
+3. Modify the component's props, sx, or styles as needed.
 
 === COMPONENT METADATA ===
-Component Name: SaveButton
-Component ID: save-button-0
-Variant: primary
-Usage Path: ActivityPage > EditTransactionModal > TransactionForm
-Instance: 0
-Props: variant=primary, disabled=false
-Source File: src/components/buttons/SaveButton.tsx
+...
 ```
 
+When you copy **Margin**, **Padding**, or **Gap**, you get the same structure with current values and instructions for changing that spacing in code (e.g. `sx={{ m: 1 }}`, `sx={{ p: 0.5 }}`, `sx={{ gap: 1 }}`).
+
+## 🔎 How to Find and Modify in Cursor
+
+The tooltip shows a **“How to find in code”** section (same on desktop and mobile):
+
+- **DOM Path** – Full path from `body` to the element (e.g. `body > div#root > div.MuiBox-root > main.MuiBox-root > …`)
+- **Parent** – Direct parent selector
+- **Role in tree** – e.g. “has 3 child element(s); parent: div.MuiStack-root”
+- **TARGET** – One-line description for Cursor: “The Card with class MuiPaper-root – the element with margin 0px 0px 16px 0px. It is the PARENT in the DOM path above, NOT a child.”
+- **Steps** – Numbered steps: use DOM path, open source file, then how to change (margin, padding, gap, or component)
+
+When you click **Copy Component**, **Copy Margin**, **Copy Padding**, or **Copy Gap**, the clipboard gets the full block (element identification, DOM path, TARGET, and “How to find and modify in code”). Paste that into Cursor and ask it to change the component, margin, padding, or gap; the text is written so Cursor can locate the right element and apply the change.
+
 ## 🚀 How to Use This Data for AI-Powered Frontend Optimization
 
 ### 1. **Precise Component Targeting**
@@ -208,12 +231,33 @@ function MyComponent({ variant, children }) {
 
 ## 🎮 Usage
 
-1. **Activate**: Hold the `CTRL` key (or `Cmd` on Mac)
-2. **Inspect**: Hover over any component with inspection metadata
-3. **View**: A tooltip appears showing component metadata
-4. **Lock**: Press `CTRL+H` to lock the tooltip position
-5. **Copy**: Click the copy icon to copy metadata to clipboard
-6. **Deactivate**: Release `CTRL` to exit inspection mode
+### Keyboard shortcuts (desktop)
+
+| Shortcut | Action |
+|----------|--------|
+| **Hold CTRL** | Enter inspection mode. Hover to inspect component (box/element). |
+| **Release CTRL** | Exit inspection mode and clear tooltip. |
+| **Hold CTRL+ALT** | Enter margin/padding mode. See orange (margin), green (padding), purple (gap). |
+| **CTRL+H** | Lock tooltip position so you can click copy buttons. |
+| **CTRL+Shift+R** | Hard refresh (browser default; not captured by the inspector). |
+
+### Basic flow
+
+1. **Activate**: Hold `CTRL` (or `Cmd` on Mac)
+2. **Inspect**: Hover over any element — tooltip shows component metadata and **How to find in code**
+3. **Copy**: Use the copy icon (component) or **Margin** / **Padding** / **Gap** buttons to copy metadata to clipboard
+4. **Lock** (optional): Press `CTRL+H` to lock the tooltip so it doesn’t follow the cursor
+5. **Deactivate**: Release `CTRL` to exit inspection mode
+
+### Margin, padding & gap inspection
+
+- **Hold CTRL+ALT** (while holding CTRL) to enter margin/padding mode. Overlays show:
+  - **Orange** = margin (outside the element)
+  - **Green** = padding (inside the element)
+  - **Purple dashed** = parent’s flex/grid gap (when the parent has `gap`)
+- If the current element has no margin, **dashed orange** outlines show ancestors that have margin; **click an outline** to inspect that ancestor.
+- Use the **Margin**, **Padding**, or **Gap** copy buttons in the tooltip to copy Cursor-ready text for that spacing.
+- The tooltip always shows **DOM Path**, **Parent**, **Role in tree**, **TARGET**, and **How to find** steps so you (and Cursor) know exactly which element to change.
 
 ## 🛡️ Safety Features
 
@@ -231,15 +275,18 @@ function MyComponent({ variant, children }) {
 
 ## 🎨 Features
 
-- ✅ Visual component highlighting
+- ✅ Visual component highlighting (box/element outline)
+- ✅ **Margin, padding & gap inspection** (hold CTRL+ALT) with orange/green/purple overlays
+- ✅ **Ancestor margin detection** – when the element has no margin, dashed outlines show ancestors with margin; click to inspect
+- ✅ **Copy Component / Margin / Padding / Gap** – Cursor-ready text with DOM path, TARGET, and how to find in code
+- ✅ **“How to find in code” in tooltip** – DOM path, parent, role in tree, TARGET, and numbered steps (desktop & mobile)
 - ✅ Rich metadata extraction
-- ✅ Copy-to-clipboard functionality
-- ✅ Automatic component detection
+- ✅ Automatic component detection (with or without `data-inspection-*`)
 - ✅ CSS selector generation
 - ✅ Usage path tracking
 - ✅ Instance indexing
 - ✅ Props signature extraction
-- ✅ Request blocking during inspection
+- ✅ Request blocking during inspection (when CTRL is held)
 - ✅ Production-safe (zero overhead)
 
 ## 🤖 Designed by Cursor AI

package/dist/InspectionContext.js

@@ -8,19 +8,18 @@ const InspectionContext = createContext(undefined);
  */
 export const InspectionProvider = ({ children }) => {
     const [ctrlHeld, setCtrlHeld] = useState(false);
-    const [isStickyInspection, setIsStickyInspection] = useState(false);
-    const isInspectionActive = ctrlHeld || isStickyInspection;
-    const [isLocked, setIsLocked] = useState(false);
     const [isMarginPaddingMode, setIsMarginPaddingMode] = useState(false);
+    const [isLocked, setIsLocked] = useState(false);
+    // Inspection active only when CTRL is held (or CTRL+ALT for margin/padding). Release CTRL = stop inspecting.
+    const isInspectionActive = ctrlHeld || isMarginPaddingMode;
     const [hoveredComponent, setHoveredComponentState] = useState(null);
     const [hoveredElement, setHoveredElement] = useState(null);
     // Use refs to always access latest state values in event handlers
     const isInspectionActiveRef = useRef(isInspectionActive);
     const isLockedRef = useRef(isLocked);
-    const isStickyInspectionRef = useRef(isStickyInspection);
     const hoveredComponentRef = useRef(hoveredComponent);
     const hKeyPressedRef = useRef(false);
-    // Touch support for locking only (3/4 finger activation removed - use Ctrl+Shift+R on laptop)
+    // Touch support for locking only (double-tap to lock tooltip)
     const lastTapRef = useRef(0);
     const [isMobile, setIsMobile] = useState(false);
     useEffect(() => {
@@ -43,10 +42,7 @@ export const InspectionProvider = ({ children }) => {
     useEffect(() => {
         hoveredComponentRef.current = hoveredComponent;
     }, [hoveredComponent]);
-    useEffect(() => {
-        isStickyInspectionRef.current = isStickyInspection;
-    }, [isStickyInspection]);
-    // Only block API/fetch when CTRL is physically held (not when sticky inspection is on)
+    // Only block API/fetch when CTRL is physically held
     useEffect(() => {
         setInspectionActive(ctrlHeld);
     }, [ctrlHeld]);
@@ -74,37 +70,18 @@ export const InspectionProvider = ({ children }) => {
                 lastTapRef.current = now;
             }
         };
-        // Keyboard: CTRL, CTRL+Shift+R (toggle inspection), CTRL+M (margin/padding), CTRL+H (lock)
+        // Keyboard: CTRL (hold = inspection), CTRL+Shift+R = hard refresh (do not capture), CTRL+ALT (margin/padding), CTRL+H (lock)
         const handleKeyDown = (e) => {
-            // R key with CTRL+Shift - toggle inspection on/off (sticky, for mobile viewport on laptop)
+            // Do NOT capture CTRL+Shift+R - let browser do hard refresh
             if (e.key && e.key.toLowerCase() === "r" && e.ctrlKey && e.shiftKey) {
-                e.preventDefault();
-                e.stopPropagation();
-                if (!e.repeat) {
-                    setIsStickyInspection(prev => {
-                        const next = !prev;
-                        if (!next) {
-                            setHoveredComponentState(null);
-                            setHoveredElement(null);
-                            setIsLocked(false);
-                        }
-                        if (process.env.NODE_ENV === "development") {
-                            console.log("[Inspection] Inspection toggled (Ctrl+Shift+R):", next ? "ON" : "OFF");
-                        }
-                        return next;
-                    });
-                }
                 return;
             }
-            // M key with CTRL (hold) - margin/padding mode while held, inspect on mouse move
-            if (e.key && e.key.toLowerCase() === "m" && e.ctrlKey && !e.shiftKey && !e.altKey) {
-                e.preventDefault();
-                e.stopPropagation();
-                if (!e.repeat) {
-                    setIsMarginPaddingMode(true);
-                    setCtrlHeld(true);
-                }
-                return;
+            // CTRL+ALT (hold both) - margin/padding/box mode; desktop and mobile
+            if (e.key === "Control" && e.altKey && !e.repeat) {
+                setIsMarginPaddingMode(true);
+            }
+            if (e.key === "Alt" && e.ctrlKey && !e.repeat) {
+                setIsMarginPaddingMode(true);
             }
             // H key pressed while CTRL is held - lock tooltip position
             if (e.key && e.key.toLowerCase() === "h" && e.ctrlKey) {
@@ -148,20 +125,18 @@ export const InspectionProvider = ({ children }) => {
                 }
                 return;
             }
-            // M key released - turn off margin/padding mode (hold-to-use, no toggle)
-            if (e.key && e.key.toLowerCase() === "m") {
+            // ALT or CTRL released - turn off margin/padding mode (CTRL+ALT only, hold to use)
+            if (e.key === "Alt") {
                 setIsMarginPaddingMode(false);
             }
-            // CTRL key released - clear only if not in sticky mode
+            // CTRL key released - stop inspecting and clear state
             if (e.key === "Control") {
                 setCtrlHeld(false);
                 hKeyPressedRef.current = false;
-                if (!isStickyInspectionRef.current) {
-                    setIsMarginPaddingMode(false);
-                    setIsLocked(false);
-                    setHoveredComponentState(null);
-                    setHoveredElement(null);
-                }
+                setIsMarginPaddingMode(false);
+                setIsLocked(false);
+                setHoveredComponentState(null);
+                setHoveredElement(null);
             }
         };
         window.addEventListener("keydown", handleKeyDown);

package/dist/InspectionHighlight.js

@@ -19,7 +19,7 @@ const parsePx = (value) => {
 };
 /**
  * Highlight overlay that shows the boundary of the hovered component
- * When hold CTRL+M: orange = margin, green = padding, purple = gap (hold-to-use, release to exit)
+ * When hold CTRL+ALT: orange = margin, green = padding, purple = gap (hold-to-use, release to exit)
  * Otherwise: blue outline for component
  */
 const stripStyle = (left, top, width, height, color, bg) => ({

package/dist/InspectionTooltip.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useState, useEffect, useRef, useMemo } from "react";
-import { Box, Paper, Typography, IconButton, Tooltip as MuiTooltip, Divider, Menu, MenuItem } from "@mui/material";
+import { Box, Paper, Typography, IconButton, Tooltip as MuiTooltip, Divider } from "@mui/material";
 import ContentCopyIcon from "@mui/icons-material/ContentCopy";
 import { useInspection } from "./InspectionContext";
-import { formatMetadataForClipboard, getParentWithGap } from "./inspection";
+import { formatMetadataForClipboard, getParentWithGap, getTooltipHowToFindInfo } from "./inspection";
 import { parseInspectionMetadata } from "./autoInspection";
 /**
  * Helper: Get element text content (first 100 chars)
@@ -87,7 +87,6 @@ export const InspectionTooltip = () => {
     const [position, setPosition] = useState({ x: 0, y: 0 });
     const [stablePosition, setStablePosition] = useState(null);
     const [copied, setCopied] = useState(null);
-    const [copyMenuAnchor, setCopyMenuAnchor] = useState(null);
     const tooltipRef = useRef(null);
     // Update position based on cursor, but keep it stable when locked or mouse is near tooltip
     useEffect(() => {
@@ -137,8 +136,29 @@ export const InspectionTooltip = () => {
         propsSignature: "default",
         sourceFile: "DOM",
     } : null);
+    // On mobile (or when locking) there is no cursor; position tooltip over/near the inspected element
+    const positionFromElement = useMemo(() => {
+        if (!hoveredElement || !document.body.contains(hoveredElement))
+            return null;
+        const padding = 10;
+        const estimatedWidth = 400;
+        const estimatedHeight = 200;
+        const rect = hoveredElement.getBoundingClientRect();
+        // Prefer below and to the right of the element, clamped to viewport
+        let x = rect.left + 15;
+        let y = rect.bottom + 10;
+        if (x + estimatedWidth > window.innerWidth - padding)
+            x = window.innerWidth - estimatedWidth - padding;
+        if (x < padding)
+            x = padding;
+        if (y + estimatedHeight > window.innerHeight - padding)
+            y = rect.top - estimatedHeight - 10;
+        if (y < padding)
+            y = padding;
+        return { x, y };
+    }, [hoveredElement]);
     // Calculate adjusted position to avoid going off-screen
-    // Use stable position if available, otherwise calculate from cursor position
+    // Use stable position if available; on mobile or when locked use element-based position so tooltip appears over inspected area
     const adjustedPosition = useMemo(() => {
         if (!displayComponent) {
             return { x: position.x + 15, y: position.y + 15 };
@@ -147,7 +167,11 @@ export const InspectionTooltip = () => {
         if (stablePosition) {
             return stablePosition;
         }
-        // Calculate new position from cursor (only when stablePosition is null)
+        // Mobile or just locked: place tooltip near the inspected element (not cursor)
+        if ((isMobile || isLocked) && positionFromElement) {
+            return positionFromElement;
+        }
+        // Desktop: calculate from cursor position
         const padding = 10;
         let x = position.x + 15;
         let y = position.y + 15;
@@ -170,7 +194,7 @@ export const InspectionTooltip = () => {
             y = padding;
         }
         return { x, y };
-    }, [position, displayComponent, stablePosition]);
+    }, [position, displayComponent, stablePosition, isMobile, isLocked, positionFromElement]);
     // Set stable position once when tooltip first appears for a new element, or when locked
     const lastComponentIdRef = useRef(null);
     useEffect(() => {
@@ -232,7 +256,6 @@ export const InspectionTooltip = () => {
             const metadata = parseInspectionMetadata(parentWithGap);
             if (!metadata)
                 return;
-            setCopyMenuAnchor(null);
             const text = formatMetadataForClipboard(metadata, parentWithGap, "gap");
             const showCopied = () => {
                 setCopied("gap");
@@ -260,7 +283,6 @@ export const InspectionTooltip = () => {
         }
         if (!displayComponent)
             return;
-        setCopyMenuAnchor(null);
         const text = formatMetadataForClipboard(displayComponent, hoveredElement, type);
         const showCopied = () => {
             setCopied(type);
@@ -292,13 +314,6 @@ export const InspectionTooltip = () => {
             setStablePosition(null);
         }
     }, [hoveredElement, isLocked]);
-    // Close copy menu when tooltip is hidden so MUI Menu never has a detached anchorEl
-    const tooltipVisible = isInspectionActive && !!displayComponent && !(isMobile && !isLocked);
-    useEffect(() => {
-        if (!tooltipVisible) {
-            setCopyMenuAnchor(null);
-        }
-    }, [tooltipVisible]);
     const parentWithGap = hoveredElement ? getParentWithGap(hoveredElement) : null;
     // Show tooltip when inspection active; on mobile only when locked (H pressed or double-tap)
     if (!isInspectionActive || !displayComponent) {
@@ -320,15 +335,21 @@ export const InspectionTooltip = () => {
             backdropFilter: "blur(8px)",
             border: "1px solid rgba(255, 255, 255, 0.1)",
             transition: stablePosition ? "none" : "left 0.1s ease-out, top 0.1s ease-out",
-        }, children: [_jsxs(Box, { sx: { display: "flex", justifyContent: "space-between", alignItems: "flex-start", mb: 1 }, children: [_jsxs(Box, { sx: { display: "flex", alignItems: "center", gap: 1 }, children: [_jsx(Typography, { variant: "subtitle2", sx: { color: "#fff", fontWeight: 600, fontSize: "0.875rem" }, children: "Component Inspector" }), isMarginPaddingMode && (_jsx(Typography, { variant: "caption", sx: { color: "#ff9800", fontSize: "0.65rem" }, children: "M/P mode" })), isLocked && (_jsx(Typography, { variant: "caption", sx: { color: "#4caf50", fontSize: "0.7rem", fontStyle: "italic" }, children: "(Locked - Release H to unlock)" }))] }), isMobile ? (_jsxs(Box, { sx: { display: "flex", alignItems: "center", gap: 0.75 }, children: [_jsx(IconButton, { size: "small", onPointerDown: (e) => { e.preventDefault(); handleCopy("component"); }, sx: { color: copied === "component" ? "#4caf50" : "#fff", p: 0.5, minWidth: 36, minHeight: 36 }, "aria-label": "Copy component", children: _jsx(ContentCopyIcon, { fontSize: "small" }) }), _jsxs(Box, { sx: {
+        }, children: [_jsxs(Box, { sx: { display: "flex", justifyContent: "space-between", alignItems: "flex-start", mb: 1 }, children: [_jsxs(Box, { sx: { display: "flex", alignItems: "center", gap: 1 }, children: [_jsx(Typography, { variant: "subtitle2", sx: { color: "#fff", fontWeight: 600, fontSize: "0.875rem" }, children: "Component Inspector" }), isMarginPaddingMode && (_jsx(Typography, { variant: "caption", sx: { color: "#ff9800", fontSize: "0.65rem" }, children: "M/P mode" })), isLocked && (_jsx(Typography, { variant: "caption", sx: { color: "#4caf50", fontSize: "0.7rem", fontStyle: "italic" }, children: "(Locked - Release H to unlock)" }))] }), _jsxs(Box, { sx: { display: "flex", alignItems: "center", gap: 0.75 }, children: [_jsx(MuiTooltip, { title: copied === "component" ? "Copied!" : "Copy component", children: _jsx(IconButton, { size: "small", onClick: (e) => { e.preventDefault(); handleCopy("component"); }, onPointerDown: (e) => { e.preventDefault(); handleCopy("component"); }, sx: {
+                                        color: copied === "component" ? "#4caf50" : "#fff",
+                                        "&:hover": { backgroundColor: "rgba(255, 255, 255, 0.1)" },
+                                        p: 0.5,
+                                        minWidth: 36,
+                                        minHeight: 36,
+                                    }, "aria-label": "Copy component", children: _jsx(ContentCopyIcon, { fontSize: "small" }) }) }), _jsxs(Box, { sx: {
                                     display: "flex",
                                     alignItems: "stretch",
                                     border: "1px solid rgba(255,255,255,0.25)",
                                     borderRadius: 1,
                                     overflow: "hidden",
-                                }, children: [_jsx(Typography, { component: "button", type: "button", variant: "caption", onPointerDown: (e) => { e.preventDefault(); handleCopy("margin"); }, sx: {
+                                }, children: [_jsx(Typography, { component: "button", type: "button", variant: "caption", onClick: (e) => { e.preventDefault(); handleCopy("margin"); }, onPointerDown: (e) => { e.preventDefault(); handleCopy("margin"); }, sx: {
                                             color: copied === "margin" ? "#4caf50" : "rgba(255,255,255,0.9)",
-                                            fontSize: "0.65rem",
+                                            fontSize: isMobile ? "0.65rem" : "0.7rem",
                                             cursor: "pointer",
                                             background: "none",
                                             border: "none",
@@ -336,9 +357,10 @@ export const InspectionTooltip = () => {
                                             padding: "4px 6px",
                                             fontFamily: "inherit",
                                             minWidth: 44,
-                                        }, children: "Margin" }), _jsx(Typography, { component: "button", type: "button", variant: "caption", onPointerDown: (e) => { e.preventDefault(); handleCopy("padding"); }, sx: {
+                                            "&:hover": { backgroundColor: "rgba(255,255,255,0.08)" },
+                                        }, children: "Margin" }), _jsx(Typography, { component: "button", type: "button", variant: "caption", onClick: (e) => { e.preventDefault(); handleCopy("padding"); }, onPointerDown: (e) => { e.preventDefault(); handleCopy("padding"); }, sx: {
                                             color: copied === "padding" ? "#4caf50" : "rgba(255,255,255,0.9)",
-                                            fontSize: "0.65rem",
+                                            fontSize: isMobile ? "0.65rem" : "0.7rem",
                                             cursor: "pointer",
                                             background: "none",
                                             border: "none",
@@ -346,20 +368,18 @@ export const InspectionTooltip = () => {
                                             padding: "4px 6px",
                                             fontFamily: "inherit",
                                             minWidth: 44,
-                                        }, children: "Padding" }), parentWithGap && (_jsx(Typography, { component: "button", type: "button", variant: "caption", onPointerDown: (e) => { e.preventDefault(); handleCopy("gap"); }, sx: {
+                                            "&:hover": { backgroundColor: "rgba(255,255,255,0.08)" },
+                                        }, children: "Padding" }), parentWithGap && (_jsx(Typography, { component: "button", type: "button", variant: "caption", onClick: (e) => { e.preventDefault(); handleCopy("gap"); }, onPointerDown: (e) => { e.preventDefault(); handleCopy("gap"); }, sx: {
                                             color: copied === "gap" ? "#4caf50" : "rgba(156, 39, 176, 0.95)",
-                                            fontSize: "0.65rem",
+                                            fontSize: isMobile ? "0.65rem" : "0.7rem",
                                             cursor: "pointer",
                                             background: "none",
                                             border: "none",
                                             padding: "4px 6px",
                                             fontFamily: "inherit",
                                             minWidth: 44,
-                                        }, children: "Gap" }))] })] })) : (_jsxs(_Fragment, { children: [_jsx(MuiTooltip, { title: copied ? `Copied ${copied}!` : "Copy: Component / Margin / Padding", children: _jsx(IconButton, { size: "small", onClick: (e) => setCopyMenuAnchor(e.currentTarget), sx: {
-                                        color: copied ? "#4caf50" : "#fff",
-                                        "&:hover": { backgroundColor: "rgba(255, 255, 255, 0.1)" },
-                                        p: 0.5,
-                                    }, children: _jsx(ContentCopyIcon, { fontSize: "small" }) }) }), _jsxs(Menu, { anchorEl: copyMenuAnchor && document.body.contains(copyMenuAnchor) ? copyMenuAnchor : null, open: !!copyMenuAnchor && document.body.contains(copyMenuAnchor), onClose: () => setCopyMenuAnchor(null), anchorOrigin: { vertical: "bottom", horizontal: "right" }, transformOrigin: { vertical: "top", horizontal: "right" }, PaperProps: { sx: { backgroundColor: "rgba(18, 18, 18, 0.95)", minWidth: 140 } }, MenuListProps: { dense: true }, children: [_jsx(MenuItem, { onClick: () => handleCopy("component"), sx: { color: "#fff", fontSize: "0.8rem" }, children: "Copy Component" }), _jsx(MenuItem, { onClick: () => handleCopy("margin"), sx: { color: "#fff", fontSize: "0.8rem" }, children: "Copy Margin" }), _jsx(MenuItem, { onClick: () => handleCopy("padding"), sx: { color: "#fff", fontSize: "0.8rem" }, children: "Copy Padding" }), parentWithGap && (_jsx(MenuItem, { onClick: () => handleCopy("gap"), sx: { color: "#9c27b0", fontSize: "0.8rem" }, children: "Copy Gap (parent)" }))] })] }))] }), isMarginPaddingMode && hoveredElement && (() => {
+                                            "&:hover": { backgroundColor: "rgba(255,255,255,0.08)" },
+                                        }, children: "Gap" }))] })] })] }), isMarginPaddingMode && hoveredElement && (() => {
                 try {
                     const cs = window.getComputedStyle(hoveredElement);
                     const mt = cs.marginTop;
@@ -378,5 +398,9 @@ export const InspectionTooltip = () => {
                 catch {
                     return (_jsxs(Box, { sx: { mb: 1, p: 0.75, borderRadius: 1, backgroundColor: "rgba(255,255,255,0.06)" }, children: [_jsx(Typography, { variant: "caption", sx: { color: "#ff9800" }, children: "Orange = Margin (outside)" }), _jsx(Typography, { variant: "caption", sx: { color: "#4caf50", display: "block" }, children: "Green = Padding (inside)" })] }));
                 }
-            })(), _jsxs(Box, { sx: { display: "flex", flexDirection: "column", gap: 1 }, children: [_jsx(Typography, { variant: "body2", sx: { color: "#fff", fontWeight: 500, mb: 0.5 }, children: displayComponent.componentName }), _jsx(Divider, { sx: { borderColor: "rgba(255, 255, 255, 0.1)", my: 0.5 } }), _jsx(ElementIdentificationSection, { element: hoveredElement, role: displayComponent.role }), _jsx(Divider, { sx: { borderColor: "rgba(255, 255, 255, 0.1)", my: 0.5 } }), _jsx(ComponentMetadataSection, { metadata: displayComponent })] })] }));
+            })(), _jsxs(Box, { sx: { display: "flex", flexDirection: "column", gap: 1 }, children: [_jsx(Typography, { variant: "body2", sx: { color: "#fff", fontWeight: 500, mb: 0.5 }, children: displayComponent.componentName }), _jsx(Divider, { sx: { borderColor: "rgba(255, 255, 255, 0.1)", my: 0.5 } }), _jsx(ElementIdentificationSection, { element: hoveredElement, role: displayComponent.role }), _jsx(Divider, { sx: { borderColor: "rgba(255, 255, 255, 0.1)", my: 0.5 } }), hoveredElement && (() => {
+                        const howToType = isMarginPaddingMode ? "margin" : "component";
+                        const info = getTooltipHowToFindInfo(displayComponent, hoveredElement, howToType);
+                        return (_jsxs(_Fragment, { children: [_jsx(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.9)", fontSize: "0.7rem", fontWeight: 600 }, children: "=== HOW TO FIND IN CODE ===" }), _jsxs(Box, { sx: { display: "flex", flexDirection: "column", gap: 0.25, pl: 0.5 }, children: [_jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.65rem", wordBreak: "break-all" }, children: [_jsx("strong", { children: "DOM Path:" }), " ", info.domPath] }), info.parent && (_jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.65rem" }, children: [_jsx("strong", { children: "Parent:" }), " ", info.parent] })), _jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.65rem" }, children: [_jsx("strong", { children: "Role in tree:" }), " ", info.roleInTree] }), _jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.85)", fontSize: "0.65rem", mt: 0.5 }, children: [_jsx("strong", { children: "TARGET:" }), " ", info.target] }), _jsx(Box, { component: "ol", sx: { m: 0, pl: 1.5, fontSize: "0.65rem", color: "rgba(255, 255, 255, 0.7)" }, children: info.howToFindSteps.map((step, i) => (_jsx(Typography, { component: "li", variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.65rem", mb: 0.25 }, children: step }, i))) })] }), _jsx(Divider, { sx: { borderColor: "rgba(255, 255, 255, 0.1)", my: 0.5 } })] }));
+                    })(), _jsx(ComponentMetadataSection, { metadata: displayComponent })] })] }));
 };

package/dist/index.d.ts

@@ -5,6 +5,6 @@ export { InspectionOverlays } from './InspectionOverlays';
 export { InspectionWrapper, withInspection } from './InspectionWrapper';
 export { useInspectionMetadata } from './useInspectionMetadata';
 export { setupInterceptors, setInspectionActive, shouldBlockRequest } from './inspectionInterceptors';
-export { generateComponentId, formatPropsSignature, formatMetadataForClipboard, formatMarginForClipboard, formatPaddingForClipboard, formatGapForClipboard, getParentWithGap, getAncestorsWithMargin, getComponentName, getNextInstanceIndex } from './inspection';
+export { generateComponentId, formatPropsSignature, formatMetadataForClipboard, formatMarginForClipboard, formatPaddingForClipboard, formatGapForClipboard, getParentWithGap, getAncestorsWithMargin, getTooltipHowToFindInfo, getComponentName, getNextInstanceIndex } from './inspection';
 export type { CopyType } from './inspection';
 export { setupAutoInspection, parseInspectionMetadata } from './autoInspection';

package/dist/index.js

@@ -6,5 +6,5 @@ export { InspectionOverlays } from './InspectionOverlays';
 export { InspectionWrapper, withInspection } from './InspectionWrapper';
 export { useInspectionMetadata } from './useInspectionMetadata';
 export { setupInterceptors, setInspectionActive, shouldBlockRequest } from './inspectionInterceptors';
-export { generateComponentId, formatPropsSignature, formatMetadataForClipboard, formatMarginForClipboard, formatPaddingForClipboard, formatGapForClipboard, getParentWithGap, getAncestorsWithMargin, getComponentName, getNextInstanceIndex } from './inspection';
+export { generateComponentId, formatPropsSignature, formatMetadataForClipboard, formatMarginForClipboard, formatPaddingForClipboard, formatGapForClipboard, getParentWithGap, getAncestorsWithMargin, getTooltipHowToFindInfo, getComponentName, getNextInstanceIndex } from './inspection';
 export { setupAutoInspection, parseInspectionMetadata } from './autoInspection';

package/dist/inspection.d.ts

@@ -30,6 +30,18 @@ export declare const getAncestorsWithMargin: (element: HTMLElement, maxCount?: n
     mb: number;
     ml: number;
 }>;
+/**
+ * Build DOM path from body to element (helps Cursor identify exact element)
+ */
+export declare const buildDomPath: (element: HTMLElement) => string;
+/**
+ * Build parent element description
+ */
+export declare const buildParentInfo: (element: HTMLElement) => string | null;
+/**
+ * Build role/disambiguation (outer vs inner, position in tree)
+ */
+export declare const buildRoleInTree: (element: HTMLElement, type: "margin" | "padding" | "component") => string;
 /**
  * Format metadata for clipboard with full element details
  */
@@ -46,6 +58,16 @@ export declare const formatPaddingForClipboard: (metadata: ComponentMetadata, el
  * Format gap info for clipboard (alias for formatMetadataForClipboard with type="gap")
  */
 export declare const formatGapForClipboard: (metadata: ComponentMetadata, element: HTMLElement) => string;
+/**
+ * Get "how to find" display info for tooltip (same logic for desktop and mobile)
+ */
+export declare const getTooltipHowToFindInfo: (metadata: ComponentMetadata, element: HTMLElement, type: CopyType) => {
+    domPath: string;
+    parent: string | null;
+    roleInTree: string;
+    target: string;
+    howToFindSteps: string[];
+};
 /**
  * Get next instance index for a component
  */

package/dist/inspection.js

@@ -103,7 +103,7 @@ export const getAncestorsWithMargin = (element, maxCount = 2) => {
 /**
  * Build DOM path from body to element (helps Cursor identify exact element)
  */
-const buildDomPath = (element) => {
+export const buildDomPath = (element) => {
     const segments = [];
     let current = element;
     while (current && current !== document.body) {
@@ -122,7 +122,7 @@ const buildDomPath = (element) => {
 /**
  * Build parent element description
  */
-const buildParentInfo = (element) => {
+export const buildParentInfo = (element) => {
     const parent = element.parentElement;
     if (!parent || parent === document.body)
         return null;
@@ -138,7 +138,7 @@ const buildParentInfo = (element) => {
 /**
  * Build role/disambiguation (outer vs inner, position in tree)
  */
-const buildRoleInTree = (element, type) => {
+export const buildRoleInTree = (element, type) => {
     const parent = element.parentElement;
     const children = element.children;
     const childCount = Array.from(children).length;
@@ -400,6 +400,79 @@ export const formatPaddingForClipboard = (metadata, element) => {
 export const formatGapForClipboard = (metadata, element) => {
     return formatMetadataForClipboard(metadata, element, "gap");
 };
+/**
+ * Get "how to find" display info for tooltip (same logic for desktop and mobile)
+ */
+export const getTooltipHowToFindInfo = (metadata, element, type) => {
+    const domPath = buildDomPath(element);
+    const parent = buildParentInfo(element);
+    if (type === "component") {
+        const rect = element.getBoundingClientRect();
+        const classNameStr = element.className ? (typeof element.className === "string" ? element.className : String(element.className)) : "";
+        const firstClass = classNameStr.split(/\s+/).find((c) => c && (c.startsWith("Mui") || c.startsWith("css-")));
+        const desc = firstClass ? `${metadata.componentName} with class ${firstClass}` : metadata.componentName;
+        const target = `The ${desc} - position (${Math.round(rect.left)}, ${Math.round(rect.top)}), size ${Math.round(rect.width)}x${Math.round(rect.height)}px. It is the element in the DOM path above, NOT a child.`;
+        const steps = [
+            "Use the DOM Path to locate the correct element - do NOT change a child if the path shows this element is the parent.",
+            metadata.sourceFile !== "DOM"
+                ? `Open ${metadata.sourceFile} and find the component that renders this element.`
+                : "Search for the parent component that renders this layout. Look for the component in Usage Path or by Element Text/Label.",
+            "Modify the component's props, sx, or styles as needed.",
+        ];
+        return { domPath, parent, roleInTree: buildRoleInTree(element, "component"), target, howToFindSteps: steps };
+    }
+    if (type === "margin" || type === "padding") {
+        const cs = window.getComputedStyle(element);
+        const classNameStr = element.className ? (typeof element.className === "string" ? element.className : String(element.className)) : "";
+        const firstClass = classNameStr.split(/\s+/).find((c) => c && (c.startsWith("Mui") || c.startsWith("css-")));
+        const desc = firstClass ? `${metadata.componentName} with class ${firstClass}` : metadata.componentName;
+        if (type === "margin") {
+            const mt = getCssValue(cs.marginTop);
+            const mr = getCssValue(cs.marginRight);
+            const mb = getCssValue(cs.marginBottom);
+            const ml = getCssValue(cs.marginLeft);
+            const target = `The ${desc} - the element with margin ${mt} ${mr} ${mb} ${ml}. It is the PARENT in the DOM path above, NOT a child.`;
+            const steps = [
+                "Use the DOM Path to locate the correct element - do NOT change a child (e.g. CardContent, MuiBox) if the path shows this element is the parent.",
+                metadata.sourceFile !== "DOM"
+                    ? `Open ${metadata.sourceFile} and find the component that renders this element.`
+                    : "Search for the parent component that renders this layout. Look for MUI components (Box, Card, etc.) - the element with these margin values may use sx={{ m: ... }} or style props.",
+                "Change margin: sx={{ margin: 0 }} or margin: \"4px\" or mt: 1, mr: 1, mb: 1, ml: 1 (MUI theme spacing).",
+            ];
+            return { domPath, parent, roleInTree: buildRoleInTree(element, "margin"), target, howToFindSteps: steps };
+        }
+        else {
+            const pt = getCssValue(cs.paddingTop);
+            const pr = getCssValue(cs.paddingRight);
+            const pb = getCssValue(cs.paddingBottom);
+            const pl = getCssValue(cs.paddingLeft);
+            const target = `The ${desc} - the element with padding ${pt} ${pr} ${pb} ${pl}. It is the PARENT in the DOM path above, NOT a child.`;
+            const steps = [
+                "Use the DOM Path to locate the correct element - do NOT change a child (e.g. CardContent, MuiBox) if the path shows this element is the parent.",
+                metadata.sourceFile !== "DOM"
+                    ? `Open ${metadata.sourceFile} and find the component that renders this element.`
+                    : "Search for the parent component that renders this layout. Look for MUI components (Box, Card, CardContent, etc.) - the element with these exact padding values may use sx={{ p: ... }} or padding props.",
+                "Change padding: sx={{ padding: 0 }} or p: \"4px\" or pt: 1, pr: 1, pb: 1, pl: 1 (MUI theme spacing).",
+            ];
+            return { domPath, parent, roleInTree: buildRoleInTree(element, "padding"), target, howToFindSteps: steps };
+        }
+    }
+    // type === "gap" - element is the parent with gap
+    const cs = window.getComputedStyle(element);
+    const gap = getCssValue(cs.gap);
+    const classNameStr = element.className ? (typeof element.className === "string" ? element.className : String(element.className)) : "";
+    const firstClass = classNameStr.split(/\s+/).find((c) => c && (c.startsWith("Mui") || c.startsWith("css-")));
+    const desc = firstClass ? `${metadata.componentName} with class ${firstClass}` : metadata.componentName;
+    const target = `The ${desc} - the flex/grid container with gap ${gap}. It is the PARENT in the DOM path above.`;
+    const steps = [
+        "Use the DOM Path to locate the flex/grid container.",
+        metadata.sourceFile !== "DOM"
+            ? `Open ${metadata.sourceFile} and find the component that renders this element.`
+            : "Search for the component that renders this layout (Box, Stack, Grid, etc.).",
+        "Change gap: sx={{ gap: 1 }} or gap: \"8px\" or rowGap/columnGap (MUI theme spacing).",
+    ];
+    return { domPath, parent, roleInTree: "flex/grid container", target, howToFindSteps: steps };
+};
 /**
  * Track component instances for instance indexing
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zargaryanvh/react-component-inspector",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "A development tool for inspecting React components with AI-friendly metadata extraction",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",