@zargaryanvh/react-component-inspector 1.0.0

package/dist/InspectionTooltip.js

@@ -0,0 +1,232 @@
+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 } from "@mui/material";
+import ContentCopyIcon from "@mui/icons-material/ContentCopy";
+import { useInspection } from "./InspectionContext";
+import { formatMetadataForClipboard } from "./inspection";
+/**
+ * Helper: Get element text content (first 100 chars)
+ */
+const getElementText = (element) => {
+    if (!element)
+        return null;
+    const textContent = element.textContent?.trim() || "";
+    const visibleText = textContent.substring(0, 100).replace(/\s+/g, " ");
+    return visibleText || null;
+};
+/**
+ * Helper: Get element classes (prioritize MUI classes)
+ */
+const getElementClasses = (element) => {
+    if (!element?.className)
+        return [];
+    const classNameStr = typeof element.className === "string"
+        ? element.className
+        : String(element.className);
+    const classes = classNameStr.split(/\s+/).filter(c => c);
+    // Prioritize MUI classes, then others
+    const muiClasses = classes.filter(c => c.includes("Mui")).slice(0, 2);
+    const otherClasses = classes.filter(c => !c.includes("Mui")).slice(0, 2);
+    return [...muiClasses, ...otherClasses].slice(0, 3);
+};
+/**
+ * Helper: Generate CSS selector for element
+ */
+const getElementSelector = (element) => {
+    if (!element)
+        return null;
+    if (element.id) {
+        return `#${element.id}`;
+    }
+    if (element.className) {
+        const classNameStr = typeof element.className === "string"
+            ? element.className
+            : String(element.className);
+        const firstClass = classNameStr.split(/\s+/).find(c => c);
+        if (firstClass) {
+            return `${element.tagName.toLowerCase()}.${firstClass}`;
+        }
+    }
+    return element.tagName.toLowerCase();
+};
+/**
+ * Helper: Get element position and size
+ */
+const getElementBounds = (element) => {
+    if (!element)
+        return null;
+    const rect = element.getBoundingClientRect();
+    return {
+        position: `(${Math.round(rect.left)}, ${Math.round(rect.top)})`,
+        size: `${Math.round(rect.width)}x${Math.round(rect.height)}px`,
+    };
+};
+/**
+ * Section: Element Identification
+ */
+const ElementIdentificationSection = ({ element, role }) => {
+    const elementText = getElementText(element);
+    const elementClasses = getElementClasses(element);
+    const selector = getElementSelector(element);
+    const bounds = getElementBounds(element);
+    return (_jsxs(Box, { sx: { display: "flex", flexDirection: "column", gap: 0.5 }, children: [_jsx(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.9)", fontSize: "0.7rem", fontWeight: 600 }, children: "=== ELEMENT IDENTIFICATION ===" }), _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.7rem" }, children: [_jsx("strong", { children: "Element Type:" }), " ", element?.tagName.toLowerCase() || "unknown"] }), elementText && (_jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Element Text/Label:" }), " \"", elementText, "\""] })), element?.id && (_jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Element ID:" }), " ", element.id] })), elementClasses.length > 0 && (_jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Element Classes:" }), " ", elementClasses.join(", ")] })), role && (_jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Role:" }), " ", role] })), selector && (_jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "CSS Selector:" }), " ", selector] })), bounds && (_jsxs(_Fragment, { children: [_jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Position:" }), " ", bounds.position] }), _jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Size:" }), " ", bounds.size] })] }))] })] }));
+};
+/**
+ * Section: Component Metadata
+ */
+const ComponentMetadataSection = ({ metadata }) => {
+    return (_jsxs(Box, { sx: { display: "flex", flexDirection: "column", gap: 0.5 }, children: [_jsx(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.9)", fontSize: "0.7rem", fontWeight: 600 }, children: "=== COMPONENT METADATA ===" }), _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.7rem" }, children: [_jsx("strong", { children: "Component Name:" }), " ", metadata.componentName] }), _jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Component ID:" }), " ", metadata.componentId] }), metadata.variant && (_jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Variant:" }), " ", metadata.variant] })), _jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Usage Path:" }), " ", metadata.usagePath] }), _jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Instance:" }), " ", metadata.instanceIndex] }), _jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Props:" }), " ", metadata.propsSignature] }), _jsxs(Typography, { variant: "caption", sx: { color: "rgba(255, 255, 255, 0.7)", fontSize: "0.7rem" }, children: [_jsx("strong", { children: "Source File:" }), " ", metadata.sourceFile] })] })] }));
+};
+/**
+ * Inspection tooltip that shows component metadata
+ * Only visible when CTRL is held and a component is hovered
+ */
+export const InspectionTooltip = () => {
+    const { isInspectionActive, isLocked, hoveredComponent, hoveredElement } = useInspection();
+    const [position, setPosition] = useState({ x: 0, y: 0 });
+    const [stablePosition, setStablePosition] = useState(null);
+    const [copied, setCopied] = useState(false);
+    const tooltipRef = useRef(null);
+    // Update position based on cursor, but keep it stable when locked or mouse is near tooltip
+    useEffect(() => {
+        if (!isInspectionActive || !hoveredElement) {
+            setStablePosition(null);
+            return;
+        }
+        // If locked, don't update position at all - keep it completely fixed
+        if (isLocked) {
+            return;
+        }
+        const updatePosition = (e) => {
+            // If we have a stable position, check if mouse is near tooltip
+            if (stablePosition && tooltipRef.current) {
+                const tooltipRect = tooltipRef.current.getBoundingClientRect();
+                const mouseX = e.clientX;
+                const mouseY = e.clientY;
+                // Create a "dead zone" around tooltip (80px padding for easier clicking)
+                const deadZone = {
+                    left: tooltipRect.left - 80,
+                    right: tooltipRect.right + 80,
+                    top: tooltipRect.top - 80,
+                    bottom: tooltipRect.bottom + 80,
+                };
+                // If mouse is in dead zone, keep position stable (don't update)
+                if (mouseX >= deadZone.left &&
+                    mouseX <= deadZone.right &&
+                    mouseY >= deadZone.top &&
+                    mouseY <= deadZone.bottom) {
+                    return; // Don't update position - keep it stable
+                }
+            }
+            // Mouse moved far from tooltip - update position
+            setPosition({ x: e.clientX, y: e.clientY });
+            // Clear stable position so it recalculates
+            setStablePosition(null);
+        };
+        window.addEventListener("mousemove", updatePosition);
+        return () => window.removeEventListener("mousemove", updatePosition);
+    }, [isInspectionActive, isLocked, hoveredElement, stablePosition]);
+    // If no component metadata but we have an element, create basic metadata
+    const displayComponent = hoveredComponent || (hoveredElement ? {
+        componentName: hoveredElement.tagName.toLowerCase(),
+        componentId: hoveredElement.id || "no-id",
+        usagePath: "DOM Element",
+        instanceIndex: 0,
+        propsSignature: "default",
+        sourceFile: "DOM",
+    } : null);
+    // Calculate adjusted position to avoid going off-screen
+    // Use stable position if available, otherwise calculate from cursor position
+    const adjustedPosition = useMemo(() => {
+        if (!displayComponent) {
+            return { x: position.x + 15, y: position.y + 15 };
+        }
+        // If we have a stable position, use it (don't recalculate)
+        if (stablePosition) {
+            return stablePosition;
+        }
+        // Calculate new position from cursor (only when stablePosition is null)
+        const padding = 10;
+        let x = position.x + 15;
+        let y = position.y + 15;
+        // Adjust if tooltip would go off right edge (estimate width)
+        const estimatedWidth = 400; // Approximate tooltip width
+        if (x + estimatedWidth > window.innerWidth - padding) {
+            x = position.x - estimatedWidth - 15;
+        }
+        // Adjust if tooltip would go off bottom edge (estimate height)
+        const estimatedHeight = 200; // Approximate tooltip height
+        if (y + estimatedHeight > window.innerHeight - padding) {
+            y = position.y - estimatedHeight - 15;
+        }
+        // Adjust if tooltip would go off left edge
+        if (x < padding) {
+            x = padding;
+        }
+        // Adjust if tooltip would go off top edge
+        if (y < padding) {
+            y = padding;
+        }
+        return { x, y };
+    }, [position, displayComponent, stablePosition]);
+    // Set stable position once when tooltip first appears for a new element, or when locked
+    const lastComponentIdRef = useRef(null);
+    useEffect(() => {
+        const currentComponentId = displayComponent?.componentId || null;
+        // When locked, ensure we have a stable position
+        if (isLocked && !stablePosition && displayComponent && adjustedPosition.x > 0 && adjustedPosition.y > 0) {
+            setStablePosition(adjustedPosition);
+            return;
+        }
+        // Only set stable position when component changes or when we don't have one yet
+        if (currentComponentId !== lastComponentIdRef.current && !stablePosition && displayComponent && adjustedPosition.x > 0 && adjustedPosition.y > 0) {
+            lastComponentIdRef.current = currentComponentId;
+            // Set stable position after a small delay to ensure tooltip is rendered
+            const timer = setTimeout(() => {
+                setStablePosition(adjustedPosition);
+            }, 50);
+            return () => clearTimeout(timer);
+        }
+    }, [displayComponent?.componentId, adjustedPosition, stablePosition, displayComponent, isLocked]);
+    const handleCopy = async () => {
+        if (!displayComponent || !hoveredElement)
+            return;
+        const text = formatMetadataForClipboard(displayComponent, hoveredElement);
+        try {
+            await navigator.clipboard.writeText(text);
+            setCopied(true);
+            setTimeout(() => setCopied(false), 2000);
+        }
+        catch (err) {
+            console.error("Failed to copy:", err);
+        }
+    };
+    // Reset stable position when element changes (but not when locked)
+    useEffect(() => {
+        if (!isLocked) {
+            setStablePosition(null);
+        }
+    }, [hoveredElement, isLocked]);
+    // Show tooltip for any hovered element when CTRL is held
+    if (!isInspectionActive || !displayComponent) {
+        return null;
+    }
+    return (_jsxs(Paper, { ref: tooltipRef, elevation: 8, sx: {
+            position: "fixed",
+            left: stablePosition?.x ?? adjustedPosition.x,
+            top: stablePosition?.y ?? adjustedPosition.y,
+            zIndex: 999999,
+            minWidth: 300,
+            maxWidth: 500,
+            p: 1.5,
+            pointerEvents: "auto",
+            backgroundColor: "rgba(18, 18, 18, 0.95)",
+            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" }), isLocked && (_jsx(Typography, { variant: "caption", sx: { color: "#4caf50", fontSize: "0.7rem", fontStyle: "italic" }, children: "(Locked - Release CTRL to unlock)" }))] }), _jsx(MuiTooltip, { title: copied ? "Copied!" : "Copy metadata", children: _jsx(IconButton, { size: "small", onClick: handleCopy, sx: {
+                                color: copied ? "#4caf50" : "#fff",
+                                "&:hover": { backgroundColor: "rgba(255, 255, 255, 0.1)" },
+                                p: 0.5,
+                            }, children: _jsx(ContentCopyIcon, { fontSize: "small" }) }) })] }), _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 })] })] }));
+};

package/dist/InspectionWrapper.d.ts

@@ -0,0 +1,28 @@
+import React, { ReactElement, ComponentType } from "react";
+/**
+ * Props for InspectionWrapper
+ */
+interface InspectionWrapperProps {
+    componentName: string;
+    variant?: string;
+    role?: string;
+    usagePath: string;
+    props: Record<string, any>;
+    sourceFile: string;
+    children: ReactElement;
+}
+/**
+ * Wrapper component that adds inspection metadata to a component
+ */
+export declare const InspectionWrapper: React.FC<InspectionWrapperProps>;
+/**
+ * HOC to wrap a component with inspection capabilities
+ */
+export declare function withInspection<P extends object>(Component: ComponentType<P>, inspectionConfig: {
+    componentName: string;
+    variant?: string;
+    role?: string;
+    getUsagePath: (props: P) => string;
+    getSourceFile: () => string;
+}): ComponentType<P>;
+export {};

package/dist/InspectionWrapper.js

@@ -0,0 +1,68 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import React from "react";
+import { useInspection } from "./InspectionContext";
+import { generateComponentId, formatPropsSignature, getComponentName, getNextInstanceIndex, } from "./inspection";
+/**
+ * Wrapper component that adds inspection metadata to a component
+ */
+export const InspectionWrapper = ({ componentName, variant, role, usagePath, props, sourceFile, children, }) => {
+    const { isInspectionActive, setHoveredComponent } = useInspection();
+    const instanceIndex = React.useMemo(() => getNextInstanceIndex(componentName), [componentName]);
+    const handleMouseEnter = (e) => {
+        if (!isInspectionActive)
+            return;
+        const target = e.currentTarget;
+        const metadata = {
+            componentName,
+            componentId: generateComponentId(componentName, instanceIndex),
+            variant,
+            role,
+            usagePath,
+            instanceIndex,
+            propsSignature: formatPropsSignature(props),
+            sourceFile,
+        };
+        setHoveredComponent(metadata, target);
+    };
+    const handleMouseLeave = () => {
+        if (!isInspectionActive)
+            return;
+        setHoveredComponent(null, null);
+    };
+    // Clone the child element and add inspection handlers
+    if (!React.isValidElement(children)) {
+        return _jsx(_Fragment, { children: children });
+    }
+    const existingProps = (children.props || {});
+    const existingOnMouseEnter = existingProps.onMouseEnter;
+    const existingOnMouseLeave = existingProps.onMouseLeave;
+    const childWithProps = React.cloneElement(children, {
+        onMouseEnter: (e) => {
+            handleMouseEnter(e);
+            if (existingOnMouseEnter) {
+                existingOnMouseEnter(e);
+            }
+        },
+        onMouseLeave: (e) => {
+            handleMouseLeave();
+            if (existingOnMouseLeave) {
+                existingOnMouseLeave(e);
+            }
+        },
+        "data-inspection-id": generateComponentId(componentName, instanceIndex),
+        "data-inspection-name": componentName,
+    });
+    return _jsx(_Fragment, { children: childWithProps });
+};
+/**
+ * HOC to wrap a component with inspection capabilities
+ */
+export function withInspection(Component, inspectionConfig) {
+    const WrappedComponent = (props) => {
+        const usagePath = inspectionConfig.getUsagePath(props);
+        const sourceFile = inspectionConfig.getSourceFile();
+        return (_jsx(InspectionWrapper, { componentName: inspectionConfig.componentName, variant: inspectionConfig.variant, role: inspectionConfig.role, usagePath: usagePath, props: props, sourceFile: sourceFile, children: _jsx(Component, { ...props }) }));
+    };
+    WrappedComponent.displayName = `withInspection(${getComponentName(Component)})`;
+    return WrappedComponent;
+}

package/dist/autoInspection.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Automatic inspection detection via data attributes
+ * Components can add data-inspection-* attributes and the system will detect them automatically
+ */
+import { ComponentMetadata } from "./InspectionContext";
+/**
+ * Parse component metadata from data attributes or infer from element
+ */
+export declare const parseInspectionMetadata: (element: HTMLElement) => ComponentMetadata | null;
+/**
+ * Setup global mouse event listener for automatic inspection detection
+ * This works with components that have data-inspection-* attributes
+ */
+export declare const setupAutoInspection: (setHoveredComponent: (metadata: ComponentMetadata | null, element: HTMLElement | null) => void, isInspectionActive: boolean, isLocked: boolean) => (() => void);

package/dist/autoInspection.js

@@ -0,0 +1,258 @@
+/**
+ * Automatic inspection detection via data attributes
+ * Components can add data-inspection-* attributes and the system will detect them automatically
+ */
+/**
+ * Extract basic element info for inspection
+ */
+const extractElementInfo = (element) => {
+    const tagName = element.tagName.toLowerCase();
+    // Convert className to string - it can be a DOMTokenList or string
+    let className = "";
+    if (typeof element.className === "string") {
+        className = element.className;
+    }
+    else if (element.className) {
+        // DOMTokenList - convert to string
+        className = String(element.className);
+    }
+    const id = element.id || "";
+    // Extract text preview (first 50 chars)
+    const textContent = element.textContent || "";
+    const textPreview = textContent.trim().substring(0, 50).replace(/\s+/g, " ");
+    // Try to detect MUI components from class names
+    let muiComponent;
+    if (className && typeof className === "string" && className.includes("Mui")) {
+        const muiMatch = className.match(/Mui(\w+)/);
+        if (muiMatch) {
+            muiComponent = muiMatch[1];
+        }
+    }
+    return { tagName, className, id, textPreview, muiComponent };
+};
+/**
+ * Parse component metadata from data attributes or infer from element
+ */
+export const parseInspectionMetadata = (element) => {
+    if (process.env.NODE_ENV !== "development") {
+        return null;
+    }
+    // First, try to find explicit inspection metadata
+    const componentName = element.getAttribute("data-inspection-name");
+    const componentId = element.getAttribute("data-inspection-id");
+    if (componentName && componentId) {
+        // Has explicit metadata - use it
+        const variant = element.getAttribute("data-inspection-variant") || undefined;
+        const role = element.getAttribute("data-inspection-role") || undefined;
+        const usagePath = element.getAttribute("data-inspection-usage-path") || "Unknown";
+        const instanceIndex = parseInt(element.getAttribute("data-inspection-instance") || "0", 10);
+        const propsSignature = element.getAttribute("data-inspection-props") || "default";
+        const sourceFile = element.getAttribute("data-inspection-file") || "Unknown";
+        return {
+            componentName,
+            componentId,
+            variant,
+            role,
+            usagePath,
+            instanceIndex,
+            propsSignature,
+            sourceFile,
+        };
+    }
+    // No explicit metadata - infer from element
+    const info = extractElementInfo(element);
+    // Generate component name
+    let inferredName = info.muiComponent || info.tagName.toUpperCase();
+    if (info.id) {
+        inferredName = `${inferredName} (${info.id})`;
+    }
+    else if (info.className) {
+        // Try to extract meaningful class name
+        const classes = info.className.split(/\s+/).filter(c => c && !c.startsWith("Mui") && c.length > 2);
+        if (classes.length > 0) {
+            inferredName = `${inferredName} .${classes[0]}`;
+        }
+    }
+    // Generate component ID - use deterministic hash based on element's position in DOM tree
+    // This ensures the same element always gets the same ID, even without explicit metadata
+    const generateDeterministicId = (el, tagName) => {
+        if (info.id) {
+            return info.id;
+        }
+        // Create a stable identifier based on element's path in DOM tree
+        const path = [];
+        let current = el;
+        // Walk up to body, collecting tag names and indices
+        while (current && current !== document.body && current !== document.documentElement) {
+            const currentTagName = current.tagName.toLowerCase();
+            const parent = current.parentElement;
+            if (parent) {
+                // Get index among siblings with same tag name
+                const siblings = Array.from(parent.children).filter((child) => child.tagName.toLowerCase() === currentTagName);
+                const index = siblings.indexOf(current);
+                path.unshift(`${currentTagName}[${index}]`);
+            }
+            else {
+                path.unshift(currentTagName);
+            }
+            current = parent;
+        }
+        // Create hash from path (simple hash function)
+        const pathString = path.join('>');
+        let hash = 0;
+        for (let i = 0; i < pathString.length; i++) {
+            const char = pathString.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32-bit integer
+        }
+        // Convert to positive hex string (6 chars)
+        const hashStr = Math.abs(hash).toString(36).substr(0, 6);
+        return `${tagName}-${hashStr}`;
+    };
+    const inferredId = generateDeterministicId(element, info.tagName);
+    // Build props signature from attributes
+    const props = [];
+    if (info.id)
+        props.push(`id=${info.id}`);
+    if (info.className) {
+        const classCount = info.className.split(/\s+/).length;
+        props.push(`classes=${classCount}`);
+    }
+    const propsSignature = props.length > 0 ? props.join(", ") : "default";
+    return {
+        componentName: inferredName,
+        componentId: inferredId,
+        variant: info.muiComponent ? info.muiComponent.toLowerCase() : undefined,
+        role: element.getAttribute("role") || element.getAttribute("aria-label") || undefined,
+        usagePath: "DOM Element",
+        instanceIndex: 0,
+        propsSignature,
+        sourceFile: "DOM",
+    };
+};
+/**
+ * Setup global mouse event listener for automatic inspection detection
+ * This works with components that have data-inspection-* attributes
+ */
+export const setupAutoInspection = (setHoveredComponent, isInspectionActive, isLocked) => {
+    if (process.env.NODE_ENV !== "development") {
+        return () => { }; // No-op in production
+    }
+    const handleMouseMove = (e) => {
+        if (!isInspectionActive) {
+            return;
+        }
+        // If locked, don't update on mouse move - keep current tooltip fixed
+        if (isLocked) {
+            return;
+        }
+        const target = e.target;
+        if (!target || !document.body.contains(target)) {
+            return;
+        }
+        // Always show inspection for any element (not just ones with metadata)
+        // Walk up the DOM tree to find a meaningful element to inspect
+        let current = target;
+        let bestElement = null;
+        let bestMetadata = null;
+        let elementWithExplicitMetadata = null;
+        let metadataWithExplicitId = null;
+        // Skip text nodes and very small elements
+        const isMeaningfulElement = (el) => {
+            const rect = el.getBoundingClientRect();
+            // Skip elements that are too small (likely text nodes or empty spans)
+            if (rect.width < 5 && rect.height < 5) {
+                return false;
+            }
+            // Prefer elements with explicit metadata, IDs, or meaningful classes
+            return !!(el.getAttribute("data-inspection-name") ||
+                el.id ||
+                el.className ||
+                el.tagName !== "SPAN" && el.tagName !== "DIV");
+        };
+        // First pass: Look for elements with explicit inspection metadata
+        // This ensures we always find the same component regardless of which child is hovered
+        while (current) {
+            // Ensure element is still in the DOM
+            if (!document.body.contains(current)) {
+                break;
+            }
+            // Check if this element has explicit inspection metadata
+            const hasExplicitMetadata = current.getAttribute("data-inspection-name") &&
+                current.getAttribute("data-inspection-id");
+            if (hasExplicitMetadata) {
+                const metadata = parseInspectionMetadata(current);
+                if (metadata) {
+                    elementWithExplicitMetadata = current;
+                    metadataWithExplicitId = metadata;
+                    break; // Found explicit metadata, use it
+                }
+            }
+            current = current.parentElement;
+            // Stop at body to avoid inspecting the entire page
+            if (current && (current.tagName === "BODY" || current.tagName === "HTML")) {
+                break;
+            }
+        }
+        // If we found explicit metadata, use it (this ensures consistent IDs)
+        if (elementWithExplicitMetadata && metadataWithExplicitId) {
+            if (process.env.NODE_ENV === "development") {
+                console.log("[Inspection] Found element with explicit metadata:", metadataWithExplicitId.componentName);
+            }
+            setHoveredComponent(metadataWithExplicitId, elementWithExplicitMetadata);
+            return;
+        }
+        // Second pass: If no explicit metadata found, look for meaningful elements
+        // Reset current to target for second pass
+        current = target;
+        while (current) {
+            // Ensure element is still in the DOM
+            if (!document.body.contains(current)) {
+                break;
+            }
+            // Check if this is a meaningful element
+            if (isMeaningfulElement(current)) {
+                const metadata = parseInspectionMetadata(current);
+                if (metadata) {
+                    // Keep the first meaningful element (closest to target)
+                    if (!bestElement) {
+                        bestElement = current;
+                        bestMetadata = metadata;
+                    }
+                }
+            }
+            current = current.parentElement;
+            // Stop at body to avoid inspecting the entire page
+            if (current && (current.tagName === "BODY" || current.tagName === "HTML")) {
+                break;
+            }
+        }
+        if (bestElement && bestMetadata) {
+            if (process.env.NODE_ENV === "development") {
+                console.log("[Inspection] Found element:", bestMetadata.componentName);
+            }
+            setHoveredComponent(bestMetadata, bestElement);
+        }
+        else {
+            // Fallback: show info for the target element itself
+            const fallbackMetadata = parseInspectionMetadata(target);
+            if (fallbackMetadata) {
+                setHoveredComponent(fallbackMetadata, target);
+            }
+            else {
+                setHoveredComponent(null, null);
+            }
+        }
+    };
+    const handleMouseLeave = () => {
+        if (isInspectionActive && !isLocked) {
+            setHoveredComponent(null, null);
+        }
+    };
+    window.addEventListener("mousemove", handleMouseMove);
+    document.addEventListener("mouseleave", handleMouseLeave);
+    return () => {
+        window.removeEventListener("mousemove", handleMouseMove);
+        document.removeEventListener("mouseleave", handleMouseLeave);
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { InspectionProvider, useInspection, ComponentMetadata } from './InspectionContext';
+export { InspectionTooltip } from './InspectionTooltip';
+export { InspectionHighlight } from './InspectionHighlight';
+export { InspectionWrapper, withInspection } from './InspectionWrapper';
+export { useInspectionMetadata } from './useInspectionMetadata';
+export { setupInterceptors, setInspectionActive, shouldBlockRequest } from './inspectionInterceptors';
+export { generateComponentId, formatPropsSignature, formatMetadataForClipboard, getComponentName, getNextInstanceIndex } from './inspection';
+export { setupAutoInspection, parseInspectionMetadata } from './autoInspection';

package/dist/index.js

@@ -0,0 +1,9 @@
+// Main exports
+export { InspectionProvider, useInspection } from './InspectionContext';
+export { InspectionTooltip } from './InspectionTooltip';
+export { InspectionHighlight } from './InspectionHighlight';
+export { InspectionWrapper, withInspection } from './InspectionWrapper';
+export { useInspectionMetadata } from './useInspectionMetadata';
+export { setupInterceptors, setInspectionActive, shouldBlockRequest } from './inspectionInterceptors';
+export { generateComponentId, formatPropsSignature, formatMetadataForClipboard, getComponentName, getNextInstanceIndex } from './inspection';
+export { setupAutoInspection, parseInspectionMetadata } from './autoInspection';

package/dist/inspection.d.ts

@@ -0,0 +1,29 @@
+import { ComponentMetadata } from "./InspectionContext";
+/**
+ * Generate a unique component ID
+ */
+export declare const generateComponentId: (componentName: string, instanceIndex: number) => string;
+/**
+ * Format props signature for display
+ */
+export declare const formatPropsSignature: (props: Record<string, any>) => string;
+/**
+ * Get component name from component type
+ */
+export declare const getComponentName: (component: React.ComponentType<any> | string) => string;
+/**
+ * Build usage path from component hierarchy
+ */
+export declare const buildUsagePath: (hierarchy: string[]) => string;
+/**
+ * Format metadata for clipboard with full element details
+ */
+export declare const formatMetadataForClipboard: (metadata: ComponentMetadata, element: HTMLElement) => string;
+/**
+ * Get next instance index for a component
+ */
+export declare const getNextInstanceIndex: (componentName: string) => number;
+/**
+ * Reset instance counts (useful for testing or remounting)
+ */
+export declare const resetInstanceCounts: () => void;