@agent360/browser-mcp 1.21.0 → 1.24.0

package/README.md

@@ -1,32 +1,73 @@
-# Browser MCP by Agent360
+# Browser MCP by [Agent360](https://agent360.dk)
 
 [![npm version](https://img.shields.io/npm/v/@agent360/browser-mcp)](https://www.npmjs.com/package/@agent360/browser-mcp)
 [![npm downloads](https://img.shields.io/npm/dw/@agent360/browser-mcp)](https://www.npmjs.com/package/@agent360/browser-mcp)
 [![GitHub stars](https://img.shields.io/github/stars/Agent360dk/browser-mcp)](https://github.com/Agent360dk/browser-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
+[![Chrome Web Store](https://img.shields.io/badge/Chrome_Web_Store-live-green)](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl)
 
-**Control your real Chrome from Claude Code — with your logins, cookies, and 2FA.**
+**Your AI agent drives your real, logged-in Chrome — and works where headless tools die.**
 
-![Browser MCP Demo](assets/demo.gif)
+[![Browser MCP Demo](assets/demo.gif)](https://browsermcp.dev)
 
-The only browser MCP with **multi-session support** (10 concurrent AI sessions), **human-in-the-loop** (2FA, CAPTCHA, credentials), and **built-in provider integrations** (Stripe, HubSpot, Slack, and 6 more). 29 tools total.
+▶ **[Watch the 37-second demo with sound →](https://browsermcp.dev)**
 
-## Install
+Browser MCP gives Claude Code (and any MCP client — Cursor, VS Code agent mode) control of your actual Chrome: your cookies, your sessions, your 2FA. So it works on CAPTCHA, 2FA and anti-bot sites where Playwright and Puppeteer get blocked — because it's *you* browsing.
+
+The killer move: it hits a login wall, reads the verification code from your own Gmail tab, and continues the sign-in. No API can do that. Operate platforms with no API, QA your own web app end-to-end, or work dashboards, LinkedIn and Reddit at human pace — with you approving the sensitive steps.
+
+34 tools. Auto-clicks the reCAPTCHA v2 checkbox, with a human fallback for the rest. Multi-session color-coded tab groups. **MIT, free, and 100% local — nothing leaves your machine.**
+
+## Install — 2 steps (~60 seconds)
+
+### Step 1: Configure the MCP server
 
 ```bash
 npx @agent360/browser-mcp install
 ```
 
-This copies the Chrome extension to `~/.browser-mcp/extension/` and configures Claude Code automatically.
+This copies the Chrome extension files to `~/.browser-mcp/extension/` and adds the MCP server to your Claude Code config. **You'll see the path to the extension folder printed in the terminal — copy it.**
+
+### Step 2: Load the extension in Chrome
+
+> Chrome won't let extensions install themselves from npm — you load it manually one time. To **update** later, re-run the install command and reload it (see [Keeping it updated](#keeping-it-updated)). Prefer the [Chrome Web Store](#chrome-web-store-one-click-install) install if you'd rather have the extension auto-update.
+
+1. **Open Chrome** and type `chrome://extensions` in the address bar
+2. **Toggle "Developer mode"** ON (top right corner)
+3. **Click "Load unpacked"** (top left, next to "Pack extension")
+4. **Navigate to `~/.browser-mcp/extension/`** and click "Select"
+   - On Mac: Press `Cmd+Shift+G` in the file picker, paste `~/.browser-mcp/extension/`, press Enter
+   - On Windows: Paste `%USERPROFILE%\.browser-mcp\extension\` in the address bar
+   - On Linux: Type `~/.browser-mcp/extension/` in the path field
+5. **Restart Claude Code** so it picks up the new MCP server
+
+That's it. The Browser MCP icon will appear in your toolbar, and 34 browser tools are now available in Claude Code.
+
+### Alternative: Manual zip download (no npm)
+
+If you don't want to use npm, download the extension directly:
 
-Then load the extension in Chrome:
-1. Open `chrome://extensions`
-2. Enable **Developer mode** (top right)
-3. Click **Load unpacked** → select `~/.browser-mcp/extension/`
-4. Restart Claude Code
+1. [Download `browser-mcp-v1.23.0.zip`](https://github.com/Agent360dk/browser-mcp/releases/latest) from the latest GitHub release
+2. Unzip the file (anywhere — e.g. `~/Downloads/browser-mcp-extension/`)
+3. Follow Step 2 above, but select the unzipped folder instead of `~/.browser-mcp/extension/`
+4. Configure Claude Code manually by adding this to your `~/.claude.json` (or run `npx @agent360/browser-mcp install --skip-extension`):
+   ```json
+   {
+     "mcpServers": {
+       "browser-mcp": {
+         "command": "npx",
+         "args": ["@agent360/browser-mcp"]
+       }
+     }
+   }
+   ```
 
-That's it. 29 browser tools are now available in Claude Code.
+### Chrome Web Store (one-click install)
+
+[**Install from Chrome Web Store →**](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl)
+
+No Developer mode needed. Then run `npx @agent360/browser-mcp install --skip-extension` to configure Claude Code.
 
 ## Why This Over Playwright MCP / BrowserMCP?
 
@@ -43,7 +84,7 @@ That's it. 29 browser tools are now available in Claude Code.
 | **Custom dropdowns** | Angular Material, React Select support | Works (headless) | Limited |
 | **Install** | `npx @agent360/browser-mcp install` | `npx @anthropic-ai/mcp-playwright` | Manual clone |
 
-## 29 Tools
+## 34 Tools
 
 ### Navigation & Content
 | Tool | Description |
@@ -63,7 +104,10 @@ That's it. 29 browser tools are now available in Claude Code.
 | `browser_wait` | Wait for element to appear |
 | `browser_hover` | Hover for tooltips/dropdowns |
 | `browser_select_option` | Native `<select>` + custom dropdowns (Angular Material, React Select) |
-| `browser_handle_dialog` | Accept/dismiss alert/confirm/prompt dialogs |
+| `browser_set_combobox` | Autocomplete/combobox: type query → wait for filtered listbox → click option (multi-value chip support). Use when `browser_select_option` fails on lazy-rendered options |
+| `browser_set_date` | Robust date inputs: tries native value-set → masked typing → calendar-picker navigation (MUI/AntD/react-datepicker/Lexical). Use when `browser_fill` fails on date fields |
+| `browser_dismiss_overlays` | Bulk-dismiss popups/modals/tooltips/banners via aria-label/text/×-char heuristics. `non_critical` mode preserves dialogs with form data |
+| `browser_handle_dialog` | Accept/dismiss native alert/confirm/prompt dialogs |
 
 ### Tabs & Frames
 | Tool | Description |
@@ -87,7 +131,7 @@ That's it. 29 browser tools are now available in Claude Code.
 ### CAPTCHA Solving
 | Tool | Description |
 |------|-------------|
-| `browser_solve_captcha` | Detect and solve CAPTCHAs. Auto-detects reCAPTCHA v2/v3, hCaptcha, Turnstile, FunCaptcha. Actions: `detect`, `click_checkbox` (auto-click, ~80% pass with Google login), `click_grid` (AI vision guided), `ask_human` (fallback) |
+| `browser_solve_captcha` | Detect and solve CAPTCHAs. Auto-detects reCAPTCHA v2/v3, hCaptcha, Turnstile, FunCaptcha. Actions: `detect`, `click_checkbox` (auto-click, often passes when signed into Google), `click_grid` (AI vision guided), `ask_human` (fallback) |
 
 ### Human-in-the-Loop
 | Tool | Description |
@@ -103,6 +147,7 @@ That's it. 29 browser tools are now available in Claude Code.
 | `browser_set_local_storage` | Write localStorage values |
 | `browser_console_logs` | Capture console.log/warn/error messages from page |
 | `browser_upload_file` | Upload files to `<input type="file">` via Chrome Debugger API (no dialog) |
+| `browser_drop_file` | Upload via drop-zones: finds hidden `<input type="file">` in target subtree/parent (up to 2 levels). Use when `browser_upload_file` fails because the zone has no visible input |
 
 ## Multi-Session Support
 
@@ -145,7 +190,7 @@ extension/
 
 mcp-server/
   index.js            # MCP server (stdio) + WebSocket client
-  tools.js            # 29 tool definitions
+  tools.js            # 34 tool definitions
   bin/cli.js          # Install CLI
 ```
 
@@ -157,11 +202,19 @@ mcp-server/
 5. Commands flow: Claude Code → MCP → Extension → Chrome APIs
 6. Process auto-exits when Claude Code closes (stdin detection)
 
-## Auto-Updates
+## Keeping it updated
+
+Browser MCP has two parts, and they update independently — how the **extension** updates depends on how you installed it:
 
-The MCP server runs via `npx @agent360/browser-mcp@latest` — always the latest version from npm. No manual git pulls needed.
+| Part | Install method | How it updates |
+|------|----------------|----------------|
+| **MCP server** | any | **Automatic.** Runs via `npx @agent360/browser-mcp@latest`, so every Claude Code session pulls the newest from npm. Nothing to do. |
+| **Extension** | **Chrome Web Store** | **Automatic.** Chrome updates it in the background (usually within a few hours). Nothing to do. |
+| **Extension** | **Unpacked** (`npx … install` or manual zip) | **Manual.** Chrome never auto-updates a load-unpacked extension. Re-run `npx @agent360/browser-mcp install`, then open `chrome://extensions` → Browser MCP → **↻ reload**. |
 
-To update the extension: `npx @agent360/browser-mcp install` (re-copies files), then reload in `chrome://extensions`.
+**Not sure which you have?** Open `chrome://extensions` and find Browser MCP. If it shows a **"Loaded from /path/…"** line, it's unpacked (manual updates). If there's no such line, it came from the Chrome Web Store (auto-updates).
+
+**Want zero-maintenance updates?** Install the extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl), then run `npx @agent360/browser-mcp install --skip-extension` to wire up just the MCP server. After that, both parts stay current on their own.
 
 ## Troubleshooting
 
@@ -183,6 +236,21 @@ To update the extension: `npx @agent360/browser-mcp install` (re-copies files),
 - Idle timeout: 4 hours without commands → auto-exit
 - Manual cleanup: `lsof -i :9876-9885 | grep LISTEN`
 
+## 💡 Help Shape Browser MCP
+
+Browser MCP is built in the open and shaped by the people using it.
+
+### Browse what others want / built
+- 💡 **[Wishlist →](WISHLIST.md)** — features people are asking for
+- 🎯 **[Use-cases →](USE_CASES.md)** — what others have built (LinkedIn ICP scraping, vendor research, daily ops, …)
+
+### Contribute in 30 seconds
+- 💡 [Wish for a feature](https://github.com/Agent360dk/browser-mcp/issues/new?template=wish.yml)
+- 🎯 [Share a use-case](https://github.com/Agent360dk/browser-mcp/issues/new?template=use-case.yml)
+- 🐛 [Report a bug](https://github.com/Agent360dk/browser-mcp/issues/new?template=bug.yml)
+
+Or just **ask Claude** — it knows about the `browser_about` tool and will draft + submit on your behalf when you say things like *"I wish browser-mcp could …"* or *"share my browser-mcp use-case"*.
+
 ## License
 
 MIT — [Agent360](https://agent360.dk)

package/bin/cli.js

@@ -85,7 +85,7 @@ function install() {
   5. Navigate to and select this folder:
      ${extensionDir}
   6. The extension "Agent360 Browser MCP" appears with a puzzle icon
-  7. Restart Claude Code — 28 browser tools are now available!
+  7. Restart Claude Code — 34 browser tools are now available!
 
 🔄 Auto-updates (fully automatic):
    - MCP server: always fetches latest from npm (npx @latest)
@@ -93,6 +93,11 @@ function install() {
    - Extension reload: auto-triggered via WebSocket
    - You don't need to do anything — updates happen on every Claude Code session start
 
+💡 Help shape Browser MCP:
+   - Public wishlist:  https://github.com/Agent360dk/browser-mcp/blob/main/WISHLIST.md
+   - Use-case gallery: https://github.com/Agent360dk/browser-mcp/blob/main/USE_CASES.md
+   - Got an idea, bug, or cool thing you built? Just ask Claude — it can draft + submit for you.
+
 📖 Docs: https://browsermcp.dev
 `);
 }

package/extension/background.js

@@ -9,34 +9,44 @@
 // ── Session Tab Management ─────────────────────────────────────────────────
 
 const SESSION_COLORS = ['blue', 'green', 'yellow', 'red', 'pink', 'purple', 'cyan', 'orange'];
+// Select-all modifier is platform-dependent: Cmd (meta=4) on macOS, Ctrl (2) elsewhere.
+// Get this wrong and the field isn't selected — Backspace no-ops and new text concatenates onto the old.
+const SELECT_ALL_MODS = /Mac/i.test(navigator.userAgent) ? 4 : 2;
 const sessions = new Map(); // port → { tabIds: Set, groupId: number|null, color: string, label: string }
-let sessionsLoaded = false;
+// FIX-2: promise-cache latch (not a boolean). The old `if(sessionsLoaded) return`
+// flipped the flag BEFORE awaiting storage, so a second concurrent caller on a freshly
+// woken service worker proceeded against an EMPTY sessions Map. Caching the promise makes
+// every concurrent caller await the SAME populated completion. Resets to null on SW
+// eviction (module re-init) and on error, so the next wake retries.
+let restorePromise = null;
 
 // Restore sessions from storage (service workers lose in-memory state on suspend)
-async function restoreSessions() {
-  if (sessionsLoaded) return;
-  sessionsLoaded = true;
-  const { sessions: saved } = await chrome.storage.local.get({ sessions: {} });
-  for (const [port, data] of Object.entries(saved)) {
-    // Verify tabs still exist
-    const validTabIds = new Set();
-    for (const tabId of (data.tabIds || [])) {
-      try {
-        await chrome.tabs.get(tabId);
-        validTabIds.add(tabId);
-      } catch {} // tab no longer exists
-    }
-    if (validTabIds.size > 0) {
-      const activeTabId = data.activeTabId && validTabIds.has(data.activeTabId) ? data.activeTabId : null;
-      sessions.set(Number(port), {
-        tabIds: validTabIds,
-        activeTabId,
-        groupId: data.groupId || null,
-        color: data.color || SESSION_COLORS[sessions.size % SESSION_COLORS.length],
-        label: data.label || `Claude ${sessions.size + 1}`,
-      });
+function restoreSessions() {
+  if (restorePromise) return restorePromise;
+  restorePromise = (async () => {
+    const { sessions: saved } = await chrome.storage.local.get({ sessions: {} });
+    for (const [port, data] of Object.entries(saved)) {
+      // Verify tabs still exist
+      const validTabIds = new Set();
+      for (const tabId of (data.tabIds || [])) {
+        try {
+          await chrome.tabs.get(tabId);
+          validTabIds.add(tabId);
+        } catch {} // tab no longer exists
+      }
+      if (validTabIds.size > 0) {
+        const activeTabId = data.activeTabId && validTabIds.has(data.activeTabId) ? data.activeTabId : null;
+        sessions.set(Number(port), {
+          tabIds: validTabIds,
+          activeTabId,
+          groupId: data.groupId || null,
+          color: data.color || SESSION_COLORS[sessions.size % SESSION_COLORS.length],
+          label: data.label || `Claude ${sessions.size + 1}`,
+        });
+      }
     }
-  }
+  })().catch(err => { restorePromise = null; throw err; });
+  return restorePromise;
 }
 
 function getSession(port) {
@@ -53,10 +63,45 @@ function getSession(port) {
   return sessions.get(port);
 }
 
+// LRU eviction cap: hver session må højst have N åbne tabs samtidigt.
+// Når en ny tab tilføjes ud over cap'en, lukkes den ÆLDSTE tab i sessionen
+// (insertion-order via Set) — bortset fra session.activeTabId (current tab).
+// Begrundelse: Claude Code-flows kan åbne 20+ navigate(new_tab=true) per session
+// over en længere conversation. Uden eviction akkumulerer disse i Chrome som
+// orphan-tabs der spiser RAM + giver "extension localhost 19+" tab-noise.
+const MAX_TABS_PER_SESSION = 10;
+
+async function evictOldestTabs(session, justAddedTabId) {
+  // Drop dead tab-ids først (user manually closed dem)
+  for (const id of [...session.tabIds]) {
+    try {
+      await chrome.tabs.get(id);
+    } catch {
+      session.tabIds.delete(id);
+    }
+  }
+  // Evict oldest indtil ≤ cap. Skip activeTabId og just-added tab.
+  const ordered = [...session.tabIds];
+  for (const oldId of ordered) {
+    if (session.tabIds.size <= MAX_TABS_PER_SESSION) break;
+    if (oldId === session.activeTabId) continue;
+    if (oldId === justAddedTabId) continue;
+    try {
+      await chrome.tabs.remove(oldId);
+    } catch {} // tab may already be closed
+    session.tabIds.delete(oldId);
+  }
+}
+
 async function addTabToSession(port, tabId) {
   const session = getSession(port);
   session.tabIds.add(tabId);
 
+  // LRU eviction: når sessionen overstiger cap, luk de ældste tabs.
+  if (session.tabIds.size > MAX_TABS_PER_SESSION) {
+    await evictOldestTabs(session, tabId);
+  }
+
   try {
     if (session.groupId !== null) {
       try {
@@ -68,10 +113,7 @@ async function addTabToSession(port, tabId) {
     }
 
     if (session.groupId === null) {
-      const validTabIds = [...session.tabIds].filter(id => {
-        try { return id; } catch { return false; }
-      });
-      const groupId = await chrome.tabs.group({ tabIds: validTabIds });
+      const groupId = await chrome.tabs.group({ tabIds: [...session.tabIds] });
       session.groupId = groupId;
       await chrome.tabGroups.update(groupId, {
         title: session.label,
@@ -123,17 +165,25 @@ function persistSessions() {
 async function getSessionTab(port, activate = false) {
   const session = getSession(port);
   let target = null;
+  // Remember our OWN about:blank placeholder so we reuse it instead of spawning another
+  // on every read-only call before the first navigate (FIX-4: about:blank proliferation).
+  let blankFallback = null;
+  const consider = (tab) => {
+    if (!tab) return false;
+    if (tab.url.startsWith('chrome://')) return false;
+    if (tab.url.startsWith('about:')) { if (!blankFallback) blankFallback = tab; return false; }
+    return true;
+  };
 
   // Prefer the active (last navigated) tab
   if (session.activeTabId) {
     try {
       const tab = await chrome.tabs.get(session.activeTabId);
-      if (tab && !tab.url.startsWith('chrome://') && !tab.url.startsWith('about:')) {
-        target = tab;
-      }
+      if (consider(tab)) target = tab;
     } catch {
+      const dead = session.activeTabId;   // FIX-17: capture id BEFORE nulling (was deleting null)
       session.activeTabId = null;
-      session.tabIds.delete(session.activeTabId);
+      session.tabIds.delete(dead);
     }
   }
 
@@ -142,30 +192,48 @@ async function getSessionTab(port, activate = false) {
     for (const tabId of session.tabIds) {
       try {
         const tab = await chrome.tabs.get(tabId);
-        if (tab && !tab.url.startsWith('chrome://') && !tab.url.startsWith('about:')) {
-          session.activeTabId = tabId;
-          target = tab;
-          break;
-        }
+        if (consider(tab)) { session.activeTabId = tabId; target = tab; break; }
       } catch {
         session.tabIds.delete(tabId);
       }
     }
   }
 
-  // No usable tab — create one
+  // Reuse our own blank placeholder rather than spawning yet another one (FIX-4).
+  if (!target && blankFallback) {
+    target = blankFallback;
+    session.activeTabId = target.id;
+    persistSessions();
+  }
+
+  // No usable tab at all — create ONE placeholder and pin it as the active tab so the
+  // NEXT call reuses it (FIX-4) instead of creating a fresh about:blank every time.
   if (!target) {
     target = await chrome.tabs.create({ url: 'about:blank', active: false });
     await addTabToSession(port, target.id);
-    return target;
+    session.activeTabId = target.id;
+    persistSessions();
+    // fall through to the activate branch (SC-3: previously returned early, skipping it)
   }
 
-  // Activate the tab so Chrome APIs target it (not whatever user is viewing)
-  if (activate && !target.active) {
-    await chrome.tabs.update(target.id, { active: true });
-    // Brief wait for Chrome to render the tab
-    await new Promise(r => setTimeout(r, 150));
-    target = await chrome.tabs.get(target.id);
+  // Activate the tab WITHOUT stealing the user's focus (FIX-1). This is a BACKGROUND tool:
+  // screenshot/press_key run constantly, so we must NOT chrome.windows.update({focused:true})
+  // here — that yanked Chrome to the foreground on every action. We only (a) un-minimize a
+  // minimized window (needed so it can composite) and (b) make the tab active within its
+  // window. The truly-occluded (covered) case is handled as a bounded last-resort
+  // raise-and-restore inside the screenshot handler only.
+  if (activate) {
+    try {
+      if (target.windowId != null) {
+        const win = await chrome.windows.get(target.windowId).catch(() => null);
+        if (win && win.state === 'minimized') {
+          await chrome.windows.update(target.windowId, { state: 'normal' }); // no focused:true
+        }
+      }
+      if (!target.active) await chrome.tabs.update(target.id, { active: true });
+      await new Promise(r => setTimeout(r, 150));
+      target = await chrome.tabs.get(target.id);
+    } catch { /* best-effort; capture path surfaces the real error */ }
   }
 
   return target;
@@ -176,18 +244,61 @@ async function getSessionTab(port, activate = false) {
 // Track which tabs have debugger attached to avoid repeated attach/detach
 const debuggerAttached = new Set();
 
-async function debuggerAttach(tabId) {
-  if (debuggerAttached.has(tabId)) return;
+// Verify Chrome's actual debugger-truth before trusting local cache.
+// Fixes "ghost-attached" state where Set says attached but Chrome side is gone
+// (happens on SW lifecycle events, user-canceled banners, anti-automation evictions).
+async function verifyAttachedWithChrome(tabId) {
   try {
-    await chrome.debugger.attach({ tabId }, '1.3');
-    debuggerAttached.add(tabId);
-  } catch (e) {
-    if (e.message?.includes('Already attached')) {
-      debuggerAttached.add(tabId);
-    } else {
-      throw e;
+    const targets = await chrome.debugger.getTargets();
+    const t = targets.find(x => x.tabId === tabId);
+    return !!t?.attached;
+  } catch {
+    return false; // assume not-attached on API error
+  }
+}
+
+async function debuggerAttach(tabId) {
+  // First check local cache — fast path
+  if (debuggerAttached.has(tabId)) {
+    // Verify with Chrome before trusting cache (cheap, ~1ms)
+    if (await verifyAttachedWithChrome(tabId)) return;
+    // Cache was stale — Chrome doesn't actually have us attached
+    debuggerAttached.delete(tabId);
+  }
+
+  // Up to 3 attempts. A "ghost attach" (attach resolves but getTargets shows the tab
+  // NOT attached) is usually TRANSIENT: the page is mid-navigation/reload — e.g. the
+  // Metro dev-server rebuilding localhost:8081 auto-detaches the debugger. Retrying
+  // after a short delay lets the reload settle. Only a ghost that survives all retries
+  // is a real user-canceled banner. (Previously we threw on the first ghost, which made
+  // dev-server URLs unusable during their initial bundle.)
+  let lastMsg = '';
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      await chrome.debugger.attach({ tabId }, '1.3');
+      if (await verifyAttachedWithChrome(tabId)) {
+        debuggerAttached.add(tabId);
+        return;
+      }
+      // Ghost — detach cleanly so the next attempt starts fresh, then retry.
+      lastMsg = 'attach resolved but Chrome shows tab not attached (ghost — page likely mid-reload)';
+      try { await chrome.debugger.detach({ tabId }); } catch {}
+    } catch (e) {
+      if (e.message?.includes('Already attached')) {
+        // Chrome side has session — sync local cache
+        debuggerAttached.add(tabId);
+        return;
+      }
+      // "Cannot attach"/"canceled" can also be transient during navigation — retry too.
+      lastMsg = e.message || String(e);
     }
+    if (attempt < 2) await new Promise(r => setTimeout(r, 250 + attempt * 250));
   }
+  throw new Error(
+    `Debugger attach failed after 3 attempts (tab ${tabId}). Last: ${lastMsg}. ` +
+    `If persistent: the page may be continuously reloading (dev-server mid-build — wait, then retry), ` +
+    `or the user canceled Chrome's debugger banner — reload Browser MCP (chrome://extensions/ → ↻) or restart Chrome.`
+  );
 }
 
 async function debuggerDetach(tabId) {
@@ -319,25 +430,75 @@ async function debuggerType(tabId, text) {
 async function debuggerClick(tabId, x, y) {
   await debuggerAttach(tabId);
   try {
+    // 0. Capture the DEEPEST target element under the point BEFORE dispatching.
+    //    Web-components (Google Ads <button-panel>, Material Web) keep their real
+    //    <button> inside an (open) shadow root, so we pierce shadow roots to reach
+    //    it. We stash it on window so the framework fallback (step 3) can verify it
+    //    is still connected — if the trusted click already navigated/re-rendered,
+    //    the ref is detached and we must NOT re-fire (avoids mis-clicks on the new
+    //    view / double-submits).
+    await cdpSend(tabId, 'Runtime.evaluate', {
+      expression: `(() => {
+        let el = document.elementFromPoint(${x}, ${y});
+        let host = el;
+        for (let i = 0; i < 20 && host && host.shadowRoot; i++) {
+          const inner = host.shadowRoot.elementFromPoint(${x}, ${y});
+          if (!inner || inner === host) break;
+          el = inner; host = inner;
+        }
+        window.__bmcpClickTarget = el || null;
+        // FIX-13: watch whether the trusted click (step 2) actually lands on the target,
+        // so step 3's framework-fallback does NOT double-fire on elements that stay
+        // connected (toggles, checkboxes, add-to-cart, form fields).
+        window.__bmcpClicked = false;
+        try { window.__bmcpClickListener && document.removeEventListener('click', window.__bmcpClickListener, true); } catch (e) {}
+        window.__bmcpClickListener = (ev) => {
+          try {
+            const t = ev.target;
+            if (el && (t === el || el.contains(t) || (ev.composedPath && ev.composedPath().includes(el)))) {
+              window.__bmcpClicked = true;
+            }
+          } catch (e) {}
+        };
+        document.addEventListener('click', window.__bmcpClickListener, true);
+      })()`,
+    });
     // 1. mouseMoved first (triggers hover state, required by some frameworks)
     await cdpSend(tabId, 'Input.dispatchMouseEvent', {
       type: 'mouseMoved', x, y,
     });
     await new Promise(r => setTimeout(r, 30));
-    // 2. mousePressed + mouseReleased (fires trusted mousedown/mouseup)
+    // 2. mousePressed + mouseReleased. The `buttons` bitmask (1 while pressed,
+    //    0 on release) plus a small press→release gap are REQUIRED for Chrome to
+    //    synthesize a *trusted* 'click' from the pair. Without them, web-components
+    //    that gate on the trusted click event (Google Ads, Material Web) never fire.
     await cdpSend(tabId, 'Input.dispatchMouseEvent', {
-      type: 'mousePressed', x, y, button: 'left', clickCount: 1,
+      type: 'mousePressed', x, y, button: 'left', buttons: 1, clickCount: 1,
     });
+    await new Promise(r => setTimeout(r, 30));
     await cdpSend(tabId, 'Input.dispatchMouseEvent', {
-      type: 'mouseReleased', x, y, button: 'left', clickCount: 1,
+      type: 'mouseReleased', x, y, button: 'left', buttons: 0, clickCount: 1,
     });
-    // 3. CDP doesn't synthesize 'click' event from mousePressed/mouseReleased.
-    //    Fire JS click + React/Angular framework fallbacks.
+    // 3. Framework fallback — only if the captured target is STILL connected (i.e.
+    //    the trusted click in step 2 did not already handle it). Settle delay lets
+    //    SPA re-renders (Google Ads) detach the element first. Fires a full pointer
+    //    + mouse sequence on the shadow-pierced target, then React/Angular handlers.
+    await new Promise(r => setTimeout(r, 120));
     await cdpSend(tabId, 'Runtime.evaluate', {
       expression: `(() => {
-        const el = document.elementFromPoint(${x}, ${y});
-        if (!el) return;
-        el.click();
+        const el = window.__bmcpClickTarget;
+        const landed = window.__bmcpClicked === true;
+        try { window.__bmcpClickListener && document.removeEventListener('click', window.__bmcpClickListener, true); } catch (e) {}
+        try { delete window.__bmcpClickTarget; delete window.__bmcpClicked; delete window.__bmcpClickListener; } catch (e) {}
+        if (landed) return;                   // FIX-13: trusted click already landed — do NOT double-fire
+        if (!el || !el.isConnected) return;   // already navigated/handled — don't double-fire
+        const opts = { bubbles: true, cancelable: true, composed: true, view: window, clientX: ${x}, clientY: ${y} };
+        try { el.dispatchEvent(new PointerEvent('pointerdown', opts)); } catch (e) {}
+        el.dispatchEvent(new MouseEvent('mousedown', opts));
+        try { el.dispatchEvent(new PointerEvent('pointerup', opts)); } catch (e) {}
+        el.dispatchEvent(new MouseEvent('mouseup', opts));
+        el.dispatchEvent(new MouseEvent('click', opts));
+        if (typeof el.click === 'function') el.click();
 
         // React fiber fallback — find and call onClick handler directly
         const fiberKey = Object.keys(el).find(k => k.startsWith('__reactFiber') || k.startsWith('__reactInternalInstance'));
@@ -349,16 +510,11 @@ async function debuggerClick(tabId, x, y) {
           }
         }
 
-        // Angular fallback — trigger via Zone.js patched events + ngClick
+        // Angular Material fallback — ripple + internal handlers
         const ngKey = Object.keys(el).find(k => k.startsWith('__ng'));
         if (ngKey || el.getAttribute('ng-click') || el.getAttribute('(click)')) {
-          // Angular uses Zone.js which patches addEventListener — dispatch real events through it
-          el.dispatchEvent(new PointerEvent('pointerdown', {bubbles:true, cancelable:true}));
-          el.dispatchEvent(new PointerEvent('pointerup', {bubbles:true, cancelable:true}));
-          el.dispatchEvent(new MouseEvent('click', {bubbles:true, cancelable:true, view:window}));
-          // Angular Material components (mat-button, mat-checkbox, etc.) use ripple + internal handlers
-          const matRipple = el.closest('[mat-button], [mat-raised-button], [mat-icon-button], [mat-fab], mat-checkbox, mat-slide-toggle, mat-radio-button');
-          if (matRipple) matRipple.dispatchEvent(new MouseEvent('click', {bubbles:true, cancelable:true, view:window}));
+          const matRipple = el.closest && el.closest('[mat-button], [mat-raised-button], [mat-icon-button], [mat-fab], mat-checkbox, mat-slide-toggle, mat-radio-button');
+          if (matRipple) matRipple.dispatchEvent(new MouseEvent('click', opts));
         }
       })()`,
     });
@@ -414,9 +570,9 @@ async function debuggerFill(tabId, selector, value) {
   await debuggerFocus(tabId, selector);
   await debuggerAttach(tabId);
   try {
-    // Ctrl+A to select all, then Backspace to clear
+    // Select-all (Cmd+A on macOS, Ctrl+A elsewhere), then Backspace to clear
     await cdpSend(tabId, 'Input.dispatchKeyEvent', {
-      type: 'keyDown', key: 'a', code: 'KeyA', modifiers: 2,
+      type: 'keyDown', key: 'a', code: 'KeyA', modifiers: SELECT_ALL_MODS,
     });
     await cdpSend(tabId, 'Input.dispatchKeyEvent', {
       type: 'keyUp', key: 'a', code: 'KeyA',
@@ -516,10 +672,20 @@ async function safeExecuteScript(tabId, func, args = [], world = 'MAIN') {
 
 function buildTextFinderJS(textPattern, tagFilter) {
   const escaped = JSON.stringify(textPattern);
-  const tagCheck = tagFilter ? `&& el.tagName === ${JSON.stringify(tagFilter.toUpperCase())}` : '';
+  const wantTag = tagFilter ? JSON.stringify(tagFilter.toUpperCase()) : 'null';
   return `(function() {
     const text = ${escaped};
-    // Collect all elements including inside shadow DOM
+    const wantTag = ${wantTag};
+    // Interactive controls we prefer to actually click. Fixes the class of bug where a
+    // text match lands on a large CONTAINER (e.g. Angular Material <mat-nav-list>,
+    // toolbar, list-item) whose center is NOT over the real <button> — so the trusted
+    // click misses and menus/dropdowns never open.
+    const CLICKABLE = 'a,button,summary,label,[role="button"],[role="menuitem"],' +
+      '[role="menuitemcheckbox"],[role="menuitemradio"],[role="option"],[role="tab"],' +
+      '[role="link"],[role="checkbox"],[role="radio"],[role="switch"],[onclick],' +
+      '[mat-button],[mat-raised-button],[mat-stroked-button],[mat-flat-button],' +
+      '[mat-icon-button],[mat-fab],[mat-mini-fab],[mat-menu-item],[mat-list-item],' +
+      'mat-checkbox,mat-slide-toggle,mat-radio-button';
     function collectAll(root, results) {
       for (const el of root.querySelectorAll('*')) {
         results.push(el);
@@ -528,23 +694,34 @@ function buildTextFinderJS(textPattern, tagFilter) {
       return results;
     }
     const all = collectAll(document, []);
-    // Exact match first (prefer leaf nodes)
-    for (const el of all) {
-      if (el.children.length > 3) continue;
-      const t = el.textContent?.trim();
-      if (t === text ${tagCheck}) {
-        return el;
-      }
-    }
-    // Partial match fallback
-    for (const el of all) {
-      if (el.children.length > 3) continue;
-      const t = el.textContent?.trim();
-      if (t && t.includes(text) ${tagCheck}) {
-        return el;
+    const tagOk = (el) => !wantTag || el.tagName === wantTag;
+    // Map a matched element to the ACTIONABLE control: itself if clickable, else the
+    // nearest clickable ancestor (only if its own text isn't much larger than the match,
+    // so we don't grab a whole toolbar), else a clickable descendant.
+    function toClickable(el) {
+      if (el.matches && el.matches(CLICKABLE)) return el;
+      const anc = el.closest && el.closest(CLICKABLE);
+      if (anc && (anc.textContent || '').trim().length <= text.length + 40) return anc;
+      const desc = el.querySelector && el.querySelector(CLICKABLE);
+      if (desc) return desc;
+      return el;
+    }
+    function pick(test) {
+      const matches = all.filter(el => tagOk(el) && test((el.textContent || '').trim()));
+      if (!matches.length) return null;
+      // Prefer the INNERMOST matches (an element that is not an ancestor of another
+      // match) — this is what "prefer leaf nodes" was supposed to do.
+      const inner = matches.filter(el => !matches.some(o => o !== el && el.contains && el.contains(o)));
+      const pool = inner.length ? inner : matches;
+      // Prefer a match that resolves to a real interactive control.
+      for (const el of pool) {
+        const c = toClickable(el);
+        if (c && c.matches && c.matches(CLICKABLE)) return c;
       }
+      return toClickable(pool[0]);
     }
-    return null;
+    // Exact match first, then partial fallback.
+    return pick(t => t === text) || pick(t => t && t.includes(text));
   })()`;
 }
 
@@ -670,7 +847,7 @@ chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
       dispatch(port, msg.method, msg.params)
         .then(result => sendResponse(result))
         .catch(err => sendResponse({ __error: err.message || String(err) }));
-    });
+    }).catch(err => sendResponse({ __error: err.message || String(err) })); // else a storage-restore reject hangs the caller
     return true; // async response
   }
 
@@ -728,22 +905,6 @@ chrome.tabs.onCreated.addListener(async (tab) => {
   }
 });
 
-// ── CAPTCHA Detection ────────────────────────────────────────────────────────
-
-async function detectCaptcha(tabId) {
-  try {
-    return await debuggerEval(tabId, `
-      (function() {
-        if (document.querySelector('iframe[src*="hcaptcha.com"]') || document.querySelector('.h-captcha')) return 'hcaptcha';
-        if (document.querySelector('iframe[src*="recaptcha"]') || document.querySelector('.g-recaptcha')) return 'recaptcha';
-        if (document.querySelector('iframe[src*="challenges.cloudflare.com"]') || document.querySelector('.cf-turnstile')) return 'turnstile';
-        if (document.documentElement.innerHTML.includes('challenge-platform')) return 'challenge';
-        return null;
-      })()
-    `);
-  } catch { return null; }
-}
-
 // ── Deep Shadow DOM Query ────────────────────────────────────────────────────
 // querySelectorDeep: finds elements inside shadow DOMs (Shopify, Salesforce, etc.)
 
@@ -894,7 +1055,7 @@ async function setDateMaskedTyping(tabId, selector, iso, format) {
   await debuggerAttach(tabId);
   try {
     await cdpSend(tabId, 'Input.dispatchKeyEvent', {
-      type: 'keyDown', key: 'a', code: 'KeyA', modifiers: 2,
+      type: 'keyDown', key: 'a', code: 'KeyA', modifiers: SELECT_ALL_MODS,
     });
     await cdpSend(tabId, 'Input.dispatchKeyEvent', {
       type: 'keyUp', key: 'a', code: 'KeyA',
@@ -938,23 +1099,6 @@ async function isPickerOpen(tabId) {
   })()`);
 }
 
-async function getPickerRoot(tabId) {
-  return await debuggerEval(tabId, `(() => {
-    const sels = ${JSON.stringify(PICKER_OPEN_SELECTORS)};
-    for (const s of sels) {
-      try {
-        const el = document.querySelector(s);
-        if (el) {
-          const root = el.closest('[role="dialog"], .react-datepicker, .MuiPickersPopper-root, .ant-picker-dropdown') || el;
-          // Return a stable selector path — for runtime use we re-query each time
-          return true;
-        }
-      } catch {}
-    }
-    return false;
-  })()`);
-}
-
 async function setDatePicker(tabId, selector, iso) {
   const [yStr, mStr, dStr] = iso.split('-');
   const targetYear = parseInt(yStr, 10);
@@ -1611,68 +1755,193 @@ async function dispatch(port, method, params) {
     }
 
     case 'screenshot': {
-      const tab = await getSessionTab(port);
-      if (tab.url.startsWith('chrome://')) throw new Error('Cannot screenshot chrome:// pages');
-      // Use debugger Page.captureScreenshot as PRIMARY method.
-      // captureVisibleTab requires active tab in active window — fails when
-      // user is in terminal. Debugger works regardless of tab focus.
-      try {
-        await debuggerAttach(tab.id);
-        const { data } = await cdpSend(tab.id, 'Page.captureScreenshot', {
-          format: 'png',
-        });
-        return { image: 'data:image/png;base64,' + data };
-      } catch {
-        // Debugger failed — fall back to captureVisibleTab (needs active tab)
+      // getSessionTab(…, true) is focus-NEUTRAL now: it un-minimizes + activates the tab
+      // but does NOT steal window focus (FIX-1). Screenshots run constantly, so the common
+      // path must never yank Chrome to the foreground.
+      const tab = await getSessionTab(port, true);
+      if (tab.url.startsWith('chrome://') || tab.url.startsWith('about:')) {
+        throw new Error(`Cannot screenshot ${tab.url.split(':')[0]}: pages — navigate to a real page first`);
+      }
+      // Capture without stealing focus: CDP Page.captureScreenshot (default → fromSurface:false
+      // retry) works for background/visible tabs; captureVisibleTab is the secondary.
+      const tryCapture = async () => {
         try {
-          await chrome.tabs.update(tab.id, { active: true });
-          await new Promise(r => setTimeout(r, 150));
-          const dataUrl = await chrome.tabs.captureVisibleTab(null, { format: 'png' });
+          await debuggerAttach(tab.id);
+          try {
+            const shot = await cdpSend(tab.id, 'Page.captureScreenshot', { format: 'png' });
+            return { image: 'data:image/png;base64,' + shot.data };
+          } catch {
+            const shot = await cdpSend(tab.id, 'Page.captureScreenshot', {
+              format: 'png', fromSurface: false, captureBeyondViewport: false,
+            });
+            return { image: 'data:image/png;base64,' + shot.data };
+          }
+        } catch {
+          // CDP failed entirely — native tabs API (needs the tab visible in its window).
+          const dataUrl = await chrome.tabs.captureVisibleTab(tab.windowId, { format: 'png' });
           return { image: dataUrl };
-        } catch (e) {
-          throw new Error('Screenshot failed: ' + e.message);
+        }
+      };
+
+      // Attempt 1 — focus-neutral. Handles the vast majority (background-but-visible window).
+      try {
+        return await tryCapture();
+      } catch (firstErr) {
+        // Both methods failed → the window is genuinely OCCLUDED (covered by other windows),
+        // so Chrome's compositor produced no frames. LAST RESORT ONLY: raise the window to
+        // de-occlude it, capture, then RESTORE the user's previously-focused window. This
+        // focus-steal happens ONLY in the rare covered case — never on a normal screenshot.
+        const prev = await chrome.windows.getLastFocused().catch(() => null);
+        try {
+          await chrome.windows.update(tab.windowId, { focused: true, state: 'normal' });
+          await chrome.tabs.update(tab.id, { active: true }).catch(() => {});
+          await new Promise(r => setTimeout(r, 250)); // let it composite
+          return await tryCapture();
+        } catch (secondErr) {
+          throw new Error(
+            `Screenshot failed after focus-neutral AND raised attempts. ` +
+            `First: ${firstErr?.message || firstErr}. Raised: ${secondErr?.message || secondErr}. ` +
+            `If both say "image readback failed" the GPU compositor is not producing frames — ` +
+            `disable Chrome hardware acceleration (chrome://settings/system) as a last resort.`
+          );
+        } finally {
+          // Give focus back to the user's previous Chrome window (best-effort; getLastFocused
+          // only sees Chrome windows, so a non-Chrome IDE can't be re-focused programmatically).
+          if (prev && prev.id != null && prev.id !== tab.windowId) {
+            await chrome.windows.update(prev.id, { focused: true }).catch(() => {});
+          }
         }
       }
     }
 
     case 'execute_script': {
+      // v1.22.2 (DIAGNOSTIC): Try scripting paths but log all errors so we can see WHY they fail
       const tab = await getSessionTab(port);
       if (tab.url.startsWith('chrome://')) throw new Error('Cannot execute scripts on chrome:// pages');
+
+      const diag = { tried: [] };
+
+      // Step 1: try ISOLATED world
+      try {
+        const [result] = await chrome.scripting.executeScript({
+          target: { tabId: tab.id },
+          world: 'ISOLATED',
+          args: [params.code],
+          func: (codeStr) => {
+            try {
+              const fn = new Function('return (' + codeStr + ')');
+              return { __ok: true, value: fn() };
+            } catch (e) {
+              return { __scriptingError: true, message: String(e?.message || e), name: e?.name, world: 'ISOLATED' };
+            }
+          },
+        });
+        const r = result?.result;
+        diag.tried.push({ world: 'ISOLATED', result_keys: r ? Object.keys(r) : null, r_type: typeof r });
+        if (r && typeof r === 'object' && r.__ok) {
+          return { result: r.value, method: 'scripting-isolated' };
+        }
+        if (r && typeof r === 'object' && r.__scriptingError) {
+          diag.isolated_error = r.message;
+        }
+      } catch (e) {
+        diag.isolated_throw = String(e?.message || e);
+      }
+
+      // Step 2: try MAIN world
       try {
         const [result] = await chrome.scripting.executeScript({
           target: { tabId: tab.id },
-          func: new Function('return (' + params.code + ')'),
           world: 'MAIN',
+          args: [params.code],
+          func: (codeStr) => {
+            try {
+              const fn = new Function('return (' + codeStr + ')');
+              return { __ok: true, value: fn() };
+            } catch (e) {
+              return { __scriptingError: true, message: String(e?.message || e), name: e?.name, world: 'MAIN' };
+            }
+          },
         });
-        return { result: result.result };
+        const r = result?.result;
+        diag.tried.push({ world: 'MAIN', result_keys: r ? Object.keys(r) : null, r_type: typeof r });
+        if (r && typeof r === 'object' && r.__ok) {
+          return { result: r.value, method: 'scripting-main' };
+        }
+        if (r && typeof r === 'object' && r.__scriptingError) {
+          diag.main_error = r.message;
+        }
       } catch (e) {
-        if (e.message?.includes('Content Security Policy') || e.message?.includes('unsafe-eval')) {
-          // CSP blocked — fall back to debugger Runtime.evaluate
-          const value = await debuggerEval(tab.id, params.code);
-          return { result: value, method: 'debugger' };
+        diag.main_throw = String(e?.message || e);
+      }
+
+      // Step 3: debugger fallback — the ONLY universal path for arbitrary STRING code
+      // (both scripting worlds block `new Function`: ISOLATED via MV3 extension-CSP,
+      // MAIN via the page's own unsafe-eval CSP). CDP Runtime.evaluate bypasses CSP.
+      // FIX (2026-07-16): retry on an EMPTY/undefined CDP response. On some pages the
+      // debugger auto-detaches mid-command and `chrome.debugger.sendCommand` RESOLVES
+      // with `undefined` instead of rejecting, so cdpSend's throw-based retry never
+      // fires and debuggerEval silently returned undefined → the caller saw a bare
+      // `{method:"debugger"}` with no result. Also surface script exceptions + raw
+      // diagnostics so a genuine failure is never mistaken for an empty success.
+      let rawDbg, dbgErr = '';
+      for (let attempt = 0; attempt < 4; attempt++) {
+        try {
+          await debuggerAttach(tab.id);
+          rawDbg = await cdpSend(tab.id, 'Runtime.evaluate', {
+            expression: '(' + params.code + '\n)',
+            returnByValue: true,
+            awaitPromise: true,
+          });
+          if (rawDbg && rawDbg.exceptionDetails) {
+            const ex = rawDbg.exceptionDetails;
+            await debuggerDetach(tab.id).catch(() => {});
+            throw new Error('__SCRIPT_EX__' + (ex.exception?.description || ex.text || 'Script exception'));
+          }
+          if (rawDbg && rawDbg.result && rawDbg.result.type !== 'undefined') {
+            await debuggerDetach(tab.id).catch(() => {});
+            return { result: rawDbg.result.value, method: 'debugger' };
+          }
+          dbgErr = 'empty/undefined CDP response: ' + JSON.stringify(rawDbg);
+        } catch (e) {
+          const m = String(e?.message || e);
+          if (m.startsWith('__SCRIPT_EX__')) {
+            throw new Error(m.slice('__SCRIPT_EX__'.length) + ' | scripting-diag: ' + JSON.stringify(diag));
+          }
+          dbgErr = m;
+          if (!/detach|attach|empty|gone|given id|not attached/i.test(m)) break;
         }
-        throw e;
+        await debuggerDetach(tab.id).catch(() => {});
+        await new Promise(r => setTimeout(r, 200 + attempt * 200));
       }
+      throw new Error(
+        'execute_script failed on all paths. debugger: ' + dbgErr +
+        ' | raw: ' + JSON.stringify(rawDbg) +
+        ' | scripting-diag: ' + JSON.stringify(diag)
+      );
     }
 
     case 'click': {
       const tab = await getSessionTab(port);
       if (tab.url.startsWith('chrome://')) throw new Error('Cannot interact with chrome:// pages');
 
-      // Resolve element (supports CSS + text selectors, auto-scrolls)
-      const el = await resolveElement(tab.id, params.selector);
-      if (!el) return { ok: false, error: 'Element not found: ' + params.selector };
-
-      // Primary path: debugger mouse events (isTrusted=true, works on React/Angular SPAs)
+      // Wrap full click flow (incl. resolveElement) so debugger failures in EITHER
+      // resolveElement (text-selectors use debuggerEval) OR debuggerClick trigger
+      // the scripting-fallback. v1.21.2: previously only debuggerClick was wrapped,
+      // leaving text-selector clicks unrecoverable when debugger was user-blocked.
       try {
+        const el = await resolveElement(tab.id, params.selector);
+        if (!el) return { ok: false, error: 'Element not found: ' + params.selector };
+
+        // Primary path: debugger mouse events (isTrusted=true, works on React/Angular SPAs)
         await debuggerClick(tab.id, el.x, el.y);
         return { ok: true, method: el.method || 'debugger', tag: el.tag, text: el.text };
       } catch (e) {
         // Fallback: synthetic click via chrome.scripting for anti-automation sites
-        // (Apple ASC etc.) where Chrome auto-detaches debugger on every interaction.
+        // (Apple ASC etc.) OR user-blocked-debugger scenarios.
         if (/Debugger detached/.test(e?.message || '')) {
           const r = await scriptingClick(tab.id, params.selector);
-          if (r.ok) return { ok: true, method: 'scripting-fallback', tag: r.tag, text: el.text };
+          if (r.ok) return { ok: true, method: 'scripting-fallback', tag: r.tag };
         }
         throw e;
       }
@@ -1847,11 +2116,24 @@ async function dispatch(port, method, params) {
     }
 
     case 'press_key': {
-      const tab = await getSessionTab(port);
+      // v1.22: activate tab so key-event lands in foreground (otherwise Chrome routes to active tab)
+      const tab = await getSessionTab(port, true);
       if (tab.url.startsWith('chrome://')) throw new Error('Cannot interact with chrome:// pages');
       const key = params.key; // e.g. "Enter", "Tab", "Escape", "ArrowDown"
       const modifiers = (params.ctrl ? 2 : 0) | (params.alt ? 1 : 0) | (params.shift ? 8 : 0) | (params.meta ? 4 : 0);
 
+      // v1.22: Chrome requires windowsVirtualKeyCode for navigation/system keys to trigger
+      // scroll/form-submit behavior. Without these, key-event is dispatched but page doesn't react.
+      const VK_CODES = {
+        'Backspace': 8, 'Tab': 9, 'Enter': 13, 'Shift': 16, 'Control': 17, 'Alt': 18,
+        'Escape': 27, 'Space': 32, ' ': 32,
+        'PageUp': 33, 'PageDown': 34, 'End': 35, 'Home': 36,
+        'ArrowLeft': 37, 'ArrowUp': 38, 'ArrowRight': 39, 'ArrowDown': 40,
+        'Delete': 46,
+      };
+      const vkCode = VK_CODES[key];
+      const vkParams = vkCode ? { windowsVirtualKeyCode: vkCode, nativeVirtualKeyCode: vkCode } : {};
+
       await debuggerAttach(tab.id);
       try {
         await cdpSend(tab.id, 'Input.dispatchKeyEvent', {
@@ -1860,12 +2142,14 @@ async function dispatch(port, method, params) {
           code: params.code || key,
           modifiers,
           text: key.length === 1 ? key : '',
+          ...vkParams,
         });
         await cdpSend(tab.id, 'Input.dispatchKeyEvent', {
           type: 'keyUp',
           key,
           code: params.code || key,
           modifiers,
+          ...vkParams,
         });
       } finally {
         await debuggerDetach(tab.id);
@@ -1874,6 +2158,8 @@ async function dispatch(port, method, params) {
     }
 
     case 'scroll': {
+      // v1.22: NO activate — CDP Input.dispatchMouseEvent goes via debugger directly to target,
+      // doesn't need active tab. Re-activating on every scroll-call destabilizes debugger.
       const tab = await getSessionTab(port);
       if (tab.url.startsWith('chrome://')) throw new Error('Cannot interact with chrome:// pages');
       // Scroll to element
@@ -1882,20 +2168,32 @@ async function dispatch(port, method, params) {
         if (!el) return { ok: false, error: 'Element not found: ' + params.selector };
         return { ok: true, scrolled_to: params.selector };
       }
-      // Scroll by pixels using CDP mouseWheel — works in React containers with overflow:scroll
+      // Scroll by pixels using CDP mouseWheel — split into smaller steps so IntersectionObservers fire.
+      // FB/Twitter/IG only trigger lazy-load on continuous wheel events, not a single large delta.
       const dx = params.x || 0;
       const dy = params.y || 0;
       try {
         await debuggerAttach(tab.id);
-        await cdpSend(tab.id, 'Input.dispatchMouseEvent', {
-          type: 'mouseWheel', x: 400, y: 300, deltaX: dx, deltaY: dy,
-        });
-        await debuggerDetach(tab.id);
-      } catch {
-        // Fallback to window.scrollBy for simple pages
+        const STEP_SIZE = 300; // pixels per wheel-event (matches a typical mouse-wheel notch)
+        const totalSteps = Math.max(1, Math.ceil(Math.max(Math.abs(dx), Math.abs(dy)) / STEP_SIZE));
+        const stepX = dx / totalSteps;
+        const stepY = dy / totalSteps;
+        for (let i = 0; i < totalSteps; i++) {
+          await cdpSend(tab.id, 'Input.dispatchMouseEvent', {
+            type: 'mouseWheel', x: 400, y: 300, deltaX: stepX, deltaY: stepY,
+          });
+          // Small delay between wheel-events so IntersectionObserver + lazy-load XHRs can fire
+          if (i < totalSteps - 1) await new Promise(r => setTimeout(r, 80));
+        }
+        // After last wheel-event, give FB/Twitter/IG ~600ms to start lazy-load XHRs
+        // before any subsequent commands run (caller often scrapes immediately after)
+        await new Promise(r => setTimeout(r, 600));
+      } catch (e) {
+        // Fallback to window.scrollBy for simple pages (synthetic but works on non-anti-scrape sites)
         await debuggerEval(tab.id, `window.scrollBy(${dx}, ${dy})`);
+        return { ok: true, scrolled: { x: dx, y: dy }, method: 'fallback', fallback_reason: e.message };
       }
-      return { ok: true, scrolled: { x: dx, y: dy } };
+      return { ok: true, scrolled: { x: dx, y: dy }, method: 'mouseWheel-stepped' };
     }
 
     case 'hover': {

package/extension/manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest_version": 3,
   "name": "Agent360 Browser MCP",
-  "version": "1.21.0",
-  "description": "Control your real Chrome from Claude Code — navigate, click, fill, screenshot, solve CAPTCHAs. 33 tools, multi-session.",
+  "version": "1.24.0",
+  "description": "Control your real Chrome from Claude Code — navigate, click, fill, screenshot, solve CAPTCHAs. 34 tools, multi-session.",
   "permissions": [
     "tabs",
     "tabGroups",

package/index.js

@@ -14,9 +14,9 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { WebSocketServer } from 'ws';
 import { execSync } from 'child_process';
-import { dirname, join } from 'path';
+import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
-import { readFileSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { TOOLS, PROVIDER_PAGES } from './tools.js';
 
 // Read version from package.json — single source of truth, never drifts
@@ -209,7 +209,7 @@ const INSTRUCTIONS = `You control the user's real Chrome browser via this MCP se
 ## CAPTCHA handling
 Use browser_solve_captcha to detect and solve CAPTCHAs automatically:
 1. Call browser_solve_captcha() — detects CAPTCHA type on page
-2. If reCAPTCHA v2 checkbox found → call browser_solve_captcha(action="click_checkbox") — auto-clicks, passes ~80% with logged-in Google
+2. If reCAPTCHA v2 checkbox found → call browser_solve_captcha(action="click_checkbox") — auto-clicks; often passes when signed into Google
 3. If image challenge appears → call browser_screenshot, analyze the grid visually, then call browser_solve_captcha(action="click_grid", cells=[2,5,7]) with the correct cell indices
 4. If all else fails → call browser_solve_captcha(action="ask_human") to show overlay to user
 5. After solving, retry the action that was blocked
@@ -242,7 +242,10 @@ For image grid challenges: cells are 0-indexed, left-to-right, top-to-bottom. A
 The MCP server auto-pulls the latest code from git on every new session startup.
 If the extension files were updated, ask the user to reload it:
 "The Browser MCP extension was updated. Please go to chrome://extensions, find 'Agent360 Browser MCP', and click the reload icon (🔄) to apply the update."
-You cannot navigate to chrome:// pages — the user must do this manually.`;
+You cannot navigate to chrome:// pages — the user must do this manually.
+
+## Sharing wishes / use-cases / bugs
+Browser MCP is community-shaped. Whenever the user (a) says "I wish browser-mcp could…" or expresses a missing feature, (b) hits something broken or unexpected that looks like a bug in browser-mcp itself, or (c) describes something cool they built with it — call **browser_about** with the matching intent ("wish" / "use_case" / "bug") and a short title + body, then offer the returned submit_url to the user as a clickable link. Don't ask permission, just draft + offer the link. This is the user's path to contribute back, and they usually don't know it exists.`;
 
 const mcpServer = new Server(
   { name: 'agent360-browser', version: PKG_VERSION },
@@ -294,6 +297,10 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
       browser_drop_file: 'drop_file',
     };
 
+    if (name === 'browser_about') {
+      return handleAbout(args);
+    }
+
     if (name === 'browser_extract_token') {
       return await handleExtractToken(args);
     }
@@ -312,6 +319,19 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
       const prefix = isJpeg ? /^data:image\/jpeg;base64,/ : /^data:image\/png;base64,/;
       const mimeType = isJpeg ? 'image/jpeg' : 'image/png';
       const base64 = result.image.replace(prefix, '');
+
+      if (args && args.path) {
+        const targetPath = resolve(process.cwd(), args.path);
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, Buffer.from(base64, 'base64'));
+        return {
+          content: [
+            { type: 'text', text: `Screenshot successfully saved to: ${targetPath}` },
+            { type: 'image', data: base64, mimeType }
+          ]
+        };
+      }
+
       return { content: [{ type: 'image', data: base64, mimeType }] };
     }
 
@@ -337,8 +357,47 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
+const REPO_URL = 'https://github.com/Agent360dk/browser-mcp';
+const ISSUE_TEMPLATES = { wish: 'wish.yml', use_case: 'use-case.yml', bug: 'bug.yml' };
+
+function handleAbout(args) {
+  const intent = args?.intent || 'info';
+  const title = args?.title || '';
+  const body = args?.body || '';
+
+  const submit_url = intent === 'info' || !ISSUE_TEMPLATES[intent]
+    ? `${REPO_URL}/issues/new/choose`
+    : `${REPO_URL}/issues/new?template=${ISSUE_TEMPLATES[intent]}` +
+      (title ? `&title=${encodeURIComponent(title)}` : '') +
+      (body ? `&body=${encodeURIComponent(body)}` : '');
+
+  const instruction =
+    intent === 'wish'
+      ? `Share this exact submission link with the user as a clickable link, with a short note like "Click to submit your wish — it'll open a pre-filled GitHub issue you can review before submitting": ${submit_url}`
+      : intent === 'use_case'
+      ? `Share this exact submission link with the user as a clickable link, with a short note like "Click to share your use-case — pre-filled, you can edit before submitting": ${submit_url}`
+      : intent === 'bug'
+      ? `Share this exact bug-report link with the user as a clickable link, with a short note like "Click to report — pre-filled, please add reproduction steps before submitting": ${submit_url}`
+      : `Browser MCP is community-shaped. Open wishlist: ${REPO_URL}/blob/main/WISHLIST.md · Use-cases: ${REPO_URL}/blob/main/USE_CASES.md · Submit anything: ${REPO_URL}/issues/new/choose`;
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        name: 'Browser MCP by Agent360',
+        version: PKG_VERSION,
+        repo: REPO_URL,
+        wishlist: `${REPO_URL}/blob/main/WISHLIST.md`,
+        use_cases: `${REPO_URL}/blob/main/USE_CASES.md`,
+        submit_url,
+        instruction,
+      }, null, 2),
+    }],
+  };
+}
+
 async function handleExtractToken(args) {
-  const { provider, store_in_vault } = args;
+  const { provider } = args;
   const info = PROVIDER_PAGES[provider];
 
   if (!info) {
@@ -351,18 +410,11 @@ async function handleExtractToken(args) {
   }
 
   const nav = await sendToExtension('navigate', { url: info.url });
-  const content = [
-    { type: 'text', text: `Navigated to ${info.url} (${nav.title})\n\nInstructions: ${info.instructions}\n\nUse browser_get_page_content or browser_screenshot to find the token, then use browser_execute_script to extract it.` },
-  ];
-
-  if (store_in_vault) {
-    content.push({
-      type: 'text',
-      text: `\nWhen you have the token, POST it to the vault:\ncurl -X POST http://localhost:8000/v1/vault/connect -H "Authorization: Bearer {jwt}" -d '{"provider":"${provider}","token":"{extracted_token}"}'`,
-    });
-  }
-
-  return { content };
+  return {
+    content: [
+      { type: 'text', text: `Navigated to ${info.url} (${nav.title})\n\nInstructions: ${info.instructions}\n\nUse browser_get_page_content or browser_screenshot to find the token, then use browser_execute_script to extract it.` },
+    ],
+  };
 }
 
 // ── Graceful shutdown ──────────────────────────────────────────────────────

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agent360/browser-mcp",
-  "version": "1.21.0",
-  "description": "Browser MCP — control your real Chrome from Claude Code. 33 tools, CAPTCHA solving, date pickers, autocomplete combobox, overlay dismissal, file upload, multi-session, human-in-the-loop.",
+  "version": "1.24.0",
+  "description": "Browser MCP — control your real Chrome from Claude Code. 34 tools, CAPTCHA solving, date pickers, autocomplete combobox, overlay dismissal, file upload, multi-session, human-in-the-loop.",
   "mcpName": "io.github.Agent360dk/browser-mcp",
   "type": "module",
   "main": "index.js",
@@ -42,7 +42,11 @@
   "engines": {
     "node": ">=18"
   },
-  "author": "Agent360 <hello@agent360.dk>",
+  "author": {
+    "name": "Agent360",
+    "email": "hello@agent360.dk",
+    "url": "https://agent360.dk"
+  },
   "license": "MIT",
   "homepage": "https://browsermcp.dev",
   "repository": {

package/tools.js

@@ -29,8 +29,13 @@ export const TOOLS = [
   },
   {
     name: 'browser_screenshot',
-    description: 'Take a screenshot of the visible area of the current tab. Returns base64 PNG.',
-    inputSchema: { type: 'object', properties: {} },
+    description: 'Take a screenshot of the visible area of the current tab. Returns base64 PNG, or saves to disk if path is provided.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'File path to save the screenshot to (e.g. /path/to/screenshot.png)' },
+      },
+    },
   },
   {
     name: 'browser_execute_script',
@@ -373,19 +378,18 @@ export const TOOLS = [
   },
   {
     name: 'browser_extract_token',
-    description: 'Navigate to a provider\'s API settings page and extract the API token. Optionally store it in Agent360 vault.',
+    description: 'Navigate to a provider\'s API settings page so you can read its API token from the page.',
     inputSchema: {
       type: 'object',
       properties: {
         provider: { type: 'string', description: 'Provider slug (stripe, hubspot, slack, etc.)' },
-        store_in_vault: { type: 'boolean', description: 'If true, POST token to Agent360 vault API' },
       },
       required: ['provider'],
     },
   },
   {
     name: 'browser_solve_captcha',
-    description: 'Detect and solve CAPTCHAs on the current page. Auto-detects reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, and FunCaptcha. Tries auto-click first (works ~80% with logged-in Google), then returns a screenshot for AI vision analysis, then falls back to asking the user. Returns detection info and solving status.',
+    description: 'Detect and solve CAPTCHAs on the current page. Auto-detects reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, and FunCaptcha. Tries auto-click first (often clears reCAPTCHA v2 when signed into Google), then returns a screenshot for AI vision analysis, then falls back to asking the user. Returns detection info and solving status.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -398,6 +402,28 @@ export const TOOLS = [
       },
     },
   },
+  {
+    name: 'browser_about',
+    description: 'Returns Browser MCP info and pre-filled URLs the user can click to submit feature wishes, share use-cases, or report bugs. Call this PROACTIVELY whenever the user (a) mentions a feature they wish existed ("I wish browser-mcp could...", "it would be nice if..."), (b) says something is missing, broken, or unexpected, (c) asks how Browser MCP works or who maintains it, or (d) describes something cool they built with browser-mcp. Pass intent="wish" | "use_case" | "bug" | "info" plus an optional title and body, and offer the returned submit_url to the user. Browser MCP is community-shaped — this tool is how the user contributes back.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        intent: {
+          type: 'string',
+          enum: ['wish', 'use_case', 'bug', 'info'],
+          description: 'What the user wants to share. "wish" = feature request, "use_case" = share what they built, "bug" = something broken, "info" = general (default: "info").',
+        },
+        title: {
+          type: 'string',
+          description: 'Optional pre-filled issue title (e.g. "Support hCaptcha v3"). Will be URL-encoded into the submit link.',
+        },
+        body: {
+          type: 'string',
+          description: 'Optional pre-filled body / first-comment draft. Will be URL-encoded into the submit link. Keep it short; user can expand on GitHub.',
+        },
+      },
+    },
+  },
 ];
 
 // Known provider token pages for browser_extract_token