chrome-bridge-mcp 1.10.1 → 1.11.1

package/README.md

@@ -1,6 +1,6 @@
 # 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-132%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-147%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)
 
 **Chrome Bridge is an MCP server that connects Claude Code to your real, logged-in Chrome browser — 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,10 +63,10 @@ Claude Code calls `navigate` (returning clickable element refs), `accessibility_
 
 ## Token-Efficient Design
 
-- **Opt-in Surface**: 31 core tools cost ≈7.6k tokens of `tools/list`, all 60 cost ≈14.6k; specialized groups (audits, visual, network, storage, dom, files) are opt-in via `--caps`. That core figure was ≈3.8k in 1.8.0 and roughly doubled in 1.10.0: MCP annotations on every tool, rewritten descriptions, and a documented `.describe()` on all 254 parameters (coverage went from 35% to 100%). The trade is deliberate and it is not free — on the form benchmark it adds ≈8% to the cache-read tokens per turn — but the measured advantage was never prefix size, it was round trips: 2.75× fewer turns. Playwright MCP's 23 core tools measured ≈4.6k in July 2026, so on prefix size alone it is the leaner one. Measure ours with `npm run measure`.
+- **Opt-in Surface**: 31 core tools cost ≈7.9k tokens of `tools/list`, all 60 cost ≈14.9k; specialized groups (audits, visual, network, storage, dom, files) are opt-in via `--caps`. That core figure was ≈3.8k in 1.8.0 and roughly doubled in 1.10.0: MCP annotations on every tool, rewritten descriptions, and a documented `.describe()` on all 254 parameters (coverage went from 35% to 100%). The trade is deliberate and it is not free — on the form benchmark it adds ≈8% to the cache-read tokens per turn — but the measured advantage was never prefix size, it was round trips: 2.75× fewer turns. Playwright MCP's 23 core tools measured ≈4.6k in July 2026, so on prefix size alone it is the leaner one. Measure ours with `npm run measure`.
 - **Act-from-Result**: Tools attach a capped preview of interactive elements with short refs. Actions only report a `page_changed` delta when the URL or title actually changes.
 - **Optimized Media**: Screenshots are downscaled to ≤1568px. Full-page captures are sliced into readable segments.
-- **Zero-Token Escape Hatches**: The [CLI](#cli) skips MCP schemas entirely, and recorded flows [replay](#launch-mode-headless--ci) without any model in the loop.
+- **Payload Escape Hatches**: `save_to` on `read_page`, `extract`, `screenshot` and `http_request` writes the result to a file and returns the path — the bytes never enter the context unless the agent decides to read them. `read_page(mode="markdown")` keeps headings, links and tables at a fraction of the HTML cost. The [CLI](#cli) skips MCP schemas entirely, and recorded flows [replay](#launch-mode-headless--ci) without any model in the loop.
 
 ## Highlights
 

package/extension/lib/page-markdown.js

@@ -0,0 +1,151 @@
+/**
+ * Rende una pagina in Markdown per il consumo del modello: struttura preservata
+ * a una frazione del costo dell'HTML.
+ *
+ * La funzione viene serializzata e iniettata nella pagina con
+ * chrome.scripting.executeScript, quindi deve essere autocontenuta: niente
+ * riferimenti a variabili esterne, niente import. Per lo stesso motivo è testata
+ * a parte contro un DOM finto (`test/unit/page-markdown.test.js`) invece che dal
+ * vivo.
+ *
+ * Cammina l'albero per blocchi invece di usare un querySelectorAll piatto: un
+ * `<li><a>x</a></li>` con il selettore piatto verrebbe emesso due volte, una
+ * come voce di lista e una come link.
+ */
+export function buildMarkdown(doc) {
+  const d = doc || document;
+  const out = [];
+
+  const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'SVG', 'CANVAS', 'IFRAME']);
+  const HEADINGS = new Set(['H1', 'H2', 'H3', 'H4', 'H5', 'H6']);
+  const BLOCKS = new Set(['P', 'LI', 'BLOCKQUOTE', 'PRE', 'DT', 'DD', 'FIGCAPTION']);
+  const MAX_TABLE_ROWS = 50;
+
+  const attr = (el, name) => (el.getAttribute ? el.getAttribute(name) : null);
+  const clean = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+
+  // Dimensioni: il rect è la verità quando c'è un layout, ma su un'immagine non
+  // ancora disposta (o in test) restano solo gli attributi.
+  const sizeOf = (el) => {
+    let w = 0;
+    let h = 0;
+    if (typeof el.getBoundingClientRect === 'function') {
+      const r = el.getBoundingClientRect();
+      w = r.width; h = r.height;
+    }
+    if (!w) w = Number(attr(el, 'width')) || 0;
+    if (!h) h = Number(attr(el, 'height')) || 0;
+    return { w, h };
+  };
+
+  // Testo inline di un blocco: i link diventano [testo](href) senza che il
+  // testo venga emesso una seconda volta dal walker.
+  const inline = (node) => {
+    if (node.nodeType === 3) return node.textContent || '';
+    if (node.nodeType !== 1) return '';
+    const tag = node.tagName;
+    if (SKIP.has(tag)) return '';
+    if (tag === 'BR') return ' ';
+    if (tag === 'IMG') {
+      const { w, h } = sizeOf(node);
+      if (w >= 50 && h >= 50) {
+        const alt = clean(attr(node, 'alt')) || 'no alt text';
+        return ` ![${alt} ${Math.round(w)}x${Math.round(h)}](${attr(node, 'src') || ''}) `;
+      }
+      return '';
+    }
+    const kids = (node.childNodes || []).map(inline).join('');
+    if (tag === 'A') {
+      const href = attr(node, 'href');
+      const label = clean(kids);
+      if (!label) return '';
+      return href ? `[${label}](${href})` : label;
+    }
+    if (tag === 'CODE' || tag === 'KBD') {
+      const label = clean(kids);
+      return label ? '`' + label + '`' : '';
+    }
+    if (tag === 'STRONG' || tag === 'B') { const l = clean(kids); return l ? `**${l}**` : ''; }
+    if (tag === 'EM' || tag === 'I') { const l = clean(kids); return l ? `*${l}*` : ''; }
+    return kids;
+  };
+
+  const cellsOf = (row) => (row.childNodes || [])
+    .filter((n) => n.nodeType === 1 && (n.tagName === 'TD' || n.tagName === 'TH'))
+    .map((c) => clean(c.textContent).replace(/\|/g, '\\|'));
+
+  const renderTable = (table) => {
+    const rows = (table.querySelectorAll ? table.querySelectorAll('tr') : []) || [];
+    if (!rows.length) return;
+    const all = rows.map(cellsOf).filter((r) => r.length);
+    if (!all.length) return;
+
+    // Gli header veri, non un segnaposto: la prima riga se contiene th,
+    // altrimenti colonne numerate.
+    const firstHasTh = (rows[0].childNodes || []).some((n) => n.nodeType === 1 && n.tagName === 'TH');
+    const header = firstHasTh ? all[0] : all[0].map((_, i) => `col${i + 1}`);
+    const body = firstHasTh ? all.slice(1) : all;
+    const width = header.length;
+
+    out.push('');
+    out.push(`| ${header.join(' | ')} |`);
+    out.push(`|${' --- |'.repeat(width)}`);
+    for (const r of body.slice(0, MAX_TABLE_ROWS)) {
+      const padded = r.slice(0, width);
+      while (padded.length < width) padded.push('');
+      out.push(`| ${padded.join(' | ')} |`);
+    }
+    if (body.length > MAX_TABLE_ROWS) {
+      out.push(`_${body.length} rows total, ${body.length - MAX_TABLE_ROWS} omitted — use extract_table with \`where\` to filter server-side instead of reading them here._`);
+    }
+    out.push('');
+  };
+
+  const walk = (node) => {
+    if (!node || node.nodeType !== 1) return;
+    const tag = node.tagName;
+    if (SKIP.has(tag)) return;
+
+    if (tag === 'TABLE') { renderTable(node); return; }
+
+    if (HEADINGS.has(tag)) {
+      const text = clean(inline(node));
+      if (text) out.push(`${'#'.repeat(Number(tag[1]))} ${text}`, '');
+      return;
+    }
+
+    if (BLOCKS.has(tag)) {
+      const text = clean(inline(node));
+      if (!text) return;
+      if (tag === 'LI') out.push(`- ${text}`);
+      else if (tag === 'BLOCKQUOTE') out.push(`> ${text}`, '');
+      else if (tag === 'PRE') out.push('```', text, '```', '');
+      else if (tag === 'FIGCAPTION') out.push(`*${text}*`, '');
+      else out.push(text, '');
+      return;
+    }
+
+    if (tag === 'IMG') {
+      const rendered = clean(inline(node));
+      if (rendered) out.push(rendered, '');
+      return;
+    }
+
+    for (const child of node.childNodes || []) walk(child);
+  };
+
+  const title = clean(d.title);
+  if (title) out.push(`# ${title}`, '');
+
+  // Sommario delle immagini grandi: dice al modello se vale la pena chiedere
+  // uno screenshot, al costo di una riga.
+  const imgs = (d.body?.querySelectorAll ? d.body.querySelectorAll('img') : []) || [];
+  const significant = imgs.filter((img) => { const { w, h } = sizeOf(img); return w >= 100 && h >= 100; });
+  if (significant.length) {
+    out.push(`_${significant.length} image(s) at least 100x100 on this page — take a screenshot if the visual matters._`, '');
+  }
+
+  walk(d.body);
+
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Chrome Bridge for Claude Code",
-  "version": "1.10.1",
+  "version": "1.11.1",
   "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/service-worker.js

@@ -6,6 +6,7 @@
  */
 
 import './telemetry.js';
+import { buildMarkdown } from './lib/page-markdown.js';
 const { pushError } = globalThis.__cbTelemetry;
 
 const DEFAULT_PORT = 8765;
@@ -423,6 +424,8 @@ async function executeCommand(msg) {
       return await cmdManageDownloads(params);
     case 'save_page':
       return await cmdSavePage(params);
+    case 'wait_for_text':
+      return await cmdWaitForText(params);
     case 'http_request':
       return await cmdHttpRequest(params);
     case 'set_zoom':
@@ -722,13 +725,13 @@ async function cmdExecuteJs({ code, tab_id, frame_id }) {
   }
 }
 
-async function cmdClick({ selector, tab_id, frame_id, force = false }) {
+async function cmdClick({ selector, tab_id, frame_id, force = false, button = 'left', count = 1 }) {
   if (!selector) throw new Error('Missing required parameter: selector');
   const tabId = await resolveTabId(tab_id);
 
   const results = await chrome.scripting.executeScript({
     target: scriptTarget(tabId, frame_id),
-    func: (sel, forceClick) => {
+    func: (sel, forceClick, btn, times) => {
       function deepQuery(sel) {
         if (!sel.includes('>>>')) return document.querySelector(sel);
         const parts = sel.split('>>>').map((s) => s.trim());
@@ -755,15 +758,29 @@ async function cmdClick({ selector, tab_id, frame_id, force = false }) {
           return { clicked: false, occluded: true, occluder: { selector: occluderSel, tag: top.tagName.toLowerCase(), text: (top.textContent || '').trim().substring(0, 80) } };
         }
       }
-      const opts = { bubbles: true, cancelable: true, clientX: cx, clientY: cy };
-      el.dispatchEvent(new PointerEvent('pointerdown', opts));
-      el.dispatchEvent(new MouseEvent('mousedown', opts));
-      el.dispatchEvent(new PointerEvent('pointerup', opts));
-      el.dispatchEvent(new MouseEvent('mouseup', opts));
-      el.click();
-      return { clicked: true, tagName: el.tagName, text: el.textContent?.substring(0, 100) };
+      // button 2 = destro: il browser non apre il suo menu nativo da un evento
+      // sintetico, ma le pagine che ne implementano uno proprio ascoltano
+      // 'contextmenu', ed è quello il caso d'uso reale.
+      const right = btn === 'right';
+      const clickCount = Math.max(1, Number(times) || 1);
+      const base = { bubbles: true, cancelable: true, clientX: cx, clientY: cy, button: right ? 2 : 0, buttons: right ? 2 : 1 };
+
+      for (let i = 0; i < clickCount; i++) {
+        const opts = { ...base, detail: i + 1 };
+        el.dispatchEvent(new PointerEvent('pointerdown', opts));
+        el.dispatchEvent(new MouseEvent('mousedown', opts));
+        el.dispatchEvent(new PointerEvent('pointerup', opts));
+        el.dispatchEvent(new MouseEvent('mouseup', opts));
+        if (right) el.dispatchEvent(new MouseEvent('contextmenu', opts));
+        else el.click();
+      }
+      // dblclick non è implicito nei due click: va emesso a parte, ed è quello
+      // che seleziona una parola o apre un editor inline.
+      if (!right && clickCount >= 2) el.dispatchEvent(new MouseEvent('dblclick', { ...base, detail: 2 }));
+
+      return { clicked: true, button: right ? 'right' : 'left', count: clickCount, tagName: el.tagName, text: el.textContent?.substring(0, 100) };
     },
-    args: [selector, force],
+    args: [selector, force, button, count],
     world: 'MAIN',
   });
 
@@ -853,6 +870,18 @@ async function cmdReadPage({ mode = 'text', tab_id, frame_id }) {
     return results?.[0]?.result ?? '';
   }
 
+  if (mode === 'markdown') {
+    // buildMarkdown è autocontenuta apposta: chrome.scripting ne serializza il
+    // sorgente e la esegue nella pagina, dove non esiste il modulo.
+    const res = await chrome.scripting.executeScript({
+      target: scriptTarget(tabId, frame_id),
+      func: buildMarkdown,
+      args: [null],
+      world: 'MAIN',
+    });
+    return res?.[0]?.result ?? '';
+  }
+
   if (mode === 'accessibility') {
     // Ritorna una struttura semplificata dell'a11y tree
     const results = await chrome.scripting.executeScript({
@@ -1639,7 +1668,7 @@ async function cmdFillForm({ fields, submit_selector, tab_id, frame_id }) {
 
 // --- viewport_resize ---
 
-async function cmdViewportResize({ preset, width, height, tab_id }) {
+async function cmdViewportResize({ preset, width, height, read_only = false, tab_id }) {
   const tabId = await resolveTabId(tab_id);
   const tab = await chrome.tabs.get(tabId);
 
@@ -1656,10 +1685,13 @@ async function cmdViewportResize({ preset, width, height, tab_id }) {
   if (targetW) updateOpts.width = targetW;
   if (targetH) updateOpts.height = targetH;
 
-  if (Object.keys(updateOpts).length === 0) throw new Error('Provide preset, width, or height');
-
-  await chrome.windows.update(tab.windowId, updateOpts);
-  await new Promise((r) => setTimeout(r, 200));
+  if (!read_only) {
+    if (Object.keys(updateOpts).length === 0) throw new Error('Provide preset, width, or height');
+    await chrome.windows.update(tab.windowId, updateOpts);
+    // La finestra si ridisegna in modo asincrono: senza la pausa si leggono le
+    // dimensioni vecchie e si riporta un risultato falso.
+    await new Promise((r) => setTimeout(r, 200));
+  }
 
   const results = await chrome.scripting.executeScript({
     target: { tabId },
@@ -1671,6 +1703,7 @@ async function cmdViewportResize({ preset, width, height, tab_id }) {
     world: 'MAIN',
   });
   const actual = results?.[0]?.result ?? {};
+  if (read_only) return { actual };
   return { requested: { width: targetW, height: targetH, preset: preset || null }, actual };
 }
 
@@ -3508,6 +3541,51 @@ async function cmdHttpRequest({ url, method = 'GET', headers, body, binary = fal
   return { ...common, body: text, size: text.length };
 }
 
+// --- wait_for_text ---
+
+/**
+ * Attende che un testo compaia. Si poteva già fare con wait_for_function, ma
+ * quella strada richiede il toggle "Allow user scripts" e un'espressione scritta
+ * a mano: questa no.
+ */
+async function cmdWaitForText({ text, selector, timeout = 10000, interval = 200, tab_id, frame_id }) {
+  if (!text) throw new Error('Missing required parameter: text');
+  const tabId = await resolveTabId(tab_id);
+
+  const results = await chrome.scripting.executeScript({
+    target: scriptTarget(tabId, frame_id),
+    func: (needle, scopeSel, tout, intv) => new Promise((resolve) => {
+      const started = Date.now();
+      const wanted = String(needle).toLowerCase();
+      const check = () => {
+        const root = scopeSel ? document.querySelector(scopeSel) : document.body;
+        const haystack = (root?.innerText || '').toLowerCase();
+        const at = haystack.indexOf(wanted);
+        if (at !== -1) {
+          resolve({
+            found: true,
+            waited_ms: Date.now() - started,
+            // Contesto attorno alla prima occorrenza: conferma di aver trovato
+            // la cosa giusta senza restituire l'intera pagina.
+            context: (root?.innerText || '').slice(Math.max(0, at - 60), at + wanted.length + 60).trim(),
+          });
+          return;
+        }
+        if (Date.now() - started >= tout) {
+          resolve({ found: false, error: `Text not found within ${tout}ms: ${needle}` });
+          return;
+        }
+        setTimeout(check, intv);
+      };
+      check();
+    }),
+    args: [text, selector || null, timeout, Math.max(50, interval)],
+    world: 'MAIN',
+  });
+
+  return results?.[0]?.result ?? { found: false, error: 'No result' };
+}
+
 async function cmdSavePage({ tab_id }) {
   const tabId = await resolveTabId(tab_id);
   const blob = await new Promise((resolve, reject) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chrome-bridge-mcp",
   "mcpName": "io.github.frsorrentino/chrome-bridge",
-  "version": "1.10.1",
+  "version": "1.11.1",
   "type": "module",
   "description": "MCP server with 60 tools for browser automation via Chrome extension. Works on ChromeOS/Crostini.",
   "main": "server/index.js",

package/server/protocol.js

@@ -43,6 +43,7 @@ export const MessageType = Object.freeze({
   UPLOAD_FILE:           'upload_file',
   WAIT_FOR_NAVIGATION:   'wait_for_navigation',
   WAIT_FOR_NETWORK_IDLE: 'wait_for_network_idle',
+  WAIT_FOR_TEXT:         'wait_for_text',
   HANDLE_DIALOGS:        'handle_dialogs',
   FIND_TEXT:             'find_text',
   NETWORK_RULES:         'network_rules',
@@ -81,7 +82,7 @@ export const MessageType = Object.freeze({
 });
 
 // Versione
-export const VERSION               = '1.10.1';
+export const VERSION               = '1.11.1';
 
 // Configurazione
 export const DEFAULT_PORT          = 8765;
@@ -127,6 +128,7 @@ export function getTimeout(type) {
   if (type === MessageType.WAIT_FOR_ELEMENT
     || type === MessageType.WAIT_FOR_NAVIGATION
     || type === MessageType.WAIT_FOR_NETWORK_IDLE
+    || type === MessageType.WAIT_FOR_TEXT
     || type === MessageType.UPLOAD_FILE
     || type === MessageType.MANAGE_DOWNLOADS
     || type === MessageType.SAVE_PAGE

package/server/tools.js

@@ -187,6 +187,18 @@ export const TOOL_CAPS = {
 
 // Parametri ubiqui: un solo testo, così `tab_id` non significa una cosa in un
 // tool e un'altra nel gemello. test/unit/tool-parameters.test.js lo verifica.
+// save_to: il payload va su disco e nel contesto resta solo il percorso più un
+// sommario. Deliberatamente opt-in per chiamata e non automatico dopo ogni
+// azione: scrivere file per chi non li leggerà è una tassa, e il server non
+// controlla la directory di lavoro del client.
+const saveToField = (what) => z.string().optional()
+  .describe(`Absolute path: write ${what} there and return the path instead of the content`);
+
+async function savedSummary(path, bytes, extra = {}) {
+  await writeFile(path, bytes);
+  return { content: [{ type: 'text', text: jsonText({ saved: path, bytes: bytes.length, ...extra }) }] };
+}
+
 const selectorField = (extra = '') => z.string()
   .describe(('CSS selector; ">>>" pierces shadow DOM. ' + extra).trim());
 const waitAfter = z.enum(['none', 'navigation', 'networkidle']).optional().default('none')
@@ -509,9 +521,12 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'Downscaled to ≤1568px, so fine print may not survive.',
     {
       tab_id: tabId,
+      save_to: saveToField('the PNG'),
     },
-    async ({ tab_id }) => {
+    async ({ tab_id, save_to }) => {
       const data = await send(MessageType.SCREENSHOT, { tab_id });
+      const b64 = data?.image ?? data?.data;
+      if (save_to && b64) return savedSummary(save_to, Buffer.from(b64, 'base64'), { mimeType: 'image/png' });
       // data.image è base64 PNG
       if (data && data.image) {
         return {
@@ -562,14 +577,16 @@ export function registerTools(server, wsManager, caps = 'all') {
       selector: z.string().optional().describe('CSS selector; ">>>" pierces shadow DOM. Ignored when ref is given'),
       ref:      z.string().optional().describe('From get_interactives, e.g. "n3"'),
       force:    z.boolean().optional().default(false).describe('Click even if occluded'),
+      button:   z.enum(['left', 'right']).optional().default('left').describe('right opens the page context menu instead of activating the element'),
+      count:    z.number().optional().default(1).describe('2 emits dblclick after the two clicks, which is what selects a word or opens an editor'),
       wait_after: waitAfter,
       tab_id:   tabId,
       frame_id: frameId,
     },
-    async ({ selector, ref, force, wait_after, tab_id, frame_id }) => {
+    async ({ selector, ref, force, button, count, wait_after, tab_id, frame_id }) => {
       const target = resolveTarget(selector, ref, tab_id);
       const before = await tabSnapshot(tab_id);
-      const data = await send(MessageType.CLICK, { selector: target, force, frame_id, tab_id });
+      const data = await send(MessageType.CLICK, { selector: target, force, button: button ?? 'left', count: count ?? 1, frame_id, tab_id });
       // Niente attesa se il click non è andato a buon fine (es. elemento occluso)
       const waited = data?.occluded ? null : await applyWaitAfter(send, wait_after, tab_id);
       const changed = data?.occluded ? null : pageDelta(before, await tabSnapshot(tab_id));
@@ -617,21 +634,26 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- read_page ---
   server.tool(
     'read_page',
-    'Read the page as text (default), raw HTML, or accessibility tree. Read-only. Expensive on large pages: '
+    'Read the page as text (default), markdown, raw HTML, or accessibility tree. Read-only. markdown keeps '
+      + 'headings, links and tables at a fraction of the HTML cost, and is usually the right middle ground. '
+      + 'Expensive on large pages: '
       + 'HTML on a big table costs tens of thousands of tokens for data you then filter anyway — prefer '
       + 'extract_table or extract for tabular and repeated content, and get_interactives to find click targets.',
     {
-      mode:       z.enum(['text', 'html', 'accessibility']).default('text').describe('text strips markup, html keeps it (costly), accessibility returns the a11y tree'),
+      mode:       z.enum(['text', 'markdown', 'html', 'accessibility']).default('text').describe('text strips markup, markdown keeps headings/links/tables far cheaper than html, accessibility returns the a11y tree'),
       tab_id:     tabId,
       frame_id:   frameId,
       max_length: z.number().optional().default(50000).describe('Max output chars'),
+      save_to:    saveToField('the page'),
     },
-    async ({ mode, tab_id, frame_id, max_length }) => {
+    async ({ mode, tab_id, frame_id, max_length, save_to }) => {
       const data = await send(MessageType.READ_PAGE, { mode, tab_id, frame_id });
+      const text = typeof data === 'string' ? data : JSON.stringify(data);
+      if (save_to) return savedSummary(save_to, Buffer.from(text, 'utf8'), { mode: mode ?? 'text' });
       return {
         content: [{
           type: 'text',
-          text: truncateText(typeof data === 'string' ? data : JSON.stringify(data), max_length ?? 50000, 'max_length'),
+          text: truncateText(text, max_length ?? 50000, 'max_length'),
         }],
       };
     }
@@ -869,8 +891,9 @@ export function registerTools(server, wsManager, caps = 'all') {
       + '**returns `found: false` with a reason instead of raising**, so a caller that ignores the result '
       + 'silently proceeds as if the wait had succeeded. Read-only: waiting changes nothing on the page.',
     {
-      condition: z.enum(['element', 'function', 'navigation', 'network_idle']).describe('function needs expression; element needs selector'),
-      selector: z.string().optional().describe('condition=element'),
+      condition: z.enum(['element', 'text', 'function', 'navigation', 'network_idle']).describe('element and text need selector or text; function needs expression'),
+      selector: z.string().optional().describe('condition=element; with condition=text it narrows the search to that subtree'),
+      text: z.string().optional().describe('Literal text to wait for (condition=text), matched case-insensitively'),
       expression: z.string().optional().describe('JS expression (condition=function)'),
       visible: z.boolean().optional().default(false).describe('Element must also be visible'),
       mode: z.enum(['load', 'spa']).optional().default('load').describe('spa = pushState/popstate/hashchange'),
@@ -880,12 +903,16 @@ export function registerTools(server, wsManager, caps = 'all') {
       tab_id: tabId,
       frame_id: frameId,
     },
-    async ({ condition, selector, expression, visible, mode, idle_ms, timeout, interval, tab_id, frame_id }) => {
+    async ({ condition, selector, text, expression, visible, mode, idle_ms, timeout, interval, tab_id, frame_id }) => {
       let data;
       if (condition === 'element') {
         data = await send(MessageType.WAIT_FOR_ELEMENT, {
           selector, timeout: timeout ?? 10000, interval: interval ?? 200, visible: visible ?? false, tab_id, frame_id,
         });
+      } else if (condition === 'text') {
+        data = await send(MessageType.WAIT_FOR_TEXT, {
+          text, selector, timeout: timeout ?? 10000, interval: interval ?? 200, tab_id, frame_id,
+        });
       } else if (condition === 'function') {
         data = await send(MessageType.WAIT_FOR_FUNCTION, {
           expression, timeout: timeout ?? 10000, polling_ms: interval ?? 100, tab_id, frame_id,
@@ -997,13 +1024,14 @@ export function registerTools(server, wsManager, caps = 'all') {
       + 'corresponding half of the preset, so preset plus width gives a custom width at the preset height. '
       + 'A maximized window on ChromeOS ignores the request.',
     {
+      action: z.enum(['set', 'get']).optional().default('set').describe('get reports the current viewport without resizing anything'),
       preset: z.enum(['mobile', 'tablet', 'desktop']).optional().describe('375x812, 768x1024, 1440x900'),
       width: z.number().optional().describe('Overrides preset'),
       height: z.number().optional().describe('Overrides preset'),
       tab_id: tabId,
     },
-    async ({ preset, width, height, tab_id }) => {
-      const data = await send(MessageType.VIEWPORT_RESIZE, { preset, width, height, tab_id });
+    async ({ action, preset, width, height, tab_id }) => {
+      const data = await send(MessageType.VIEWPORT_RESIZE, { preset, width, height, read_only: (action ?? 'set') === 'get', tab_id });
       return {
         content: [{
           type: 'text',
@@ -1877,8 +1905,9 @@ export function registerTools(server, wsManager, caps = 'all') {
       format: z.enum(['lines', 'json']).optional().default('lines').describe('lines is compact; json keeps one object per record'),
       tab_id: tabId,
       max_length: z.number().optional().default(20000).describe('Max output chars'),
+      save_to: saveToField('the records as JSON'),
     },
-    async ({ item_selector, fields, max_items, format, tab_id, max_length }) => {
+    async ({ item_selector, fields, max_items, format, tab_id, max_length , save_to }) => {
       max_length = max_length ?? DEFAULT_MAX_OUTPUT;
       const html = await send(MessageType.READ_PAGE, { mode: 'html', tab_id });
       if (typeof html !== 'string') throw new Error('Could not read page HTML');
@@ -1895,6 +1924,7 @@ export function registerTools(server, wsManager, caps = 'all') {
         }
         return row;
       });
+      if (save_to) return savedSummary(save_to, Buffer.from(JSON.stringify({ total: nodes.length, shown: items.length, items }), 'utf8'), { total: nodes.length, shown: items.length });
       if ((format ?? 'lines') === 'json') {
         return { content: [{ type: 'text', text: truncateText(JSON.stringify({ total: nodes.length, shown: items.length, items }), max_length, 'max_items or max_length') }] };
       }

package/tools/cws-upload.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * Carica e pubblica lo zip dell'estensione sul Chrome Web Store via API.
+ *
+ * Esiste per togliere di mezzo il TOTP: la dev console non è automatizzabile
+ * (la gallery non è scriptabile da un'estensione, e via CDP serve comunque il
+ * login Google completo), mentre l'API vuole solo un refresh token revocabile.
+ *
+ * Credenziali in ~/.config/chrome-bridge/cws.json (chmod 600), MAI nel repo:
+ *   { "client_id": "...", "client_secret": "...", "refresh_token": "...", "item_id": "..." }
+ * Sovrascrivibili da CWS_CLIENT_ID / CWS_CLIENT_SECRET / CWS_REFRESH_TOKEN / CWS_ITEM_ID.
+ *
+ * Uso:
+ *   node tools/cws-upload.mjs dist/chrome-bridge-extension-1.11.0.zip           # carica come bozza
+ *   node tools/cws-upload.mjs dist/....zip --publish                            # carica e pubblica
+ *   node tools/cws-upload.mjs --auth [porta]                                    # URL di consenso + cattura del codice sul loopback
+ *   node tools/cws-upload.mjs --exchange <code> [--redirect <uri>]              # code → refresh token
+ */
+import { createServer } from 'node:http';
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+const CONFIG = join(homedir(), '.config', 'chrome-bridge', 'cws.json');
+const SCOPE = 'https://www.googleapis.com/auth/chromewebstore';
+// Google ha dismesso il redirect fuori banda (urn:ietf:wg:oauth:2.0:oob): un
+// client nuovo che lo usa riceve "Errore 400: invalid_request". Per i client
+// desktop la strada supportata è il loopback su una porta qualsiasi, che qui
+// viene aperta al volo e chiusa appena arriva il codice.
+function buildAuthUrl(clientId, redirectUri) {
+  return 'https://accounts.google.com/o/oauth2/auth?' + new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    response_type: 'code',
+    scope: SCOPE,
+    access_type: 'offline',
+    prompt: 'consent',
+  });
+}
+
+// Attende un solo codice sul loopback e poi chiude: nessun server che resta su.
+function waitForCode(port) {
+  return new Promise((resolve, reject) => {
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, `http://127.0.0.1:${port}`);
+      const code = url.searchParams.get('code');
+      const err = url.searchParams.get('error');
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(`<h2>${code ? 'Autorizzato. Puoi chiudere questa scheda.' : 'Errore: ' + (err || 'nessun codice')}</h2>`);
+      server.close();
+      if (code) resolve(code); else reject(new Error(err || 'nessun codice nella risposta'));
+    });
+    server.on('error', reject);
+    server.listen(port, '127.0.0.1');
+    setTimeout(() => { server.close(); reject(new Error('nessuna autorizzazione entro 5 minuti')); }, 300000);
+  });
+}
+
+export async function loadConfig(env = process.env) {
+  let file = {};
+  try { file = JSON.parse(await readFile(CONFIG, 'utf8')); } catch { /* prima esecuzione */ }
+  return {
+    client_id: env.CWS_CLIENT_ID || file.client_id,
+    client_secret: env.CWS_CLIENT_SECRET || file.client_secret,
+    refresh_token: env.CWS_REFRESH_TOKEN || file.refresh_token,
+    item_id: env.CWS_ITEM_ID || file.item_id,
+  };
+}
+
+export function requireFields(cfg, fields) {
+  const missing = fields.filter((f) => !cfg[f]);
+  if (missing.length) {
+    throw new Error(`Manca ${missing.join(', ')} — mettili in ${CONFIG} o nelle variabili CWS_*`);
+  }
+}
+
+/**
+ * Il Web Store risponde 200 anche quando il caricamento è fallito: l'esito vero
+ * è in uploadState, e itemError porta il motivo. Trattare 200 come successo è
+ * il modo di credere di aver pubblicato senza averlo fatto.
+ */
+export function interpretUpload(body) {
+  const state = body?.uploadState;
+  if (state === 'SUCCESS') return { ok: true, state };
+  const reasons = (body?.itemError || []).map((e) => e.error_detail || e.errorDetail || JSON.stringify(e));
+  return { ok: false, state: state ?? 'UNKNOWN', reasons };
+}
+
+export function interpretPublish(body) {
+  const status = body?.status || [];
+  const ok = status.includes('OK') || status.includes('PUBLISHED_WITH_FRICTION_WARNING');
+  return { ok, status, detail: body?.statusDetail || [] };
+}
+
+async function exchange(cfg, code, redirectUri) {
+  const res = await fetch('https://oauth2.googleapis.com/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      client_id: cfg.client_id, client_secret: cfg.client_secret,
+      code, grant_type: 'authorization_code', redirect_uri: redirectUri,
+    }),
+  });
+  const body = await res.json();
+  if (!body.refresh_token) throw new Error(`Nessun refresh_token: ${JSON.stringify(body)}`);
+  return body.refresh_token;
+}
+
+async function saveRefreshToken(cfg, refresh_token) {
+  await mkdir(dirname(CONFIG), { recursive: true });
+  await writeFile(CONFIG, JSON.stringify({ ...cfg, refresh_token }, null, 2), { mode: 0o600 });
+  console.log(`refresh_token salvato in ${CONFIG} (chmod 600)`);
+}
+
+async function accessToken(cfg) {
+  const res = await fetch('https://oauth2.googleapis.com/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      client_id: cfg.client_id,
+      client_secret: cfg.client_secret,
+      refresh_token: cfg.refresh_token,
+      grant_type: 'refresh_token',
+    }),
+  });
+  const body = await res.json();
+  if (!res.ok || !body.access_token) {
+    // invalid_grant qui significa quasi sempre consent screen in "Testing":
+    // in quello stato Google scade i refresh token dopo 7 giorni.
+    throw new Error(`Token refresh fallito (${res.status}): ${JSON.stringify(body)}`);
+  }
+  return body.access_token;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cfg = await loadConfig();
+
+  if (argv.includes('--auth')) {
+    requireFields(cfg, ['client_id', 'client_secret']);
+    const portArg = argv[argv.indexOf('--auth') + 1];
+    const port = Number(portArg) > 0 ? Number(portArg) : 8899;
+    const redirect = `http://localhost:${port}`;
+    console.log(buildAuthUrl(cfg.client_id, redirect));
+    console.error(`in attesa del codice su ${redirect} …`);
+
+    const code = await waitForCode(port);
+    const token = await exchange(cfg, code, redirect);
+    await saveRefreshToken(cfg, token);
+    return;
+  }
+
+  const exIdx = argv.indexOf('--exchange');
+  if (exIdx !== -1) {
+    requireFields(cfg, ['client_id', 'client_secret']);
+    const code = argv[exIdx + 1];
+    if (!code) throw new Error('Uso: --exchange <codice> [--redirect <uri>]');
+    const rIdx = argv.indexOf('--redirect');
+    const redirect = rIdx !== -1 ? argv[rIdx + 1] : 'http://localhost:8899';
+    await saveRefreshToken(cfg, await exchange(cfg, code, redirect));
+    return;
+  }
+
+  const zip = argv.find((a) => a.endsWith('.zip'));
+  if (!zip) throw new Error('Indica lo zip da caricare, o usa --auth / --exchange');
+  requireFields(cfg, ['client_id', 'client_secret', 'refresh_token', 'item_id']);
+
+  const size = (await stat(zip)).size;
+  const token = await accessToken(cfg);
+
+  const up = await fetch(`https://www.googleapis.com/upload/chromewebstore/v1.1/items/${cfg.item_id}`, {
+    method: 'PUT',
+    headers: { Authorization: `Bearer ${token}`, 'x-goog-api-version': '2' },
+    body: await readFile(zip),
+  });
+  const upBody = await up.json();
+  const upRes = interpretUpload(upBody);
+  console.log(`upload ${zip} (${size} B): ${upRes.ok ? 'SUCCESS' : `FALLITO [${upRes.state}] ${upRes.reasons.join(' | ')}`}`);
+  if (!upRes.ok) process.exit(1);
+
+  if (!argv.includes('--publish')) {
+    console.log('bozza caricata; ripassa con --publish per mandarla in review');
+    return;
+  }
+
+  const pub = await fetch(`https://www.googleapis.com/chromewebstore/v1.1/items/${cfg.item_id}/publish`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'x-goog-api-version': '2', 'Content-Length': '0' },
+  });
+  const pubRes = interpretPublish(await pub.json());
+  console.log(`publish: ${pubRes.ok ? 'OK' : 'FALLITO'} ${pubRes.status.join(',')} ${pubRes.detail.join(' | ')}`);
+  if (!pubRes.ok) process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error(String(e.message || e)); process.exit(1); });
+}