chrome-bridge-mcp 1.10.0 → 1.11.0

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-131%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.4k tokens of `tools/list`, all 60 cost ≈14.1k; 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.0",
+  "version": "1.11.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/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.0",
+  "version": "1.11.0",
   "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.0';
+export const VERSION               = '1.11.0';
 
 // 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,17 @@ 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. L'idea è di superpowers-chrome, che scrive automaticamente a ogni
+// azione; qui è opt-in, perché scrivere file per chi non li leggerà è una tassa.
+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 +520,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 +576,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));
@@ -586,7 +602,11 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- type_text ---
   server.tool(
     'type_text',
-    'Type text into an input, by CSS selector or by ref from get_interactives.',
+    'Put text into an input, textarea or contenteditable, by CSS selector or by a ref from get_interactives. '
+      + 'Replaces the whole value rather than appending, and assigns through the native setter so React and '
+      + 'Vue controlled inputs register the change, then fires input and change. mode=keys instead emits '
+      + 'keydown/input/keyup per character, which is what autocomplete and masked fields need — slower, so '
+      + 'reach for it only when mode=set leaves the field empty or the dropdown never opens.',
     {
       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"'),
@@ -613,21 +633,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'),
         }],
       };
     }
@@ -859,10 +884,15 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- wait_for ---
   server.tool(
     'wait_for',
-    'Wait for: element (selector in DOM), function (JS expression truthy; needs "Allow user scripts"), navigation (mode=spa for route changes), network_idle.',
+    'Block until a condition holds: element (selector in the DOM), function (JS expression turns truthy; needs '
+      + 'the "Allow user scripts" toggle), navigation (mode=spa for client-side route changes), network_idle. '
+      + 'Polls until timeout — 10s for element and function, 15s for navigation and network_idle — then '
+      + '**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'),
@@ -872,12 +902,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,
@@ -983,15 +1017,20 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- viewport_resize ---
   server.tool(
     'viewport_resize',
-    'Resize Chrome window to preset (mobile/tablet/desktop) or custom dimensions',
+    'Resize the Chrome **window** to a preset (mobile 375x812, tablet 768x1024, desktop 1440x900) or to explicit '
+      + 'dimensions. The rendered viewport ends up smaller than what you ask for, by the height of the browser '
+      + 'chrome — measure it with execute_js if the exact number matters. width and height each override the '
+      + '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',
@@ -1072,7 +1111,10 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- highlight_elements ---
   server.tool(
     'highlight_elements',
-    'Add colored overlay on elements matching a CSS selector. remove=true clears all highlights.',
+    'Outline every element matching a selector with a coloured overlay, to see on a screenshot what a selector '
+      + 'actually caught. Each call clears the overlays left by the previous one instead of stacking them, and '
+      + 'remove=true clears without adding. The overlays are injected DOM nodes: a reload or a navigation drops '
+      + 'them, and they sit above the page without altering its layout or its own styles.',
     {
       selector: z.string().optional().describe('CSS selector; ">>>" pierces shadow DOM. Every match is outlined'),
       color: z.string().optional().default('rgba(255,0,0,0.3)').describe('Any CSS color for the overlay label'),
@@ -1740,7 +1782,11 @@ export function registerTools(server, wsManager, caps = 'all') {
   // --- session_fixture ---
   server.tool(
     'session_fixture',
-    'Save/restore localStorage+sessionStorage+cookies as a named fixture (e.g. a logged-in state). Restore requires the tab to be on the origin recorded at save.',
+    'Snapshot localStorage, sessionStorage and cookies of the current origin into a named fixture on the server, '
+      + 'restore one, or list what has been saved. A logged-in state is the usual reason. save overwrites a '
+      + 'fixture of the same name without asking; restore writes entries on top of what is already there '
+      + 'rather than clearing first, and refuses outright when the tab sits on a different origin than the '
+      + 'one recorded — cookies would otherwise attach to the wrong site. name is required except for list.',
     {
       action: z.enum(['save', 'restore', 'list']).describe('save snapshots the current origin; restore writes it back'),
       name: z.string().optional().describe('Required for save/restore'),
@@ -1858,8 +1904,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');
@@ -1876,6 +1923,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') }] };
       }