chromex-mcp 1.4.0 → 1.5.0

package/README.md

@@ -2,13 +2,18 @@
 
 Zero-dependency Chrome DevTools Protocol toolkit for AI agents. 56 typed MCP tools + CLI. Connects directly to Chrome, Brave, Edge, or Chromium via WebSocket. No Puppeteer, no bloat.
 
+Designed from the ground up for token efficiency: incremental diffs, query-filtered snapshots, ref-based selection, and a plain-text output format that consistently beats JSON and YAML-style structured alternatives by 25% to 126% in head-to-head token measurements (see [Token Efficiency](#token-efficiency) below).
+
 ## Features
 
 - **56 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
+- **Query-filtered snapshots** -- `snap --query=login` returns only matching nodes and their ancestors, cutting output by 95% to 99% on large pages like GitHub, Jira, or Gmail
 - **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
+- **Contextual hints** -- after each action, chromex appends up to 3 `help[]` next-step suggestions picked from the current ref map, eliminating the "what do I do next" turn. Opt-out with `--no-hints`
+- **Pre-computed aggregates** -- `net` and `console` outputs embed counters (`network[47] errors:3 pending:0 ok:44`, `console[12] errors:2 warnings:4 info:6`) so the agent never needs a follow-up count
 - **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
@@ -157,6 +162,7 @@ chromex snap    <target>                    # Accessibility tree snapshot (compa
 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 snap    <target> --query=login      # Filter to matching nodes + ancestors (hierarchy preserved)
 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
@@ -381,6 +387,30 @@ chromex snap <target> --depth=3    # Only 3 levels deep
 
 Nodes at the depth limit render as leaves (children are not expanded).
 
+### Query Filter
+
+On large pages, a full accessibility tree can be tens of kilobytes. Use `--query` to keep only the nodes you care about, with their ancestors preserved so the hierarchy stays intact:
+
+```bash
+chromex snap <target> --query=login     # Substring match (case-insensitive)
+chromex snap <target> --query=issues    # role/name/value all searched
+```
+
+Matched nodes are prefixed with `>` in the output, so the agent can spot them at a glance. Ancestor chains are included from the match up to the root, so the agent still understands the surrounding structure.
+
+`@eN` refs stay stable across filtered and unfiltered calls because the ref map is always computed against the full tree. A filtered `snap --query=login` followed by a plain `snap --refs` returns the same ref numbering. Fingerprints for incremental diff are also computed on the full tree, so the next non-query snapshot still produces a correct diff against the previous state.
+
+Measured reduction on a real 65 KB GitHub repo page snapshot:
+
+| Query | Output bytes | Reduction |
+|-------|-------------:|----------:|
+| `snap --full` (baseline) | 65,455 | -- |
+| `snap --query=issues` | 317 | **-99.5%** |
+| `snap --query=star` | 1,490 | **-97.7%** |
+| `snap --query=readme` | 936 | **-98.6%** |
+
+When no node matches, chromex returns the explicit empty state `snap: no matches for query "X"` so the agent never confuses an empty filter with a silent failure.
+
 ### Scroll Detection
 
 Snapshots automatically detect scrollable containers and report remaining scroll distance:
@@ -421,6 +451,95 @@ chromex fill <target> @e2 "secret123" --no-snap
 chromex click <target> @e3    # Only this one triggers snapshot
 ```
 
+## Contextual Hints
+
+After any action that produces a fresh ref map (auto-snap on interactive commands, or an explicit `snap --refs`), chromex appends a `help[N]:` block with up to 3 next-step suggestions picked heuristically from the current elements and the last command:
+
+```
+Navigated to https://github.com/login
+
+RootWebArea "Sign in to GitHub"
+  @e1 [textbox] Username or email address
+  @e2 [textbox] Password
+  @e3 [button] Sign in
+  @e4 [link] Forgot password?
+
+help[3]:
+  chromex fill <t> @e1 "<value>"  # textbox "Username or email address"
+  chromex click <t> @e3           # button "Sign in"
+  chromex click <t> @e4           # link "Forgot password?"
+```
+
+The agent gets the most probable next commands inline, eliminating the "decide what to click" turn. Heuristic rules:
+
+- **After `fill`** -- priority is a matching submit button (label matches `login`, `submit`, `send`, `search`, `go`, `continue`, ...) or `key Enter` fallback, then the next unfilled input.
+- **After `nav`** -- first input (highest priority), then first submit button, then first link.
+- **After `snap --refs`** (or any default) -- top interactive elements with non-empty names.
+- **Maximum 3 hints per response.**
+
+### Staleness Guard
+
+Hints are only emitted when chromex can guarantee the ref map matches the DOM that was just rendered. This prevents the agent from clicking `@eN` coordinates that no longer exist on screen:
+
+| Command | Hints? | Why |
+|---------|--------|-----|
+| `click`, `fill`, `nav`, `type`, ... (default) | Yes | auto-snap just ran with refs |
+| `click @e1 --no-snap`, `fill ... --no-snap` | **No** | ref map may be stale |
+| `snap --refs` | Yes | ref map populated by this call |
+| `snap --refs` on a page with zero interactive elements | **No** | nothing to suggest, avoids a `snap --refs` loop |
+| Bare `snap` (no `--refs`) | **No** | ref map was not refreshed |
+
+Navigation (URL, back, forward, reload) always clears the ref map before dispatching, so post-nav hints always reflect the new page.
+
+Opt out explicitly with `--no-hints` (CLI) or `noHints: true` (MCP) for scripts that parse output strictly.
+
+## Token Efficiency
+
+Chromex outputs are designed to be read by LLM agents, not humans. Every format decision -- plain text, refs over CSS selectors, incremental diffs, query filters -- was made to minimize tokens while preserving the information the agent actually needs to act.
+
+### Measured against common alternatives
+
+We measured the current plain-text output against three structured format candidates often proposed for agent interfaces: minified JSON, pretty-printed JSON, and a TOON-style compact encoder (a zero-dependency 60-line implementation of the YAML-inline compact style). Five representative chromex outputs were encoded in each format and tokenized with `tiktoken` (`cl100k_base`). Lower token counts are better.
+
+#### Case by case
+
+| Case                           | text-free  | json-min       | json-pretty     | toon-compact    |
+|--------------------------------|-----------:|---------------:|----------------:|----------------:|
+| `snap-login-small`             |    **130** |    178 (+37%)  |     301 (+132%) |      212 (+63%) |
+| `snap-repo-large` (65 KB real) | **19,702** | 34,315 (+74%)  |  63,232 (+221%) |  44,613 (+126%) |
+| `net-list-50`                  |    **454** |    574 (+26%)  |     921 (+103%) |      706 (+56%) |
+| `console-list-12`              |    **273** |    363 (+33%)  |     576 (+111%) |      453 (+66%) |
+| `fill-action-small`            |     **99** |    127 (+28%)  |     221 (+123%) |      146 (+48%) |
+
+The five cases cover the most common outputs an agent sees during a real session: a small accessibility snapshot with refs (a login form), a large accessibility snapshot of a real GitHub repository page, a network list with 50 tracked requests, a console list with a mix of `log`, `warn` and `error` entries, and a post-action result (fill + incremental diff + hints).
+
+#### Aggregate (5 cases combined)
+
+| Format                 |    tokens | vs text-free |
+|------------------------|----------:|-------------:|
+| **text-free (current)**| **20,658**|        --    |
+| json-min               |    35,557 |       +72.1% |
+| json-pretty            |    65,251 |      +215.9% |
+| toon-compact (custom)  |    46,130 |      +123.3% |
+
+The current plain-text output is the most token-efficient in every single case. Every structured alternative costs more tokens, not less, because JSON and YAML-style encodings add syntactic overhead (`{`, `}`, `"`, `:`, `,`, indentation) that the chromex plain-text format omits entirely. The chromex format is already dense: short refs (`@e5`), unquoted labels, no wrapping, no redundancy. Structured formats have nothing to optimize away.
+
+### Why this matters
+
+- **No structured-output refactor is planned.** Chromex keeps the current plain-text format because the data shows it wins.
+- **`@eN` refs beat CSS selectors** not just for reliability (accessibility tree is stable across SPA re-renders) but also for token count -- `@e5` is one token, `document.querySelector('#login-form > div.field input[name="email"]')` is around fifteen.
+- **`--query` and incremental diff** are where the real token savings live. A filtered snapshot on a large page drops output by 95% to 99%, and an incremental diff after an action drops it by 90% or more. These are multiplicative with the already-dense base format.
+
+### Reproducing the benchmark
+
+The comparison script is checked into the repo and runs standalone:
+
+```bash
+node tests/benchmarks/token-format-comparison.mjs
+```
+
+It uses `js-tiktoken` (devDependency) with `cl100k_base`, the GPT-4 tokenizer. Claude uses its own BPE tokenizer with a different vocabulary, so absolute numbers would shift by a few percent -- but both are byte-pair encoders over similar corpora, and the direction of the comparison (which format wins) is consistent across BPE tokenizers. Nothing in the results is a rounding error: the gaps are 25% to 220%.
+
 ## MCP vs CLI
 
 Both interfaces call the same core, same daemons, same commands. The difference is how they integrate with Claude Code.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "chromex-mcp",
-  "version": "1.4.0",
-  "description": "Zero-dependency Chrome DevTools Protocol MCP server for AI agents. 56 typed tools, per-tab daemons, security hardened.",
+  "version": "1.5.0",
+  "description": "Zero-dependency Chrome DevTools Protocol MCP server for AI agents. 56 typed tools, per-tab daemons, security hardened, contextual hints, query-filtered snapshots.",
   "type": "module",
   "bin": {
-    "chromex": "./bin/chromex.mjs",
-    "chromex-mcp": "./bin/chromex-mcp.mjs",
-    "chromex-cli": "./bin/chromex-cli.mjs"
+    "chromex": "bin/chromex.mjs",
+    "chromex-mcp": "bin/chromex-mcp.mjs",
+    "chromex-cli": "bin/chromex-cli.mjs"
   },
   "files": [
     "bin/",
@@ -40,13 +40,14 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/whallysson/chromex"
+    "url": "git+https://github.com/whallysson/chromex.git"
   },
   "homepage": "https://github.com/whallysson/chromex#mcp-server-recommended-for-claude-code",
   "engines": {
     "node": ">=22.0.0"
   },
   "devDependencies": {
+    "js-tiktoken": "^1.0.21",
     "vitest": "^3.0.0"
   }
 }

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

@@ -51,7 +51,11 @@ Usage: chromex <command> [args]
     incognito [url]                     Create isolated browser context (no relaunch)
 
   INSPECT
-    snap    <target>                    Accessibility tree snapshot (compact)
+    snap    <target> [options]          Accessibility tree snapshot (compact)
+      --refs                            Assign @eN refs to interactive elements
+      --full                            Force full snapshot (skip incremental diff)
+      --depth=N                         Limit tree depth (nodes at limit render as leaves)
+      --query=TEXT                      Filter to nodes matching substring + ancestors
     html    <target> [selector]         Get HTML (full page or CSS selector)
     shot    <target> [file] [options]   Screenshot (viewport, full page, or element)
       --full                            Full page capture
@@ -132,6 +136,10 @@ Usage: chromex <command> [args]
 
 <target> is a unique targetId prefix from "chromex list". Ambiguous prefixes are rejected.
 
+OUTPUT FLAGS
+  --no-snap   Skip auto-snapshot after interactive commands
+  --no-hints  Suppress contextual help[] suggestions
+
 SECURITY
   Config: ~/.chromex/config.json
   - blockedDomains / allowedDomains: domain filtering
@@ -265,7 +273,8 @@ async function main() {
   const conn = await getOrStartTabDaemon(targetId, config);
 
   const noSnap = args.includes('--no-snap');
-  const cmdArgs = args.slice(1).filter(a => a !== '--no-snap');
+  const noHints = args.includes('--no-hints');
+  const cmdArgs = args.slice(1).filter(a => a !== '--no-snap' && a !== '--no-hints');
 
   // Juntar argumentos para comandos que aceitam texto livre
   if (cmd === 'eval') {
@@ -300,6 +309,7 @@ async function main() {
   }
 
   if (noSnap) cmdArgs.push('--no-snap');
+  if (noHints) cmdArgs.push('--no-hints');
   const response = await sendCommand(conn, { cmd, args: cmdArgs });
 
   if (response.ok) {

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

@@ -1,6 +1,26 @@
 // Console: live capture, stored message list, and detail with stack traces
 
 import { sleep } from '../utils.mjs';
+import { emptyState, aggregate } from '../output.mjs';
+
+// Pre-computed aggregates for a list of console entries.
+// Returns { errors, warnings, info } counts; zero keys omitted by callers.
+function bucketConsoleByType(entries) {
+  let errors = 0;
+  let warnings = 0;
+  let info = 0;
+  for (const e of entries) {
+    const type = e.type;
+    if (type === 'error') errors++;
+    else if (type === 'warning' || type === 'warn') warnings++;
+    else info++;
+  }
+  const meta = {};
+  if (errors) meta.errors = errors;
+  if (warnings) meta.warnings = warnings;
+  if (info) meta.info = info;
+  return meta;
+}
 
 export async function consoleStr(cdp, sid, durationMs = 5000) {
   const duration = parseInt(durationMs) || 5000;
@@ -28,22 +48,30 @@ export async function consoleStr(cdp, sid, durationMs = 5000) {
   await sleep(duration);
   off();
 
-  if (entries.length === 0) return `No console output captured in ${duration}ms.`;
+  if (entries.length === 0) return emptyState('console', `0 messages captured in ${duration}ms`);
 
-  return entries.map(e => {
+  const header = aggregate('console', entries.length, bucketConsoleByType(entries));
+  const rows = entries.map(e => {
     const prefix = e.type === 'error' ? 'ERR' : e.type === 'warn' ? 'WRN' : e.type.toUpperCase().slice(0, 3);
     return `[${e.ts}] ${prefix.padEnd(3)}  ${e.msg.substring(0, 200)}`;
-  }).join('\n');
+  });
+  return `${header}\n${rows.join('\n')}`;
 }
 
 export function consoleListStr(consoleMessages) {
-  if (consoleMessages.length === 0) return 'No console messages captured since daemon started.';
+  if (consoleMessages.length === 0) return emptyState('console', '0 messages captured since daemon started');
+
+  const header = aggregate('console', consoleMessages.length, bucketConsoleByType(consoleMessages));
   const msgs = consoleMessages.slice(-50);
-  return msgs.map(e => {
+  const rows = msgs.map(e => {
     const ts = new Date(e.ts).toISOString().slice(11, 23);
     const prefix = e.type === 'error' ? 'ERR' : e.type === 'warn' ? 'WRN' : e.type.toUpperCase().slice(0, 3);
     return `[${e.id}] ${ts} ${prefix.padEnd(3)}  ${e.args.join(' ').substring(0, 200)}`;
-  }).join('\n');
+  });
+  const truncNote = consoleMessages.length > 50
+    ? `\n(showing last 50 of ${consoleMessages.length})`
+    : '';
+  return `${header}\n${rows.join('\n')}${truncNote}`;
 }
 
 export function consoleDetailStr(consoleMessages, msgId) {

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

@@ -1,6 +1,7 @@
 // Cookie management via CDP Network domain
 
 import { evalStr } from './evaluate.mjs';
+import { emptyState } from '../output.mjs';
 
 export async function cookiesStr(cdp, sid, action, arg) {
   switch (action) {
@@ -12,7 +13,7 @@ export async function cookiesStr(cdp, sid, action, arg) {
       const { cookies } = await cdp.send('Network.getCookies', { urls: [url] }, sid);
       await cdp.send('Network.disable', {}, sid);
 
-      if (cookies.length === 0) return 'No cookies found for this page.';
+      if (cookies.length === 0) return emptyState('cookies', '0 cookies for this page');
 
       return cookies.map(c => {
         const flags = [

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

@@ -1,27 +1,56 @@
 // Network: resource timing + CDP request detail
 
 import { evalStr } from './evaluate.mjs';
+import { emptyState, aggregate, formatBytes } from '../output.mjs';
 
 export async function netStr(cdp, sid) {
   const raw = await evalStr(cdp, sid, `JSON.stringify(performance.getEntriesByType('resource').map(e => ({
     name: e.name.substring(0, 120), type: e.initiatorType,
     duration: Math.round(e.duration), size: e.transferSize
   })))`);
-  return JSON.parse(raw).map(e =>
+  const resources = JSON.parse(raw);
+  if (resources.length === 0) return emptyState('network', '0 resources timed (page not loaded or resources cached)');
+
+  // Pre-computed aggregates: total transfer size so agent doesn't need a follow-up sum.
+  const totalSize = resources.reduce((s, e) => s + (e.size || 0), 0);
+  const header = aggregate('network', resources.length, { size: formatBytes(totalSize) });
+
+  const rows = resources.map(e =>
     `${String(e.duration).padStart(5)}ms  ${String(e.size || '?').padStart(8)}B  ${e.type.padEnd(8)}  ${e.name}`
-  ).join('\n');
+  );
+  return `${header}\n${rows.join('\n')}`;
 }
 
 export function netListStr(networkRequests) {
-  if (networkRequests.size === 0) return 'No network requests captured since daemon started.';
+  if (networkRequests.size === 0) return emptyState('network', '0 requests captured since daemon started');
+
+  // Pre-computed aggregates: breakdown by status class.
+  // Agents commonly ask "are there any errors?" -- embedding the count eliminates a round-trip.
+  let errors = 0;
+  let pending = 0;
+  let ok = 0;
+  for (const [, r] of networkRequests.entries()) {
+    if (r.status == null) pending++;
+    else if (r.status >= 400) errors++;
+    else ok++;
+  }
+  const meta = {};
+  if (errors) meta.errors = errors;
+  if (pending) meta.pending = pending;
+  if (ok) meta.ok = ok;
+  const header = aggregate('network', networkRequests.size, meta);
+
   const entries = [...networkRequests.entries()].slice(-50);
-  const header = `${'STATUS'.padStart(3)}  ${'METHOD'.padEnd(6)}  ${'ID'.padEnd(14)}  URL`;
+  const tableHeader = `${'STATUS'.padStart(3)}  ${'METHOD'.padEnd(6)}  ${'ID'.padEnd(14)}  URL`;
   const rows = entries.map(([id, r]) => {
     const status = r.status != null ? String(r.status).padStart(3) : '...';
     const method = (r.method || 'GET').padEnd(6);
     return `  ${status}  ${method}  ${id.substring(0, 14).padEnd(14)}  ${r.url?.substring(0, 100) || '?'}`;
   });
-  return `${header}\n${rows.join('\n')}\n\n${entries.length} requests. Use "net <target> <requestId>" for detail.`;
+  const truncNote = networkRequests.size > 50
+    ? `\n(showing last 50 of ${networkRequests.size})`
+    : '';
+  return `${header}\n${tableHeader}\n${rows.join('\n')}${truncNote}\n\nUse "net <target> <requestId>" for detail.`;
 }
 
 export async function netDetailStr(cdp, sid, requestId, networkRequests) {

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

@@ -1,6 +1,7 @@
 // Core Web Vitals + performance metrics
 
 import { evalStr } from './evaluate.mjs';
+import { emptyState } from '../output.mjs';
 
 export async function perfStr(cdp, sid) {
   // Métricas do CDP
@@ -53,6 +54,15 @@ export async function perfStr(cdp, sid) {
   const cdpMetrics = {};
   for (const m of metrics) cdpMetrics[m.name] = m.value;
 
+  // Empty state: no vitals, no nav timing, no resources -- page not loaded or blank
+  if (
+    v.lcp == null && v.fcp == null && v.ttfb == null &&
+    v.domInteractive == null && v.load == null &&
+    (!v.resources || v.resources === 0)
+  ) {
+    return emptyState('perf', 'no metrics available (page not loaded?)');
+  }
+
   const lines = ['## Core Web Vitals'];
 
   if (v.lcp != null) lines.push(`LCP:  ${v.lcp}ms  (${v.lcpElement})${v.lcp <= 2500 ? ' [GOOD]' : v.lcp <= 4000 ? ' [NEEDS IMPROVEMENT]' : ' [POOR]'}`);

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

@@ -1,5 +1,7 @@
 // Accessibility tree snapshot with incremental diff and interactive refs (@e1, @e2...)
 
+import { emptyState } from '../output.mjs';
+
 const INTERACTIVE_ROLES = new Set([
   'button', 'link', 'textbox', 'checkbox', 'radio', 'combobox',
   'menuitem', 'tab', 'switch', 'searchbox', 'slider', 'spinbutton',
@@ -38,25 +40,35 @@ function truncate(str, max = MAX_NAME_LENGTH) {
   return str.slice(0, max) + '...';
 }
 
-function formatAxNode(node, depth, refIndex, refs, isNew = false) {
+// Render a single AX node line. Ref assignment is done OUT of this function
+// (via the refMap pre-pass) so that query-filtered renders still produce
+// the same @eN numbering as unfiltered renders.
+function formatNodeLine(node, depth, refNum, isNew = false, isMatch = false) {
   const role = node.role?.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()) && isAxNodeInteractable(node)) {
-    refTag = `@e${refIndex.value} `;
-    refIndex.value++;
-  }
-
+  const refTag = refNum != null ? `@e${refNum} ` : '';
+  const matchTag = isMatch ? '> ' : '';
   const newTag = isNew ? '*' : '';
-  let line = `${indent}${newTag}${refTag}[${role}]`;
+  let line = `${indent}${matchTag}${newTag}${refTag}[${role}]`;
   if (name !== '') line += ` ${name}`;
   if (!(value === '' || value == null)) line += ` = ${JSON.stringify(truncate(String(value)))}`;
   return line;
 }
 
+// Case-insensitive substring match against role, name and value.
+function nodeMatchesQuery(node, query) {
+  if (!query) return false;
+  const q = query.toLowerCase();
+  const role = (node.role?.value || '').toLowerCase();
+  const name = (node.name?.value || '').toLowerCase();
+  const value = node.value?.value;
+  const valueStr = value == null ? '' : String(value).toLowerCase();
+  return role.includes(q) || name.includes(q) || valueStr.includes(q);
+}
+
 function orderedAxChildren(node, nodesById, childrenByParent) {
   const children = [];
   const seen = new Set();
@@ -144,8 +156,11 @@ async function detectScrollables(cdp, sid) {
 // The caller (daemon) stores this map for later ref resolution.
 // previousFingerprints: Map from prior snapshot for incremental diff.
 // maxDepth: limit tree depth (0 = unlimited). Nodes at the limit render as leaves.
+// query: when set, filter the rendered output to nodes matching (substring) the
+//        query plus their ancestors. Fingerprints and refMap are still computed
+//        against the full tree so incremental diff and @eN stability survive.
 // Returns { text, refMap, fingerprints } -- caller stores fingerprints for next diff.
-export async function snapshotStr(cdp, sid, compact = true, refs = false, previousFingerprints = null, maxDepth = 0) {
+export async function snapshotStr(cdp, sid, compact = true, refs = false, previousFingerprints = null, maxDepth = 0, query = null) {
   const { nodes } = await cdp.send('Accessibility.getFullAXTree', {}, sid);
   const nodesById = new Map(nodes.map(node => [node.nodeId, node]));
   const childrenByParent = new Map();
@@ -156,11 +171,73 @@ 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 isDiff = previousFingerprints !== null && previousFingerprints.size > 0 && !query;
   const scrollables = await detectScrollables(cdp, sid);
 
-  const refIndex = { value: 1 };
+  const roots = nodes.filter(node => !node.parentId || !nodesById.has(node.parentId));
+
+  // ---- Pre-pass: populate refMap on the FULL tree so @eN stays stable
+  // regardless of query filtering.
   const refMap = new Map();
+  const nodeIdToRef = new Map();
+  if (refs) {
+    let refCounter = 1;
+    const prepassSeen = new Set();
+    const prepass = (node) => {
+      if (!node || prepassSeen.has(node.nodeId)) return;
+      prepassSeen.add(node.nodeId);
+      if (shouldShowAxNode(node, compact)) {
+        const role = node.role?.value || '';
+        if (INTERACTIVE_ROLES.has(role.toLowerCase()) && isAxNodeInteractable(node)) {
+          refMap.set(refCounter, {
+            backendNodeId: node.backendDOMNodeId,
+            nodeId: node.nodeId,
+            role,
+            name: node.name?.value ?? '',
+          });
+          nodeIdToRef.set(node.nodeId, refCounter);
+          refCounter++;
+        }
+      }
+      for (const child of orderedAxChildren(node, nodesById, childrenByParent)) {
+        prepass(child);
+      }
+    };
+    for (const root of roots) prepass(root);
+    if (!maxDepth) {
+      for (const node of nodes) prepass(node);
+    }
+  }
+
+  // ---- Query filter: compute matchedIds + their ancestors (keepIds)
+  let matchedIds = null;
+  let keepIds = null;
+  if (query) {
+    matchedIds = new Set();
+    keepIds = new Set();
+    for (const node of nodes) {
+      if (!shouldShowAxNode(node, compact)) continue;
+      if (nodeMatchesQuery(node, query)) {
+        matchedIds.add(node.nodeId);
+        // Walk ancestors via parentId; include non-visible parents too so the
+        // visit() pass can reach the match by descending through them.
+        let pid = node.parentId;
+        while (pid && !keepIds.has(pid)) {
+          keepIds.add(pid);
+          pid = nodesById.get(pid)?.parentId;
+        }
+        keepIds.add(node.nodeId);
+      }
+    }
+    if (matchedIds.size === 0) {
+      return {
+        text: `snap: no matches for query "${query}"`,
+        refMap,
+        fingerprints: currentFingerprints,
+      };
+    }
+  }
+
   const lines = [];
   const visited = new Set();
 
@@ -173,7 +250,6 @@ export async function snapshotStr(cdp, sid, compact = true, refs = false, previo
     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;
@@ -186,6 +262,10 @@ export async function snapshotStr(cdp, sid, compact = true, refs = false, previo
     if (!node || visited.has(node.nodeId)) return;
     visited.add(node.nodeId);
 
+    // Query filter: if this node isn't on the keep path, skip the whole subtree.
+    // All nodes with matches have their ancestors in keepIds, so pruning here is safe.
+    if (query && !keepIds.has(node.nodeId)) return;
+
     const show = shouldShowAxNode(node, compact);
 
     if (!show) {
@@ -196,29 +276,18 @@ export async function snapshotStr(cdp, sid, compact = true, refs = false, previo
       return;
     }
 
-    // Incremental diff: if this subtree is unchanged, collapse it
+    // Incremental diff: if this subtree is unchanged, collapse it.
+    // Disabled when a query filter is active (user wants the matched content, not a diff).
     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);
+    const isMatch = !!(matchedIds && matchedIds.has(node.nodeId));
+    const refNum = refs ? nodeIdToRef.get(node.nodeId) ?? null : null;
 
-    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 ?? '',
-      });
-    }
+    lines.push(formatNodeLine(node, depth, refNum, isNew, isMatch));
 
     // Depth limiting: at the limit, render as leaf (no children)
     if (maxDepth > 0 && depth >= maxDepth) return;
@@ -228,30 +297,6 @@ export async function snapshotStr(cdp, sid, compact = true, refs = false, previo
     }
   }
 
-  // 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)) {
-      advanceRefsForSubtree(child);
-    }
-  }
-
-  const roots = nodes.filter(node => !node.parentId || !nodesById.has(node.parentId));
   for (const root of roots) visit(root, 0);
   // Second pass: catch disconnected nodes (skip when depth-limited to avoid false depth=0)
   if (!maxDepth) {
@@ -265,6 +310,10 @@ export async function snapshotStr(cdp, sid, compact = true, refs = false, previo
     const changedCount = totalVisible - unchangedCount;
     text = `[incremental: ${changedCount} changed, ${unchangedCount} unchanged]\n${text}`;
   }
+  // Empty state: no visible nodes and not an incremental diff -> page is blank/not ready
+  if (lines.length === 0 && !isDiff) {
+    text = emptyState('snap', 'empty accessibility tree');
+  }
   // Append scroll info footer when scrollable containers exist
   if (scrollables.length > 0) {
     text += `\n[scroll: ${scrollables.join(' | ')}]`;

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

@@ -2,6 +2,7 @@
 // Tracks command counts, timing, errors, and session timeline
 
 import { writeFileSync } from 'fs';
+import { emptyState } from '../output.mjs';
 
 export class SessionStats {
   constructor() {
@@ -26,13 +27,15 @@ export class SessionStats {
 }
 
 export function statsStr(stats, full = false, exportPath = null) {
-  if (!stats) return 'No stats available.';
+  if (!stats) return emptyState('stats', 'no stats available');
 
   const lines = [];
   const uptime = ((Date.now() - stats.startTime) / 1000).toFixed(0);
   const totalCmds = [...stats.commands.values()].reduce((s, e) => s + e.count, 0);
   const totalErrors = [...stats.commands.values()].reduce((s, e) => s + e.errors, 0);
 
+  if (totalCmds === 0) return emptyState('stats', `no commands executed yet (uptime: ${uptime}s)`);
+
   lines.push(`Session Stats (uptime: ${uptime}s, commands: ${totalCmds}, errors: ${totalErrors})`);
   lines.push('');
 

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

@@ -1,6 +1,7 @@
 // LocalStorage / SessionStorage management
 
 import { evalStr } from './evaluate.mjs';
+import { emptyState } from '../output.mjs';
 
 export async function storageStr(cdp, sid, action) {
   switch (action) {
@@ -12,7 +13,7 @@ export async function storageStr(cdp, sid, action) {
       `);
       const data = JSON.parse(raw);
       const keys = Object.keys(data);
-      if (keys.length === 0) return 'localStorage is empty.';
+      if (keys.length === 0) return emptyState('storage', 'localStorage is empty');
       return keys.map(k => {
         const v = data[k];
         const val = v && v.length > 80 ? v.slice(0, 80) + '...' : v;
@@ -28,7 +29,7 @@ export async function storageStr(cdp, sid, action) {
       `);
       const data = JSON.parse(raw);
       const keys = Object.keys(data);
-      if (keys.length === 0) return 'sessionStorage is empty.';
+      if (keys.length === 0) return emptyState('storage', 'sessionStorage is empty');
       return keys.map(k => {
         const v = data[k];
         const val = v && v.length > 80 ? v.slice(0, 80) + '...' : v;

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

@@ -49,6 +49,7 @@ import { parseRef, clickRefStr, hoverRefStr, fillRefStr } from './commands/refs.
 import { highlightStr } from './commands/highlight.mjs';
 import { auditStr } from './commands/audit.mjs';
 import { SessionStats, statsStr } from './commands/stats.mjs';
+import { generateHints, renderHints, isRefMapFresh } from './hints.mjs';
 import { sleep } from './utils.mjs';
 
 // Commands that modify visible DOM and should trigger automatic post-action snapshot.
@@ -121,6 +122,9 @@ export async function runDaemon(targetId, config) {
   // Per-tab state: ref map for @eN resolution + fingerprints for incremental diff
   let currentRefMap = new Map();
   let previousFingerprints = null;
+  // Track the last @eN that was filled so hints can prioritize the NEXT input
+  // in a multi-field form instead of re-suggesting the one we just touched.
+  let lastFilledRef = null;
   const sessionStats = new SessionStats();
 
   // Network request tracking (CDP Network domain) for detail drill-down
@@ -177,10 +181,11 @@ export async function runDaemon(targetId, config) {
     const startMs = Date.now();
     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).
+      // Strip --no-snap / --no-hints before dispatch so they don'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');
+      const noHints = args.includes('--no-hints');
+      if (noSnap || noHints) args = args.filter(a => a !== '--no-snap' && a !== '--no-hints');
 
       let result;
       let isRefCmd = false;
@@ -194,6 +199,7 @@ export async function runDaemon(targetId, config) {
           result = await clickRefStr(cdp, sessionId, currentRefMap, refNum, dbl);
         } else if (cmd === 'fill') {
           result = await fillRefStr(cdp, sessionId, currentRefMap, refNum, args.slice(1).join(' '));
+          lastFilledRef = refNum;
         } else if (cmd === 'hover') {
           result = await hoverRefStr(cdp, sessionId, currentRefMap, refNum);
         } else {
@@ -218,11 +224,17 @@ export async function runDaemon(targetId, config) {
           const forceFull = args.includes('--full');
           const depthArg = args.find(a => a.startsWith('--depth='));
           const maxDepth = depthArg ? parseInt(depthArg.split('=')[1]) || 0 : 0;
+          const queryArg = args.find(a => a.startsWith('--query='));
+          const query = queryArg ? queryArg.slice('--query='.length) : null;
           const prevFp = forceFull ? null : previousFingerprints;
-          const snapResult = await snapshotStr(cdp, sessionId, true, useRefs, prevFp, maxDepth);
+          const snapResult = await snapshotStr(cdp, sessionId, true, useRefs, prevFp, maxDepth, query);
           result = snapResult.text;
+          // Always track fingerprints on the full tree -- this survives query filtering
+          // because snapshotStr computes them before applying the filter.
           previousFingerprints = snapResult.fingerprints;
-          if (useRefs && snapResult.refMap.size > 0) {
+          // Replace the ref map even when it is empty: a fresh snapshot that found
+          // zero interactive refs must clear any stale @eN left from an older page.
+          if (useRefs) {
             currentRefMap = snapResult.refMap;
           }
           break;
@@ -253,12 +265,17 @@ export async function runDaemon(targetId, config) {
           result = await htmlStr(cdp, sessionId, args[0]);
           break;
         case 'nav': case 'navigate': {
-          const navAction = args[0]?.toLowerCase();
           result = await navStr(cdp, sessionId, args[0], config);
-          // Reset fingerprints for URL navigation and reload (new content)
-          if (navAction !== 'back' && navAction !== 'forward') {
-            previousFingerprints = null;
-          }
+          // Any navigation changes page identity and can restore DOM via
+          // BFCache/hydration. Reset the diff baseline unconditionally so the
+          // first post-navigation snapshot is always a trustworthy full view.
+          previousFingerprints = null;
+          // ANY navigation (including back/forward) invalidates the ref map:
+          // the @eN numbers were assigned against a specific DOM render,
+          // and even back/forward can restore the page with different hydration.
+          // Auto-snap (if not --no-snap) will repopulate the refMap immediately below.
+          currentRefMap = new Map();
+          lastFilledRef = null;
           break;
         }
         case 'net': case 'network':
@@ -469,13 +486,33 @@ export async function runDaemon(targetId, config) {
           await sleep(settleMs);
           const snapResult = await snapshotStr(cdp, sessionId, true, true, previousFingerprints);
           previousFingerprints = snapResult.fingerprints;
-          if (snapResult.refMap.size > 0) {
-            currentRefMap = snapResult.refMap;
-          }
+          // Same rule as explicit snap --refs: fresh empty ref maps must replace
+          // stale state, otherwise hints can suggest dead @eN from a prior screen.
+          currentRefMap = snapResult.refMap;
           result = (result ?? '') + '\n\n' + snapResult.text;
         } catch (e) { process.stderr.write(`[auto-snap] ${e.message}\n`); }
       }
 
+      // Contextual hints: append next-step suggestions to help the agent
+      // pick the next action without guessing. Opt-out via --no-hints.
+      // Only emit hints when the refMap is guaranteed FRESH for this command
+      // (either auto-snap ran, or the user explicitly asked for `snap --refs`).
+      // Without this guard, --no-snap or bare `snap` would emit hints pointing
+      // to @eN from a prior page -- stale and dangerous.
+      const shouldHint = !noHints && isRefMapFresh({ cmd, shouldSnap, noSnap, args });
+      if (shouldHint) {
+        try {
+          const hints = generateHints({
+            cmd,
+            refMap: currentRefMap,
+            lastFilledRef,
+            hasPage: true,
+          });
+          const hintsText = renderHints(hints);
+          if (hintsText) result = (result ?? '') + '\n\n' + hintsText;
+        } catch (e) { process.stderr.write(`[hints] ${e.message}\n`); }
+      }
+
       sessionStats.record(cmd, args, startMs, Date.now(), true, null);
       return { ok: true, result: result ?? '' };
     } catch (e) {

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

@@ -0,0 +1,203 @@
+// Contextual next-step hints generator.
+// Pure function, zero deps. Consumes refMap + last action context
+// and produces up to MAX_HINTS suggestions of "what to do next".
+//
+// Design notes:
+//   - Hints always use a <t> placeholder for target because the daemon
+//     does not know the CLI prefix the agent is using.
+//   - Heuristic is deliberately simple: bucket refs by role, then pick
+//     based on the last command. More sophisticated ranking can come
+//     later if measurement shows it matters.
+//   - After `fill`, a submit button is the most likely next step, so
+//     it gets priority. We fall back to "key Enter" when no submit is
+//     visible (common on search boxes).
+
+const SUBMIT_RX = /submit|login|log\s*in|sign\s*in|signin|send|search|go\b|continue|confirm|\bok\b|apply|save|create|next/i;
+
+export const MAX_HINTS = 3;
+
+const INPUT_ROLES = new Set(['textbox', 'searchbox', 'spinbutton', 'slider']);
+
+/**
+ * @typedef {Object} Hint
+ * @property {string} cmd     - CLI command with <t> placeholder
+ * @property {string} comment - Short human-readable context annotation
+ */
+
+/**
+ * Classify refMap entries by interaction type.
+ * Returns buckets preserving original ref order (stable across calls).
+ *
+ * @param {Map<number, {role: string, name: string}>} refMap
+ */
+function bucket(refMap) {
+  const submitButtons = [];
+  const buttons = [];
+  const inputs = [];
+  const selects = [];
+  const links = [];
+
+  for (const [num, ref] of refMap.entries()) {
+    const role = (ref.role || '').toLowerCase();
+    const name = ref.name || '';
+    const entry = { num, name, role };
+
+    if (role === 'button') {
+      if (SUBMIT_RX.test(name)) submitButtons.push(entry);
+      else buttons.push(entry);
+    } else if (INPUT_ROLES.has(role)) {
+      inputs.push(entry);
+    } else if (role === 'combobox') {
+      selects.push(entry);
+    } else if (role === 'link') {
+      links.push(entry);
+    }
+  }
+
+  return { submitButtons, buttons, inputs, selects, links };
+}
+
+function truncate(s, max = 40) {
+  if (!s) return '';
+  if (s.length <= max) return s;
+  return s.slice(0, max) + '...';
+}
+
+function commentFor(entry) {
+  if (!entry.name) return entry.role;
+  return `${entry.role} "${truncate(entry.name)}"`;
+}
+
+function clickHint(entry) {
+  return { cmd: `chromex click <t> @e${entry.num}`, comment: commentFor(entry) };
+}
+
+function fillHint(entry) {
+  return { cmd: `chromex fill <t> @e${entry.num} "<value>"`, comment: commentFor(entry) };
+}
+
+/**
+ * Generate up to MAX_HINTS next-step suggestions based on command context and refMap.
+ *
+ * @param {Object} ctx
+ * @param {string} ctx.cmd                 - Command just executed
+ * @param {Map<number, {role,name,backendNodeId}>} ctx.refMap
+ * @param {number|null} [ctx.lastFilledRef] - Ref number just filled (flow awareness)
+ * @param {boolean} [ctx.hasPage]           - Whether a page/tab is active
+ * @returns {Hint[]}
+ */
+export function generateHints({ cmd, refMap, lastFilledRef = null, hasPage = true }) {
+  // No page/tab -> bootstrap hints
+  if (!hasPage) {
+    return [
+      { cmd: 'chromex list', comment: 'see open tabs' },
+      { cmd: 'chromex launch', comment: 'start a browser with remote debugging' },
+    ];
+  }
+
+  // Missing refMap usually means the caller never captured refs for this page.
+  // In that case, teach the agent how to populate them.
+  if (!refMap) {
+    return [
+      { cmd: 'chromex snap <t> --refs', comment: 'assign @eN refs to interactive elements' },
+    ];
+  }
+
+  // Fresh snapshot with an EMPTY refMap means there are no interactive refs on
+  // the page we just rendered. Returning "snap --refs" here would create a
+  // pointless loop, because the agent already did that work and learned "none".
+  if (refMap.size === 0) return [];
+
+  const buckets = bucket(refMap);
+  const { submitButtons, buttons, inputs, links } = buckets;
+
+  // After fill: submit is most likely next step
+  if (cmd === 'fill') {
+    const hints = [];
+    if (submitButtons.length > 0) {
+      hints.push(clickHint(submitButtons[0]));
+    } else {
+      hints.push({ cmd: 'chromex key <t> Enter', comment: 'submit via Enter key' });
+    }
+    // Next unfilled input keeps the flow going
+    const unfilled = inputs.filter((i) => i.num !== lastFilledRef);
+    if (unfilled.length > 0 && hints.length < MAX_HINTS) {
+      hints.push(fillHint(unfilled[0]));
+    }
+    return hints.slice(0, MAX_HINTS);
+  }
+
+  // After nav: first input is usually the entry point (search, login, etc)
+  if (cmd === 'nav' || cmd === 'navigate') {
+    const hints = [];
+    if (inputs.length > 0) hints.push(fillHint(inputs[0]));
+    if (hints.length < MAX_HINTS && submitButtons.length > 0) hints.push(clickHint(submitButtons[0]));
+    else if (hints.length < MAX_HINTS && buttons.length > 0) hints.push(clickHint(buttons[0]));
+    if (hints.length < MAX_HINTS && links.length > 0) hints.push(clickHint(links[0]));
+    return hints.slice(0, MAX_HINTS);
+  }
+
+  // Default (snap, click, hover, others): top interactives with non-empty labels
+  return topInteractives(buckets, MAX_HINTS);
+}
+
+function topInteractives({ submitButtons, buttons, inputs, selects, links }, max) {
+  const ordered = [...inputs, ...submitButtons, ...buttons, ...selects, ...links];
+  const hints = [];
+  for (const entry of ordered) {
+    if (hints.length >= max) break;
+    if (!entry.name) continue; // skip nameless nodes -- they rarely help the agent
+    hints.push(INPUT_ROLES.has(entry.role) ? fillHint(entry) : clickHint(entry));
+  }
+  return hints;
+}
+
+/**
+ * Decide whether the daemon's currentRefMap is "fresh" for this command,
+ * i.e. safe to feed into generateHints without producing stale @eN pointers.
+ *
+ * Fresh means a snapshot with refs=true actually ran in THIS command:
+ *   - auto-snap fired (shouldSnap && !noSnap) -- daemon always passes refs=true there
+ *   - OR explicit `snap` with --refs/-i flag
+ *
+ * If neither happened, currentRefMap may still hold refs from a prior page
+ * (for example after nav --no-snap, or after a bare `snap` without --refs),
+ * so hints would point to coordinates that no longer exist in the DOM.
+ *
+ * This is a pure function so the daemon logic stays testable.
+ *
+ * @param {Object} ctx
+ * @param {string} ctx.cmd
+ * @param {boolean} ctx.shouldSnap  - Whether this cmd is in the AUTO_SNAP_CMDS set
+ * @param {boolean} ctx.noSnap      - Whether the caller passed --no-snap
+ * @param {string[]} ctx.args       - Command args (to detect --refs / -i on snap)
+ * @returns {boolean}
+ */
+export function isRefMapFresh({ cmd, shouldSnap, noSnap, args }) {
+  // Auto-snap always uses refs=true in the daemon -- if it ran, refs are fresh.
+  if (shouldSnap && !noSnap) return true;
+  // Explicit `snap --refs` (or `snap -i` alias) also populates refMap.
+  if ((cmd === 'snap' || cmd === 'snapshot') && Array.isArray(args)) {
+    if (args.includes('--refs') || args.includes('-i')) return true;
+  }
+  return false;
+}
+
+/**
+ * Render an array of hints into the chromex help[] block format.
+ * Format mirrors what Claude can parse unambiguously:
+ *   help[N]:
+ *     chromex <cmd>  # comment
+ *
+ * @param {Hint[]} hints
+ * @returns {string} Empty string when hints is empty/missing.
+ */
+export function renderHints(hints) {
+  if (!hints || hints.length === 0) return '';
+  const header = `help[${hints.length}]:`;
+  const lines = hints.map((h) => {
+    if (h.comment) return `  ${h.cmd}  # ${h.comment}`;
+    return `  ${h.cmd}`;
+  });
+  return `${header}\n${lines.join('\n')}`;
+}

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

@@ -0,0 +1,74 @@
+// Standardized output helpers: empty states, aggregates, indentation.
+// Pure functions, zero deps. Shared by commands and hints.
+
+/**
+ * Render a standardized empty state for a given domain.
+ * Used to distinguish "no results" from "silent failure" so agents
+ * do not retry commands hoping for different output.
+ *
+ * @param {string} domain - command or data domain (e.g. 'network', 'console')
+ * @param {string} [msg='empty'] - human-readable reason
+ * @returns {string}
+ *
+ * @example
+ *   emptyState('network', '0 requests captured')
+ *   // => 'network: 0 requests captured'
+ */
+export function emptyState(domain, msg = 'empty') {
+  return `${domain}: ${msg}`;
+}
+
+/**
+ * Render an aggregate header with count and optional key:value metadata.
+ * Embeds totals/counters into the first line of output so agents do not
+ * need a follow-up command just to ask "how many?".
+ *
+ * @param {string} domain
+ * @param {number} count
+ * @param {Object<string, string|number>} [meta]
+ * @returns {string}
+ *
+ * @example
+ *   aggregate('network', 47, { errors: 3, pending: 0 })
+ *   // => 'network[47] errors:3 pending:0'
+ */
+export function aggregate(domain, count, meta) {
+  const header = `${domain}[${count}]`;
+  if (!meta) return header;
+  const parts = Object.entries(meta).map(([k, v]) => `${k}:${v}`);
+  if (parts.length === 0) return header;
+  return `${header} ${parts.join(' ')}`;
+}
+
+/**
+ * Format a byte count into a human-readable string (B / KB / MB / GB).
+ * Keeps one decimal place above 1KB. Returns '?' for null/undefined.
+ *
+ * @param {number|null|undefined} bytes
+ * @returns {string}
+ */
+export function formatBytes(bytes) {
+  if (bytes == null) return '?';
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+}
+
+/**
+ * Indent every non-empty line of a block by `level` (2 spaces per level).
+ * Empty lines are preserved as empty (no trailing whitespace).
+ *
+ * @param {string} text
+ * @param {number} [level=1]
+ * @returns {string}
+ */
+export function indent(text, level = 1) {
+  if (!text) return '';
+  if (level <= 0) return text;
+  const pad = '  '.repeat(level);
+  return text
+    .split('\n')
+    .map((line) => (line === '' ? '' : pad + line))
+    .join('\n');
+}

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

@@ -14,7 +14,7 @@ import { launchBrowser, incognitoContext } from './lib/launcher.mjs';
 import { openTabStr, closeTabStr, focusTabStr } from './lib/commands/tab.mjs';
 
 const config = loadConfig();
-const SERVER_INFO = { name: 'chromex', version: '1.4.0' };
+const SERVER_INFO = { name: 'chromex', version: '1.5.0' };
 
 // ---- JSON-RPC helpers ----
 
@@ -55,6 +55,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' };
+const P_NO_HINTS = { type: 'boolean', description: 'Skip contextual help[] suggestions in output' };
 
 // ---- Tool definitions (56 tools) ----
 
@@ -102,12 +103,14 @@ const TOOLS = [
 
   // == INSPECT (readOnly) ==
   tool('chromex_snapshot',
-    'Accessibility tree snapshot. Returns incremental diff after first call (only changed nodes). 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. Use query to filter to matching nodes + ancestors (preserves hierarchy, slashes page output for large sites). Hints (help[]) are only emitted when refs=true because they rely on a fresh refMap.',
     {
       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)' },
+      query: { type: 'string', description: 'Filter tree to nodes matching substring (case-insensitive) in role/name/value. Ancestors preserved so hierarchy is intact. @eN refs stay stable.' },
+      noHints: P_NO_HINTS,
     }, ['target'], RO),
 
   tool('chromex_html',
@@ -185,6 +188,7 @@ const TOOLS = [
       target: P_TARGET,
       url: { type: 'string', description: 'URL, or action: "back", "forward", "reload", "reload-hard"' },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'url'], RW),
 
   tool('chromex_waitfor',
@@ -219,6 +223,7 @@ const TOOLS = [
       selector: { type: 'string', description: 'CSS selector or @eN ref' },
       dblClick: { type: 'boolean', description: 'Double-click instead of single click', default: false },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'selector'], RW),
 
   tool('chromex_clickxy',
@@ -229,6 +234,7 @@ const TOOLS = [
       y: { type: 'number', description: 'Y in CSS pixels' },
       dblClick: { type: 'boolean', description: 'Double-click instead of single click', default: false },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'x', 'y'], RW),
 
   tool('chromex_type',
@@ -237,6 +243,7 @@ const TOOLS = [
       target: P_TARGET,
       text: { type: 'string', description: 'Text to type' },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'text'], RW),
 
   tool('chromex_hover',
@@ -253,6 +260,7 @@ const TOOLS = [
       from: { type: 'string', description: 'Source selector or x,y' },
       to: { type: 'string', description: 'Destination selector or x,y' },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'from', 'to'], RW),
 
   tool('chromex_touch',
@@ -262,6 +270,7 @@ const TOOLS = [
       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,
+      noHints: P_NO_HINTS,
     }, ['target', 'gesture'], RW),
 
   tool('chromex_dialog',
@@ -271,6 +280,7 @@ const TOOLS = [
       action: { type: 'string', enum: ['accept', 'dismiss', 'auto'], description: 'Dialog action' },
       text: { type: 'string', description: 'Text for prompt (only with accept)' },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'action'], RW),
 
   tool('chromex_press_key',
@@ -279,6 +289,7 @@ const TOOLS = [
       target: P_TARGET,
       key: { type: 'string', description: 'Key or combination: "Enter", "Tab", "Escape", "Control+A", "Control+Shift+R", "Meta+C"' },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'key'], RW),
 
   tool('chromex_loadall',
@@ -288,6 +299,7 @@ const TOOLS = [
       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,
+      noHints: P_NO_HINTS,
     }, ['target', 'selector'], RW),
 
   // == FORMS ==
@@ -298,6 +310,7 @@ const TOOLS = [
       selector: { type: 'string', description: 'CSS selector or @eN ref' },
       value: { type: 'string', description: 'Value to fill' },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'selector', 'value'], RW),
 
   tool('chromex_clear',
@@ -306,6 +319,7 @@ const TOOLS = [
       target: P_TARGET,
       selector: { type: 'string', description: 'CSS selector' },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'selector'], RW),
 
   tool('chromex_select',
@@ -315,6 +329,7 @@ const TOOLS = [
       selector: { type: 'string', description: 'CSS selector of select element' },
       value: { type: 'string', description: 'Option value or visible text' },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'selector', 'value'], RW),
 
   tool('chromex_check',
@@ -324,6 +339,7 @@ const TOOLS = [
       selector: { type: 'string', description: 'CSS selector' },
       checked: { type: 'boolean', description: 'Desired state (default: true)', default: true },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'selector'], RW),
 
   tool('chromex_form',
@@ -332,6 +348,7 @@ const TOOLS = [
       target: P_TARGET,
       fields: { type: 'string', description: 'JSON: {"#email":"user@test.com","#terms":true}' },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'fields'], RW),
 
   tool('chromex_upload',
@@ -341,6 +358,7 @@ const TOOLS = [
       selector: { type: 'string', description: 'CSS selector of file input' },
       files: { type: 'array', items: { type: 'string' }, description: 'File path(s)' },
       noSnap: P_NO_SNAP,
+      noHints: P_NO_HINTS,
     }, ['target', 'selector', 'files'], RW),
 
   // == DATA ==
@@ -516,6 +534,7 @@ function toolToCmd(name, p) {
       if (p.refs) a.push('--refs');
       if (p.full) a.push('--full');
       if (p.depth) a.push(`--depth=${p.depth}`);
+      if (p.query) a.push(`--query=${p.query}`);
       return { cmd: 'snap', args: a };
     }
     case 'chromex_html':       return { cmd: 'html', args: p.selector ? [p.selector] : [] };
@@ -713,6 +732,7 @@ async function executeTool(name, params) {
   if (!mapped) return fail(`Unknown tool: ${name}`);
 
   if (params.noSnap) mapped.args.push('--no-snap');
+  if (params.noHints) mapped.args.push('--no-hints');
 
   const conn = await getOrStartTabDaemon(targetId, config);
   const response = await sendCommand(conn, { cmd: mapped.cmd, args: mapped.args });