chrome-bridge-mcp 1.15.0 → 1.16.0

package/README.md

@@ -1,15 +1,17 @@
 # Chrome Bridge
 
-![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-187%20unit%20%2B%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
+![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-brightgreen) ![Chrome 135+](https://img.shields.io/badge/chrome-%E2%89%A5135-blue) ![Tests](https://img.shields.io/badge/tests-257%20unit%20%2B%2032%20e2e-brightgreen) [![Chrome Web Store](https://img.shields.io/badge/web%20store-published-blue)](https://chromewebstore.google.com/detail/chrome-bridge-for-claude/bioknpaeahidbelaljjohjofiloeodmb)
 
 **An MCP server that gives Claude Code your real, logged-in Chrome — measured
 2.75× fewer turns and 2.28× lower cost than the official "Claude in Chrome"
 extension on a form-filling task, with ~3× the toolset and no paid plan.**
 
-63 web-development tools (navigation, DOM inspection, visual regression, audits,
+59 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.
 
+![The same form filled in 6 turns instead of 16.5 — 2.75× fewer turns, 2.28× lower cost](assets/readme/card1-race.png)
+
 ## Quickstart
 
 **Requires** Node.js 18+ and Chrome 135+.
@@ -25,7 +27,7 @@ cd chrome-bridge && ./install.sh
 
 Then ask for something like *"open localhost:3000, run an accessibility audit
 and find the Sign Up button"*: Claude Code calls `navigate`,
-`accessibility_audit` and `find_text`. Because `navigate` already returns
+`audit` and `find_text`. Because `navigate` already returns
 element refs, `click(ref="n1")` follows with no discovery turn in between.
 
 > **On ChromeOS/Crostini** install from the [Chrome Web
@@ -43,11 +45,11 @@ Chrome Bridge → Details (on Chrome 135-137, enable Developer Mode instead).
 | | Chrome Bridge | Claude in Chrome | Chrome DevTools MCP | Playwright MCP |
 |---|---|---|---|---|
 | **ChromeOS / Crostini** | **Yes** (real host) | No | Container only | Container only |
-| **Tools** | **63** (34 core) | ~20 | ~50 | 23 core (71 total) |
+| **Tools** | **59** (38 core) | ~20 | ~50 | 23 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 |
-| **Audits (a11y/SEO/sec)** | **Yes** (full suite) | No | Partial | No |
+| **Audits (a11y/SEO/sec)** | **Yes** (one call, report on disk) | No | Partial | No |
 | **Headless / CI** | **Yes** | No | Yes | Yes |
 | **GIF / video** | No | **Yes** | Partial | No |
 | **Breakpoints / heap** | No | No | **Yes** | No |
@@ -60,10 +62,22 @@ The full benchmark — method, every raw run including the unfavourable ones, an
 what the harness can't measure — is in
 [docs/EFFICIENCY.md](docs/EFFICIENCY.md).
 
+![Claude checks its own work: console errors, pixel diffs, network mocking and audits](assets/readme/card5-devloop.png)
+
 ## Using it
 
+The **skill** in [`skills/chrome-bridge/SKILL.md`](skills/chrome-bridge/SKILL.md)
+is what makes the tools discoverable: recipes with the phrase that triggers
+each one ("verify the email arrives", "test the checkout with a test card",
+"which plugin slows the page", "what fires before consent"), the tool sequence,
+and the zero-token CLI commands the model would otherwise never see.
+`install.sh` copies it to `~/.claude/skills/chrome-bridge`; do the same by
+hand for other clients.
+
 Beyond the MCP tools, two lanes keep work away from the model entirely.
 
+![Some jobs never touch the model: the CLI lane runs the same tools at zero tokens](assets/readme/card3-lane.png)
+
 **CLI** — batch operations, piped through `grep` or `jq` before anything reaches
 the context:
 
@@ -87,23 +101,27 @@ user-script toggle isn't available.
 
 ## Tools
 
-63 in total, in seven groups. Only `core` (34 tools) loads by default; the rest
+59 in total, in seven groups. Only `core` (38 tools) loads by default; the rest
 are opt-in via `--caps`.
 
+![59 tools in seven groups, from clicking a button to auditing a whole page](assets/readme/card4-toolbox.png)
+
 | Group | N | What's in it |
 |---|---|---|
-| Core & Navigation | 9 | tabs, windows, `navigate`, `screenshot`, `tile_windows` |
+| Core & Navigation | 13 | tabs, windows, `navigate`, `screenshot`, `tile_windows` |
 | Interaction | 11 | `click`, `fill_form`, `upload_file`, dialogs, clipboard |
-| DOM & Inspection | 11 | `read_page`, `extract`, `query_dom`, `watch_dom` |
-| Debugging & Network | 9 | `execute_js`, console, network log, mocking, Web Vitals |
-| Visual & Responsive | 7 | `screenshot_diff`, viewport, zoom, media emulation |
-| Audits | 6 | a11y, SEO, security headers, links, `extract_table` |
+| DOM & Inspection | 10 | `read_page`, `extract`, `query_dom`, `watch_dom` |
+| Debugging & Network | 8 | `execute_js`, console, network log, mocking, `track_events` |
+| Visual & Responsive | 5 | `screenshot_diff`, viewport and zoom, media emulation |
+| Audits | 2 | `audit` (a11y, keyboard, SEO, security, links, vitals, css, resources, cache in one call), `cookie_audit` |
 | State, Storage & Files | 9 | storage, fixtures, MHTML, recording, `assert` |
 
 Every tool, with the notes that matter: [docs/TOOLS.md](docs/TOOLS.md).
 
 ## How it works
 
+![It drives the Chrome you are logged into, over a local WebSocket bridge](assets/readme/card2-bridge.png)
+
 ```
 Claude Code  <--stdio-->  MCP Server  <--WebSocket :8765-->  Chrome Extension
                           (server/)                          (extension/, MV3)
@@ -153,7 +171,7 @@ paste into a chat.
 
 ## Documentation
 
-- [docs/TOOLS.md](docs/TOOLS.md) — all 63 tools, by group
+- [docs/TOOLS.md](docs/TOOLS.md) — all 59 tools, by group
 - [docs/EFFICIENCY.md](docs/EFFICIENCY.md) — the benchmark and the design behind it
 - [bench/RESULTS.md](bench/RESULTS.md) — raw runs and inclusion rule
 - [CHANGELOG.md](CHANGELOG.md)
@@ -161,7 +179,9 @@ paste into a chat.
 ## Tests
 
 `npm test` (Chrome-free, ~22s) · `npm run test:e2e` (needs Chrome and a
-connected extension) · `npm run measure` (schema cost).
+connected extension; with a bridge already on 8765:
+`CHROME_BRIDGE_PORT=8799 node test/test-devtools.js --launch`, which opens
+its own Chromium with `extension/`) · `npm run measure` (schema cost).
 
 ## License
 

package/extension/lib/download-state.js

@@ -0,0 +1,43 @@
+/**
+ * Legge lo stato reale di un download.
+ *
+ * `chrome.downloads.download()` restituisce un id e basta: dire "started: true"
+ * e fermarsi lì è come fidarsi di un HTTP 200 senza guardare il corpo. Su
+ * ChromeOS, con l'impostazione «Chiedi dove salvare ogni file» attiva, Chrome
+ * ignora `saveAs: false` e apre il selettore: il file viene scaricato per intero
+ * ma non viene scritto da nessuna parte finché un umano non sceglie.
+ *
+ * La firma di quella condizione è precisa e verificata dal vivo:
+ * `state: 'in_progress'`, `filename: ''`, `bytesReceived === totalBytes`.
+ * Senza distinguerla, un agente aspetta un file che non arriverà mai da solo.
+ */
+export function classifyDownload(item) {
+  if (!item) return { state: 'unknown', done: false, reason: 'download not found' };
+
+  const { state, filename, bytesReceived = 0, totalBytes = 0, error } = item;
+
+  if (state === 'complete') return { state: 'complete', done: true, filename };
+  if (state === 'interrupted') {
+    return { state: 'interrupted', done: true, error: error || 'interrupted', filename };
+  }
+
+  // Nessuna destinazione decisa: il selettore è aperto e aspetta una persona.
+  if (!filename) {
+    const fetched = totalBytes > 0 && bytesReceived >= totalBytes;
+    return {
+      state: 'waiting_for_user',
+      done: false,
+      bytes: { received: bytesReceived, total: totalBytes },
+      reason: fetched
+        ? 'bytes fetched, but Chrome is asking where to save — the "Ask where to save each file" setting overrides saveAs:false'
+        : 'no destination chosen yet — Chrome is showing the save dialog',
+    };
+  }
+
+  return {
+    state: 'in_progress',
+    done: false,
+    filename,
+    bytes: { received: bytesReceived, total: totalBytes },
+  };
+}

package/extension/manifest.json

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