chrome-bridge-mcp 1.29.3 → 1.30.0

package/README.md

@@ -164,12 +164,12 @@ user-script toggle isn't available.
 
 ## Tools
 
-66 in total. `core` (43 tools, every tool used in 101 real sessions) loads by
+67 in total. `core` (44 tools, every tool used in 101 real sessions) loads by
 default; the other 23 sit in seven optional caps that the agent switches on
 mid-session with `get_status({enable: ["visual"]})`, with no restart
 (`--caps` still sets them at startup).
 
-![66 tools in eight groups, from clicking a button to tracing a page](assets/readme/card4-toolbox.png)
+![67 tools in eight groups, from clicking a button to tracing a page](assets/readme/card4-toolbox.png)
 
 | Group | N | What's in it |
 |---|---|---|
@@ -179,7 +179,7 @@ mid-session with `get_status({enable: ["visual"]})`, with no restart
 | 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` |
+| State, Storage & Files | 10 | storage, fixtures, MHTML, `capture_downloads` (exports saved with no "Save as" dialog), recording, `assert` |
 | Motion & Performance | 6 | `animations`, `frames` (long frames, CLS, INP), `perf_trace`, `screencast`, `lighthouse` and `heap_snapshot` (launch mode) |
 
 Every tool, with the notes that matter: [docs/TOOLS.md](docs/TOOLS.md).
@@ -316,7 +316,7 @@ count.
 
 ## Documentation
 
-- [docs/TOOLS.md](docs/TOOLS.md) — all 66 tools, by group
+- [docs/TOOLS.md](docs/TOOLS.md) — all 67 tools, by group
 - [docs/CAPABILITIES.md](docs/CAPABILITIES.md) — what the bridge gets past and what it does not, one dated state per wall
 - [docs/EFFICIENCY.md](docs/EFFICIENCY.md) — the benchmark and the design behind it
 - [docs/PERFORMANCE.md](docs/PERFORMANCE.md) — latency per tool on the real path, `npm run bench:latency`

package/extension/lib/capture-hook.js

@@ -0,0 +1,206 @@
+/**
+ * capture_downloads, lato pagina: i file che la pagina costruisce da sé
+ * arrivano al server senza passare dal download di Chrome.
+ *
+ * Il problema (14/10/2026): un click su «Esporta» apre la finestra di sistema
+ * «Salva con nome», che nessun tool può premere; su ChromeOS con «Chiedi dove
+ * salvare ciascun file» si apre anche con saveAs:false. Qui il file viene preso
+ * prima che diventi un download:
+ * - a[download] con href blob: o data:, cliccato davvero o con a.click() su un
+ *   elemento staccato dal DOM (il caso più comune: createElement, click, revoke);
+ * - window.showSaveFilePicker: un handle finto raccoglie le scritture e alla
+ *   close consegna il file;
+ * - URL.createObjectURL tiene un riferimento al Blob mentre la cattura è armata,
+ *   così un revokeObjectURL subito dopo il click non lo perde.
+ *
+ * I file restano nella pagina (window.__cbCapture.items) finché il server li
+ * legge a pezzi e li butta. Disarmata, la pagina si comporta come senza hook.
+ *
+ * Non è un modulo ES: si inietta con files: in MAIN world (come element-label.js).
+ */
+(() => {
+  if (window.__cbCapture) return;
+  const st = {
+    armed: false,
+    max: 0,
+    items: [],
+    blobs: new Map(),
+    seq: 0,
+  };
+  Object.defineProperty(window, '__cbCapture', { value: st, configurable: true });
+
+  const newId = () => `c${Date.now().toString(36)}${(st.seq++).toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+
+  function add(blob, name, source) {
+    const item = { id: newId(), name: String(name || ''), mime: blob.type || '', size: blob.size, source };
+    if (blob.size > st.max) item.error = `too large: ${blob.size} bytes, max_mb allows ${st.max}`;
+    else item.blob = blob;
+    st.items.push(item);
+    return item;
+  }
+
+  // Un file preso da un URL (blob:, data:) è asincrono: l'item c'è subito,
+  // pending, così l'attesa del server lo vede e non chiude prima del tempo.
+  async function fromUrl(url, name, source) {
+    const item = { id: newId(), name: String(name || ''), source, pending: true };
+    st.items.push(item);
+    try {
+      const blob = st.blobs.get(url) ?? await (await fetch(url)).blob();
+      item.mime = blob.type || '';
+      item.size = blob.size;
+      if (blob.size > st.max) item.error = `too large: ${blob.size} bytes, max_mb allows ${st.max}`;
+      else item.blob = blob;
+    } catch (e) {
+      item.error = `could not read ${url.slice(0, 60)}: ${e.message}`;
+    }
+    delete item.pending;
+    return item;
+  }
+  st.fromUrl = fromUrl;
+
+  const origCreate = URL.createObjectURL;
+  URL.createObjectURL = function createObjectURL(obj) {
+    const url = origCreate.call(URL, obj);
+    if (st.armed && obj instanceof Blob) st.blobs.set(url, obj);
+    return url;
+  };
+
+  const capturable = (a) => a instanceof HTMLAnchorElement && a.hasAttribute('download') && /^(blob|data):/i.test(a.href || '');
+  const take = (a) => fromUrl(a.href, a.getAttribute('download') || '', a.href.startsWith('data:') ? 'data_url' : 'blob');
+
+  // Click veri o sintetici su un'ancora nel documento: bolla fino a window.
+  // Se la pagina ha già annullato il click, il download non era voluto.
+  const handled = new WeakSet();
+  window.addEventListener('click', (e) => {
+    if (!st.armed || e.defaultPrevented || handled.has(e)) return;
+    const a = e.composedPath().find((n) => n instanceof HTMLAnchorElement);
+    if (!capturable(a)) return;
+    handled.add(e);
+    e.preventDefault();
+    take(a);
+  });
+
+  // a.click() su un'ancora staccata: l'evento non arriva a window. Lo si
+  // spedisce qui, così i listener della pagina girano comunque. Anche un click
+  // sintetico attiva l'ancora (verificato 14/10: blob preso due volte, una
+  // dall'hook e una dal download): un listener sull'ancora, aggiunto dopo
+  // quelli della pagina, annulla l'azione nativa se la pagina non l'ha fatto.
+  const origClick = HTMLAnchorElement.prototype.click;
+  HTMLAnchorElement.prototype.click = function click() {
+    if (!st.armed || !capturable(this)) return origClick.apply(this, arguments);
+    const ev = new MouseEvent('click', { bubbles: true, cancelable: true, composed: true, view: window });
+    let wanted = false;
+    const last = (e) => {
+      if (e !== ev || e.defaultPrevented) return;
+      wanted = true;
+      handled.add(e);
+      e.preventDefault();
+    };
+    this.addEventListener('click', last);
+    try { this.dispatchEvent(ev); } finally { this.removeEventListener('click', last); }
+    if (wanted) take(this);
+  };
+
+  // --- showSaveFilePicker ---
+  const toBytes = async (d) => {
+    if (typeof d === 'string') return new TextEncoder().encode(d);
+    if (d instanceof Blob) return new Uint8Array(await d.arrayBuffer());
+    if (ArrayBuffer.isView(d)) return new Uint8Array(d.buffer, d.byteOffset, d.byteLength);
+    if (d instanceof ArrayBuffer) return new Uint8Array(d);
+    throw new TypeError('chrome-bridge capture: unsupported data for write()');
+  };
+  const isParams = (d) => d && typeof d === 'object' && !(d instanceof Blob) && !ArrayBuffer.isView(d) && !(d instanceof ArrayBuffer) && 'type' in d;
+
+  function makeHandle(name, mime) {
+    let committed = new Blob([], { type: mime });
+    const handle = {
+      kind: 'file',
+      name,
+      getFile: async () => new File([committed], name, { type: mime }),
+      createWritable: async (opts = {}) => {
+        let buf = new Uint8Array(0);
+        let len = 0;
+        let pos = 0;
+        if (opts.keepExistingData) {
+          buf = new Uint8Array(await committed.arrayBuffer());
+          len = buf.length;
+        }
+        const ensure = (n) => {
+          if (n > st.max) throw new DOMException(`chrome-bridge capture: ${name} over max_mb`, 'QuotaExceededError');
+          if (n <= buf.length) return;
+          const nb = new Uint8Array(Math.max(n, buf.length * 2, 64 * 1024));
+          nb.set(buf.subarray(0, len));
+          buf = nb;
+        };
+        const apply = async (d) => {
+          if (isParams(d)) {
+            if (d.type === 'seek') { pos = d.position; return; }
+            if (d.type === 'truncate') {
+              ensure(d.size);
+              if (d.size > len) buf.fill(0, len, d.size);
+              len = d.size;
+              if (pos > len) pos = len;
+              return;
+            }
+            if (d.position != null) pos = d.position;
+            d = d.data;
+          }
+          const b = await toBytes(d);
+          ensure(pos + b.length);
+          buf.set(b, pos);
+          pos += b.length;
+          if (pos > len) len = pos;
+        };
+        let closed = false;
+        const finish = () => {
+          if (closed) return;
+          closed = true;
+          committed = new Blob([buf.slice(0, len)], { type: mime });
+          add(committed, name, 'showSaveFilePicker');
+        };
+        const ws = new WritableStream({ write: (chunk) => apply(chunk), close: finish });
+        // write/seek/truncate/close diretti, come FileSystemWritableFileStream;
+        // pipeTo e getWriter passano dal sink qui sopra.
+        Object.assign(ws, {
+          write: (d) => apply(d),
+          seek: async (p) => { pos = p; },
+          truncate: async (size) => apply({ type: 'truncate', size }),
+          close: async () => finish(),
+        });
+        try { if (window.FileSystemWritableFileStream) Object.setPrototypeOf(ws, FileSystemWritableFileStream.prototype); } catch {}
+        return ws;
+      },
+      queryPermission: async () => 'granted',
+      requestPermission: async () => 'granted',
+      isSameEntry: async (other) => other === handle,
+    };
+    try { if (window.FileSystemFileHandle) Object.setPrototypeOf(handle, FileSystemFileHandle.prototype); } catch {}
+    return handle;
+  }
+
+  const origPicker = window.showSaveFilePicker;
+  if (typeof origPicker === 'function') {
+    window.showSaveFilePicker = function showSaveFilePicker(opts = {}) {
+      if (!st.armed) return origPicker.apply(this, arguments);
+      const first = opts?.types?.[0]?.accept ?? {};
+      const mime = Object.keys(first).find((m) => !m.includes('*')) || '';
+      const ext = [].concat(Object.values(first)[0] ?? [])[0] || '';
+      const name = opts?.suggestedName || `download${ext}`;
+      return Promise.resolve(makeHandle(String(name), mime));
+    };
+  }
+
+  // Dal service worker: elenco, lettura a pezzi, scarto.
+  st.list = () => st.items.map(({ blob, ...meta }) => meta);
+  st.read = async (id, offset, length) => {
+    const it = st.items.find((x) => x.id === id);
+    if (!it?.blob) throw new Error(`capture: no file ${id} in this page`);
+    const part = new Uint8Array(await it.blob.slice(offset, offset + length).arrayBuffer());
+    let s = '';
+    for (let i = 0; i < part.length; i += 0x8000) s += String.fromCharCode.apply(null, part.subarray(i, i + 0x8000));
+    return btoa(s);
+  };
+  st.drop = (id) => { st.items = st.items.filter((x) => x.id !== id); };
+  st.arm = (max) => { st.armed = true; st.max = max; };
+  st.disarm = () => { st.armed = false; st.items = []; st.blobs.clear(); };
+})();

package/extension/lib/capture-names.js

@@ -0,0 +1,32 @@
+/**
+ * Il nome di un file intercettato da capture_downloads, prima della pulizia
+ * del server (server/capture.js, che decide il nome sul disco).
+ *
+ * Ordine: filename* di Content-Disposition (RFC 5987, UTF-8 percent-encoded),
+ * filename, il nome che Chrome aveva già scelto, l'ultimo segmento dell'URL.
+ */
+export function dispositionName(header) {
+  const h = String(header || '');
+  const star = /filename\*\s*=\s*([^']*)'[^']*'([^;]+)/i.exec(h);
+  if (star) {
+    try { return decodeURIComponent(star[2].trim().replace(/^"|"$/g, '')); } catch {}
+  }
+  const plain = /filename\s*=\s*("((?:[^"\\]|\\.)*)"|[^;]+)/i.exec(h);
+  if (plain) return (plain[2] != null ? plain[2].replace(/\\(.)/g, '$1') : plain[1]).trim();
+  return '';
+}
+
+export function nameFromUrl(url) {
+  try {
+    const u = new URL(url);
+    if (!/^https?:$/.test(u.protocol)) return '';
+    const last = u.pathname.split('/').filter(Boolean).pop() || '';
+    return decodeURIComponent(last);
+  } catch {
+    return '';
+  }
+}
+
+export function downloadName({ disposition, chromeName, url }) {
+  return dispositionName(disposition) || String(chromeName || '').split(/[\\/]/).pop() || nameFromUrl(url) || '';
+}

package/extension/manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest_version": 3,
   "name": "Chrome Bridge for Claude Code",
-  "version": "1.29.3",
-  "description": "Bridge your browser to Claude Code: 66 token-efficient web-dev automation tools over a local WebSocket. ChromeOS included.",
+  "version": "1.30.0",
+  "description": "Bridge your browser to Claude Code: 67 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": [

package/extension/service-worker.js

@@ -11,6 +11,7 @@ import { pageFingerprint } from './lib/page-fingerprint.js';
 import { createPacer } from './lib/capture-pacing.js';
 import { computeTiles } from './lib/tile-layout.js';
 import { classifyDownload } from './lib/download-state.js';
+import { downloadName } from './lib/capture-names.js';
 import { findTextInPage } from './lib/find-text.js';
 import { elementOutcome, watchNavErrors, navErrorMessage } from './lib/command-outcome.js';
 import { withDebugger, keyEvents, mouseClickEvents, holdDebugger, releaseDebugger, debuggerHeld } from './lib/trusted-input.js';
@@ -520,6 +521,8 @@ async function executeCommand(msg) {
       return await cmdSetGeolocation(params);
     case 'manage_downloads':
       return await cmdManageDownloads(params);
+    case 'capture_files':
+      return await cmdCaptureFiles(params);
     case 'save_page':
       return await cmdSavePage(params);
     case 'wait_for_text':
@@ -5026,6 +5029,164 @@ async function cmdManageDownloads({ action, url, filename, timeout = 30000, limi
   throw new Error(`Unknown action: ${action}`);
 }
 
+// --- capture_downloads ---
+
+/**
+ * I file che la pagina crea o scarica arrivano al server senza la finestra
+ * «Salva con nome» (14/10/2026). Due vie:
+ * - nella pagina, lib/capture-hook.js prende blob, data URL e
+ *   showSaveFilePicker prima che diventino un download;
+ * - qui, un download che parte comunque mentre la scheda è armata viene
+ *   annullato appena creato, e i byte si riprendono con i cookie del browser
+ *   (http/https), dalla pagina (blob:) o dall'URL stesso (data:).
+ * I byte restano nella pagina o qui finché il server li legge a pezzi.
+ */
+const captureArmed = new Map();   // tabId → { max }
+const captureItems = new Map();   // id → { tabId, name, mime, size, bytes, source, error, url, pending }
+let captureSeq = 0;
+
+async function injectCaptureHook(tabId, max, frameIds) {
+  const target = frameIds ? { tabId, frameIds } : { tabId, allFrames: true };
+  await chrome.scripting.executeScript({ target, files: ['lib/capture-hook.js'], world: 'MAIN', injectImmediately: true });
+  await chrome.scripting.executeScript({ target, func: (m) => window.__cbCapture?.arm(m), args: [max], world: 'MAIN', injectImmediately: true });
+}
+
+// Una navigazione nella scheda armata porta un documento senza hook.
+chrome.webNavigation.onCommitted.addListener(({ tabId, frameId }) => {
+  const armed = captureArmed.get(tabId);
+  if (armed) injectCaptureHook(tabId, armed.max, [frameId]).catch(() => {});
+});
+
+function captureTabFor(item) {
+  if (captureArmed.size === 1) return captureArmed.keys().next().value;
+  return null;
+}
+
+async function captureDownload(item) {
+  if (!captureArmed.size || item.byExtensionId === chrome.runtime.id) return;
+  let tabId = captureTabFor(item);
+  if (tabId == null) {
+    const ref = item.referrer || item.url;
+    for (const id of captureArmed.keys()) {
+      try {
+        const tab = await chrome.tabs.get(id);
+        if (tab.url && ref && new URL(tab.url).origin === new URL(ref).origin) { tabId = id; break; }
+      } catch {}
+    }
+    tabId ??= captureArmed.keys().next().value;
+  }
+  const { max } = captureArmed.get(tabId);
+  // Prima di tutto fermarlo: la finestra di salvataggio non deve aprirsi.
+  let browserCopy = null;
+  try { await chrome.downloads.cancel(item.id); } catch {}
+  try {
+    const [now] = await chrome.downloads.search({ id: item.id });
+    if (now?.state === 'complete') browserCopy = now.filename;
+    else await chrome.downloads.erase({ id: item.id });
+  } catch {}
+
+  const url = item.finalUrl || item.url;
+  const id = `d${Date.now().toString(36)}${(captureSeq++).toString(36)}`;
+  const entry = { id, tabId, name: '', mime: item.mime || '', source: 'download', url, pending: true, ...(browserCopy && { browser_copy: browserCopy }) };
+  captureItems.set(id, entry);
+  try {
+    if (/^blob:/i.test(url)) {
+      // Il Blob vive nella pagina: lo prende l'hook, che lo tiene in mappa
+      // anche se la pagina ha già chiamato revokeObjectURL.
+      const origin = url.slice(5).replace(/\/[^/]*$/, '');
+      const probes = await chrome.scripting.executeScript({
+        target: { tabId, allFrames: true }, world: 'MAIN',
+        func: (u, o) => (window.__cbCapture?.blobs.has(u) ? 2 : (location.origin === o ? 1 : 0)),
+        args: [url, origin],
+      });
+      const best = probes.filter((r) => r.result > 0).sort((a, b) => b.result - a.result)[0];
+      if (!best) throw new Error('blob URL from a frame without capture hook');
+      captureItems.delete(id);
+      await chrome.scripting.executeScript({
+        target: { tabId, frameIds: [best.frameId] }, world: 'MAIN',
+        func: (u, n) => window.__cbCapture?.fromUrl(u, n, 'download').then(() => true),
+        args: [url, item.filename ? item.filename.split(/[\\/]/).pop() : ''],
+      });
+      return;
+    }
+    const res = await fetch(url, { credentials: 'include', redirect: 'follow' });
+    const declared = Number(res.headers.get('content-length') || 0);
+    entry.mime = res.headers.get('content-type') || entry.mime;
+    entry.name = downloadName({ disposition: res.headers.get('content-disposition'), chromeName: item.filename, url: res.url || url });
+    if (!res.ok) throw new Error(`refetch answered HTTP ${res.status} (a POST download or a one-time link cannot be fetched again)`);
+    if (declared > max) {
+      try { await res.body?.cancel(); } catch {}
+      throw new Error(`too large: ${declared} bytes, max_mb allows ${max}`);
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    if (bytes.length > max) throw new Error(`too large: ${bytes.length} bytes, max_mb allows ${max}`);
+    entry.bytes = bytes;
+    entry.size = bytes.length;
+  } catch (e) {
+    entry.error = e.message;
+  }
+  delete entry.pending;
+}
+
+chrome.downloads.onCreated.addListener((item) => { captureDownload(item).catch(() => {}); });
+
+async function cmdCaptureFiles({ op, tab_id, max_bytes, id, frame_id, offset = 0, length = 4 * 1024 * 1024 }) {
+  const tabId = await resolveTabId(tab_id);
+  if (op === 'arm') {
+    const max = Math.max(1, Number(max_bytes) || 100 * 1024 * 1024);
+    captureArmed.set(tabId, { max });
+    await injectCaptureHook(tabId, max);
+    return { armed: true, tabId, max_bytes: max };
+  }
+  if (op === 'disarm') {
+    captureArmed.delete(tabId);
+    for (const [k, v] of captureItems) if (v.tabId === tabId) captureItems.delete(k);
+    try {
+      await chrome.scripting.executeScript({ target: { tabId, allFrames: true }, world: 'MAIN', func: () => window.__cbCapture?.disarm() });
+    } catch {}
+    return { armed: false, tabId };
+  }
+  if (op === 'list') {
+    const items = [];
+    let frames = [];
+    try {
+      frames = await chrome.scripting.executeScript({ target: { tabId, allFrames: true }, world: 'MAIN', func: () => window.__cbCapture?.list() ?? null });
+    } catch {}
+    for (const f of frames) for (const it of f.result ?? []) items.push({ ...it, frame_id: f.frameId });
+    for (const v of captureItems.values()) {
+      if (v.tabId !== tabId) continue;
+      const { bytes, tabId: _t, ...meta } = v;
+      items.push(meta);
+    }
+    return { armed: captureArmed.has(tabId), tabId, items };
+  }
+  if (op === 'read') {
+    if (!id) throw new Error('Missing required parameter: id');
+    const held = captureItems.get(id);
+    if (held) {
+      if (!held.bytes) throw new Error(`capture: ${id} has no bytes (${held.error || 'pending'})`);
+      return { b64: await blobToBase64(new Blob([held.bytes.subarray(offset, offset + length)])) };
+    }
+    const [r] = await chrome.scripting.executeScript({
+      target: scriptTarget(tabId, frame_id ?? 0), world: 'MAIN',
+      func: (i, o, l) => window.__cbCapture ? window.__cbCapture.read(i, o, l) : Promise.reject(new Error('capture hook gone: the page was reloaded')),
+      args: [id, offset, length],
+    });
+    if (r?.error) throw new Error(r.error.message || String(r.error));
+    if (typeof r?.result !== 'string') throw new Error(`capture: could not read ${id}`);
+    return { b64: r.result };
+  }
+  if (op === 'drop') {
+    if (!id) throw new Error('Missing required parameter: id');
+    if (captureItems.delete(id)) return { dropped: id };
+    try {
+      await chrome.scripting.executeScript({ target: scriptTarget(tabId, frame_id ?? 0), world: 'MAIN', func: (i) => window.__cbCapture?.drop(i), args: [id] });
+    } catch {}
+    return { dropped: id };
+  }
+  throw new Error(`Unknown capture op: ${op}`);
+}
+
 // --- save_page (MHTML via pageCapture) ---
 
 // --- http_request ---

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "chrome-bridge-mcp",
   "mcpName": "io.github.frsorrentino/chrome-bridge",
-  "version": "1.29.3",
+  "version": "1.30.0",
   "type": "module",
-  "description": "Chrome Bridge by frsorrentino: MCP server that lets Claude Code borrow a tab from your own logged-in Chrome and hand it back — logins, 2FA and CAPTCHAs stay with you (handoff). 66 tools; 2.8-4.3× cheaper and up to 9.3× fewer turns than Claude in Chrome, measured; ChromeOS included.",
+  "description": "Chrome Bridge by frsorrentino: MCP server that lets Claude Code borrow a tab from your own logged-in Chrome and hand it back — logins, 2FA and CAPTCHAs stay with you (handoff). 67 tools; 2.8-4.3× cheaper and up to 9.3× fewer turns than Claude in Chrome, measured; ChromeOS included.",
   "main": "server/index.js",
   "bin": {
     "chrome-bridge-mcp": "server/index.js",

package/server/capture.js

@@ -0,0 +1,108 @@
+/**
+ * capture_downloads, lato server: i file presi dalla pagina (blob, data URL,
+ * showSaveFilePicker, download annullati) arrivano qui a pezzi, come
+ * upload_file al contrario, e vengono scritti nella cartella scelta all'arm.
+ *
+ * Il nome lo decide la pagina, quindi è input ostile: si tiene solo l'ultimo
+ * segmento, senza caratteri di controllo né riservati, senza punti iniziali
+ * (niente .bashrc, .env), e un file esistente non viene mai sovrascritto.
+ */
+import { open, rm } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { MessageType } from './protocol.js';
+
+export const CAPTURE_CHUNK_BYTES = 4 * 1024 * 1024;
+export const CAPTURE_DEFAULT_MB = 100;
+export const CAPTURE_MAX_MB = 200;
+
+const EXT_BY_MIME = {
+  'application/pdf': '.pdf', 'text/csv': '.csv', 'application/json': '.json', 'text/plain': '.txt',
+  'application/zip': '.zip', 'image/png': '.png', 'image/jpeg': '.jpg', 'image/svg+xml': '.svg',
+  'text/html': '.html', 'application/xml': '.xml', 'text/xml': '.xml', 'image/webp': '.webp',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
+};
+const MAX_NAME_BYTES = 180;
+
+export function sanitizeFileName(name, mime = '') {
+  let n = String(name ?? '').split(/[\\/]/).pop().normalize('NFC');
+  n = n.replace(/[\x00-\x1f\x7f<>:"|?*]/g, '_').replace(/^[.\s]+/, '').replace(/[.\s]+$/, '');
+  if (/^(con|prn|aux|nul|com\d|lpt\d)(\..*)?$/i.test(n)) n = `_${n}`;
+  if (!n) n = `download${EXT_BY_MIME[String(mime).split(';')[0].trim().toLowerCase()] ?? ''}`;
+  if (Buffer.byteLength(n) > MAX_NAME_BYTES) {
+    const ext = extname(n).slice(0, 16);
+    let stem = n.slice(0, n.length - ext.length);
+    while (Buffer.byteLength(stem + ext) > MAX_NAME_BYTES) stem = stem.slice(0, -1);
+    n = stem + ext;
+  }
+  return n;
+}
+
+/** Apre in esclusiva `dir/name`, o `name (1)`, `name (2)`… se esiste già. */
+export async function openUnique(dir, name) {
+  const ext = extname(name);
+  const stem = name.slice(0, name.length - ext.length);
+  for (let i = 0; i < 1000; i++) {
+    const path = join(dir, i ? `${stem} (${i})${ext}` : name);
+    try {
+      return { path, fh: await open(path, 'wx') };
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+    }
+  }
+  throw new Error(`capture: too many files named ${name} in ${dir}`);
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Aspetta i file catturati nella scheda, li scrive in `dir` e li toglie dalla
+ * pagina. Appena compare il primo file aspetta ancora `settle` ms: un export
+ * può produrne più d'uno.
+ */
+export async function collectCaptured(send, { tab_id, dir, timeout = 15000, settle = 700, poll = 250, chunk = CAPTURE_CHUNK_BYTES }) {
+  const started = Date.now();
+  let firstSeen = null;
+  let list;
+  for (;;) {
+    list = await send(MessageType.CAPTURE_FILES, { op: 'list', tab_id });
+    const items = list?.items ?? [];
+    if (items.length && firstSeen == null) firstSeen = Date.now();
+    if (items.length && !items.some((i) => i.pending) && Date.now() - firstSeen >= settle) break;
+    if (Date.now() - started >= timeout) break;
+    await sleep(poll);
+  }
+  const saved = [];
+  const skipped = [];
+  const pending = [];
+  for (const it of list?.items ?? []) {
+    if (it.pending) { pending.push({ name: it.name, source: it.source }); continue; }
+    const drop = () => send(MessageType.CAPTURE_FILES, { op: 'drop', id: it.id, frame_id: it.frame_id, tab_id }).catch(() => {});
+    if (it.error) {
+      skipped.push({ name: it.name, source: it.source, error: it.error, ...(it.url && { url: it.url }) });
+      await drop();
+      continue;
+    }
+    const { path, fh } = await openUnique(dir, sanitizeFileName(it.name, it.mime));
+    let written = 0;
+    try {
+      for (let offset = 0; offset < it.size; offset += chunk) {
+        const { b64 } = await send(MessageType.CAPTURE_FILES, { op: 'read', id: it.id, frame_id: it.frame_id, offset, length: chunk, tab_id });
+        const buf = Buffer.from(b64 ?? '', 'base64');
+        await fh.write(buf);
+        written += buf.length;
+      }
+      await fh.close();
+      if (written !== it.size) throw new Error(`${written} bytes arrived, ${it.size} expected`);
+    } catch (e) {
+      await fh.close().catch(() => {});
+      await rm(path, { force: true });
+      skipped.push({ name: it.name, source: it.source, error: e.message });
+      await drop();
+      continue;
+    }
+    saved.push({ path, bytes: written, mime: it.mime || undefined, source: it.source, ...(it.browser_copy && { browser_copy: it.browser_copy }) });
+    await drop();
+  }
+  return { saved, skipped, pending, armed: list?.armed ?? false, waited_ms: Date.now() - started };
+}

package/server/index.js

@@ -82,6 +82,12 @@ async function main() {
       // Il 42% delle sessioni reali caricava i tool con 2+ ToolSearch (media 2,0).
       'When tools are deferred, batch every tool needed for the next workflow into ONE ToolSearch call using exact names (select:name1,name2,...); do not search one tool at a time.',
       'Missing optional tools: call get_status({enable:["group",...]}) once for all required groups (audits, visual, network, storage, dom, files, perf; "all" enables all). After tools/list_changed, use them next turn; if still deferred, batch-search their names once. No restart or user configuration needed.',
+      // 14/10/2026: nei flussi di lavoro Claude restava fermo sulla finestra
+      // «Salva con nome», di sistema e fuori portata dell'estensione. Su ChromeOS
+      // con «Chiedi dove salvare ciascun file» si apre anche con saveAs:false.
+      'Saving a file: never click a Download/Export button and wait for the browser download, the OS "Save as" dialog can open and no tool can press it. '
+        + 'A file with a URL: http_request with save_to (browser cookies, bytes written to disk, no dialog). '
+        + 'A file the page builds itself (blob, data URL, showSaveFilePicker, a download the page starts): capture_downloads arm, then click, then capture_downloads wait.',
       'A tab in a minimized, covered or background window does not render: screenshots fail, timers slow down. get_page_info reports visibility (page_hidden in a result means the same); bring the window on screen, or create_tab new_window with bounds.',
     ].join(' '),
   });

package/server/protocol.js

@@ -62,6 +62,7 @@ export const MessageType = Object.freeze({
   CLIPBOARD:             'clipboard',
   SET_GEOLOCATION:       'set_geolocation',
   MANAGE_DOWNLOADS:      'manage_downloads',
+  CAPTURE_FILES:         'capture_files',
   SAVE_PAGE:             'save_page',
   HTTP_REQUEST:          'http_request',
   SET_ZOOM:              'set_zoom',
@@ -99,7 +100,7 @@ export const MessageType = Object.freeze({
 });
 
 // Versione
-export const VERSION               = '1.29.3';
+export const VERSION               = '1.30.0';
 
 // Configurazione
 export const DEFAULT_PORT          = 8765;
@@ -153,6 +154,7 @@ export function getTimeout(type) {
     || type === MessageType.UPLOAD_FILE
     || type === MessageType.UPLOAD_CHUNK
     || type === MessageType.MANAGE_DOWNLOADS
+    || type === MessageType.CAPTURE_FILES
     || type === MessageType.SAVE_PAGE
     || type === MessageType.HTTP_REQUEST
     || type === MessageType.TILE_WINDOWS

package/server/tools.js

@@ -8,7 +8,7 @@
 import { createHash } from 'node:crypto';
 import { appendFile, mkdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { basename, dirname, extname, join, resolve, sep } from 'node:path';
+import { basename, dirname, extname, isAbsolute, join, resolve, sep } from 'node:path';
 import { parse as parseHtml } from 'node-html-parser';
 import { z } from 'zod';
 import { runAssert } from './assertions.js';
@@ -27,6 +27,7 @@ import { fingerprintDelta } from './effect.js';
 import { analyzeTrace, traceEventsOf } from './trace-analysis.js';
 import { assembleVideo } from './video.js';
 import { uploadBuffer, MAX_UPLOAD_BYTES } from './upload.js';
+import { collectCaptured, CAPTURE_DEFAULT_MB, CAPTURE_MAX_MB } from './capture.js';
 import { cdpConnect, targetWsUrl, takeHeapSnapshot, summarizeHeap, diffHeap } from './heap.js';
 import { lighthouseArgs, runLighthouse, summarizeLighthouse } from './lighthouse.js';
 import { consoleLines, networkLines, interactivesLines, interactiveLine, linksLines } from './formatters.js';
@@ -364,6 +365,7 @@ export const TOOL_ANNOTATIONS = {
   get_storage: ro(),
   get_tabs: ro(),
   manage_downloads: rw({ open: true }),  // action=download scrive un file sul disco e va in rete
+  capture_downloads: rw({ open: true }),  // scrive file nuovi (mai sovrascritti), un download annullato si riprende dalla rete
   measure_spacing: ro(),
   animations: rw(),   // con action clicca, passa sopra, scorre o preme un tasto
   frames: rw(),
@@ -2810,7 +2812,8 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
     'manage_downloads',
     'List downloads, start one, or wait for the newest to finish. Files land in the browser Downloads folder, not on the server. '
       + 'download reports the real state: with Chrome set to ask where to save, it comes back waiting_for_user — bytes fetched, '
-      + 'nothing moves until someone picks a destination.',
+      + 'nothing moves until someone picks a destination. To save a file that has a URL use http_request with save_to instead: '
+      + 'browser cookies, bytes on disk, no dialog; a file the page builds goes through capture_downloads.',
     {
       action: z.enum(['list', 'wait_for_complete', 'download']).describe('download fetches with the browser cookies and reports the real state; wait_for_complete blocks until the newest finishes'),
       url: z.string().optional().describe('What to download (action=download); sent with the session cookies of its origin'),
@@ -2821,6 +2824,63 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
     async ({ action, url, filename, timeout, limit }) => {
       if (action === 'download' && !url) throw new Error('action=download requires url');
       const data = await send(MessageType.MANAGE_DOWNLOADS, { action, url, filename, timeout, limit });
+      // Fermo sul selettore: nessun tool lo preme, la strada è un'altra.
+      if (data?.state === 'waiting_for_user') {
+        data.hint = `The save dialog needs a person. Instead: http_request {url: "${data.url ?? url}", save_to: "/absolute/path"} `
+          + 'fetches with the same cookies and writes the bytes without a dialog.';
+      }
+      return { content: [{ type: 'text', text: jsonText(data) }] };
+    }
+  );
+
+  // --- capture_downloads ---
+  // Cartella e tetto per scheda armata. I nomi li sceglie la pagina: li pulisce
+  // server/capture.js, e la cartella non può stare fra le chiavi.
+  const captures = new Map();
+  const captureTab = (tab_id) => tab_id ?? (captures.size === 1 ? captures.keys().next().value : undefined);
+  server.tool(
+    'capture_downloads',
+    'Save files the page builds itself, with no browser download and no "Save as" dialog: blob and data URL links (a[download]), '
+      + 'window.showSaveFilePicker writes, and downloads the page starts (cancelled at once, bytes fetched again with the browser cookies). '
+      + 'arm with save_dir, then click Export/Download, then wait: it returns the saved paths. A file with a URL: http_request save_to instead. '
+      + 'Names are cleaned, existing files never overwritten, size capped by max_mb.',
+    {
+      action: z.enum(['arm', 'wait', 'disarm']).describe('arm before the click; wait returns what arrived and stays armed; disarm restores the page'),
+      save_dir: z.string().optional().describe('arm: absolute directory for the files; created if missing'),
+      max_mb: z.number().optional().describe(`arm: per-file cap in MB (default ${CAPTURE_DEFAULT_MB}, max ${CAPTURE_MAX_MB}); a bigger file is skipped`),
+      timeout: z.number().optional().default(15000).describe('wait: max ms for the first file'),
+      tab_id: tabId,
+    },
+    async ({ action, save_dir, max_mb, timeout, tab_id }) => {
+      if (action === 'arm') {
+        if (!save_dir || !isAbsolute(save_dir)) throw new Error('arm requires save_dir, an absolute directory');
+        const dir = resolve(save_dir);
+        guardWrite(dir);
+        const inside = (p, root) => p === root || p.startsWith(root + sep);
+        if (SECRET_DIRS.some((d) => inside(dir, d))) throw new Error(`Refusing to write into ${dir}: a key or credential folder`);
+        await mkdir(dir, { recursive: true });
+        const real = await realpath(dir);
+        if (SECRET_DIRS.some((d) => inside(real, d))) throw new Error(`Refusing to write into ${real}: a key or credential folder`);
+        guardWrite(real);
+        const mb = Math.min(CAPTURE_MAX_MB, Math.max(1, max_mb ?? CAPTURE_DEFAULT_MB));
+        const data = await send(MessageType.CAPTURE_FILES, { op: 'arm', tab_id, max_bytes: Math.round(mb * 1024 * 1024) });
+        captures.set(data.tabId, { dir: real, mb });
+        return { content: [{ type: 'text', text: jsonText({ armed: true, tab_id: data.tabId, save_dir: real, max_mb: mb, next: 'click the Export/Download control, then capture_downloads wait' }) }] };
+      }
+      const tid = captureTab(tab_id);
+      if (action === 'disarm') {
+        const data = await send(MessageType.CAPTURE_FILES, { op: 'disarm', tab_id: tid });
+        captures.delete(data.tabId);
+        return { content: [{ type: 'text', text: jsonText({ armed: false, tab_id: data.tabId }) }] };
+      }
+      const armed = captures.get(tid);
+      if (!armed) throw new Error('Nothing armed for this tab: capture_downloads arm with save_dir first');
+      const data = await collectCaptured(send, { tab_id: tid, dir: armed.dir, timeout });
+      if (!data.saved.length && !data.skipped.length) {
+        data.hint = data.armed
+          ? 'Nothing captured: no file built by the page and no download started. Check the click hit the control; a file with a URL goes through http_request save_to.'
+          : 'The page lost the capture (reload or navigation): arm again, then click.';
+      }
       return { content: [{ type: 'text', text: jsonText(data) }] };
     }
   );
@@ -2846,7 +2906,8 @@ export function registerTools(server, wsManager, caps = 'all', options = {}) {
     'http_request',
     'HTTP request sent from the browser, with the logged-in user\'s cookies: fetches what a server-side request gets a login page for '
       + '(invoices, authenticated JSON, exports). Text bodies inline (capped by max_length); save_to writes the bytes — the way to read a PDF, '
-      + 'since read_page returns nothing on a PDF tab.',
+      + 'since read_page returns nothing on a PDF tab, and the way to save any file that has a URL: no click on Download, '
+      + 'no browser download, no "Save as" dialog.',
     {
       url: z.string().describe('Absolute URL. Cookies are sent for its origin'),
       method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']).optional().default('GET').describe('HEAD fetches headers only, without the body'),

package/skills/chrome-bridge/SKILL.md

@@ -173,4 +173,8 @@ out.push((await cb.extract_table({where:{id}})).rows[0]); } return out;'
   need `chrome.debugger`, which this extension deliberately doesn't hold.
 - Certificate details and DNS queries: use a checker page.
 - CAPTCHA, 2FA, passwords: the user does it in the browser; the tab stays theirs.
-- A PDF open in the viewer: download it (`manage_downloads`) and read the file.
+- A PDF open in the viewer: `http_request` with `save_to` (its URL, the browser cookies) and read the file.
+- Saving any file: never click Download and wait for the browser download, the
+  OS "Save as" dialog can open and nothing can press it. A file with a URL:
+  `http_request` `save_to`; a file the page builds (Export button, blob):
+  `capture_downloads` arm, click, wait.