chromex-mcp 1.0.0 → 1.2.0

package/README.md

@@ -289,11 +289,11 @@ Chromex also ships as an MCP server -- typed tools, auto-approve with one line,
 ### Setup
 
 ```bash
-# Via npx (recommended)
-claude mcp add chromex npx chromex-mcp@latest
+# Global (all projects)
+claude mcp add chromex -s user npx chromex-mcp@latest
 
-# Or with absolute path (no npm needed)
-claude mcp add chromex node /path/to/plugins/chromex/skills/chromex/scripts/mcp-server.mjs
+# Or project-only
+claude mcp add chromex npx chromex-mcp@latest
 ```
 
 ### Auto-Approve

package/bin/chromex-cli.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../plugins/chromex/skills/chromex/scripts/chromex.mjs';

package/bin/chromex-mcp.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../plugins/chromex/skills/chromex/scripts/mcp-server.mjs';

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "chromex-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Zero-dependency Chrome DevTools Protocol MCP server for AI agents. 52 typed tools, per-tab daemons, security hardened.",
   "type": "module",
   "bin": {
-    "chromex-mcp": "./plugins/chromex/skills/chromex/scripts/mcp-server.mjs",
-    "chromex-cli": "./plugins/chromex/skills/chromex/scripts/chromex.mjs"
+    "chromex-mcp": "./bin/chromex-mcp.mjs",
+    "chromex-cli": "./bin/chromex-cli.mjs"
   },
   "files": [
+    "bin/",
     "plugins/chromex/skills/chromex/scripts/",
     "LICENSE",
     "README.md"

package/plugins/chromex/skills/chromex/scripts/chromex.mjs

@@ -244,7 +244,8 @@ async function main() {
 
   const conn = await getOrStartTabDaemon(targetId, config);
 
-  const cmdArgs = args.slice(1);
+  const noSnap = args.includes('--no-snap');
+  const cmdArgs = args.slice(1).filter(a => a !== '--no-snap');
 
   // Juntar argumentos para comandos que aceitam texto livre
   if (cmd === 'eval') {
@@ -278,6 +279,7 @@ async function main() {
     process.exit(1);
   }
 
+  if (noSnap) cmdArgs.push('--no-snap');
   const response = await sendCommand(conn, { cmd, args: cmdArgs });
 
   if (response.ok) {

package/plugins/chromex/skills/chromex/scripts/lib/commands/snapshot.mjs

@@ -1,4 +1,4 @@
-// Accessibility tree snapshot with optional interactive refs (@e1, @e2...)
+// Accessibility tree snapshot with incremental diff and interactive refs (@e1, @e2...)
 
 const INTERACTIVE_ROLES = new Set([
   'button', 'link', 'textbox', 'checkbox', 'radio', 'combobox',
@@ -6,7 +6,17 @@ const INTERACTIVE_ROLES = new Set([
   'option', 'menuitemcheckbox', 'menuitemradio', 'treeitem',
 ]);
 
+// Check if AX node is marked as ignored/hidden by the browser
+function isAxNodeHidden(node) {
+  if (node.ignored) return true;
+  // CDP includes boolean properties like 'hidden' in the properties array
+  const hidden = node.properties?.find(p => p.name === 'hidden');
+  if (hidden?.value?.value === true) return true;
+  return false;
+}
+
 function shouldShowAxNode(node, compact = false) {
+  if (isAxNodeHidden(node)) return false;
   const role = node.role?.value || '';
   const name = node.name?.value ?? '';
   const value = node.value?.value;
@@ -14,21 +24,36 @@ function shouldShowAxNode(node, compact = false) {
   return role !== 'none' && role !== 'generic' && !(name === '' && (value === '' || value == null));
 }
 
-function formatAxNode(node, depth, refIndex, refs) {
+// Check if element is focusable/clickable (not disabled, not aria-disabled)
+function isAxNodeInteractable(node) {
+  const disabled = node.properties?.find(p => p.name === 'disabled');
+  if (disabled?.value?.value === true) return false;
+  return true;
+}
+
+const MAX_NAME_LENGTH = 200;
+
+function truncate(str, max = MAX_NAME_LENGTH) {
+  if (!str || str.length <= max) return str;
+  return str.slice(0, max) + '...';
+}
+
+function formatAxNode(node, depth, refIndex, refs, isNew = false) {
   const role = node.role?.value || '';
-  const name = node.name?.value ?? '';
+  const name = truncate(node.name?.value ?? '');
   const value = node.value?.value;
   const indent = '  '.repeat(Math.min(depth, 10));
 
   let refTag = '';
-  if (refs && INTERACTIVE_ROLES.has(role.toLowerCase())) {
+  if (refs && INTERACTIVE_ROLES.has(role.toLowerCase()) && isAxNodeInteractable(node)) {
     refTag = `@e${refIndex.value} `;
     refIndex.value++;
   }
 
-  let line = `${indent}${refTag}[${role}]`;
+  const newTag = isNew ? '*' : '';
+  let line = `${indent}${newTag}${refTag}[${role}]`;
   if (name !== '') line += ` ${name}`;
-  if (!(value === '' || value == null)) line += ` = ${JSON.stringify(value)}`;
+  if (!(value === '' || value == null)) line += ` = ${JSON.stringify(truncate(String(value)))}`;
   return line;
 }
 
@@ -51,9 +76,76 @@ function orderedAxChildren(node, nodesById, childrenByParent) {
   return children;
 }
 
+// Build a fingerprint for each visible node: role + name + value + childCount
+// Used for incremental diff to detect changes
+function buildFingerprints(nodes, nodesById, childrenByParent, compact) {
+  const fingerprints = new Map();
+  for (const node of nodes) {
+    if (!shouldShowAxNode(node, compact)) continue;
+    const role = node.role?.value || '';
+    const name = node.name?.value ?? '';
+    const value = node.value?.value ?? '';
+    const children = orderedAxChildren(node, nodesById, childrenByParent);
+    const childIds = children.filter(c => shouldShowAxNode(c, compact)).map(c => c.nodeId).join(',');
+    fingerprints.set(node.nodeId, `${role}|${name}|${value}|${childIds}`);
+  }
+  return fingerprints;
+}
+
+// Detect scrollable containers. Returns human-readable summary lines.
+// Only reports containers with overflow:auto|scroll and >50px hidden content.
+async function detectScrollables(cdp, sid) {
+  try {
+    const { result } = await cdp.send('Runtime.evaluate', {
+      expression: `(() => {
+        const MIN = 50;
+        const out = [];
+        const walk = (el, path) => {
+          if (el.nodeType !== 1 || out.length >= 10) return;
+          const sh = el.scrollHeight, sw = el.scrollWidth;
+          const ch = el.clientHeight, cw = el.clientWidth;
+          const isRoot = el === document.documentElement || el === document.body;
+          const style = isRoot ? null : getComputedStyle(el);
+          const oy = isRoot ? 'auto' : style.overflowY;
+          const ox = isRoot ? 'auto' : style.overflowX;
+          const scrollableY = isRoot || oy === 'auto' || oy === 'scroll';
+          const scrollableX = isRoot || ox === 'auto' || ox === 'scroll';
+          if (((scrollableY && sh > ch + MIN) || (scrollableX && sw > cw + MIN)) && ch > 0) {
+            const dirs = [];
+            if (scrollableY && sh > ch + MIN) {
+              const down = sh - ch - el.scrollTop;
+              const up = el.scrollTop;
+              if (up > MIN) dirs.push('up:' + Math.round(up) + 'px');
+              if (down > MIN) dirs.push('down:' + Math.round(down) + 'px');
+            }
+            if (scrollableX && sw > cw + MIN) {
+              const right = sw - cw - el.scrollLeft;
+              const left = el.scrollLeft;
+              if (left > MIN) dirs.push('left:' + Math.round(left) + 'px');
+              if (right > MIN) dirs.push('right:' + Math.round(right) + 'px');
+            }
+            if (dirs.length) {
+              const label = isRoot ? 'page' : (el.getAttribute('aria-label') || el.getAttribute('role') || el.id || el.tagName.toLowerCase());
+              out.push(label + ': ' + dirs.join(', '));
+            }
+          }
+          for (const c of el.children) walk(c);
+        };
+        walk(document.documentElement);
+        return out;
+      })()`,
+      returnByValue: true,
+    }, sid);
+    return result?.value || [];
+  } catch { return []; }
+}
+
 // refMap is populated when refs=true: { refNumber -> { backendNodeId, role, name } }
 // The caller (daemon) stores this map for later ref resolution.
-export async function snapshotStr(cdp, sid, compact = true, refs = false) {
+// previousFingerprints: Map from prior snapshot for incremental diff.
+// maxDepth: limit tree depth (0 = unlimited). Nodes at the limit render as leaves.
+// Returns { text, refMap, fingerprints } -- caller stores fingerprints for next diff.
+export async function snapshotStr(cdp, sid, compact = true, refs = false, previousFingerprints = null, maxDepth = 0) {
   const { nodes } = await cdp.send('Accessibility.getFullAXTree', {}, sid);
   const nodesById = new Map(nodes.map(node => [node.nodeId, node]));
   const childrenByParent = new Map();
@@ -63,38 +155,120 @@ export async function snapshotStr(cdp, sid, compact = true, refs = false) {
     childrenByParent.get(node.parentId).push(node);
   }
 
+  const currentFingerprints = buildFingerprints(nodes, nodesById, childrenByParent, compact);
+  const isDiff = previousFingerprints !== null && previousFingerprints.size > 0;
+  const scrollables = await detectScrollables(cdp, sid);
+
   const refIndex = { value: 1 };
   const refMap = new Map();
   const lines = [];
   const visited = new Set();
 
+  // Track unchanged subtree roots for diff output
+  let unchangedCount = 0;
+
+  function isSubtreeUnchanged(node) {
+    if (!previousFingerprints) return false;
+    const nodeId = node.nodeId;
+    const curr = currentFingerprints.get(nodeId);
+    const prev = previousFingerprints.get(nodeId);
+    if (!curr || !prev || curr !== prev) return false;
+    // Node itself matches -- check all visible children recursively
+    const children = orderedAxChildren(node, nodesById, childrenByParent);
+    for (const child of children) {
+      if (!shouldShowAxNode(child, compact)) continue;
+      if (!isSubtreeUnchanged(child)) return false;
+    }
+    return true;
+  }
+
   function visit(node, depth) {
     if (!node || visited.has(node.nodeId)) return;
     visited.add(node.nodeId);
-    if (shouldShowAxNode(node, compact)) {
-      const role = node.role?.value || '';
-      const currentRef = refIndex.value;
 
-      lines.push(formatAxNode(node, depth, refIndex, refs));
+    const show = shouldShowAxNode(node, compact);
+
+    if (!show) {
+      // Generic/none node: collapse by visiting children at SAME depth (no indentation increase)
+      for (const child of orderedAxChildren(node, nodesById, childrenByParent)) {
+        visit(child, depth);
+      }
+      return;
+    }
+
+    // Incremental diff: if this subtree is unchanged, collapse it
+    if (isDiff && isSubtreeUnchanged(node)) {
+      unchangedCount++;
+      if (refs) {
+        advanceRefsForSubtree(node);
+      }
+      return;
+    }
+
+    const role = node.role?.value || '';
+    const currentRef = refIndex.value;
+    const isNew = isDiff && !previousFingerprints.has(node.nodeId);
+
+    lines.push(formatAxNode(node, depth, refIndex, refs, isNew));
+
+    if (refs && refIndex.value > currentRef) {
+      refMap.set(currentRef, {
+        backendNodeId: node.backendDOMNodeId,
+        nodeId: node.nodeId,
+        role,
+        name: node.name?.value ?? '',
+      });
+    }
+
+    // Depth limiting: at the limit, render as leaf (no children)
+    if (maxDepth > 0 && depth >= maxDepth) return;
+
+    for (const child of orderedAxChildren(node, nodesById, childrenByParent)) {
+      visit(child, depth + 1);
+    }
+  }
 
-      // If ref was assigned (refIndex advanced), record the mapping
-      if (refs && refIndex.value > currentRef) {
-        refMap.set(currentRef, {
+  // Advance ref counter for unchanged subtrees to keep ref numbers stable
+  // Uses its own visited set because visit() already marked nodes before calling this
+  const refAdvanced = new Set();
+  function advanceRefsForSubtree(node) {
+    if (!node || refAdvanced.has(node.nodeId)) return;
+    refAdvanced.add(node.nodeId);
+    if (shouldShowAxNode(node, compact)) {
+      const role = node.role?.value || '';
+      if (INTERACTIVE_ROLES.has(role.toLowerCase()) && isAxNodeInteractable(node)) {
+        refMap.set(refIndex.value, {
           backendNodeId: node.backendDOMNodeId,
           nodeId: node.nodeId,
           role,
           name: node.name?.value ?? '',
         });
+        refIndex.value++;
       }
     }
     for (const child of orderedAxChildren(node, nodesById, childrenByParent)) {
-      visit(child, depth + 1);
+      advanceRefsForSubtree(child);
     }
   }
 
   const roots = nodes.filter(node => !node.parentId || !nodesById.has(node.parentId));
   for (const root of roots) visit(root, 0);
-  for (const node of nodes) visit(node, 0);
+  // Second pass: catch disconnected nodes (skip when depth-limited to avoid false depth=0)
+  if (!maxDepth) {
+    for (const node of nodes) visit(node, 0);
+  }
+
+  // Add diff summary header when in incremental mode
+  let text = lines.join('\n');
+  if (isDiff && unchangedCount > 0) {
+    const totalVisible = currentFingerprints.size;
+    const changedCount = totalVisible - unchangedCount;
+    text = `[incremental: ${changedCount} changed, ${unchangedCount} unchanged]\n${text}`;
+  }
+  // Append scroll info footer when scrollable containers exist
+  if (scrollables.length > 0) {
+    text += `\n[scroll: ${scrollables.join(' | ')}]`;
+  }
 
-  return { text: lines.join('\n'), refMap };
+  return { text, refMap, fingerprints: currentFingerprints };
 }

package/plugins/chromex/skills/chromex/scripts/lib/daemon.mjs

@@ -46,6 +46,15 @@ import { touchStr } from './commands/touch.mjs';
 import { domsnapshotStr } from './commands/domsnapshot.mjs';
 import { parseRef, clickRefStr, hoverRefStr, fillRefStr } from './commands/refs.mjs';
 import { highlightStr } from './commands/highlight.mjs';
+import { sleep } from './utils.mjs';
+
+// Commands that modify visible DOM and should trigger automatic post-action snapshot.
+// After these commands, an incremental snapshot with refs is appended to the result,
+// so the AI agent sees the page state without needing a separate snapshot call.
+const AUTO_SNAP_CMDS = new Set([
+  'click', 'clickxy', 'type', 'fill', 'clear', 'select', 'check', 'form',
+  'nav', 'navigate', 'dialog', 'loadall', 'drag', 'touch', 'upload',
+]);
 
 export function getOrCreateToken(config) {
   if (!config.socketAuth) return null;
@@ -106,17 +115,26 @@ export async function runDaemon(targetId, config) {
     idleTimer = setTimeout(shutdown, config.idleTimeout);
   }
 
-  // Ref-based selection state: stores mapping from @eN -> {backendNodeId, role, name}
+  // Per-tab state: ref map for @eN resolution + fingerprints for incremental diff
   let currentRefMap = new Map();
+  let previousFingerprints = null;
 
   async function handleCommand({ cmd, args }) {
     resetIdle();
     const auditResult = { ok: true };
     try {
+      // Strip --no-snap before dispatch so it doesn't contaminate command args
+      // (e.g. fill would type "--no-snap" into the input field).
+      const noSnap = args.includes('--no-snap');
+      if (noSnap) args = args.filter(a => a !== '--no-snap');
+
+      let result;
+      let isRefCmd = false;
+
       // Ref-based dispatch: click @e5, fill @e3 "value", hover @e12
       if (args[0] && parseRef(args[0]) !== null) {
+        isRefCmd = true;
         const refNum = parseRef(args[0]);
-        let result;
         if (cmd === 'click') {
           result = await clickRefStr(cdp, sessionId, currentRefMap, refNum);
         } else if (cmd === 'fill') {
@@ -126,12 +144,9 @@ export async function runDaemon(targetId, config) {
         } else {
           throw new Error(`Ref @e${refNum} not supported for command "${cmd}". Use with: click, fill, hover.`);
         }
-        audit(cmd, targetId, args, auditResult, config);
-        return { ok: true, result };
       }
 
-      let result;
-      switch (cmd) {
+      if (!isRefCmd) switch (cmd) {
         // --- Comandos originais ---
         case 'list': {
           const pages = await getPages(cdp);
@@ -145,8 +160,13 @@ export async function runDaemon(targetId, config) {
         }
         case 'snap': case 'snapshot': {
           const useRefs = args.includes('--refs') || args.includes('-i');
-          const snapResult = await snapshotStr(cdp, sessionId, true, useRefs);
+          const forceFull = args.includes('--full');
+          const depthArg = args.find(a => a.startsWith('--depth='));
+          const maxDepth = depthArg ? parseInt(depthArg.split('=')[1]) || 0 : 0;
+          const prevFp = forceFull ? null : previousFingerprints;
+          const snapResult = await snapshotStr(cdp, sessionId, true, useRefs, prevFp, maxDepth);
           result = snapResult.text;
+          previousFingerprints = snapResult.fingerprints;
           if (useRefs && snapResult.refMap.size > 0) {
             currentRefMap = snapResult.refMap;
           }
@@ -166,6 +186,7 @@ export async function runDaemon(targetId, config) {
           break;
         case 'nav': case 'navigate':
           result = await navStr(cdp, sessionId, args[0], config);
+          previousFingerprints = null; // Reset: new page needs full snapshot
           break;
         case 'net': case 'network':
           result = await netStr(cdp, sessionId);
@@ -316,6 +337,29 @@ export async function runDaemon(targetId, config) {
         }
       }
       audit(cmd, targetId, args, auditResult, config);
+
+      // Auto-snapshot: append incremental snapshot with refs after DOM-modifying actions.
+      // This lets the AI agent see the resulting page state in a single round-trip.
+      // Opt-out with --no-snap for scripts doing rapid sequential actions.
+      const shouldSnap = isRefCmd
+        ? (cmd === 'click' || cmd === 'fill') // hover doesn't change DOM
+        : AUTO_SNAP_CMDS.has(cmd);
+
+      if (shouldSnap && !noSnap) {
+        try {
+          // Navigate already waits for load+readyState; shorter settle for it.
+          // Other actions (click, fill) need more time for SPA re-renders.
+          const settleMs = (cmd === 'nav' || cmd === 'navigate') ? 100 : 300;
+          await sleep(settleMs);
+          const snapResult = await snapshotStr(cdp, sessionId, true, true, previousFingerprints);
+          previousFingerprints = snapResult.fingerprints;
+          if (snapResult.refMap.size > 0) {
+            currentRefMap = snapResult.refMap;
+          }
+          result = (result ?? '') + '\n\n' + snapResult.text;
+        } catch (e) { process.stderr.write(`[auto-snap] ${e.message}\n`); }
+      }
+
       return { ok: true, result: result ?? '' };
     } catch (e) {
       auditResult.ok = false;

package/plugins/chromex/skills/chromex/scripts/mcp-server.mjs

@@ -54,6 +54,7 @@ function tool(name, description, properties, required, annotations) {
 }
 
 const P_TARGET = { type: 'string', description: 'Target ID prefix from chromex_list' };
+const P_NO_SNAP = { type: 'boolean', description: 'Skip auto-snapshot after action' };
 
 // ---- Tool definitions (52 tools) ----
 
@@ -97,10 +98,12 @@ const TOOLS = [
 
   // == INSPECT (readOnly) ==
   tool('chromex_snapshot',
-    'Accessibility tree snapshot. Prefer over HTML for page structure. Use refs=true to get @eN references for click/fill/hover.',
+    'Accessibility tree snapshot. Returns incremental diff after first call (only changed nodes). Use refs=true to get @eN references for click/fill/hover.',
     {
       target: P_TARGET,
       refs: { type: 'boolean', description: 'Assign @eN refs to interactive elements', default: false },
+      full: { type: 'boolean', description: 'Force full snapshot (skip incremental diff)', default: false },
+      depth: { type: 'number', description: 'Max tree depth (0 = unlimited)' },
     }, ['target'], RO),
 
   tool('chromex_html',
@@ -165,10 +168,11 @@ const TOOLS = [
 
   // == NAVIGATE ==
   tool('chromex_navigate',
-    'Navigate to URL and wait for page load.',
+    'Navigate to URL and wait for page load. Returns full snapshot with refs of the new page.',
     {
       target: P_TARGET,
       url: { type: 'string', description: 'URL to navigate to' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'url'], RW),
 
   tool('chromex_waitfor',
@@ -197,25 +201,28 @@ const TOOLS = [
 
   // == INTERACT ==
   tool('chromex_click',
-    'Click element by CSS selector or @eN ref from snapshot.',
+    'Click element by CSS selector or @eN ref from snapshot. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       selector: { type: 'string', description: 'CSS selector or @eN ref' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'selector'], RW),
 
   tool('chromex_clickxy',
-    'Click at CSS pixel coordinates.',
+    'Click at CSS pixel coordinates. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       x: { type: 'number', description: 'X in CSS pixels' },
       y: { type: 'number', description: 'Y in CSS pixels' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'x', 'y'], RW),
 
   tool('chromex_type',
-    'Type text at currently focused element.',
+    'Type text at currently focused element. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       text: { type: 'string', description: 'Text to type' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'text'], RW),
 
   tool('chromex_hover',
@@ -226,82 +233,92 @@ const TOOLS = [
     }, ['target', 'ref'], RW),
 
   tool('chromex_drag',
-    'Drag and drop between selectors or coordinate pairs (x1,y1 x2,y2).',
+    'Drag and drop between selectors or coordinate pairs (x1,y1 x2,y2). Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       from: { type: 'string', description: 'Source selector or x,y' },
       to: { type: 'string', description: 'Destination selector or x,y' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'from', 'to'], RW),
 
   tool('chromex_touch',
-    'Touch gesture: tap, swipe, pinch, longpress.',
+    'Touch gesture: tap, swipe, pinch, longpress. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       gesture: { type: 'string', enum: ['tap', 'swipe', 'pinch', 'longpress'], description: 'Gesture type' },
       args: { type: 'array', items: { type: 'string' }, description: 'Gesture args: tap(x,y), swipe(x1,y1,x2,y2), pinch(x,y,scale), longpress(x,y,[ms])' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'gesture'], RW),
 
   tool('chromex_dialog',
-    'Handle JS dialogs (alert/confirm/prompt). Use "auto" to auto-accept all.',
+    'Handle JS dialogs (alert/confirm/prompt). Use "auto" to auto-accept all. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       action: { type: 'string', enum: ['accept', 'dismiss', 'auto'], description: 'Dialog action' },
       text: { type: 'string', description: 'Text for prompt (only with accept)' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'action'], RW),
 
   tool('chromex_loadall',
-    'Click "load more" button repeatedly until it disappears.',
+    'Click "load more" button repeatedly until it disappears. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       selector: { type: 'string', description: 'CSS selector of load-more button' },
       interval: { type: 'number', description: 'Interval between clicks in ms (default: 1500)' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'selector'], RW),
 
   // == FORMS ==
   tool('chromex_fill',
-    'Fill input/textarea. Handles React/Vue/Angular controlled inputs. Accepts @eN ref.',
+    'Fill input/textarea. Handles React/Vue/Angular controlled inputs. Accepts @eN ref. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       selector: { type: 'string', description: 'CSS selector or @eN ref' },
       value: { type: 'string', description: 'Value to fill' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'selector', 'value'], RW),
 
   tool('chromex_clear',
-    'Clear input field.',
+    'Clear input field. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       selector: { type: 'string', description: 'CSS selector' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'selector'], RW),
 
   tool('chromex_select',
-    'Select option in dropdown.',
+    'Select option in dropdown. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       selector: { type: 'string', description: 'CSS selector of select element' },
       value: { type: 'string', description: 'Option value or visible text' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'selector', 'value'], RW),
 
   tool('chromex_check',
-    'Toggle checkbox or radio button.',
+    'Toggle checkbox or radio button. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       selector: { type: 'string', description: 'CSS selector' },
       checked: { type: 'boolean', description: 'Desired state (default: true)', default: true },
+      noSnap: P_NO_SNAP,
     }, ['target', 'selector'], RW),
 
   tool('chromex_form',
-    'Batch fill form. JSON maps selectors to values. Booleans toggle checkboxes.',
+    'Batch fill form. JSON maps selectors to values. Booleans toggle checkboxes. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       fields: { type: 'string', description: 'JSON: {"#email":"user@test.com","#terms":true}' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'fields'], RW),
 
   tool('chromex_upload',
-    'Upload file(s) to input[type=file].',
+    'Upload file(s) to input[type=file]. Returns auto-snapshot with updated refs.',
     {
       target: P_TARGET,
       selector: { type: 'string', description: 'CSS selector of file input' },
       files: { type: 'array', items: { type: 'string' }, description: 'File path(s)' },
+      noSnap: P_NO_SNAP,
     }, ['target', 'selector', 'files'], RW),
 
   // == DATA ==
@@ -445,7 +462,13 @@ const TOOLS = [
 function toolToCmd(name, p) {
   switch (name) {
     // Inspect
-    case 'chromex_snapshot':   return { cmd: 'snap', args: p.refs ? ['--refs'] : [] };
+    case 'chromex_snapshot': {
+      const a = [];
+      if (p.refs) a.push('--refs');
+      if (p.full) a.push('--full');
+      if (p.depth) a.push(`--depth=${p.depth}`);
+      return { cmd: 'snap', args: a };
+    }
     case 'chromex_html':       return { cmd: 'html', args: p.selector ? [p.selector] : [] };
     case 'chromex_screenshot': {
       const a = [];
@@ -623,6 +646,8 @@ async function executeTool(name, params) {
   const mapped = toolToCmd(name, params);
   if (!mapped) return fail(`Unknown tool: ${name}`);
 
+  if (params.noSnap) mapped.args.push('--no-snap');
+
   const conn = await getOrStartTabDaemon(targetId, config);
   const response = await sendCommand(conn, { cmd: mapped.cmd, args: mapped.args });