ghost-bridge 0.5.2 → 0.6.0

package/README.md

@@ -1,183 +1,151 @@
 # 👻 Ghost Bridge
 
 [![npm version](https://img.shields.io/npm/v/ghost-bridge.svg?style=flat-square)](https://www.npmjs.com/package/ghost-bridge)
+[![npm total downloads](https://img.shields.io/npm/dt/ghost-bridge.svg?style=flat-square&label=downloads)](https://www.npmjs.com/package/ghost-bridge)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-> **Zero-restart Chrome AI Copilot** — Subvert your workflow. Allow AI to seamlessly take over the browser you're already using, enabling real-time debugging, visual observation, and interactive manipulation without launching a new Chrome instance.
+> Zero-restart Chrome bridge for MCP clients. Let AI inspect, debug, and operate the browser session you are already using.
 
----
+## Why
 
-## ✨ Why Ghost Bridge?
+Most browser-capable AI tools start a separate browser. Ghost Bridge connects AI to your existing Chrome session instead, so it can work with the page state you already have: logged-in accounts, reproduced bugs, in-progress flows, network failures, and real UI state.
 
-- 🔌 **Zero-Config Attach** — Bypasses the need for `--remote-debugging-port`. Captures Chrome's native DevTools Protocol directly via an extension.
-- 🔍 **No-Sourcemap Debugging** — Slice code fragments, perform string searches, and analyze coverage to pinpoint bugs straight in minified production code.
-- 🌐 **Deep Network Analysis** — Comprehensive capture of requests/responses with multi-dimensional filtering and response body inspection.
-- 📸 **Visual & Structural Perception** — Full-page or clipped high-fidelity screenshots paired with structural data extraction (titles, links, forms, buttons).
-- 🎯 **DOM Physical Manipulation** — Empowers AI to click, type, and form-submit with CDP-level physical simulation. Fully compatible with complex SPAs (React/Vue/Angular/Svelte).
-- 📊 **Performance Diagnostics** — Get granular engine metrics: JS Heap, Layout recalculations, Web Vitals (TTFB/FCP/LCP), and resource loading speeds.
-- 🔄 **Multi-Client Mastery** — Built-in singleton manager automatically coordinates multiple MCP clients sharing a single Chrome transport.
+## What It Does
 
----
+- Attach to Chrome without `--remote-debugging-port`
+- Inspect page structure, text, screenshots, errors, and network traffic
+- Search and extract script sources, even in production bundles
+- Click, type, scroll, and submit forms on the current page
+- Share one Chrome transport across multiple MCP clients
 
-## 🚀 Quick Start
+## What's New in 0.6.0
 
-### 1. Install & Initialize
+- `inspect_page` now collects structured page data and interactive elements in one browser-side snapshot, reducing duplicate DOM scans and cutting one round-trip from the hot path
+- `capture_screenshot` now defaults to JPEG for better transfer efficiency: visible viewport screenshots default to `quality: 80`, and `fullPage` screenshots default to `quality: 70`
+- Use `format: "png"` when you need high-fidelity text rendering, 1px lines, icon edges, transparency, or pixel-level UI inspection
+- Attachment and request cleanup paths are more robust under concurrent usage and multi-client reconnect scenarios
+
+## Quick Start
+
+### 1. Install
 
 ```bash
-# Install globally
 npm install -g ghost-bridge
-
-# Auto-configure MCP (Claude Code, Codex, Cursor, Antigravity) and prepare the extension directory
 ghost-bridge init
 ```
 
-> `ghost-bridge init` currently writes:
-> - Claude Code: `~/.claude/settings.json` or legacy `~/.claude.json`
-> - Codex: `~/.codex/config.toml`
-> - Cursor: `~/.cursor/mcp.json`
-> - Antigravity: `~/.gemini/antigravity/mcp.json`
->
-> **Note on other MCP clients (Windsurf, Roo, others):** 
-> `ghost-bridge init` attempts to auto-configure supported clients. If your client isn't auto-detected, add one of the following snippets to the appropriate MCP configuration file:
->
-> JSON-style MCP configs (`mcp.json`, Claude JSON config, Cursor):
-> ```json
-> {
->   "mcpServers": {
->     "ghost-bridge": {
->       "command": "/absolute/path/to/node",
->       "args": ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
->     }
->   }
-> }
-> ```
->
-> Codex TOML config (`~/.codex/config.toml`):
-> ```toml
-> [mcp_servers.ghost-bridge]
-> type = "stdio"
-> command = "/absolute/path/to/node"
-> args = ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
-> ```
-
-### 2. Load the Chrome Extension
-
-1. Open Chrome and navigate to `chrome://extensions`
-2. Toggle **Developer mode** in the top right corner.
-3. Click **Load unpacked**
-4. Select the directory: `~/.ghost-bridge/extension`
-
-> 💡 *Tip: Run `ghost-bridge extension --open` to reveal the directory directly.*
-
-### 3. Connect & Command
-
-1. Click the **Ghost Bridge** ghost icon in your browser toolbar.
-2. Click **Connect** and wait for the status to turn to ✅ **ON**.
-3. Open Claude Desktop or your Claude CLI. All tools are now primed and ready!
-
-**Prompting tips:**
-- You usually do not need to say "please use ghost-bridge". Direct requests like `分析当前页面`、`看看这个网站的 DOM 结构`、`帮我检查这个页面为什么布局错了`、`帮我点击登录按钮并提交表单` should be enough.
-- `inspect_page` is the default entry tool for generic page analysis.
-- For visual/UI issues, the model should prefer `capture_screenshot`.
-- For text/DOM extraction, the model should prefer `get_page_content`.
-- For page actions, the model should start with `get_interactive_snapshot` and then call `dispatch_action`.
-
----
-
-## 🛠️ Tool Arsenal
-
-### 🔍 Core Debugging
-
-| Tool | Capability |
-|------|------------|
-| `inspect_page` | Best default entry for page analysis. Returns metadata, structured content, and an interactive-elements overview. |
-| `get_server_info` | Retrieves server instance status, WebSocket ports, and client roles. |
-| `get_last_error` | Aggregates recent exceptions, console errors, and failed network requests with mapped locators. |
-| `get_script_source` | Pulls raw script definitions. Supports URL-fragment filtering, specific line targeting, and beautification. |
-| `coverage_snapshot` | Triggers a quick coverage trace (1.5s default) to identify the most active scripts on the page. |
-| `find_by_string` | Scans page script sources for keywords, returning a 200-character context window. |
-| `symbolic_hints` | Gathers context clues: Resource lists, Global Variable keys, LocalStorage schema, and UA strings. |
-| `eval_script` | Executes raw JavaScript expressions in the page context. *(Use with caution)* |
-
-### 🌍 Network Intelligence
-
-| Tool | Capability |
-|------|------------|
-| `list_network_requests` | Lists captured network traffic. Supports filtering by URL, Method, Status Code, or Resource Type. |
-| `get_network_detail` | Dives deep into a specific request's Headers, Timing, and optional Response Body extraction. |
-| `clear_network_requests` | Wipes the current network capture buffer. |
-
-### 📸 Page Perception
-
-| Tool | Capability |
-|------|------------|
-| `capture_screenshot` | Captures the viewport or emulates full-page scrolling screenshots. |
-| `get_page_content` | Extracts raw text, sanitized HTML, or structured actionable data representations. |
-
-### 🎯 Interactive Automation (DOM)
-
-| Tool | Capability |
-|------|------------|
-| `get_interactive_snapshot` | Scans for visible interactive elements, returning a concise map `[e1, e2...]`. Pierces open Shadow DOMs. |
-| `dispatch_action` | Dispatches physical UI actions (click, fill, press, hover) against targeted element references (e.g., `e1`). |
-
-**Example Agent Workflow:**
-1. AI: `get_interactive_snapshot` ➝ `[{ref:"e1", tag:"input", placeholder:"Search..."}, {ref:"e2", tag:"button", text:"Login"}]`
-2. AI: `dispatch_action({ref: "e1", action: "fill", value: "hello"})`
-3. AI: `dispatch_action({ref: "e2", action: "click"})`
-4. AI: `capture_screenshot` to verify state changes.
-
-### 📊 Performance Profiling
-
-| Tool | Capability |
-|------|------------|
-| `perf_metrics` | Collects layered performance data (Engine Metrics, Web Vitals, and Resource Load Summaries). |
-
----
-
-## ⚙️ Configuration
-
-| Setting | Default | Description |
-|---------|---------|-------------|
-| **Base Port** | `33333` | Fixed WS port. If occupied, Ghost Bridge fails fast and asks you to free it or set `GHOST_BRIDGE_PORT`. |
-| **Token** | *Monthly UUID* | Local WS auth token, auto-rotates on the 1st of every month. |
-| **Auto Detach** | `false` | Keeps debugger attached to actively buffer invisible exceptions and network calls. |
-
-**Environment Variables:**
-- `GHOST_BRIDGE_PORT` — Override base port.
-- `GHOST_BRIDGE_TOKEN` — Override connection token.
+`ghost-bridge init` currently writes config for:
 
----
+- Claude Code: `~/.claude/settings.json` or `~/.claude.json`
+- Codex: `~/.codex/config.toml`
+- Cursor: `~/.cursor/mcp.json`
+- Antigravity: `~/.gemini/antigravity/mcp.json`
 
-## 🏗️ Architecture
+If your MCP client is not auto-detected, add one of these manually.
 
-```mermaid
-graph LR
-    A[Claude CLI/Desktop] <-->|stdio| B(MCP Server\nserver.js)
-    B <-->|WebSocket| C(Chrome Extension\nbackground.js)
-    C <-->|CDP| D[Browser Tab\nTarget Context]
+JSON config:
+
+```json
+{
+  "mcpServers": {
+    "ghost-bridge": {
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
+    }
+  }
+}
+```
+
+Codex TOML:
+
+```toml
+[mcp_servers.ghost-bridge]
+type = "stdio"
+command = "/absolute/path/to/node"
+args = ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
 ```
 
-- **MCP Server**: Spawned by Claude via standard I/O streams. Orchestrates WS connections.
-- **Chrome Extension (MV3)**: Taps into `chrome.debugger` API. Utilizes an Offscreen Document to prevent WS hibernation.
-- **Singleton Design**: If multiple agents spawn servers, the first becomes the master bridge while subsequent instances chain transparently as clients.
+### 2. Load the Extension
+
+1. Open `chrome://extensions`
+2. Enable Developer mode
+3. Click `Load unpacked`
+4. Select `~/.ghost-bridge/extension`
 
----
+You can also run:
+
+```bash
+ghost-bridge extension --open
+```
 
-## ⚠️ Known Limitations
+### 3. Connect
 
-- **Service Workers Suspending**: MV3 background workers may suspend. We've built robust auto-reconnection logic, but prolonged inactivity might require re-toggling.
-- **DevTools Conflict**: If you manually open Chrome DevTools (F12) on the target tab, `chrome.debugger.attach` may be rejected.
-- **Beautify Overhead**: Beautifying massive single-line bundles is expensive; the server will auto-truncate overly large scripts.
-- **Cross-Origin OOPIF**: Elements and errors deeply embedded in strict Cross-Origin Iframes might evade the primary debugger hook without further multi-target attach logic.
+1. Click the Ghost Bridge extension icon
+2. Click `Connect`
+3. Wait until the status becomes `ON`
+4. Open your MCP client and start working on the current page
 
----
+Typical prompts:
+
+- `Analyze the current page`
+- `Check why this layout is broken`
+- `Inspect the DOM structure`
+- `Click the login button and submit the form`
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `inspect_page` | Default entry point for page analysis |
+| `capture_screenshot` | Visual inspection and UI debugging |
+| `get_page_content` | Text, HTML, and structured DOM extraction |
+| `get_interactive_snapshot` | Find clickable and editable elements |
+| `dispatch_action` | Click, fill, press, scroll, hover, select |
+| `list_network_requests` | Inspect captured network traffic |
+| `get_network_detail` | Read one request in detail |
+| `get_last_error` | Inspect recent errors and exceptions |
+| `get_script_source` | Extract page scripts |
+| `find_by_string` | Search within bundled script content |
+| `coverage_snapshot` | Identify active scripts quickly |
+| `perf_metrics` | Collect Web Vitals and engine metrics |
+
+Recommended flow:
+
+1. Start with `inspect_page`
+2. Use `capture_screenshot` for visual issues
+   Default is optimized for transfer with JPEG; switch to `png` for pixel-level checks
+3. Use `get_page_content` for DOM or text extraction
+4. Use `get_interactive_snapshot` before `dispatch_action`
+
+## Configuration
+
+| Setting | Default | Notes |
+|---------|---------|-------|
+| Port | `33333` | Set `GHOST_BRIDGE_PORT` to override |
+| Token | Monthly UUID | Set `GHOST_BRIDGE_TOKEN` to override |
+| Auto detach | `false` | Keeps debugger attached for ongoing capture |
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A["AI Client<br/>Claude / Codex / Cursor"]
+    B["Ghost Bridge MCP Server<br/>server.js"]
+    C["Chrome Extension<br/>background.js"]
+    D["Browser Tab<br/>Target Context"]
+
+    A <-->|"stdio"| B
+    B <-->|"WebSocket"| C
+    C <-->|"CDP"| D
+```
 
-## 🤝 Contributing
+## Limitations
 
-Contributions, issues, and feature requests are welcome! 
-Check out our [Contributing Guide](CONTRIBUTING.md) to get started building tools or improving the bridge.
+- Chrome DevTools on the target tab can conflict with `chrome.debugger.attach`
+- MV3 background lifecycle can still cause reconnect scenarios after long idle periods
+- Very large minified bundles may be truncated during beautify or extraction
+- Deep cross-origin iframe cases are not fully covered yet
 
-## 📄 License
+## License
 
-This project is [MIT](LICENSE) licensed.
+[MIT](LICENSE)

package/dist/server.js

@@ -28813,9 +28813,18 @@ function connectToMainInstance() {
   });
 }
 function failAllPending(message) {
-  pendingRequests.forEach(({ reject, timer }) => {
-    clearTimeout(timer);
-    reject(new Error(message));
+  pendingRequests.forEach((pending, id) => {
+    if (pending.reject) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error(message));
+    } else if (pending.source) {
+      try {
+        if (pending.source.readyState === import_websocket.default.OPEN) {
+          pending.source.send(JSON.stringify({ id, error: message }));
+        }
+      } catch {
+      }
+    }
   });
   pendingRequests.clear();
 }
@@ -29068,18 +29077,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "capture_screenshot",
-      description: "\u3010\u63A8\u8350\u7528\u4E8E\u89C6\u89C9\u5206\u6790\u3011\u622A\u53D6\u5F53\u524D\u9875\u9762\u7684\u622A\u56FE\uFF0C\u8FD4\u56DE base64 \u56FE\u7247\u3002\u9002\u7528\u4E8E\uFF1A1) \u67E5\u770B\u9875\u9762\u5B9E\u9645\u89C6\u89C9\u6548\u679C 2) \u6392\u67E5 UI/\u6837\u5F0F/\u5E03\u5C40/\u989C\u8272\u95EE\u9898 3) \u9A8C\u8BC1\u9875\u9762\u6E32\u67D3 4) \u5206\u6790\u5143\u7D20\u4F4D\u7F6E\u548C\u95F4\u8DDD 5) \u67E5\u770B\u56FE\u7247/\u56FE\u6807\u7B49\u89C6\u89C9\u5185\u5BB9\u3002\u5F53\u7528\u6237\u8BF4\u201C\u770B\u770B\u8FD9\u4E2A\u9875\u9762\u957F\u4EC0\u4E48\u6837\u201D\u201C\u5E2E\u6211\u5206\u6790\u754C\u9762/\u5E03\u5C40/\u6837\u5F0F\u201D\u65F6\uFF0C\u5E94\u4F18\u5148\u4F7F\u7528\u6B64\u5DE5\u5177\uFF0C\u65E0\u9700\u7528\u6237\u663E\u5F0F\u63D0\u5230 ghost-bridge\u3002\u5F53\u9700\u8981\u770B\u5230\u9875\u9762\u300C\u957F\u4EC0\u4E48\u6837\u300D\u65F6\u4F7F\u7528\u6B64\u5DE5\u5177\u3002\u5982\u4EC5\u9700\u6587\u672C/\u94FE\u63A5\u7B49\u4FE1\u606F\uFF0C\u5EFA\u8BAE\u4F7F\u7528\u66F4\u5FEB\u7684 get_page_content\u3002",
+      description: "\u3010\u63A8\u8350\u7528\u4E8E\u89C6\u89C9\u5206\u6790\u3011\u622A\u53D6\u5F53\u524D\u9875\u9762\u7684\u622A\u56FE\uFF0C\u8FD4\u56DE base64 \u56FE\u7247\u3002\u9002\u7528\u4E8E\uFF1A1) \u67E5\u770B\u9875\u9762\u5B9E\u9645\u89C6\u89C9\u6548\u679C 2) \u6392\u67E5 UI/\u6837\u5F0F/\u5E03\u5C40/\u989C\u8272\u95EE\u9898 3) \u9A8C\u8BC1\u9875\u9762\u6E32\u67D3 4) \u5206\u6790\u5143\u7D20\u4F4D\u7F6E\u548C\u95F4\u8DDD 5) \u67E5\u770B\u56FE\u7247/\u56FE\u6807\u7B49\u89C6\u89C9\u5185\u5BB9\u3002\u5F53\u7528\u6237\u8BF4\u201C\u770B\u770B\u8FD9\u4E2A\u9875\u9762\u957F\u4EC0\u4E48\u6837\u201D\u201C\u5E2E\u6211\u5206\u6790\u754C\u9762/\u5E03\u5C40/\u6837\u5F0F\u201D\u65F6\uFF0C\u5E94\u4F18\u5148\u4F7F\u7528\u6B64\u5DE5\u5177\uFF0C\u65E0\u9700\u7528\u6237\u663E\u5F0F\u63D0\u5230 ghost-bridge\u3002\u5F53\u9700\u8981\u770B\u5230\u9875\u9762\u300C\u957F\u4EC0\u4E48\u6837\u300D\u65F6\u4F7F\u7528\u6B64\u5DE5\u5177\u3002\u9ED8\u8BA4\u4F18\u5148\u4F7F\u7528\u66F4\u7701\u4F20\u8F93\u7684 JPEG\uFF1A\u666E\u901A\u622A\u56FE\u9ED8\u8BA4 quality 80\uFF0C\u5B8C\u6574\u957F\u622A\u56FE\u9ED8\u8BA4 quality 70\u3002\u5F53\u9700\u8981\u68C0\u67E5\u6587\u5B57\u6E05\u6670\u5EA6\u30011px \u7EC6\u7EBF\u3001\u56FE\u6807\u8FB9\u7F18\u3001\u900F\u660E\u80CC\u666F\u6216\u50CF\u7D20\u7EA7\u7EC6\u8282\u65F6\uFF0C\u5E94\u4F18\u5148\u4F7F\u7528 PNG\u3002\u5982\u4EC5\u9700\u6587\u672C/\u94FE\u63A5\u7B49\u4FE1\u606F\uFF0C\u5EFA\u8BAE\u4F7F\u7528\u66F4\u5FEB\u7684 get_page_content\u3002",
       inputSchema: {
         type: "object",
         properties: {
           format: {
             type: "string",
             enum: ["png", "jpeg"],
-            description: "\u56FE\u7247\u683C\u5F0F\uFF0C\u9ED8\u8BA4 png\uFF08\u65E0\u635F\uFF09\uFF0Cjpeg \u66F4\u5C0F"
+            description: "\u56FE\u7247\u683C\u5F0F\u3002\u9ED8\u8BA4\u4F7F\u7528 jpeg\uFF1B\u9700\u8981\u9AD8\u4FDD\u771F\u6587\u5B57\u3001\u7EC6\u7EBF\u3001\u900F\u660E\u80CC\u666F\u65F6\u7528 png"
           },
           quality: {
             type: "number",
-            description: "JPEG \u8D28\u91CF (0-100)\uFF0C\u4EC5\u5F53 format \u4E3A jpeg \u65F6\u6709\u6548\uFF0C\u5EFA\u8BAE 80"
+            description: "JPEG \u8D28\u91CF (0-100)\uFF0C\u4EC5\u5F53 format \u4E3A jpeg \u65F6\u6709\u6548\u3002\u9ED8\u8BA4\u666E\u901A\u622A\u56FE 80\uFF0C\u5B8C\u6574\u957F\u622A\u56FE 70"
           },
           fullPage: {
             type: "boolean",
@@ -29192,20 +29201,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     if (name === "inspect_page") {
       const { selector, includeInteractive = true, maxElements = 30 } = args;
-      const page = await askChrome("getPageContent", {
-        mode: "structured",
+      const snapshot = await askChrome("inspectPageSnapshot", {
         selector,
-        maxLength: 2e4,
-        includeMetadata: true
+        includeInteractive,
+        maxElements
       });
-      let interactive = null;
-      if (includeInteractive) {
-        interactive = await askChrome("getInteractiveSnapshot", {
-          selector,
-          includeText: true,
-          maxElements
-        });
-      }
+      const page = snapshot?.page;
+      const interactive = snapshot?.interactive ?? null;
       const links = page?.counts?.links;
       const buttons = page?.counts?.buttons;
       const forms = page?.counts?.forms;
@@ -29357,6 +29359,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
       const metadata = {
         format: res.format,
+        ...res.quality !== void 0 ? { quality: res.quality } : {},
         fullPage: res.fullPage,
         width: res.width,
         height: res.height,

package/extension/background.js

@@ -398,46 +398,57 @@ function compactStack(stackTrace) {
 
 // ========== Debugger 操作 ==========
 
+// attach 互斥锁：防止并发调用 ensureAttached 导致重复 attach / 状态竞态
+let _attachLock = Promise.resolve()
+
 async function ensureAttached() {
-  if (!state.enabled) throw new Error("扩展已暂停，点击图标开启后再试")
-  const [tab] = await chrome.tabs.query({ active: true, lastFocusedWindow: true })
-  if (!tab) throw new Error("没有激活的标签页")
-  if (attachedTabId !== tab.id) {
-    if (attachedTabId) {
-      try { await chrome.debugger.detach({ tabId: attachedTabId }) } catch (e) {}
-    }
-    try {
-      await chrome.debugger.attach({ tabId: tab.id }, "1.3")
-      setBadgeState("on")
-    } catch (e) {
-      attachedTabId = null
-      if (state.connected) {
+  let _release
+  const _prev = _attachLock
+  _attachLock = new Promise(r => _release = r)
+  await _prev
+  try {
+    if (!state.enabled) throw new Error("扩展已暂停，点击图标开启后再试")
+    const [tab] = await chrome.tabs.query({ active: true, lastFocusedWindow: true })
+    if (!tab) throw new Error("没有激活的标签页")
+    if (attachedTabId !== tab.id) {
+      if (attachedTabId) {
+        try { await chrome.debugger.detach({ tabId: attachedTabId }) } catch (e) {}
+      }
+      try {
+        await chrome.debugger.attach({ tabId: tab.id }, "1.3")
         setBadgeState("on")
-      } else {
-        setBadgeState("att")
+      } catch (e) {
+        attachedTabId = null
+        if (state.connected) {
+          setBadgeState("on")
+        } else {
+          setBadgeState("att")
+        }
+        throw e
       }
-      throw e
+      attachedTabId = tab.id
+      scriptMap = new Map()
+      scriptSourceCache = new Map()
+      networkRequests = []
+      requestMap = new Map()
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Runtime.enable")
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Log.enable")
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Console.enable").catch(() => {})
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Debugger.enable")
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Profiler.enable")
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Network.enable").catch(() => {})
+
+      // Enable auto-attach to sub-targets (iframes, workers) for comprehensive capture
+      await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Target.setAutoAttach", {
+        autoAttach: true,
+        waitForDebuggerOnStart: false,
+        flatten: true,
+      }).catch(() => {})
     }
-    attachedTabId = tab.id
-    scriptMap = new Map()
-    scriptSourceCache = new Map()
-    networkRequests = []
-    requestMap = new Map()
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Runtime.enable")
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Log.enable")
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Console.enable").catch(() => {})
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Debugger.enable")
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Profiler.enable")
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Network.enable").catch(() => {})
-    
-    // Enable auto-attach to sub-targets (iframes, workers) for comprehensive capture
-    await chrome.debugger.sendCommand({ tabId: attachedTabId }, "Target.setAutoAttach", {
-      autoAttach: true,
-      waitForDebuggerOnStart: false,
-      flatten: true,
-    }).catch(() => {})
+    return { tabId: attachedTabId }
+  } finally {
+    _release()
   }
-  return { tabId: attachedTabId }
 }
 
 async function maybeDetach(force = false) {
@@ -879,13 +890,17 @@ function roundMs(seconds) {
 
 async function handleCaptureScreenshot(params = {}) {
   const target = await ensureAttached()
-  const { format = 'png', quality, fullPage = false, clip } = params
+  const { format: requestedFormat, quality: requestedQuality, fullPage = false, clip } = params
+  const format = requestedFormat || 'jpeg'
+  const quality = format === 'jpeg'
+    ? (requestedQuality ?? (fullPage ? 70 : 80))
+    : undefined
 
   await chrome.debugger.sendCommand(target, 'Page.enable')
 
   let captureParams = {
     format,
-    ...(quality !== undefined && format === 'jpeg' ? { quality } : {}),
+    ...(format === 'jpeg' ? { quality } : {}),
   }
 
   if (clip) {
@@ -927,7 +942,7 @@ async function handleCaptureScreenshot(params = {}) {
         }
         await chrome.debugger.sendCommand(target, 'Emulation.clearDeviceMetricsOverride').catch(() => {})
         return {
-          imageData: data, format, fullPage: true, width: maxWidth, height: maxHeight,
+          imageData: data, format, quality, fullPage: true, width: maxWidth, height: maxHeight,
           note: pageSize.height > maxHeight ? `页面高度 ${pageSize.height}px 超过限制，已截取前 ${maxHeight}px` : undefined,
         }
       } catch (e) {
@@ -943,7 +958,207 @@ async function handleCaptureScreenshot(params = {}) {
     returnByValue: true,
   })
 
-  return { imageData: data, format, fullPage: false, width: sizeResult?.value?.width, height: sizeResult?.value?.height }
+  return {
+    imageData: data,
+    format,
+    quality,
+    fullPage: false,
+    width: sizeResult?.value?.width,
+    height: sizeResult?.value?.height
+  }
+}
+
+async function handleInspectPageSnapshot(params = {}) {
+  const target = await ensureAttached()
+  const { selector, includeInteractive = true, maxElements = 30 } = params
+
+  const selectorStr = selector ? JSON.stringify(selector) : 'null'
+
+  const expression = `(function() {
+    try {
+      if (document.readyState === 'loading') {
+        return { error: '页面尚未加载完成，请稍后重试', readyState: document.readyState };
+      }
+
+      const includeInteractive = ${includeInteractive};
+      const maxEls = ${maxElements};
+      const selector = ${selectorStr};
+      const result = {};
+      let targetElement = document.body;
+
+      if (selector) {
+        try {
+          targetElement = document.querySelector(selector);
+          if (!targetElement) {
+            return { error: '选择器未匹配到任何元素', selector: selector, suggestion: '请检查选择器是否正确' };
+          }
+          result.selector = selector;
+          result.matchedTag = targetElement.tagName.toLowerCase();
+        } catch (e) {
+          return { error: '无效的 CSS 选择器: ' + e.message, selector: selector };
+        }
+      }
+
+      result.metadata = {
+        title: document.title || '',
+        url: window.location.href,
+        description: document.querySelector('meta[name="description"]')?.content || '',
+        keywords: document.querySelector('meta[name="keywords"]')?.content || '',
+        charset: document.characterSet,
+        language: document.documentElement.lang || '',
+      };
+
+      const structured = {};
+      const headings = targetElement.querySelectorAll('h1,h2,h3,h4,h5,h6');
+      structured.headings = Array.from(headings).slice(0, 50).map(h => ({
+        level: parseInt(h.tagName[1]),
+        text: h.innerText.trim().slice(0, 200)
+      }));
+      const links = targetElement.querySelectorAll('a[href]');
+      structured.links = Array.from(links).slice(0, 100).map(a => ({
+        text: (a.innerText || '').trim().slice(0, 100),
+        href: a.href
+      })).filter(l => l.href && !l.href.startsWith('javascript:'));
+      const buttons = targetElement.querySelectorAll('button, input[type="button"], input[type="submit"], [role="button"]');
+      structured.buttons = Array.from(buttons).slice(0, 50).map(b => ({
+        text: (b.innerText || b.value || b.getAttribute('aria-label') || '').trim().slice(0, 100),
+        type: b.type || 'button',
+        disabled: b.disabled || false
+      }));
+      const forms = targetElement.querySelectorAll('form');
+      structured.forms = Array.from(forms).slice(0, 20).map(f => {
+        const fields = Array.from(f.querySelectorAll('input, select, textarea')).slice(0, 30);
+        return {
+          action: f.action || '',
+          method: (f.method || 'GET').toUpperCase(),
+          fieldCount: fields.length,
+          fields: fields.map(field => ({
+            tag: field.tagName.toLowerCase(),
+            type: field.type || '',
+            name: field.name || '',
+            placeholder: field.placeholder || '',
+            required: field.required || false
+          }))
+        };
+      });
+      const images = targetElement.querySelectorAll('img');
+      structured.images = Array.from(images).slice(0, 50).map(img => ({
+        alt: img.alt || '',
+        src: img.src ? img.src.slice(0, 200) : ''
+      })).filter(img => img.src);
+      const tables = targetElement.querySelectorAll('table');
+      structured.tables = Array.from(tables).slice(0, 10).map(table => {
+        const headers = Array.from(table.querySelectorAll('th')).map(th => th.innerText.trim().slice(0, 50));
+        const rows = table.querySelectorAll('tr');
+        return { headers: headers.slice(0, 20), rowCount: rows.length };
+      });
+
+      result.page = {
+        metadata: result.metadata,
+        ...(result.selector ? { selector: result.selector, matchedTag: result.matchedTag } : {}),
+        structured,
+        counts: {
+          headings: structured.headings.length,
+          links: structured.links.length,
+          buttons: structured.buttons.length,
+          forms: structured.forms.length,
+          images: structured.images.length,
+          tables: structured.tables.length
+        },
+        mode: 'structured'
+      };
+
+      if (!includeInteractive) {
+        result.interactive = null;
+        return result;
+      }
+
+      let refCounter = 0;
+      const elements = [];
+      const INTERACTIVE_SELECTOR = 'a,button,input,select,textarea,[role="button"],[role="link"],[role="tab"],[role="menuitem"],[role="checkbox"],[role="radio"],[role="switch"],[role="combobox"],[tabindex]:not([tabindex="-1"]),[contenteditable="true"],[onclick]';
+
+      function isVisible(el) {
+        const style = window.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden' || parseFloat(style.opacity) === 0) return null;
+        if (!el.offsetParent && el.tagName !== 'HTML' && el.tagName !== 'BODY' &&
+            style.position !== 'fixed' && style.position !== 'sticky') return null;
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return null;
+        return rect;
+      }
+
+      function buildEntry(el, rect) {
+        refCounter++;
+        const ref = 'e' + refCounter;
+        el.setAttribute('data-ghost-ref', ref);
+        const tag = el.tagName.toLowerCase();
+        const entry = { ref, tag, cx: Math.round(rect.left + rect.width / 2), cy: Math.round(rect.top + rect.height / 2) };
+        if (el.type) entry.type = el.type;
+        if (el.name) entry.name = el.name;
+        if (el.getAttribute('role')) entry.role = el.getAttribute('role');
+        if (el.placeholder) entry.placeholder = el.placeholder.slice(0, 80);
+        if (el.value && tag !== 'textarea') entry.value = el.value.slice(0, 80);
+        if (tag === 'a') entry.href = (el.href || '').slice(0, 150);
+        if (tag === 'select') {
+          entry.options = Array.from(el.options).slice(0, 10).map(o => ({
+            value: o.value, text: o.text.slice(0, 50), selected: o.selected
+          }));
+        }
+        const text = (el.innerText || el.textContent || el.getAttribute('aria-label') || '').trim();
+        if (text && text.length <= 100) entry.text = text;
+        else if (text) entry.text = text.slice(0, 97) + '...';
+        if (el.disabled) entry.disabled = true;
+        return entry;
+      }
+
+      function scanRoot(root) {
+        const candidates = root.querySelectorAll(INTERACTIVE_SELECTOR);
+        for (let i = 0; i < candidates.length && elements.length < maxEls; i++) {
+          const rect = isVisible(candidates[i]);
+          if (rect) elements.push(buildEntry(candidates[i], rect));
+        }
+        if (elements.length < maxEls) {
+          const all = root.querySelectorAll('*');
+          for (let i = 0; i < all.length && elements.length < maxEls; i++) {
+            const el = all[i];
+            if (el.shadowRoot) scanRoot(el.shadowRoot);
+            if (el.onclick && !el.hasAttribute('data-ghost-ref')) {
+              const rect = isVisible(el);
+              if (rect) elements.push(buildEntry(el, rect));
+            }
+          }
+        }
+      }
+
+      document.querySelectorAll('[data-ghost-ref]').forEach(el => el.removeAttribute('data-ghost-ref'));
+      scanRoot(targetElement);
+
+      result.interactive = {
+        url: window.location.href,
+        title: document.title,
+        elementCount: elements.length,
+        viewport: {
+          width: window.innerWidth,
+          height: window.innerHeight,
+          scrollX: Math.round(window.scrollX),
+          scrollY: Math.round(window.scrollY),
+        },
+        elements
+      };
+
+      return result;
+    } catch (e) {
+      return { error: e.message };
+    }
+  })()`
+
+  const { result } = await chrome.debugger.sendCommand(target, "Runtime.evaluate", {
+    expression,
+    returnByValue: true,
+  })
+
+  if (result?.value?.error) throw new Error(result.value.error)
+  return result?.value
 }
 
 async function handleGetPageContent(params = {}) {
@@ -1061,78 +1276,65 @@ async function handleGetInteractiveSnapshot(params = {}) {
       let refCounter = 0;
       const elements = [];
 
-      // 判断元素是否可见
+      const maxEls = ${maxElements};
+      // 候选集选择器——用浏览器原生选择器引擎代替全树 JS 递归
+      const INTERACTIVE_SELECTOR = 'a,button,input,select,textarea,[role="button"],[role="link"],[role="tab"],[role="menuitem"],[role="checkbox"],[role="radio"],[role="switch"],[role="combobox"],[tabindex]:not([tabindex="-1"]),[contenteditable="true"],[onclick]';
+
+      // 可见性检测（单次 getComputedStyle，返回 rect 复用）
       function isVisible(el) {
-        if (!el.offsetParent && el.tagName !== 'HTML' && el.tagName !== 'BODY' &&
-            window.getComputedStyle(el).position !== 'fixed' &&
-            window.getComputedStyle(el).position !== 'sticky') return false;
         const style = window.getComputedStyle(el);
-        if (style.display === 'none' || style.visibility === 'hidden' || parseFloat(style.opacity) === 0) return false;
+        if (style.display === 'none' || style.visibility === 'hidden' || parseFloat(style.opacity) === 0) return null;
+        if (!el.offsetParent && el.tagName !== 'HTML' && el.tagName !== 'BODY' &&
+            style.position !== 'fixed' && style.position !== 'sticky') return null;
         const rect = el.getBoundingClientRect();
-        if (rect.width === 0 && rect.height === 0) return false;
-        return true;
+        if (rect.width === 0 && rect.height === 0) return null;
+        return rect;
       }
 
-      // 判断元素是否可交互
-      function isInteractive(el) {
+      function buildEntry(el, rect) {
+        refCounter++;
+        const ref = 'e' + refCounter;
+        el.setAttribute('data-ghost-ref', ref);
         const tag = el.tagName.toLowerCase();
-        if (['a', 'button', 'input', 'select', 'textarea'].includes(tag)) return true;
-        if (el.getAttribute('role') === 'button' || el.getAttribute('role') === 'link' ||
-            el.getAttribute('role') === 'tab' || el.getAttribute('role') === 'menuitem' ||
-            el.getAttribute('role') === 'checkbox' || el.getAttribute('role') === 'radio' ||
-            el.getAttribute('role') === 'switch' || el.getAttribute('role') === 'combobox') return true;
-        if (el.getAttribute('tabindex') && parseInt(el.getAttribute('tabindex')) >= 0) return true;
-        if (el.getAttribute('contenteditable') === 'true') return true;
-        if (el.onclick || el.getAttribute('onclick')) return true;
-        return false;
+        const entry = { ref, tag, cx: Math.round(rect.left + rect.width / 2), cy: Math.round(rect.top + rect.height / 2) };
+        if (el.type) entry.type = el.type;
+        if (el.name) entry.name = el.name;
+        if (el.getAttribute('role')) entry.role = el.getAttribute('role');
+        if (${includeText}) {
+          if (el.placeholder) entry.placeholder = el.placeholder.slice(0, 80);
+          if (el.value && tag !== 'textarea') entry.value = el.value.slice(0, 80);
+          if (tag === 'a') entry.href = (el.href || '').slice(0, 150);
+          if (tag === 'select') {
+            entry.options = Array.from(el.options).slice(0, 10).map(o => ({
+              value: o.value, text: o.text.slice(0, 50), selected: o.selected
+            }));
+          }
+          const text = (el.innerText || el.textContent || el.getAttribute('aria-label') || '').trim();
+          if (text && text.length <= 100) entry.text = text;
+          else if (text) entry.text = text.slice(0, 97) + '...';
+        }
+        if (el.disabled) entry.disabled = true;
+        return entry;
       }
 
-      // 递归遍历 DOM 树（含 Shadow DOM）
-      function walkDOM(node, root) {
-        if (elements.length >= ${maxElements}) return;
-        const children = node.children || [];
-        for (let i = 0; i < children.length; i++) {
-          if (elements.length >= ${maxElements}) return;
-          const el = children[i];
-          if (isInteractive(el) && isVisible(el)) {
-            refCounter++;
-            const ref = 'e' + refCounter;
-            el.setAttribute('data-ghost-ref', ref);
-            const tag = el.tagName.toLowerCase();
-            const rect = el.getBoundingClientRect();
-            const entry = {
-              ref: ref,
-              tag: tag,
-              cx: Math.round(rect.left + rect.width / 2),
-              cy: Math.round(rect.top + rect.height / 2),
-            };
-            // 类型信息
-            if (el.type) entry.type = el.type;
-            if (el.name) entry.name = el.name;
-            if (el.getAttribute('role')) entry.role = el.getAttribute('role');
-            // 文本信息
-            if (${includeText}) {
-              if (el.placeholder) entry.placeholder = el.placeholder.slice(0, 80);
-              if (el.value && tag !== 'textarea') entry.value = el.value.slice(0, 80);
-              if (tag === 'a') entry.href = (el.href || '').slice(0, 150);
-              if (tag === 'select') {
-                entry.options = Array.from(el.options).slice(0, 10).map(o => ({
-                  value: o.value, text: o.text.slice(0, 50), selected: o.selected
-                }));
-              }
-              const text = (el.innerText || el.textContent || el.getAttribute('aria-label') || '').trim();
-              if (text && text.length <= 100) entry.text = text;
-              else if (text) entry.text = text.slice(0, 97) + '...';
+      // 候选集扫描（含 Shadow DOM 穿透）
+      function scanRoot(root) {
+        const candidates = root.querySelectorAll(INTERACTIVE_SELECTOR);
+        for (let i = 0; i < candidates.length && elements.length < maxEls; i++) {
+          const rect = isVisible(candidates[i]);
+          if (rect) elements.push(buildEntry(candidates[i], rect));
+        }
+        // 穿透 Shadow DOM + 兜底检测 el.onclick = fn 形式的 JS 属性绑定
+        if (elements.length < maxEls) {
+          const all = root.querySelectorAll('*');
+          for (let i = 0; i < all.length && elements.length < maxEls; i++) {
+            const el = all[i];
+            if (el.shadowRoot) scanRoot(el.shadowRoot);
+            // CSS 选择器只能匹配 [onclick] 属性，这里兜住 el.onclick = fn 的情况
+            if (el.onclick && !el.hasAttribute('data-ghost-ref')) {
+              const rect = isVisible(el);
+              if (rect) elements.push(buildEntry(el, rect));
             }
-            // disabled 状态
-            if (el.disabled) entry.disabled = true;
-            elements.push(entry);
-          }
-          // 递归子节点
-          walkDOM(el, root);
-          // 穿透 Shadow DOM
-          if (el.shadowRoot) {
-            walkDOM(el.shadowRoot, root);
           }
         }
       }
@@ -1140,7 +1342,6 @@ async function handleGetInteractiveSnapshot(params = {}) {
       // 清理旧的 ref 标记
       document.querySelectorAll('[data-ghost-ref]').forEach(el => el.removeAttribute('data-ghost-ref'));
 
-      // 确定扫描根节点
       let rootEl = document.body;
       const sel = ${selectorStr};
       if (sel) {
@@ -1148,7 +1349,7 @@ async function handleGetInteractiveSnapshot(params = {}) {
         if (!rootEl) return { error: '选择器未匹配到任何元素', selector: sel };
       }
 
-      walkDOM(rootEl, rootEl);
+      scanRoot(rootEl);
 
       return {
         url: window.location.href,
@@ -1368,6 +1569,7 @@ async function handleCommand(message) {
     else if (command === "clearNetworkRequests") result = await handleClearNetworkRequests()
     else if (command === "perfMetrics") result = await handlePerfMetrics(params)
     else if (command === "captureScreenshot") result = await handleCaptureScreenshot(params)
+    else if (command === "inspectPageSnapshot") result = await handleInspectPageSnapshot(params)
     else if (command === "getPageContent") result = await handleGetPageContent(params)
     else if (command === "getInteractiveSnapshot") result = await handleGetInteractiveSnapshot(params)
     else if (command === "dispatchAction") result = await handleDispatchAction(params)

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Ghost Bridge",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Zero-restart Chrome debugger bridge for Claude MCP, optimized for no-sourcemap production debugging.",
   "permissions": [
     "debugger",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghost-bridge",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "description": "Ghost Bridge: Zero-restart Chrome debugger bridge for Claude MCP. Includes CLI for easy setup.",
@@ -48,5 +48,8 @@
     "fs-extra": "^11.1.1",
     "js-beautify": "^1.14.11",
     "ws": "^8.14.2"
+  },
+  "dependencies": {
+    "ghost-bridge": "^0.5.2"
   }
 }