chrome-bridge-mcp 1.23.4 → 1.25.0

package/README.md

@@ -9,15 +9,16 @@ with your extensions and your cookies — works in it, and hands it back. What
 only a person can do (a login, a 2FA code, a CAPTCHA, a choice) comes back to
 you through `handoff`: a banner in the page, you act, the agent continues.**
 
-Measured against the official browser extension (paired runs, 27/09/2026, n=5
-per task, same model): filling a form, 2.5× fewer turns and 1.9× lower cost;
-finding one row in a 1,500-row table, 2.3× lower cost in about the same number
-of turns. ~3× the toolset and no paid plan. 60
+Measured against the official browser extension (paired runs, 29/09/2026, n=5
+per task, same model): filling a form, 4.7× fewer turns and 2.8× lower cost;
+finding one row in a 1,500-row table, 2.3× fewer turns and 3.4× lower cost;
+debugging a broken page, 4.7× fewer turns and 3.2× lower cost. 15 correct
+answers out of 15, against 12 ([bench/RESULTS.md](bench/RESULTS.md)). ~3× the toolset and no paid plan. 60
 web-development tools (navigation, DOM inspection, visual regression, audits,
 network mocking) over a local WebSocket bridge, plus a headless instance for
 CI. Self-hosted, local-only. Works on ChromeOS.
 
-![The same form filled in 6 turns instead of 15 — 2.5× fewer turns on the form, about half the cost on the form and on a 1,500-row table (paired runs, 27/09/2026, n=5)](assets/readme/card1-race.png)
+![The same form filled in 3 turns instead of 14 — 4.7× fewer turns on the form, 2.8-3.4× lower cost on form, 1,500-row table and debugging (paired runs, 29/09/2026, n=5)](assets/readme/card1-race.png)
 
 ## Quickstart
 
@@ -57,10 +58,13 @@ element refs, `click(ref="n1")` follows with no discovery turn in between.
 For `execute_js`, enable **Allow user scripts** in `chrome://extensions` →
 Chrome Bridge → Details (on Chrome 135-137, enable Developer Mode instead).
 
-**As a plugin, without a clone:** in Claude Code,
+**As a plugin, without a clone:** inside a Claude Code session,
 `/plugin install chrome-bridge --marketplace frsorrentino/chrome-bridge`
 (one command, Claude Code 2.1.275+; on older versions `/plugin marketplace add
-frsorrentino/chrome-bridge` then `/plugin install chrome-bridge@chrome-bridge`)
+frsorrentino/chrome-bridge` then `/plugin install chrome-bridge@chrome-bridge`).
+From a shell, `claude plugin install` has no `--marketplace` option: run
+`claude plugin marketplace add frsorrentino/chrome-bridge`, then
+`claude plugin install chrome-bridge@chrome-bridge`. Either way the plugin
 registers the MCP server from npm (all capabilities) together with the recipes
 skill; clients that read [Agent Plugins 1.0](https://agent-plugins.org) get the
 same from `plugin.json` + `mcp.json`. The extension still comes from the Web
@@ -91,7 +95,7 @@ or let you pick one or more elements on the page.
 | | Chrome Bridge | Claude in Chrome | Chrome DevTools MCP | Playwright MCP |
 |---|---|---|---|---|
 | **ChromeOS / Crostini** | **Yes** (real host) | No | Container only | Container only |
-| **Tools** | **60** (39 core) | 22 | 29 default (56 with flags) | 24 core (71 total) |
+| **Tools** | **60** (43 core) | 22 | 29 default (56 with flags) | 24 core (71 total) |
 | **Requires paid plan** | **No** | Yes (Pro+) | No | No |
 | **Network mocking** | **Yes** (stub/headers) | No | No | Yes |
 | **Visual regression** | **Yes** (`screenshot_diff`) | No | No | No |
@@ -160,8 +164,10 @@ user-script toggle isn't available.
 
 ## Tools
 
-60 in total, in seven groups. Only `core` (39 tools) loads by default; the rest
-are opt-in via `--caps`.
+60 in total. `core` (43 tools, every tool used in 101 real sessions) loads by
+default; the other 17 sit in six optional caps that the agent switches on
+mid-session with `get_status({enable: ["visual"]})`, with no restart
+(`--caps` still sets them at startup).
 
 ![60 tools in seven groups, from clicking a button to auditing a whole page](assets/readme/card4-toolbox.png)
 
@@ -199,7 +205,7 @@ Environment variables, each with a matching CLI flag:
 | `CHROME_BRIDGE_PORT` | `8765` | |
 | `CHROME_BRIDGE_HOST` / `--host` | `127.0.0.1` | `0.0.0.0` **only** where the browser lives outside the container (ChromeOS/Crostini port-forward) — and only with a token |
 | `CHROME_BRIDGE_TOKEN` | unset | Required on both `ext_init` and `relay_init`. Strongly recommended whenever the bind isn't loopback |
-| `CHROME_BRIDGE_CAPS` / `--caps` | `core` | `core`, `audits`, `visual`, `network`, `storage`, `dom`, `files`, `all`. `install.sh` uses `all` |
+| `CHROME_BRIDGE_CAPS` / `--caps` | `core` | `core`, `audits`, `visual`, `network`, `storage`, `dom`, `files`, `all`. Optional caps can also be switched on at runtime with `get_status({enable})` |
 | `CHROME_BRIDGE_NO_JS` / `--no-js` | unset | No arbitrary JavaScript in the page: `execute_js` and `modify_dom` leave the schema, `wait_for(condition=function)` and `javascript:`/`data:` URLs are refused. `get_status` reports `js_evaluation` |
 | `CHROME_BRIDGE_READ_ROOT` / `--read-root` | unset | Where `upload_file` may read from. Unset: any file except keys and credentials (`~/.ssh`, `~/.aws`, `~/.gnupg`, `.env*`, `id_*`, `*.pem`, `*.key`, …), symlinks resolved first. Set: only files under this directory, whatever their name — the way to upload a certificate key on purpose |
 | `CHROME_BRIDGE_BROWSER` | unset | Launch mode only: the browser binary, e.g. `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`. Unset: the first of Chromium, Edge, Brave, Google Chrome found in the standard paths (on Linux Chromium, then Google Chrome). Google Chrome 137+ cannot load the extension |

package/extension/console-capture.js

@@ -12,11 +12,22 @@
   window.__chromeBridge_consoleHooked = true;
   window.__chromeBridge_consoleLogs = [];
   const MAX = 1000;
+  // seq: cursore per read_console({since}), che restituisce solo le voci nuove
+  // senza cancellare niente.
+  let seq = 0;
   const push = (entry) => {
+    entry.seq = ++seq;
     const buf = window.__chromeBridge_consoleLogs;
     if (buf.length >= MAX) buf.shift(); // ring buffer: tieni i più recenti, non i primi 1000
     buf.push(entry);
   };
+  // Un Error passato a console.error diventava "{}" (JSON.stringify non vede
+  // message e stack, che non sono enumerabili): lo stack è l'unica cosa che
+  // read_console(sourcemap) può riportare ai sorgenti. Duck typing e non
+  // instanceof, perché un Error di un iframe viene da un altro realm.
+  const errorText = (v) => (v && typeof v === 'object' && typeof v.message === 'string'
+    ? (typeof v.stack === 'string' && v.stack ? v.stack : `${v.name || 'Error'}: ${v.message}`)
+    : null);
   for (const method of ['log', 'warn', 'error', 'info', 'debug']) {
     const orig = console[method].bind(console);
     console[method] = (...args) => {
@@ -24,7 +35,7 @@
         push({
           level: method,
           args: args.map((a) => {
-            try { return typeof a === 'object' ? JSON.stringify(a) : String(a); }
+            try { return errorText(a) ?? (typeof a === 'object' ? JSON.stringify(a) : String(a)); }
             catch { return String(a); }
           }),
           timestamp: Date.now(),
@@ -34,12 +45,29 @@
     };
   }
   window.addEventListener('error', (e) => {
-    try { push({ level: 'error', args: [`Uncaught ${e.message} at ${e.filename || '?'}:${e.lineno || 0}`], timestamp: Date.now() }); } catch {}
+    try {
+      // Un'immagine o uno script che non si carica arriva qui in fase di
+      // cattura, con target l'elemento e nessun messaggio: prima diventava
+      // «Uncaught  at ?:0:0». Ora dice quale risorsa.
+      const t = e.target;
+      if (t && t !== window && t.tagName) {
+        const url = t.currentSrc || t.src || t.href || '';
+        push({ level: 'error', args: [`Failed to load ${String(t.tagName).toLowerCase()}${url ? ` ${url}` : ''}`], timestamp: Date.now() });
+        return;
+      }
+      // Con la colonna il frame diventa url:riga:colonna, risolvibile dalla source map.
+      const stack = errorText(e.error);
+      push({
+        level: 'error',
+        args: [stack ? `Uncaught ${stack}` : `Uncaught ${e.message} at ${e.filename || '?'}:${e.lineno || 0}:${e.colno || 0}`],
+        timestamp: Date.now(),
+      });
+    } catch {}
   }, true);
   window.addEventListener('unhandledrejection', (e) => {
     try {
       let reason;
-      try { reason = String(e.reason); } catch { reason = '<unstringifiable>'; }
+      try { reason = errorText(e.reason) ?? String(e.reason); } catch { reason = '<unstringifiable>'; }
       push({ level: 'error', args: [`Unhandled rejection: ${reason}`], timestamp: Date.now() });
     } catch {}
   });

package/extension/lib/capture-pacing.js

@@ -5,11 +5,15 @@
  * 520 ms dalla precedente. Orologio e sleep iniettabili per i test.
  */
 export function createPacer({ minIntervalMs = 520, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
-  let last = -Infinity;
+  // Lo slot si prenota prima di dormire: due catture concorrenti leggevano lo
+  // stesso "ultimo" e si svegliavano insieme, e la seconda sforava la quota.
+  let next = -Infinity;
   const pace = async () => {
-    const wait = Math.max(0, last + minIntervalMs - now());
+    const t = now();
+    const slot = Math.max(t, next);
+    next = slot + minIntervalMs;
+    const wait = slot - t;
     if (wait > 0) await sleep(wait);
-    last = now();
     return wait;
   };
   pace.minIntervalMs = minIntervalMs;

package/extension/lib/css-cascade.js

@@ -290,7 +290,21 @@
     const out = [];
     for (let i = 0; i < style.length; i += 1) {
       const prop = style[i];
-      out.push({ prop, value: style.getPropertyValue(prop), important: style.getPropertyPriority(prop) === 'important' });
+      let value = style.getPropertyValue(prop);
+      // `background: var(--x)`: per la specifica CSSOM le proprietà singole
+      // valgono "" (sostituzione in sospeso). Il testo vero sta nella
+      // abbreviata: background-color → background, border-top-color →
+      // border-top → border.
+      let shorthand;
+      if (value === '' && !prop.startsWith('--')) {
+        const parts = prop.split('-');
+        for (let k = parts.length - 1; k >= 1 && value === ''; k -= 1) {
+          const sh = parts.slice(0, k).join('-');
+          const v = style.getPropertyValue(sh);
+          if (v) { value = v; shorthand = sh; }
+        }
+      }
+      out.push({ prop, value, ...(shorthand && { shorthand }), important: style.getPropertyPriority(prop) === 'important' });
     }
     return out;
   };
@@ -330,6 +344,7 @@
   const fmtEntry = (list, computed, inheritedFrom) => {
     const [winner, ...rest] = list;
     const entry = { value: winner.value };
+    if (winner.shorthand) entry.shorthand = winner.shorthand;
     if (winner.important) entry.important = true;
     if (computed != null) entry.computed = computed;
     if (inheritedFrom) entry.inherited_from = inheritedFrom;
@@ -386,6 +401,16 @@
       }
     }
 
+    // var(--x) senza --x definita sull'elemento (né ereditata): la proprietà
+    // cade sul valore iniziale. Detto qui, il modello non spende una seconda
+    // chiamata a cercare dove --x sia definita (benchmark debug del 28/09).
+    for (const entry of Object.values(properties)) {
+      const names = [...String(entry.value ?? '').matchAll(/var\(\s*(--[\w-]+)\s*(,)?/g)]
+        .filter((m) => !m[2]).map((m) => m[1]);
+      const missing = [...new Set(names)].filter((n) => String(computedOf(n) ?? '').trim() === '');
+      if (missing.length) entry.undefined_vars = missing;
+    }
+
     const sorted = {};
     for (const k of Object.keys(properties).sort()) sorted[k] = properties[k];
     const out = { selector: opts.selector ?? null, element: describe(el), matched_rules: matched };

package/extension/lib/page-fingerprint.js

@@ -7,8 +7,31 @@
  * sorgente e la esegue nella pagina, dove niente di questo modulo esiste.
  * Prende `doc` per essere testabile su un DOM finto (test/unit).
  */
-export function pageFingerprint(doc) {
+export function pageFingerprint(doc, settle) {
   const d = doc || document;
+  // Con settle l'impronta aspetta che il DOM si fermi: nessuna mutazione per
+  // quiet_ms, al più max_ms. Sostituisce la pausa fissa dopo un click (150 ms
+  // anche su una pagina già ferma). Su una pagina nascosta i timer sono
+  // strozzati a 1 s: niente attesa, e lo dice.
+  if (settle && typeof MutationObserver === 'function') {
+    const quiet = settle.quiet_ms ?? 50;
+    const max = settle.max_ms ?? 250;
+    if (d.hidden) return { ...pageFingerprint(d), settled_ms: 0, hidden: true };
+    return new Promise((resolve) => {
+      const t0 = performance.now();
+      let last = t0;
+      const mo = new MutationObserver(() => { last = performance.now(); });
+      try { mo.observe(d.documentElement, { subtree: true, childList: true, attributes: true, characterData: true }); } catch { /* niente da osservare */ }
+      const tick = () => {
+        const now = performance.now();
+        if (now - last >= quiet || now - t0 >= max) {
+          mo.disconnect();
+          resolve({ ...pageFingerprint(d), settled_ms: Math.round(now - t0) });
+        } else setTimeout(tick, 10);
+      };
+      setTimeout(tick, quiet);
+    });
+  }
   const count = (sel) => { try { return d.querySelectorAll(sel).length; } catch { return 0; } };
   let checked = 0;
   try { for (const el of d.querySelectorAll('input')) if (el.checked) checked += 1; } catch { /* nessun input */ }

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Chrome Bridge for Claude Code",
-  "version": "1.23.4",
+  "version": "1.25.0",
   "description": "Bridge your browser to Claude Code: 60 token-efficient web-dev automation tools over a local WebSocket. ChromeOS included.",
   "homepage_url": "https://github.com/frsorrentino/chrome-bridge",
   "minimum_chrome_version": "135",

package/extension/network-hook.js

@@ -0,0 +1,100 @@
+/**
+ * Gancio fetch/XHR in MAIN world, a document_start insieme alla cattura della
+ * console (vedi _applyInstrumentation nel service worker): le richieste fatte
+ * durante il caricamento della pagina entrano nel buffer letto da
+ * monitor_network. Prima il gancio arrivava solo alla prima chiamata e la
+ * richiesta fallita all'avvio, il caso tipico da debuggare, non si vedeva.
+ * Lo stesso file viene iniettato da ensureNetworkHook sulle pagine aperte
+ * prima dell'estensione; la guardia lo rende idempotente.
+ */
+(() => {
+      if (window.__chromeBridge_networkHooked) return;
+      window.__chromeBridge_networkHooked = true;
+      window.__chromeBridge_networkRequests = [];
+      window.__chromeBridge_netSeq = 0;
+      window.__chromeBridge_inflight = 0;
+      window.__chromeBridge_lastNetActivity = Date.now();
+      const MAX = 1000;
+
+      // --- Patch fetch ---
+      const origFetch = window.fetch.bind(window);
+      window.fetch = async (...args) => {
+        const req = args[0];
+        const url = typeof req === 'string' ? req : req?.url || String(req);
+        const method = (args[1]?.method || (req?.method) || 'GET').toUpperCase();
+        const entry = { type: 'fetch', method, url, startTime: Date.now(), status: null, duration: null, error: null };
+        window.__chromeBridge_inflight += 1;
+        window.__chromeBridge_lastNetActivity = Date.now();
+        try {
+          const resp = await origFetch(...args);
+          entry.status = resp.status;
+          entry.duration = Date.now() - entry.startTime;
+          // Ring buffer: scarta le più VECCHIE, non le nuove. Scartare le nuove
+          // faceva consegnare al modello le richieste dei primi secondi di vita
+          // della pagina etichettate come "most recent".
+          entry.seq = ++window.__chromeBridge_netSeq; window.__chromeBridge_networkRequests.push(entry);
+          if (window.__chromeBridge_networkRequests.length > MAX) {
+            window.__chromeBridge_networkRequests.shift();
+          }
+          window.__chromeBridge_inflight -= 1;
+          window.__chromeBridge_lastNetActivity = Date.now();
+          return resp;
+        } catch (err) {
+          entry.error = err.message;
+          entry.duration = Date.now() - entry.startTime;
+          // Ring buffer: scarta le più VECCHIE, non le nuove. Scartare le nuove
+          // faceva consegnare al modello le richieste dei primi secondi di vita
+          // della pagina etichettate come "most recent".
+          entry.seq = ++window.__chromeBridge_netSeq; window.__chromeBridge_networkRequests.push(entry);
+          if (window.__chromeBridge_networkRequests.length > MAX) {
+            window.__chromeBridge_networkRequests.shift();
+          }
+          window.__chromeBridge_inflight -= 1;
+          window.__chromeBridge_lastNetActivity = Date.now();
+          throw err;
+        }
+      };
+
+      // --- Patch XMLHttpRequest ---
+      const OrigXHR = window.XMLHttpRequest;
+      const origOpen = OrigXHR.prototype.open;
+      const origSend = OrigXHR.prototype.send;
+      OrigXHR.prototype.open = function (method, url, ...rest) {
+        this.__cb_method = method;
+        this.__cb_url = url;
+        return origOpen.call(this, method, url, ...rest);
+      };
+      OrigXHR.prototype.send = function (...args) {
+        const entry = { type: 'xhr', method: (this.__cb_method || 'GET').toUpperCase(), url: this.__cb_url || '', startTime: Date.now(), status: null, duration: null, error: null };
+        this.addEventListener('load', () => {
+          entry.status = this.status;
+          entry.duration = Date.now() - entry.startTime;
+          // Ring buffer: scarta le più VECCHIE, non le nuove. Scartare le nuove
+          // faceva consegnare al modello le richieste dei primi secondi di vita
+          // della pagina etichettate come "most recent".
+          entry.seq = ++window.__chromeBridge_netSeq; window.__chromeBridge_networkRequests.push(entry);
+          if (window.__chromeBridge_networkRequests.length > MAX) {
+            window.__chromeBridge_networkRequests.shift();
+          }
+        });
+        this.addEventListener('error', () => {
+          entry.error = 'Network error';
+          entry.duration = Date.now() - entry.startTime;
+          // Ring buffer: scarta le più VECCHIE, non le nuove. Scartare le nuove
+          // faceva consegnare al modello le richieste dei primi secondi di vita
+          // della pagina etichettate come "most recent".
+          entry.seq = ++window.__chromeBridge_netSeq; window.__chromeBridge_networkRequests.push(entry);
+          if (window.__chromeBridge_networkRequests.length > MAX) {
+            window.__chromeBridge_networkRequests.shift();
+          }
+        });
+        // loadend copre load, error e abort: traccia sempre la fine dell'in-flight
+        this.addEventListener('loadend', () => {
+          window.__chromeBridge_inflight -= 1;
+          window.__chromeBridge_lastNetActivity = Date.now();
+        });
+        window.__chromeBridge_inflight += 1;
+        window.__chromeBridge_lastNetActivity = Date.now();
+        return origSend.apply(this, args);
+      };
+    })();