chromex-mcp 1.1.0 → 1.3.0

package/README.md

@@ -1,50 +1,87 @@
 # Chromex
 
-Zero-dependency Chrome DevTools Protocol CLI for AI agents. Connects directly to Chrome, Brave, Edge, or Chromium via WebSocket. No Puppeteer, no npm install, no bloat.
-
-Built as a [Claude Code](https://claude.ai/code) plugin but works standalone with any AI agent or from the terminal.
+Zero-dependency Chrome DevTools Protocol toolkit for AI agents. 52 typed MCP tools + CLI. Connects directly to Chrome, Brave, Edge, or Chromium via WebSocket. No Puppeteer, no bloat.
 
 ## Features
 
-- **45+ commands** -- screenshots, form filling, cookies, PDF, device emulation, network interception, performance tracing, touch gestures, and more
+- **52 MCP tools** -- typed JSON Schema, annotations (`readOnlyHint`, `destructiveHint`), inline screenshots (base64)
 - **Zero dependencies** -- uses only Node.js 22+ built-in modules (WebSocket, fs, net, crypto)
 - **Ref-based selection** -- `snap --refs` assigns `@e1`, `@e2`... to interactive elements, then `click @e5` or `fill @e3 "value"`. No fragile CSS selectors
+- **Incremental snapshots** -- second snapshot returns only changed nodes (diff), reducing output from thousands of lines to just what changed
+- **Auto-snapshot** -- interactive commands (click, fill, nav, etc.) automatically append an incremental snapshot with refs, so the agent sees the page state in a single round-trip
+- **Scroll detection** -- snapshots report scrollable containers with remaining distance (`[scroll: page: down:1200px | sidebar: up:300px]`)
 - **Per-tab persistent daemons** -- each tab gets a background process connected via Unix socket. Chrome's "Allow debugging" modal fires once, not on every command
 - **Security hardened** -- domain filtering (allow/blocklist), CDP method blocklist, token-authenticated sockets, full audit log
 - **Multi-browser** -- auto-detects Brave, Chrome, Chrome Canary, Chromium, Edge, Vivaldi (macOS + Linux)
 - **Network control** -- throttle to 3G/offline, intercept & mock requests, record HAR files
 - **Form filling** -- fill inputs, select dropdowns, toggle checkboxes, upload files, batch fill entire forms. Works with React/Vue/Angular
 - **Browser launcher** -- launch browser with remote debugging pre-enabled (skips the "Allow debugging" modal entirely)
+- **CLI included** -- same commands available from the terminal for scripts and CI/CD
 
 ## Requirements
 
 - Node.js 22+ (for built-in WebSocket)
 - Any Chromium-based browser
 
-## Quick Start
-
-### As a Claude Code plugin
+## Installation
 
 ```bash
-# Add the marketplace
-/plugin marketplace add github:whallysson/chromex
+# Add to Claude Code (global -- all projects)
+claude mcp add chromex -s user npx chromex-mcp@latest
 
-# Install
-/plugin install chromex
+# Or project-only
+claude mcp add chromex npx chromex-mcp@latest
 ```
 
-### Standalone
+### Auto-Approve (recommended)
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": ["mcp__chromex"]
+  }
+}
+```
+
+This approves all 52 MCP tools at once. For granular control, approve individual tools:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__chromex__chromex_list",
+      "mcp__chromex__chromex_snapshot",
+      "mcp__chromex__chromex_screenshot",
+      "mcp__chromex__chromex_perf"
+    ]
+  }
+}
+```
+
+### Global install (optional)
 
 ```bash
-git clone https://github.com/whallysson/chromex.git
-cd chromex
-chmod +x skills/chromex/scripts/chromex.mjs
+npm install -g chromex-mcp
+```
+
+This installs three binaries:
+
+| Binary | Purpose |
+|--------|---------|
+| `chromex` | CLI -- the main command for terminal usage |
+| `chromex-cli` | Alias for `chromex` |
+| `chromex-mcp` | MCP server (stdio JSON-RPC) -- used by `claude mcp add`, not run directly |
 
-# Optional: create an alias
-alias chromex="node $(pwd)/skills/chromex/scripts/chromex.mjs"
+```bash
+chromex list                          # List open tabs
+chromex launch --url https://example.com  # Launch browser
+chromex snap 6BE8 --refs              # Snapshot with refs
+chromex click 6BE8 @e3               # Click by ref
 ```
 
-### Connect to your browser
+## Connect to Your Browser
 
 **Option A: Launch a new browser** (recommended -- no setup needed)
 
@@ -56,8 +93,6 @@ This starts Chrome/Brave/Edge with remote debugging pre-enabled. No manual confi
 
 **Option B: Connect to an already-running browser**
 
-You **must** enable remote debugging first:
-
 1. Open your browser (Chrome, Brave, Edge, etc.)
 2. Navigate to `chrome://inspect/#remote-debugging`
 3. **Toggle the switch ON** to enable remote debugging
@@ -67,11 +102,7 @@ You **must** enable remote debugging first:
 
 > **Note:** With Option B, Chrome will show an "Allow debugging" dialog the first time you access each tab. Click "Allow" once per tab -- the daemon keeps the session alive after that.
 
-```bash
-chromex list
-```
-
-### Your first commands
+## Quick Start
 
 ```bash
 # List open tabs
@@ -118,8 +149,10 @@ chromex stop                                        # Stop all daemons
 ### Inspect
 
 ```bash
-chromex snap    <target>                    # Accessibility tree (prefer over html)
+chromex snap    <target>                    # Accessibility tree snapshot (compact)
 chromex snap    <target> --refs             # With interactive refs (@e1, @e2...)
+chromex snap    <target> --depth=3          # Limit tree depth
+chromex snap    <target> --full             # Force full snapshot (skip diff)
 chromex html    <target> "#main"            # Element HTML by selector
 chromex shot    <target> /tmp/page.png      # Viewport screenshot
 chromex shot    <target> /tmp/full.png --full  # Full page screenshot
@@ -151,8 +184,10 @@ chromex wait    <target> load                      # Wait for page load
 chromex wait    <target> domready                  # Wait for DOMContentLoaded
 chromex wait    <target> fcp                       # Wait for First Contentful Paint
 chromex scroll  <target> down 500                  # Scroll down 500px
-chromex scroll  <target> to "#footer"              # Scroll to element
+chromex scroll  <target> up 300                    # Scroll up 300px
 chromex scroll  <target> top                       # Scroll to top
+chromex scroll  <target> bottom                    # Scroll to bottom
+chromex scroll  <target> to "#footer"              # Scroll to element
 ```
 
 ### Interact
@@ -207,6 +242,7 @@ chromex pdf     <target> /tmp/page.pdf              # Export as PDF
 ```bash
 chromex throttle <target> 3g                       # Throttle to 3G
 chromex throttle <target> slow-3g                  # Throttle to slow 3G
+chromex throttle <target> 4g                       # Throttle to 4G
 chromex throttle <target> offline                  # Go offline
 chromex throttle <target> custom 200 1000 500      # Custom: latency, down, up (kbps)
 chromex throttle <target> reset                    # Remove throttling
@@ -224,8 +260,12 @@ chromex har <target> stop /tmp/trace.har           # Save HAR file
 
 ```bash
 chromex emulate  <target> iphone-14                # 390x844 @3x mobile
+chromex emulate  <target> iphone-15-pro            # 393x852 @3x mobile
 chromex emulate  <target> ipad-pro                 # 1024x1366 @2x tablet
 chromex emulate  <target> pixel-7                  # 412x915 @2.625x mobile
+chromex emulate  <target> galaxy-s23               # 360x780 @3x mobile
+chromex emulate  <target> macbook-air              # 1440x900 @2x laptop
+chromex emulate  <target> desktop-1080p            # 1920x1080 @1x
 chromex emulate  <target> desktop-4k               # 3840x2160 @1x
 chromex emulate  <target> reset                    # Reset to default
 chromex geo      <target> -23.55 -46.63            # Set geolocation (Sao Paulo)
@@ -236,8 +276,6 @@ chromex cpu      <target> 4                        # CPU 4x slower
 chromex cpu      <target> reset                    # Reset CPU speed
 ```
 
-Available devices: `iphone-14`, `iphone-15-pro`, `ipad-pro`, `pixel-7`, `galaxy-s23`, `macbook-air`, `desktop-1080p`, `desktop-4k`.
-
 ### Advanced
 
 ```bash
@@ -278,73 +316,127 @@ chromex click <target> @e3
 chromex click <target> @e4
 ```
 
-Refs are assigned to all interactive elements (buttons, links, inputs, checkboxes, radios, dropdowns, tabs, switches). They persist until the next `snap --refs` call.
+Refs are assigned to all interactive elements (buttons, links, inputs, checkboxes, radios, dropdowns, tabs, switches, sliders, search boxes). They persist until the next `snap --refs` call.
 
 Supported ref commands: `click @eN`, `fill @eN "value"`, `hover @eN`.
 
-## MCP Server (Recommended for Claude Code)
+## Snapshot Optimizations
+
+Chromex snapshots are designed to minimize token usage for AI agents.
 
-Chromex also ships as an MCP server -- typed tools, auto-approve with one line, no Bash globs.
+### Incremental Diff
 
-### Setup
+The first snapshot returns the full accessibility tree. Subsequent snapshots return only nodes that changed:
+
+```
+[incremental: 2 changed, 45 unchanged]
+  *[textbox] Email = "user@example.com"
+  *[button] Submit
+```
+
+- Changed/new nodes are marked with `*`
+- Unchanged subtrees are collapsed entirely
+- Use `--full` to force a full snapshot (skips diff)
+- Navigation (`nav`) resets the diff baseline automatically
+
+### Depth Limiting
+
+Limit tree depth for large pages:
 
 ```bash
-# Global (all projects)
-claude mcp add chromex -s user npx chromex-mcp@latest
+chromex snap <target> --depth=3    # Only 3 levels deep
+```
 
-# Or project-only
-claude mcp add chromex npx chromex-mcp@latest
+Nodes at the depth limit render as leaves (children are not expanded).
+
+### Scroll Detection
+
+Snapshots automatically detect scrollable containers and report remaining scroll distance:
+
+```
+[scroll: page: down:1200px | sidebar: up:300px, down:800px]
 ```
 
-### Auto-Approve
+### Visibility Filtering
 
-Add to `~/.claude/settings.json`:
+- Ignored/hidden accessibility nodes are automatically omitted
+- Disabled interactive elements are shown but not assigned refs (can't be interacted with)
+- Generic wrapper nodes (`div`, `span` with no semantic role) are collapsed -- their children inherit the parent's depth
+- Names longer than 200 characters are truncated with `...`
 
-```json
-{
-  "permissions": {
-    "allow": ["mcp__chromex"]
-  }
-}
+## Auto-Snapshot
+
+Interactive commands automatically append an incremental snapshot with refs after execution. This lets the AI agent see the updated page state without a separate `snap` call:
+
+```bash
+chromex click <target> @e3
+# Output:
+#   Clicked @e3 [button] "Submit"
+#
+#   [incremental: 5 changed, 40 unchanged]
+#   @e1 [heading] Thank you!
+#   @e2 [link] Back to home
+#   ...
 ```
 
-This approves all 52 MCP tools at once. For granular control, approve individual tools:
+Commands that trigger auto-snapshot: `click`, `clickxy`, `type`, `fill`, `clear`, `select`, `check`, `form`, `nav`, `dialog`, `loadall`, `drag`, `touch`, `upload`.
 
-```json
-{
-  "permissions": {
-    "allow": [
-      "mcp__chromex__chromex_list",
-      "mcp__chromex__chromex_snapshot",
-      "mcp__chromex__chromex_screenshot",
-      "mcp__chromex__chromex_perf"
-    ]
-  }
-}
+Suppress with `--no-snap` for scripts doing rapid sequential actions:
+
+```bash
+chromex fill <target> @e1 "user@test.com" --no-snap
+chromex fill <target> @e2 "secret123" --no-snap
+chromex click <target> @e3    # Only this one triggers snapshot
 ```
 
-### Why MCP over CLI?
+## MCP vs CLI
 
-| | CLI (Bash) | MCP Server |
+Both interfaces call the same core, same daemons, same commands. The difference is how they integrate with Claude Code.
+
+| | CLI (`chromex-cli`) | MCP Server (`chromex-mcp`) |
 |---|---|---|
-| Auto-approve | Fragile glob pattern | `"mcp__chromex"` -- one line |
+| Token overhead | Zero schema cost | ~500 tokens per tool used (deferred loading) |
+| Auto-approve | Glob pattern in settings | `"mcp__chromex"` -- one line |
 | Permissions | All-or-nothing | Per-tool granularity |
 | Parameters | Positional string args | Typed JSON Schema |
-| Annotations | None | `readOnlyHint`, `destructiveHint` |
-| Token cost | ~60-80 overhead/call | ~15-25 overhead/call |
-| Screenshots | Returns file path | Returns inline image (base64) |
+| Screenshots | File path (needs `Read` to view) | Inline image (base64, no extra call) |
+| Best for | Terminal, scripts, CI/CD, token-sensitive sessions | Plug-and-play automation, users who want zero-config |
+
+### Switching Between MCP and CLI
 
-The CLI still works and is useful for terminal, scripts, and CI/CD. The MCP server is the recommended interface for Claude Code.
+You can enable and disable the MCP server at any time. The CLI always works regardless.
 
-### npm
+**Disable MCP** (saves ~3-5k tokens per session):
 
 ```bash
-npm install -g chromex-mcp    # Global install
-chromex-mcp                    # Run MCP server
-chromex-cli list               # CLI also available
+claude mcp remove chromex
 ```
 
-## Auto-Approve for CLI (Alternative)
+The CLI (`chromex-cli`) continues working normally -- same commands, same daemons, no change.
+
+**Re-enable MCP:**
+
+```bash
+# Global (all projects)
+claude mcp add chromex -s user npx chromex-mcp@latest
+
+# Project-only
+claude mcp add chromex npx chromex-mcp@latest
+```
+
+**When to disable MCP:**
+- Token-sensitive sessions where every token counts
+- You only need occasional commands (`list`, `snap`, `shot`)
+- You're already comfortable with the CLI syntax
+- You're using chromex from terminal/scripts, not from Claude Code
+
+**When to keep MCP enabled:**
+- Automating multi-step browser workflows (snap -> click -> fill -> snap)
+- You want per-tool auto-approve without glob patterns
+- You want inline screenshots without a separate `Read` call
+- First time using chromex (discovery via tool schema)
+
+### CLI Auto-Approve
 
 If you prefer the CLI interface, add this to `~/.claude/settings.json`:
 
@@ -352,14 +444,12 @@ If you prefer the CLI interface, add this to `~/.claude/settings.json`:
 {
   "permissions": {
     "allow": [
-      "Bash(node *chromex/scripts/chromex.mjs *)"
+      "Bash(chromex-cli *)"
     ]
   }
 }
 ```
 
-> **Warning:** This approves all chromex commands without distinction. The security config (`~/.chromex/config.json`) still applies -- domain filtering, CDP blocklist, and audit log remain active.
-
 ## Security
 
 Config at `~/.chromex/config.json` (auto-created on first run):
@@ -376,11 +466,26 @@ Config at `~/.chromex/config.json` (auto-created on first run):
 
 - **Domain filtering**: block sensitive sites or restrict to a whitelist
 - **CDP blocklist**: dangerous methods blocked by default in `evalraw`
-- **Socket auth**: 32-byte random token per session
+- **Socket auth**: 32-byte random token per session (mode 0600)
 - **Audit log**: every command logged with timestamp and status
 
 See [docs/security.md](docs/security.md) for full details.
 
+## How It Works
+
+1. **Browser detection** -- scans ~30 paths for `DevToolsActivePort` (or use `CDP_PORT_FILE` env var)
+2. **Daemon spawn** -- first command to a tab spawns a background Node.js process connected via CDP WebSocket
+3. **Session persistence** -- daemon holds the session open; Chrome's "Allow" modal fires once per daemon
+4. **Unix sockets** -- CLI/MCP communicates with daemon via authenticated Unix sockets
+5. **Auto-exit** -- daemons shut down after 20 minutes of inactivity (configurable)
+
+```
+CLI Client ──Unix Socket + Auth──> Per-Tab Daemon ──CDP WebSocket──> Chrome
+MCP Server ──Unix Socket + Auth──>     (same)     ──CDP WebSocket──> Chrome
+```
+
+See [docs/architecture.md](docs/architecture.md) for the full deep dive.
+
 ## Documentation
 
 | Guide | Description |
@@ -396,16 +501,6 @@ See [docs/security.md](docs/security.md) for full details.
 | [Advanced](docs/advanced.md) | Script injection, code coverage, tracing, heap snapshots, WebAuthn |
 | [Architecture](docs/architecture.md) | How it works: daemon model, connection modes, file layout |
 
-## How It Works
-
-1. **Browser detection** -- scans ~30 paths for `DevToolsActivePort` (or use `CDP_PORT_FILE` env var)
-2. **Daemon spawn** -- first command to a tab spawns a background Node.js process connected via CDP WebSocket
-3. **Session persistence** -- daemon holds the session open; Chrome's "Allow" modal fires once per daemon
-4. **Unix sockets** -- CLI communicates with daemon via authenticated Unix sockets
-5. **Auto-exit** -- daemons shut down after 20 minutes of inactivity (configurable)
-
-See [docs/architecture.md](docs/architecture.md) for the full deep dive.
-
 ## License
 
 MIT

package/bin/chromex.mjs

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

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "chromex-mcp",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Zero-dependency Chrome DevTools Protocol MCP server for AI agents. 52 typed tools, per-tab daemons, security hardened.",
   "type": "module",
   "bin": {
+    "chromex": "./bin/chromex.mjs",
     "chromex-mcp": "./bin/chromex-mcp.mjs",
     "chromex-cli": "./bin/chromex-cli.mjs"
   },

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

@@ -38,7 +38,7 @@ function truncate(str, max = MAX_NAME_LENGTH) {
   return str.slice(0, max) + '...';
 }
 
-function formatAxNode(node, depth, refIndex, refs) {
+function formatAxNode(node, depth, refIndex, refs, isNew = false) {
   const role = node.role?.value || '';
   const name = truncate(node.name?.value ?? '');
   const value = node.value?.value;
@@ -50,7 +50,8 @@ function formatAxNode(node, depth, refIndex, refs) {
     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(truncate(String(value)))}`;
   return line;
@@ -91,6 +92,54 @@ function buildFingerprints(nodes, nodesById, childrenByParent, compact) {
   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.
 // previousFingerprints: Map from prior snapshot for incremental diff.
@@ -108,6 +157,7 @@ export async function snapshotStr(cdp, sid, compact = true, refs = false, previo
 
   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();
@@ -157,8 +207,9 @@ export async function snapshotStr(cdp, sid, compact = true, refs = false, previo
 
     const role = node.role?.value || '';
     const currentRef = refIndex.value;
+    const isNew = isDiff && !previousFingerprints.has(node.nodeId);
 
-    lines.push(formatAxNode(node, depth, refIndex, refs));
+    lines.push(formatAxNode(node, depth, refIndex, refs, isNew));
 
     if (refs && refIndex.value > currentRef) {
       refMap.set(currentRef, {
@@ -214,6 +265,10 @@ export async function snapshotStr(cdp, sid, compact = true, refs = false, previo
     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, 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;
@@ -114,10 +123,18 @@ export async function runDaemon(targetId, config) {
     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') {
@@ -127,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);
@@ -172,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);
@@ -322,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) ----
 
@@ -167,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',
@@ -199,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',
@@ -228,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 ==
@@ -631,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 });