@zargaryanvh/react-component-inspector 1.0.3 → 1.0.6

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,274 +1,321 @@
-# React Component Inspector
-
-> **A powerful development tool for inspecting React components with AI-friendly metadata extraction. Fully designed by Cursor AI.**
-
-## 🎯 What is This?
-
-React Component Inspector is a development-only tool that helps you identify, inspect, and extract detailed metadata from React components in your application. It's designed to work seamlessly with AI coding assistants (like Cursor) by providing structured, copyable metadata about any component in your UI.
-
-## 🔍 What Problem Does It Solve?
-
-### The Challenge
-When working with AI assistants to fix or modify frontend code, you often need to:
-- Identify which component is responsible for a specific UI element
-- Understand the component's props, variants, and usage context
-- Get the exact file path and component structure
-- Extract CSS selectors and element identifiers for precise targeting
-
-**Without this tool**, you'd need to:
-- Manually inspect the DOM
-- Search through codebases
-- Guess component names and file locations
-- Manually extract element information
-
-### The Solution
-React Component Inspector provides:
-- **One-click component identification** - Just hold CTRL and hover
-- **Rich metadata extraction** - Component name, props, file path, usage context
-- **AI-optimized format** - Copy-paste ready metadata for AI assistants
-- **Zero production overhead** - Completely disabled in production builds
-
-## 📊 What Data Does It Provide?
-
-When you inspect a component, you get:
-
-### Element Identification
-- Element type (HTML tag)
-- Element text/label content
-- Element ID
-- CSS classes
-- CSS selector
-- Position and size
-- Role and accessibility attributes
-
-### Component Metadata
-- Component name
-- Component ID (unique instance identifier)
-- Variant (if applicable)
-- Usage path (component hierarchy)
-- Instance index
-- Props signature (key props affecting behavior)
-- Source file path
-
-### Example Output
-```
-=== 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
-
-=== 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
-```
-
-## 🚀 How to Use This Data for AI-Powered Frontend Optimization
-
-### 1. **Precise Component Targeting**
-Copy the metadata and ask your AI assistant:
-```
-"I need to modify the SaveButton component. Here's the metadata:
-[paste metadata]
-
-Change the button color to green and add an icon."
-```
-
-### 2. **Context-Aware Refactoring**
-The usage path tells you exactly where the component is used:
-```
-"Refactor the TransactionCard component used in:
-ActivityPage > TransactionList > TransactionCard
-
-Make it accept a new 'priority' prop."
-```
-
-### 3. **CSS Selector Generation**
-Use the CSS selector for automated testing or styling:
-```javascript
-// The metadata provides: button#save-button
-const saveButton = document.querySelector('button#save-button');
-```
-
-### 4. **Component Discovery**
-Find all instances of a component:
-```
-"Find all instances of TransactionCard in the codebase.
-The component is defined in: src/components/transactions/TransactionCard.tsx"
-```
-
-### 5. **AI-Powered Debugging**
-Share component metadata with AI to debug issues:
-```
-"This button isn't working. Component metadata:
-[paste metadata]
-
-The onClick handler should be in: src/components/buttons/SaveButton.tsx"
-```
-
-## 📦 Installation
-
-```bash
-npm install react-component-inspector
-```
-
-## 🔧 Setup
-
-### 1. Wrap Your App
-
-```tsx
-import { InspectionProvider } from 'react-component-inspector';
-import { InspectionTooltip } from 'react-component-inspector';
-import { InspectionHighlight } from 'react-component-inspector';
-import { setupInterceptors } from 'react-component-inspector';
-
-function App() {
-  // Setup request interceptors (optional - blocks API calls when CTRL is held)
-  useEffect(() => {
-    setupInterceptors();
-  }, []);
-
-  return (
-    <InspectionProvider>
-      <YourApp />
-      <InspectionTooltip />
-      <InspectionHighlight />
-    </InspectionProvider>
-  );
-}
-```
-
-### 2. Add Metadata to Components
-
-#### Option A: Using the Hook (Recommended)
-
-```tsx
-import { useInspectionMetadata } from 'react-component-inspector';
-
-function MyButton({ variant, disabled, onClick }) {
-  const inspectionProps = useInspectionMetadata({
-    componentName: "MyButton",
-    variant: variant,
-    usagePath: "HomePage > ActionBar",
-    props: { variant, disabled },
-    sourceFile: "src/components/MyButton.tsx",
-  });
-
-  return (
-    <button {...inspectionProps} onClick={onClick}>
-      Click me
-    </button>
-  );
-}
-```
-
-#### Option B: Using the Wrapper Component
-
-```tsx
-import { InspectionWrapper } from 'react-component-inspector';
-
-function MyComponent({ variant, children }) {
-  return (
-    <InspectionWrapper
-      componentName="MyComponent"
-      variant={variant}
-      usagePath="HomePage > ContentArea"
-      props={{ variant }}
-      sourceFile="src/components/MyComponent.tsx"
-    >
-      <div>{children}</div>
-    </InspectionWrapper>
-  );
-}
-```
-
-#### Option C: Using Data Attributes (Manual)
-
-```tsx
-<div
-  data-inspection-name="MyComponent"
-  data-inspection-id="my-component-0"
-  data-inspection-variant="primary"
-  data-inspection-usage-path="HomePage > ContentArea"
-  data-inspection-instance="0"
-  data-inspection-props="variant=primary"
-  data-inspection-file="src/components/MyComponent.tsx"
->
-  Content
-</div>
-```
-
-## 🎮 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
-
-## 🛡️ Safety Features
-
-- **Development Only**: Completely disabled in production (`NODE_ENV !== "development"`)
-- **Request Blocking**: When CTRL is held, all API/Firebase requests are blocked to prevent accidental mutations
-- **Zero Overhead**: No code included in production builds
-- **Non-Intrusive**: Doesn't modify your components or affect their behavior
-
-## 📚 Documentation
-
-- [Quick Start Guide](./docs/QUICK_START.md)
-- [API Reference](./docs/API.md)
-- [Advanced Usage](./docs/ADVANCED.md)
-- [AI Integration Guide](./docs/AI_INTEGRATION.md)
-
-## 🎨 Features
-
-- ✅ Visual component highlighting
-- ✅ Rich metadata extraction
-- ✅ Copy-to-clipboard functionality
-- ✅ Automatic component detection
-- ✅ CSS selector generation
-- ✅ Usage path tracking
-- ✅ Instance indexing
-- ✅ Props signature extraction
-- ✅ Request blocking during inspection
-- ✅ Production-safe (zero overhead)
-
-## 🤖 Designed by Cursor AI
-
-This tool was fully designed and developed using [Cursor](https://cursor.sh), an AI-powered code editor. The entire codebase, architecture, and documentation were created through AI-assisted development, demonstrating the power of AI in building developer tools.
-
-## 📄 License
-
-MIT
-
-## 🤝 Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## ⚠️ Important Notes
-
-- This tool is **development-only** and will not work in production
-- Requires Material-UI (MUI) for the tooltip UI components
-- Works best with TypeScript but supports JavaScript
-- Request interceptors are optional but recommended for safety
-
-## 💡 Tips for AI Integration
-
-1. **Always copy the full metadata** - It contains all context needed
-2. **Include the usage path** - Helps AI understand component hierarchy
-3. **Share the source file** - Directs AI to the exact location
-4. **Use CSS selectors** - For precise element targeting in AI prompts
-5. **Copy element text** - Helps AI understand component purpose
-
----
-
-**Made with ❤️ using Cursor AI**
+# React Component Inspector
+
+> **A powerful development tool for inspecting React components with AI-friendly metadata extraction. Fully designed by Cursor AI.**
+
+## 🎯 What is This?
+
+React Component Inspector is a development-only tool that helps you identify, inspect, and extract detailed metadata from React components in your application. It's designed to work seamlessly with AI coding assistants (like Cursor) by providing structured, copyable metadata about any component in your UI.
+
+## 🔍 What Problem Does It Solve?
+
+### The Challenge
+When working with AI assistants to fix or modify frontend code, you often need to:
+- Identify which component is responsible for a specific UI element
+- Understand the component's props, variants, and usage context
+- Get the exact file path and component structure
+- Extract CSS selectors and element identifiers for precise targeting
+
+**Without this tool**, you'd need to:
+- Manually inspect the DOM
+- Search through codebases
+- Guess component names and file locations
+- Manually extract element information
+
+### The Solution
+React Component Inspector provides:
+- **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 (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
+- Element type (HTML tag)
+- Element text/label content
+- Element ID
+- CSS classes
+- CSS selector
+- Position and size
+- Role and accessibility attributes
+
+### Component Metadata
+- Component name
+- Component ID (unique instance identifier)
+- Variant (if applicable)
+- Usage path (component hierarchy)
+- Instance index
+- Props signature (key props affecting behavior)
+- Source file path
+
+### Example Output (Copy Component)
+```
+=== TYPE: COMPONENT ===
+
+=== ELEMENT IDENTIFICATION ===
+Element Type: button
+Element Text/Label: "Save Transaction"
+...
+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 ===
+...
+```
+
+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**
+Copy the metadata and ask your AI assistant:
+```
+"I need to modify the SaveButton component. Here's the metadata:
+[paste metadata]
+
+Change the button color to green and add an icon."
+```
+
+### 2. **Context-Aware Refactoring**
+The usage path tells you exactly where the component is used:
+```
+"Refactor the TransactionCard component used in:
+ActivityPage > TransactionList > TransactionCard
+
+Make it accept a new 'priority' prop."
+```
+
+### 3. **CSS Selector Generation**
+Use the CSS selector for automated testing or styling:
+```javascript
+// The metadata provides: button#save-button
+const saveButton = document.querySelector('button#save-button');
+```
+
+### 4. **Component Discovery**
+Find all instances of a component:
+```
+"Find all instances of TransactionCard in the codebase.
+The component is defined in: src/components/transactions/TransactionCard.tsx"
+```
+
+### 5. **AI-Powered Debugging**
+Share component metadata with AI to debug issues:
+```
+"This button isn't working. Component metadata:
+[paste metadata]
+
+The onClick handler should be in: src/components/buttons/SaveButton.tsx"
+```
+
+## 📦 Installation
+
+```bash
+npm install react-component-inspector
+```
+
+## 🔧 Setup
+
+### 1. Wrap Your App
+
+```tsx
+import { InspectionProvider } from 'react-component-inspector';
+import { InspectionTooltip } from 'react-component-inspector';
+import { InspectionHighlight } from 'react-component-inspector';
+import { setupInterceptors } from 'react-component-inspector';
+
+function App() {
+  // Setup request interceptors (optional - blocks API calls when CTRL is held)
+  useEffect(() => {
+    setupInterceptors();
+  }, []);
+
+  return (
+    <InspectionProvider>
+      <YourApp />
+      <InspectionTooltip />
+      <InspectionHighlight />
+    </InspectionProvider>
+  );
+}
+```
+
+### 2. Add Metadata to Components
+
+#### Option A: Using the Hook (Recommended)
+
+```tsx
+import { useInspectionMetadata } from 'react-component-inspector';
+
+function MyButton({ variant, disabled, onClick }) {
+  const inspectionProps = useInspectionMetadata({
+    componentName: "MyButton",
+    variant: variant,
+    usagePath: "HomePage > ActionBar",
+    props: { variant, disabled },
+    sourceFile: "src/components/MyButton.tsx",
+  });
+
+  return (
+    <button {...inspectionProps} onClick={onClick}>
+      Click me
+    </button>
+  );
+}
+```
+
+#### Option B: Using the Wrapper Component
+
+```tsx
+import { InspectionWrapper } from 'react-component-inspector';
+
+function MyComponent({ variant, children }) {
+  return (
+    <InspectionWrapper
+      componentName="MyComponent"
+      variant={variant}
+      usagePath="HomePage > ContentArea"
+      props={{ variant }}
+      sourceFile="src/components/MyComponent.tsx"
+    >
+      <div>{children}</div>
+    </InspectionWrapper>
+  );
+}
+```
+
+#### Option C: Using Data Attributes (Manual)
+
+```tsx
+<div
+  data-inspection-name="MyComponent"
+  data-inspection-id="my-component-0"
+  data-inspection-variant="primary"
+  data-inspection-usage-path="HomePage > ContentArea"
+  data-inspection-instance="0"
+  data-inspection-props="variant=primary"
+  data-inspection-file="src/components/MyComponent.tsx"
+>
+  Content
+</div>
+```
+
+## 🎮 Usage
+
+### 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
+
+- **Development Only**: Completely disabled in production (`NODE_ENV !== "development"`)
+- **Request Blocking**: When CTRL is held, all API/Firebase requests are blocked to prevent accidental mutations
+- **Zero Overhead**: No code included in production builds
+- **Non-Intrusive**: Doesn't modify your components or affect their behavior
+
+## 📚 Documentation
+
+- [Quick Start Guide](./docs/QUICK_START.md)
+- [API Reference](./docs/API.md)
+- [Advanced Usage](./docs/ADVANCED.md)
+- [AI Integration Guide](./docs/AI_INTEGRATION.md)
+
+## 🎨 Features
+
+- ✅ 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
+- ✅ Automatic component detection (with or without `data-inspection-*`)
+- ✅ CSS selector generation
+- ✅ Usage path tracking
+- ✅ Instance indexing
+- ✅ Props signature extraction
+- ✅ Request blocking during inspection (when CTRL is held)
+- ✅ Production-safe (zero overhead)
+
+## 🤖 Designed by Cursor AI
+
+This tool was fully designed and developed using [Cursor](https://cursor.sh), an AI-powered code editor. The entire codebase, architecture, and documentation were created through AI-assisted development, demonstrating the power of AI in building developer tools.
+
+## 📄 License
+
+MIT
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## ⚠️ Important Notes
+
+- This tool is **development-only** and will not work in production
+- Requires Material-UI (MUI) for the tooltip UI components
+- Works best with TypeScript but supports JavaScript
+- Request interceptors are optional but recommended for safety
+
+## 💡 Tips for AI Integration
+
+1. **Always copy the full metadata** - It contains all context needed
+2. **Include the usage path** - Helps AI understand component hierarchy
+3. **Share the source file** - Directs AI to the exact location
+4. **Use CSS selectors** - For precise element targeting in AI prompts
+5. **Copy element text** - Helps AI understand component purpose
+
+---
+
+**Made with ❤️ using 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,54 +1,55 @@
-{
-  "name": "@zargaryanvh/react-component-inspector",
-  "version": "1.0.3",
-  "description": "A development tool for inspecting React components with AI-friendly metadata extraction",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "files": [
-    "dist/**/*",
-    "README.md",
-    "LICENSE",
-    "package.json"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [
-    "react",
-    "component",
-    "inspection",
-    "development",
-    "debugging",
-    "ai",
-    "metadata",
-    "tool",
-    "cursor",
-    "cursor-ai"
-  ],
-  "author": "zargaryanvh",
-  "license": "MIT",
-  "peerDependencies": {
-    "react": ">=16.8.0",
-    "react-dom": ">=16.8.0",
-    "@mui/material": ">=5.0.0",
-    "@mui/icons-material": ">=5.0.0"
-  },
-  "devDependencies": {
-    "@types/react": "^18.0.0",
-    "@types/react-dom": "^18.0.0",
-    "typescript": "^5.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zargaryanvh/react-component-inspector.git"
-  }
-}
+{
+  "name": "@zargaryanvh/react-component-inspector",
+  "version": "1.0.6",
+  "description": "A development tool for inspecting React components with AI-friendly metadata extraction",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "react",
+    "component",
+    "inspection",
+    "development",
+    "debugging",
+    "ai",
+    "metadata",
+    "tool",
+    "cursor",
+    "cursor-ai"
+  ],
+  "author": "zargaryanvh",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0",
+    "@mui/material": ">=5.0.0",
+    "@mui/icons-material": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "typescript": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zargaryanvh/react-component-inspector.git"
+  }
+}