@linhey/react-debug-inspector 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 linhay
+
+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,11 +1,38 @@
 # @linhey/react-debug-inspector 🎯
 
+[![CI](https://github.com/linhay/react-debug-inspector/actions/workflows/ci.yml/badge.svg)](https://github.com/linhay/react-debug-inspector/actions/workflows/ci.yml)
+[![NPM Version](https://img.shields.io/npm/v/@linhey/react-debug-inspector)](https://www.npmjs.com/package/@linhey/react-debug-inspector)
+[![NPM Downloads](https://img.shields.io/npm/dm/@linhey/react-debug-inspector)](https://www.npmjs.com/package/@linhey/react-debug-inspector)
+[![License](https://img.shields.io/npm/l/@linhey/react-debug-inspector)](https://github.com/linhay/react-debug-inspector/blob/main/LICENSE)
+[![repo](https://img.shields.io/badge/github-linhay%2Freact--debug--inspector-181717?logo=github)](https://github.com/linhay/react-debug-inspector)
+
 一个轻量级的 React 调试辅助工具，让你在浏览器中直接识别组件、标签及其对应的源码行号。
 
+## 🎬 演示
+
+### 在线演示
+
+🌐 **[在线体验 Demo](https://linhay.github.io/react-debug-inspector/)**
+
+> GitHub Pages 配置说明见 [GITHUB_PAGES.md](./pages/GITHUB_PAGES.md)
+
+### 快速预览
+
+1. 点击右下角的 🎯 按钮进入检查模式
+2. 鼠标悬停在任何元素上查看调试信息
+3. 点击元素复制完整的调试标识
+4. 按 `Esc` 键退出检查模式
+
+<!-- TODO: 添加演示 GIF -->
+<!-- ![基本使用演示](./assets/demo-basic.gif) -->
+
+> 📹 查看 [录制指南](./RECORDING_GUIDE.md) 了解如何制作演示视频
+
 ## 特性
 
 - 🚀 **零配置注入**：通过 Babel 插件自动为每个 JSX 元素添加 `data-debug` 属性。
 - 🎯 **瞄准模式**：悬浮显示元素标识，单击一键复制。
+- 📁 **完整路径**：显示文件路径、组件名、标签名和行号，精确定位源码。
 - 🌳 **零污染**：生产环境构建时自动剔除，不增加包体积。
 - ⌨️ **快捷键支持**：支持 Esc 退出及 Alt+右键 快速复制。
 
@@ -49,11 +76,53 @@ if (import.meta.env.DEV) {
 ## 交互说明
 
 - **🎯 按钮**：位于右下角，点击进入/退出审查模式。
-- **悬浮模式**：进入模式后，鼠标指向的元素将被高亮，并显示 `组件:标签:行号`。
-- **单击左键**：复制标识到剪贴板并退出。
+- **悬浮模式**：进入模式后，鼠标指向的元素将被高亮，并显示 `文件名 › 组件 › 标签:行号`。
+- **单击左键**：复制完整标识（`文件路径:组件:标签:行号`）到剪贴板并退出。
 - **Esc**：退出模式。
 - **Alt + 右键**：非模式下亦可直接复制标识。
 
+## 输出格式
+
+复制到剪贴板的格式为：`src/components/Button.tsx:Button:button:42`
+
+- `src/components/Button.tsx` - 文件相对路径
+- `Button` - 组件名
+- `button` - HTML 标签名
+- `42` - 源码行号
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 运行单元测试
+npm test
+
+# 运行 E2E 测试
+npm run test:e2e
+
+# 运行所有测试
+npm run test:all
+
+# 构建
+npm run build
+
+# 开发模式
+npm run dev
+```
+
+## 发布
+
+本项目使用 GitHub Actions 自动化发布流程。详见 [GITHUB_ACTIONS.md](./GITHUB_ACTIONS.md)。
+
+### 快速发布
+
+1. 进入 GitHub Actions 页面
+2. 选择 "Version Bump and Release" 工作流
+3. 点击 "Run workflow"，选择版本类型（patch/minor/major）
+4. 自动完成测试、构建、发布到 NPM
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -1,7 +1,6 @@
 declare function babelPluginDebugLabel(): {
     visitor: {
-        FunctionDeclaration(path: any): void;
-        VariableDeclarator(path: any): void;
+        Program(programPath: any, state: any): void;
     };
 };
 

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 declare function babelPluginDebugLabel(): {
     visitor: {
-        FunctionDeclaration(path: any): void;
-        VariableDeclarator(path: any): void;
+        Program(programPath: any, state: any): void;
     };
 };
 

package/dist/index.js

@@ -29,28 +29,42 @@ module.exports = __toCommonJS(index_exports);
 function babelPluginDebugLabel() {
   return {
     visitor: {
-      FunctionDeclaration(path) {
-        const name = path.node.id?.name;
-        if (!name || name[0] !== name[0].toUpperCase()) return;
-        injectAllJSX(path, name);
-      },
-      VariableDeclarator(path) {
-        const name = path.node.id?.name;
-        if (!name || name[0] !== name[0].toUpperCase()) return;
-        const init = path.node.init;
-        if (init && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")) {
-          injectAllJSX(path.get("init"), name);
-        }
+      Program(programPath, state) {
+        const filename = state.file.opts.filename || state.filename || "";
+        const cwd = state.cwd || (typeof process !== "undefined" ? process.cwd() : "");
+        const getRelativePath = (absolutePath) => {
+          if (!absolutePath) return "unknown";
+          if (absolutePath.startsWith(cwd)) {
+            return absolutePath.slice(cwd.length + 1);
+          }
+          return absolutePath;
+        };
+        const relativePath = getRelativePath(filename);
+        programPath.traverse({
+          FunctionDeclaration(path) {
+            const name = path.node.id?.name;
+            if (!name || name[0] !== name[0].toUpperCase()) return;
+            injectAllJSX(path, name, relativePath);
+          },
+          VariableDeclarator(path) {
+            const name = path.node.id?.name;
+            if (!name || name[0] !== name[0].toUpperCase()) return;
+            const init = path.node.init;
+            if (init && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")) {
+              injectAllJSX(path.get("init"), name, relativePath);
+            }
+          }
+        });
       }
     }
   };
-  function injectAllJSX(path, componentName) {
+  function injectAllJSX(path, componentName, filePath) {
     path.traverse({
       JSXElement(jsxPath) {
         const { openingElement } = jsxPath.node;
         const tagName = getTagName(openingElement.name);
         const line = openingElement.loc?.start.line || "0";
-        const debugId = `${componentName}:${tagName}:${line}`;
+        const debugId = `${filePath}:${componentName}:${tagName}:${line}`;
         const alreadyHas = openingElement.attributes.some(
           (attr) => attr.type === "JSXAttribute" && attr.name?.name === "data-debug"
         );
@@ -76,6 +90,16 @@ function babelPluginDebugLabel() {
 function initInspector() {
   if (typeof window === "undefined") return;
   let isInspecting = false;
+  let hasUserPosition = false;
+  let isDragging = false;
+  let pointerMoved = false;
+  let dragOffsetX = 0;
+  let dragOffsetY = 0;
+  let dragStartX = 0;
+  let dragStartY = 0;
+  let overlay = null;
+  let tooltip = null;
+  const edgeOffset = 24;
   const toggleBtn = document.createElement("button");
   toggleBtn.innerHTML = "\u{1F3AF}";
   toggleBtn.title = "\u5F00\u542F\u7EC4\u4EF6\u5B9A\u4F4D\u5668";
@@ -99,7 +123,111 @@ function initInspector() {
     transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
   `;
   document.body.appendChild(toggleBtn);
-  const overlay = document.createElement("div");
+  const applyAnchor = (anchor) => {
+    if (hasUserPosition) return;
+    toggleBtn.style.top = anchor.startsWith("top") ? `${edgeOffset}px` : "";
+    toggleBtn.style.bottom = anchor.startsWith("bottom") ? `${edgeOffset}px` : "";
+    if (anchor.endsWith("left")) {
+      toggleBtn.style.left = `${edgeOffset}px`;
+      toggleBtn.style.right = "";
+      return;
+    }
+    toggleBtn.style.right = `${edgeOffset}px`;
+    toggleBtn.style.left = "";
+  };
+  const getVisibleDialogs = () => {
+    if (typeof document === "undefined") return [];
+    const candidates = Array.from(
+      document.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]')
+    );
+    return candidates.filter((node) => {
+      if (node.getAttribute("aria-hidden") === "true") return false;
+      if (node.getAttribute("data-aria-hidden") === "true") return false;
+      const style = window.getComputedStyle(node);
+      return style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0";
+    });
+  };
+  const ensureToggleHost = (host) => {
+    if (toggleBtn.parentElement !== host) {
+      host.appendChild(toggleBtn);
+    }
+  };
+  const isIgnorableObstacle = (el) => {
+    if (el === toggleBtn || el === overlay || el === tooltip) return true;
+    if (el instanceof HTMLElement) {
+      if (el.contains(toggleBtn) || toggleBtn.contains(el)) return true;
+      if (overlay && el.contains(overlay)) return true;
+      if (tooltip && el.contains(tooltip)) return true;
+      if (el === document.body || el === document.documentElement) return true;
+      if (el.getAttribute("data-inspector-ignore") === "true") return true;
+      const style = window.getComputedStyle(el);
+      if (style.pointerEvents === "none") return true;
+      if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") return true;
+    }
+    return false;
+  };
+  const sampleAnchorObstructionScore = () => {
+    const pickStack = typeof document.elementsFromPoint === "function" ? (x, y) => document.elementsFromPoint(x, y) : (x, y) => {
+      const one = document.elementFromPoint?.(x, y);
+      return one ? [one] : [];
+    };
+    const rect = toggleBtn.getBoundingClientRect();
+    const points = [
+      [rect.left + rect.width / 2, rect.top + rect.height / 2],
+      [rect.left + 2, rect.top + 2],
+      [rect.right - 2, rect.top + 2],
+      [rect.left + 2, rect.bottom - 2],
+      [rect.right - 2, rect.bottom - 2]
+    ];
+    let score = 0;
+    for (const [x, y] of points) {
+      const stack = pickStack(x, y);
+      const blocker = stack.find((el) => !isIgnorableObstacle(el));
+      if (blocker) score += 1;
+    }
+    return score;
+  };
+  const pickBestAnchor = (preferLeft = false) => {
+    const candidates = preferLeft ? ["bottom-left", "top-left", "bottom-right", "top-right"] : ["bottom-right", "top-right", "bottom-left", "top-left"];
+    let best = candidates[0];
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const anchor of candidates) {
+      applyAnchor(anchor);
+      const score = sampleAnchorObstructionScore();
+      if (score < bestScore) {
+        bestScore = score;
+        best = anchor;
+      }
+      if (score === 0) break;
+    }
+    applyAnchor(best);
+  };
+  const updateAnchorForDialogs = () => {
+    if (typeof document === "undefined") return;
+    const dialogs = getVisibleDialogs();
+    if (dialogs.length > 0) {
+      ensureToggleHost(dialogs[dialogs.length - 1]);
+      pickBestAnchor(true);
+      return;
+    }
+    ensureToggleHost(document.body);
+    pickBestAnchor(false);
+  };
+  let anchorUpdatePending = false;
+  const scheduleAnchorUpdate = () => {
+    if (typeof window === "undefined") return;
+    if (anchorUpdatePending) return;
+    anchorUpdatePending = true;
+    const schedule = typeof window.requestAnimationFrame === "function" ? window.requestAnimationFrame.bind(window) : (cb) => window.setTimeout(() => cb(Date.now()), 16);
+    schedule(() => {
+      anchorUpdatePending = false;
+      updateAnchorForDialogs();
+    });
+  };
+  const dialogObserver = new MutationObserver(() => {
+    scheduleAnchorUpdate();
+  });
+  overlay = document.createElement("div");
   overlay.style.cssText = `
     position: fixed;
     pointer-events: none;
@@ -110,10 +238,10 @@ function initInspector() {
     transition: all 0.1s ease-out;
   `;
   document.body.appendChild(overlay);
-  const tooltip = document.createElement("div");
+  tooltip = document.createElement("div");
   tooltip.style.cssText = `
     position: fixed;
-    pointer-events: none;
+    pointer-events: auto;
     z-index: 9999999;
     background: #1e293b;
     color: #38bdf8;
@@ -126,8 +254,19 @@ function initInspector() {
     display: none;
     white-space: nowrap;
     transition: all 0.1s ease-out;
+    cursor: help;
   `;
   document.body.appendChild(tooltip);
+  dialogObserver.observe(document.body, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: ["style", "class", "open", "aria-hidden"]
+  });
+  window.addEventListener("beforeunload", () => dialogObserver.disconnect(), { once: true });
+  window.addEventListener("resize", scheduleAnchorUpdate);
+  window.addEventListener("scroll", scheduleAnchorUpdate, true);
+  updateAnchorForDialogs();
   const stopInspecting = () => {
     isInspecting = false;
     toggleBtn.style.transform = "scale(1)";
@@ -136,7 +275,44 @@ function initInspector() {
     overlay.style.display = "none";
     tooltip.style.display = "none";
   };
-  toggleBtn.onclick = () => {
+  const onPointerMove = (e) => {
+    if (!isDragging) return;
+    const deltaX = Math.abs(e.clientX - dragStartX);
+    const deltaY = Math.abs(e.clientY - dragStartY);
+    if (deltaX > 3 || deltaY > 3) {
+      pointerMoved = true;
+    }
+    const left = Math.max(8, Math.min(window.innerWidth - 52, e.clientX - dragOffsetX));
+    const top = Math.max(8, Math.min(window.innerHeight - 52, e.clientY - dragOffsetY));
+    toggleBtn.style.left = `${left}px`;
+    toggleBtn.style.top = `${top}px`;
+    toggleBtn.style.right = "";
+    toggleBtn.style.bottom = "";
+    hasUserPosition = true;
+  };
+  const onPointerUp = () => {
+    isDragging = false;
+    window.removeEventListener("mousemove", onPointerMove);
+    window.removeEventListener("mouseup", onPointerUp);
+  };
+  toggleBtn.addEventListener("mousedown", (e) => {
+    const rect = toggleBtn.getBoundingClientRect();
+    isDragging = true;
+    pointerMoved = false;
+    dragStartX = e.clientX;
+    dragStartY = e.clientY;
+    dragOffsetX = e.clientX - rect.left;
+    dragOffsetY = e.clientY - rect.top;
+    window.addEventListener("mousemove", onPointerMove);
+    window.addEventListener("mouseup", onPointerUp);
+  });
+  toggleBtn.onclick = (e) => {
+    if (pointerMoved) {
+      e.preventDefault();
+      e.stopPropagation();
+      pointerMoved = false;
+      return;
+    }
     isInspecting = !isInspecting;
     if (isInspecting) {
       toggleBtn.style.transform = "scale(0.9)";
@@ -146,11 +322,21 @@ function initInspector() {
       stopInspecting();
     }
   };
-  window.addEventListener("mousemove", (e) => {
+  const formatDebugId = (debugId) => {
+    const parts = debugId.split(":");
+    if (parts.length === 4) {
+      const [filePath, componentName, tagName, line] = parts;
+      const fileName = filePath.split("/").pop() || filePath;
+      return `${fileName} \u203A ${componentName} \u203A ${tagName}:${line}`;
+    }
+    return debugId.replace(/:/g, " \u203A ");
+  };
+  const inspectByPointer = (e) => {
     if (!isInspecting) return;
     const target = e.target;
     if (target === toggleBtn || target === overlay || target === tooltip) return;
     const debugEl = target.closest("[data-debug]");
+    if (debugEl && debugEl === lastHoveredDebugEl) return;
     if (debugEl) {
       const debugId = debugEl.getAttribute("data-debug") || "";
       const rect = debugEl.getBoundingClientRect();
@@ -160,15 +346,33 @@ function initInspector() {
       overlay.style.width = rect.width + "px";
       overlay.style.height = rect.height + "px";
       tooltip.style.display = "block";
-      tooltip.textContent = debugId;
+      tooltip.textContent = formatDebugId(debugId);
       tooltip.style.color = "#38bdf8";
+      tooltip.title = debugId;
       const tooltipY = rect.top < 30 ? rect.bottom + 4 : rect.top - 28;
       tooltip.style.top = tooltipY + "px";
       tooltip.style.left = rect.left + "px";
+      lastHoveredDebugEl = debugEl;
     } else {
       overlay.style.display = "none";
       tooltip.style.display = "none";
+      lastHoveredDebugEl = null;
     }
+  };
+  let pendingHoverFrame = false;
+  let latestHoverEvent = null;
+  let lastHoveredDebugEl = null;
+  document.addEventListener("mousemove", (e) => {
+    if (!isInspecting) return;
+    latestHoverEvent = e;
+    if (pendingHoverFrame) return;
+    pendingHoverFrame = true;
+    const schedule = typeof window.requestAnimationFrame === "function" ? window.requestAnimationFrame.bind(window) : (cb) => window.setTimeout(() => cb(Date.now()), 16);
+    schedule(() => {
+      pendingHoverFrame = false;
+      if (!latestHoverEvent) return;
+      inspectByPointer(latestHoverEvent);
+    });
   });
   window.addEventListener(
     "click",

package/dist/index.mjs

@@ -2,28 +2,42 @@
 function babelPluginDebugLabel() {
   return {
     visitor: {
-      FunctionDeclaration(path) {
-        const name = path.node.id?.name;
-        if (!name || name[0] !== name[0].toUpperCase()) return;
-        injectAllJSX(path, name);
-      },
-      VariableDeclarator(path) {
-        const name = path.node.id?.name;
-        if (!name || name[0] !== name[0].toUpperCase()) return;
-        const init = path.node.init;
-        if (init && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")) {
-          injectAllJSX(path.get("init"), name);
-        }
+      Program(programPath, state) {
+        const filename = state.file.opts.filename || state.filename || "";
+        const cwd = state.cwd || (typeof process !== "undefined" ? process.cwd() : "");
+        const getRelativePath = (absolutePath) => {
+          if (!absolutePath) return "unknown";
+          if (absolutePath.startsWith(cwd)) {
+            return absolutePath.slice(cwd.length + 1);
+          }
+          return absolutePath;
+        };
+        const relativePath = getRelativePath(filename);
+        programPath.traverse({
+          FunctionDeclaration(path) {
+            const name = path.node.id?.name;
+            if (!name || name[0] !== name[0].toUpperCase()) return;
+            injectAllJSX(path, name, relativePath);
+          },
+          VariableDeclarator(path) {
+            const name = path.node.id?.name;
+            if (!name || name[0] !== name[0].toUpperCase()) return;
+            const init = path.node.init;
+            if (init && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")) {
+              injectAllJSX(path.get("init"), name, relativePath);
+            }
+          }
+        });
       }
     }
   };
-  function injectAllJSX(path, componentName) {
+  function injectAllJSX(path, componentName, filePath) {
     path.traverse({
       JSXElement(jsxPath) {
         const { openingElement } = jsxPath.node;
         const tagName = getTagName(openingElement.name);
         const line = openingElement.loc?.start.line || "0";
-        const debugId = `${componentName}:${tagName}:${line}`;
+        const debugId = `${filePath}:${componentName}:${tagName}:${line}`;
         const alreadyHas = openingElement.attributes.some(
           (attr) => attr.type === "JSXAttribute" && attr.name?.name === "data-debug"
         );
@@ -49,6 +63,16 @@ function babelPluginDebugLabel() {
 function initInspector() {
   if (typeof window === "undefined") return;
   let isInspecting = false;
+  let hasUserPosition = false;
+  let isDragging = false;
+  let pointerMoved = false;
+  let dragOffsetX = 0;
+  let dragOffsetY = 0;
+  let dragStartX = 0;
+  let dragStartY = 0;
+  let overlay = null;
+  let tooltip = null;
+  const edgeOffset = 24;
   const toggleBtn = document.createElement("button");
   toggleBtn.innerHTML = "\u{1F3AF}";
   toggleBtn.title = "\u5F00\u542F\u7EC4\u4EF6\u5B9A\u4F4D\u5668";
@@ -72,7 +96,111 @@ function initInspector() {
     transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
   `;
   document.body.appendChild(toggleBtn);
-  const overlay = document.createElement("div");
+  const applyAnchor = (anchor) => {
+    if (hasUserPosition) return;
+    toggleBtn.style.top = anchor.startsWith("top") ? `${edgeOffset}px` : "";
+    toggleBtn.style.bottom = anchor.startsWith("bottom") ? `${edgeOffset}px` : "";
+    if (anchor.endsWith("left")) {
+      toggleBtn.style.left = `${edgeOffset}px`;
+      toggleBtn.style.right = "";
+      return;
+    }
+    toggleBtn.style.right = `${edgeOffset}px`;
+    toggleBtn.style.left = "";
+  };
+  const getVisibleDialogs = () => {
+    if (typeof document === "undefined") return [];
+    const candidates = Array.from(
+      document.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]')
+    );
+    return candidates.filter((node) => {
+      if (node.getAttribute("aria-hidden") === "true") return false;
+      if (node.getAttribute("data-aria-hidden") === "true") return false;
+      const style = window.getComputedStyle(node);
+      return style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0";
+    });
+  };
+  const ensureToggleHost = (host) => {
+    if (toggleBtn.parentElement !== host) {
+      host.appendChild(toggleBtn);
+    }
+  };
+  const isIgnorableObstacle = (el) => {
+    if (el === toggleBtn || el === overlay || el === tooltip) return true;
+    if (el instanceof HTMLElement) {
+      if (el.contains(toggleBtn) || toggleBtn.contains(el)) return true;
+      if (overlay && el.contains(overlay)) return true;
+      if (tooltip && el.contains(tooltip)) return true;
+      if (el === document.body || el === document.documentElement) return true;
+      if (el.getAttribute("data-inspector-ignore") === "true") return true;
+      const style = window.getComputedStyle(el);
+      if (style.pointerEvents === "none") return true;
+      if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") return true;
+    }
+    return false;
+  };
+  const sampleAnchorObstructionScore = () => {
+    const pickStack = typeof document.elementsFromPoint === "function" ? (x, y) => document.elementsFromPoint(x, y) : (x, y) => {
+      const one = document.elementFromPoint?.(x, y);
+      return one ? [one] : [];
+    };
+    const rect = toggleBtn.getBoundingClientRect();
+    const points = [
+      [rect.left + rect.width / 2, rect.top + rect.height / 2],
+      [rect.left + 2, rect.top + 2],
+      [rect.right - 2, rect.top + 2],
+      [rect.left + 2, rect.bottom - 2],
+      [rect.right - 2, rect.bottom - 2]
+    ];
+    let score = 0;
+    for (const [x, y] of points) {
+      const stack = pickStack(x, y);
+      const blocker = stack.find((el) => !isIgnorableObstacle(el));
+      if (blocker) score += 1;
+    }
+    return score;
+  };
+  const pickBestAnchor = (preferLeft = false) => {
+    const candidates = preferLeft ? ["bottom-left", "top-left", "bottom-right", "top-right"] : ["bottom-right", "top-right", "bottom-left", "top-left"];
+    let best = candidates[0];
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const anchor of candidates) {
+      applyAnchor(anchor);
+      const score = sampleAnchorObstructionScore();
+      if (score < bestScore) {
+        bestScore = score;
+        best = anchor;
+      }
+      if (score === 0) break;
+    }
+    applyAnchor(best);
+  };
+  const updateAnchorForDialogs = () => {
+    if (typeof document === "undefined") return;
+    const dialogs = getVisibleDialogs();
+    if (dialogs.length > 0) {
+      ensureToggleHost(dialogs[dialogs.length - 1]);
+      pickBestAnchor(true);
+      return;
+    }
+    ensureToggleHost(document.body);
+    pickBestAnchor(false);
+  };
+  let anchorUpdatePending = false;
+  const scheduleAnchorUpdate = () => {
+    if (typeof window === "undefined") return;
+    if (anchorUpdatePending) return;
+    anchorUpdatePending = true;
+    const schedule = typeof window.requestAnimationFrame === "function" ? window.requestAnimationFrame.bind(window) : (cb) => window.setTimeout(() => cb(Date.now()), 16);
+    schedule(() => {
+      anchorUpdatePending = false;
+      updateAnchorForDialogs();
+    });
+  };
+  const dialogObserver = new MutationObserver(() => {
+    scheduleAnchorUpdate();
+  });
+  overlay = document.createElement("div");
   overlay.style.cssText = `
     position: fixed;
     pointer-events: none;
@@ -83,10 +211,10 @@ function initInspector() {
     transition: all 0.1s ease-out;
   `;
   document.body.appendChild(overlay);
-  const tooltip = document.createElement("div");
+  tooltip = document.createElement("div");
   tooltip.style.cssText = `
     position: fixed;
-    pointer-events: none;
+    pointer-events: auto;
     z-index: 9999999;
     background: #1e293b;
     color: #38bdf8;
@@ -99,8 +227,19 @@ function initInspector() {
     display: none;
     white-space: nowrap;
     transition: all 0.1s ease-out;
+    cursor: help;
   `;
   document.body.appendChild(tooltip);
+  dialogObserver.observe(document.body, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: ["style", "class", "open", "aria-hidden"]
+  });
+  window.addEventListener("beforeunload", () => dialogObserver.disconnect(), { once: true });
+  window.addEventListener("resize", scheduleAnchorUpdate);
+  window.addEventListener("scroll", scheduleAnchorUpdate, true);
+  updateAnchorForDialogs();
   const stopInspecting = () => {
     isInspecting = false;
     toggleBtn.style.transform = "scale(1)";
@@ -109,7 +248,44 @@ function initInspector() {
     overlay.style.display = "none";
     tooltip.style.display = "none";
   };
-  toggleBtn.onclick = () => {
+  const onPointerMove = (e) => {
+    if (!isDragging) return;
+    const deltaX = Math.abs(e.clientX - dragStartX);
+    const deltaY = Math.abs(e.clientY - dragStartY);
+    if (deltaX > 3 || deltaY > 3) {
+      pointerMoved = true;
+    }
+    const left = Math.max(8, Math.min(window.innerWidth - 52, e.clientX - dragOffsetX));
+    const top = Math.max(8, Math.min(window.innerHeight - 52, e.clientY - dragOffsetY));
+    toggleBtn.style.left = `${left}px`;
+    toggleBtn.style.top = `${top}px`;
+    toggleBtn.style.right = "";
+    toggleBtn.style.bottom = "";
+    hasUserPosition = true;
+  };
+  const onPointerUp = () => {
+    isDragging = false;
+    window.removeEventListener("mousemove", onPointerMove);
+    window.removeEventListener("mouseup", onPointerUp);
+  };
+  toggleBtn.addEventListener("mousedown", (e) => {
+    const rect = toggleBtn.getBoundingClientRect();
+    isDragging = true;
+    pointerMoved = false;
+    dragStartX = e.clientX;
+    dragStartY = e.clientY;
+    dragOffsetX = e.clientX - rect.left;
+    dragOffsetY = e.clientY - rect.top;
+    window.addEventListener("mousemove", onPointerMove);
+    window.addEventListener("mouseup", onPointerUp);
+  });
+  toggleBtn.onclick = (e) => {
+    if (pointerMoved) {
+      e.preventDefault();
+      e.stopPropagation();
+      pointerMoved = false;
+      return;
+    }
     isInspecting = !isInspecting;
     if (isInspecting) {
       toggleBtn.style.transform = "scale(0.9)";
@@ -119,11 +295,21 @@ function initInspector() {
       stopInspecting();
     }
   };
-  window.addEventListener("mousemove", (e) => {
+  const formatDebugId = (debugId) => {
+    const parts = debugId.split(":");
+    if (parts.length === 4) {
+      const [filePath, componentName, tagName, line] = parts;
+      const fileName = filePath.split("/").pop() || filePath;
+      return `${fileName} \u203A ${componentName} \u203A ${tagName}:${line}`;
+    }
+    return debugId.replace(/:/g, " \u203A ");
+  };
+  const inspectByPointer = (e) => {
     if (!isInspecting) return;
     const target = e.target;
     if (target === toggleBtn || target === overlay || target === tooltip) return;
     const debugEl = target.closest("[data-debug]");
+    if (debugEl && debugEl === lastHoveredDebugEl) return;
     if (debugEl) {
       const debugId = debugEl.getAttribute("data-debug") || "";
       const rect = debugEl.getBoundingClientRect();
@@ -133,15 +319,33 @@ function initInspector() {
       overlay.style.width = rect.width + "px";
       overlay.style.height = rect.height + "px";
       tooltip.style.display = "block";
-      tooltip.textContent = debugId;
+      tooltip.textContent = formatDebugId(debugId);
       tooltip.style.color = "#38bdf8";
+      tooltip.title = debugId;
       const tooltipY = rect.top < 30 ? rect.bottom + 4 : rect.top - 28;
       tooltip.style.top = tooltipY + "px";
       tooltip.style.left = rect.left + "px";
+      lastHoveredDebugEl = debugEl;
     } else {
       overlay.style.display = "none";
       tooltip.style.display = "none";
+      lastHoveredDebugEl = null;
     }
+  };
+  let pendingHoverFrame = false;
+  let latestHoverEvent = null;
+  let lastHoveredDebugEl = null;
+  document.addEventListener("mousemove", (e) => {
+    if (!isInspecting) return;
+    latestHoverEvent = e;
+    if (pendingHoverFrame) return;
+    pendingHoverFrame = true;
+    const schedule = typeof window.requestAnimationFrame === "function" ? window.requestAnimationFrame.bind(window) : (cb) => window.setTimeout(() => cb(Date.now()), 16);
+    schedule(() => {
+      pendingHoverFrame = false;
+      if (!latestHoverEvent) return;
+      inspectByPointer(latestHoverEvent);
+    });
   });
   window.addEventListener(
     "click",

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@linhey/react-debug-inspector",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A developer tool to inspect React components in browser and jump to source code.",
   "author": "linhey",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/linhay/react-debug-inspector"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -12,13 +16,30 @@
   ],
   "scripts": {
     "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
+    "dev:test-app": "vite --config vite.config.test.ts",
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
+    "test:all": "npm run test && npm run test:e2e",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "@babel/core": "^7.24.0",
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^25.3.5",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.4",
+    "jsdom": "^26.1.0",
+    "playwright": "^1.58.2",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "tsup": "^8.0.2",
-    "typescript": "^5.4.2"
+    "typescript": "^5.4.2",
+    "vite": "^7.3.1",
+    "vitest": "^3.2.4"
   },
   "peerDependencies": {
     "react": ">=16.8.0"