chromex-mcp 1.3.0 → 1.5.0

package/README.md

@@ -1,14 +1,19 @@
 # Chromex
 
-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.
+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
 
-- **52 MCP tools** -- typed JSON Schema, annotations (`readOnlyHint`, `destructiveHint`), inline screenshots (base64)
+- **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
@@ -45,7 +50,7 @@ Add to `~/.claude/settings.json`:
 }
 ```
 
-This approves all 52 MCP tools at once. For granular control, approve individual tools:
+This approves all 56 MCP tools at once. For granular control, approve individual tools:
 
 ```json
 {
@@ -141,6 +146,10 @@ chromex close  <target>                            # Close tab
 chromex focus  <target>                            # Activate/focus tab
 chromex launch                                     # Launch browser with debugging
 chromex launch --incognito --browser brave          # Launch Brave in incognito
+chromex launch --headless --url https://example.com # Headless mode for CI/CD
+chromex launch --proxy socks5://localhost:1080      # Launch with proxy
+chromex launch --insecure                           # Ignore certificate errors
+chromex launch --chrome-arg --disable-web-security  # Pass custom Chrome flag
 chromex launch --profile testing --url https://...  # Isolated profile + URL
 chromex incognito https://example.com               # Isolated context (no relaunch)
 chromex stop                                        # Stop all daemons
@@ -153,12 +162,18 @@ 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
-chromex net     <target>                    # Network resource timing
+chromex shot    <target> --format=jpeg --quality=80  # JPEG/WebP with quality control
+chromex shot    <target> @e5               # Screenshot of specific element by ref
+chromex net     <target>                    # List network requests (CDP tracked)
+chromex net     <target> <requestId>        # Request detail: headers, timing, body
 chromex perf    <target>                    # Core Web Vitals + memory + DOM stats
 chromex console <target> 5000               # Capture console.log/error for 5s
+chromex console <target> list               # Show stored messages since daemon start
+chromex console <target> detail <id>        # Message detail with stack trace
 chromex domsnapshot <target>                # Structured DOM with bounding rects
 chromex domsnapshot <target> --styles       # Include computed styles
 chromex highlight <target> "h1"             # Highlight element with overlay
@@ -178,6 +193,10 @@ chromex evalraw <target> "Page.getLayoutMetrics"                   # Layout info
 
 ```bash
 chromex nav     <target> "https://example.com"    # Navigate + wait for load
+chromex nav     <target> back                      # Go back in history
+chromex nav     <target> forward                   # Go forward in history
+chromex nav     <target> reload                    # Reload page
+chromex nav     <target> reload-hard               # Reload ignoring cache
 chromex waitfor <target> ".results" 10000          # Wait for CSS selector (10s)
 chromex wait    <target> networkidle               # Wait for network idle
 chromex wait    <target> load                      # Wait for page load
@@ -195,7 +214,12 @@ chromex scroll  <target> to "#footer"              # Scroll to element
 ```bash
 chromex click   <target> "button.submit"           # Click by CSS selector
 chromex click   <target> @e5                       # Click by ref (from snap --refs)
+chromex click   <target> @e5 --dbl                 # Double-click
 chromex clickxy <target> 100 200                   # Click at CSS pixel coords
+chromex clickxy <target> 100 200 --dbl             # Double-click at coords
+chromex key     <target> Enter                     # Press key
+chromex key     <target> "Control+A"               # Key combination
+chromex key     <target> "Control+Shift+R"         # Multi-modifier combo
 chromex type    <target> "hello world"             # Type text (works cross-origin)
 chromex hover   <target> @e12                      # Hover element by ref
 chromex drag    <target> "#source" "#dest"         # Drag & drop by selector
@@ -268,6 +292,8 @@ 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 resize   <target> 1280 720                 # Custom viewport dimensions
+chromex resize   <target> 1440 900 2               # Custom with DPR (retina)
 chromex geo      <target> -23.55 -46.63            # Set geolocation (Sao Paulo)
 chromex geo      <target> reset                    # Clear geolocation
 chromex timezone <target> "America/Sao_Paulo"      # Set timezone
@@ -295,6 +321,18 @@ chromex webauthn <target> creds                    # List stored credentials
 chromex webauthn <target> disable                  # Remove authenticator
 ```
 
+### Audit & Analytics
+
+```bash
+chromex audit   <target>                           # Full Lighthouse audit (all categories)
+chromex audit   <target> performance,seo           # Specific categories
+chromex audit   <target> accessibility desktop     # Accessibility on desktop
+chromex stats   <target>                           # Session analytics (command counts, timing)
+chromex stats   <target> --full                    # Full action timeline
+chromex stats   <target> --reset                   # Reset counters
+chromex stats   <target> --export=/tmp/stats.json  # Export as JSON
+```
+
 ## Ref-Based Selection
 
 The killer feature for AI agents. Instead of fragile CSS selectors, use numbered refs:
@@ -349,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:
@@ -379,7 +441,7 @@ chromex click <target> @e3
 #   ...
 ```
 
-Commands that trigger auto-snapshot: `click`, `clickxy`, `type`, `fill`, `clear`, `select`, `check`, `form`, `nav`, `dialog`, `loadall`, `drag`, `touch`, `upload`.
+Commands that trigger auto-snapshot: `click`, `clickxy`, `type`, `key`, `fill`, `clear`, `select`, `check`, `form`, `nav`, `dialog`, `loadall`, `drag`, `touch`, `upload`.
 
 Suppress with `--no-snap` for scripts doing rapid sequential actions:
 
@@ -389,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.3.0",
-  "description": "Zero-dependency Chrome DevTools Protocol MCP server for AI agents. 52 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

@@ -27,7 +27,7 @@ const NEEDS_TARGET = new Set([
   'intercept', 'har', 'coverage',
   // Tier 3
   'trace', 'heap', 'webauthn', 'drag', 'touch', 'domsnapshot', 'highlight',
-  'hover',
+  'hover', 'key', 'resize', 'audit', 'stats',
 ]);
 
 const USAGE = `chromex - Chrome DevTools Protocol CLI for AI agents
@@ -44,15 +44,29 @@ Usage: chromex <command> [args]
       --browser chrome|brave|edge       Choose browser
       --profile NAME                    Use named profile
       --url URL                         Open URL on launch
+      --headless                        Launch in headless mode (no UI)
+      --proxy PROXY                     Proxy server (e.g. socks5://localhost:1080)
+      --insecure                        Ignore certificate errors
+      --chrome-arg FLAG                 Pass custom Chrome flag (e.g. --chrome-arg --disable-web-security)
     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] [--full]    Screenshot (viewport or full page)
-    net     <target>                    Network performance entries
+    shot    <target> [file] [options]   Screenshot (viewport, full page, or element)
+      --full                            Full page capture
+      --format=jpeg|webp|png            Image format (default: png)
+      --quality=N                       Compression quality 0-100 (JPEG/WebP)
+      @eN                               Capture specific element by ref
+    net     <target> [requestId]        Network requests list, or detail by request ID
     perf    <target>                    Core Web Vitals + performance metrics
     console <target> [duration_ms]      Capture console output (default 5000ms)
+    console <target> list               Show stored messages since daemon start
+    console <target> detail <id>        Message detail with stack trace
     domsnapshot <target> [--styles]     Structured DOM snapshot with bounding rects
     highlight <target> <sel|clear>      Highlight element with overlay
 
@@ -61,14 +75,15 @@ Usage: chromex <command> [args]
     evalraw <target> <method> [json]    Raw CDP command (some methods blocked)
 
   NAVIGATE
-    nav     <target> <url>              Navigate to URL and wait for load
+    nav     <target> <url|action>        Navigate: URL, back, forward, reload, reload-hard
     waitfor <target> <selector> [ms]    Wait for CSS selector to appear
     wait    <target> <event> [ms]       Wait for: networkidle, load, domready, fcp
     scroll  <target> <dir> [amount]     Scroll: up, down, top, bottom, to <selector>
 
   INTERACT
-    click   <target> <selector>         Click element by CSS selector
-    clickxy <target> <x> <y>            Click at CSS pixel coordinates
+    click   <target> <selector> [--dbl]  Click element (supports double-click)
+    clickxy <target> <x> <y> [--dbl]   Click at coordinates (supports double-click)
+    key     <target> <combo>            Press key: Enter, Tab, Escape, Control+A, Meta+C
     type    <target> <text>             Type text at current focus
     drag    <target> <from> <to>        Drag & drop (selectors or x1,y1 x2,y2)
     touch   <target> <gesture> [args]   Touch: tap, swipe, pinch, longpress
@@ -99,6 +114,7 @@ Usage: chromex <command> [args]
     timezone <target> <tz|reset>        Set timezone (e.g. America/Sao_Paulo)
     locale  <target> <locale|reset>     Set locale (e.g. pt-BR)
     cpu     <target> <rate|reset>       CPU throttle (1=normal, 4=4x slower, 6=mobile)
+    resize  <target> <w> <h> [dpr]     Resize viewport to custom dimensions
 
   ADVANCED
     inject  <target> <script|flags>     Inject JS on every page load (--file, --remove, --list)
@@ -108,11 +124,22 @@ Usage: chromex <command> [args]
     heap    <target> snapshot [file]     Heap snapshot for memory analysis
     webauthn <target> enable|creds|dis  Virtual authenticator for passkey testing
 
+  AUDIT
+    audit   <target> [categories] [device]  Lighthouse audit (performance, accessibility, SEO)
+      categories: performance,accessibility,seo,best-practices
+      device: mobile (default) or desktop
+    stats   <target> [--full] [--reset] Session analytics (command counts, timing, errors)
+      --export=/path/to/stats.json      Export as JSON
+
   DAEMON
     stop    [target]                    Stop daemon(s)
 
 <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
@@ -166,7 +193,8 @@ async function main() {
 
   // Launch
   if (cmd === 'launch') {
-    const options = parseFlags(args, ['incognito'], ['browser', 'profile', 'url']);
+    const options = parseFlags(args, ['incognito', 'headless', 'insecure'], ['browser', 'profile', 'url', 'proxy', 'chrome-arg']);
+    if (options['chrome-arg']) { options.chromeArgs = [options['chrome-arg']]; delete options['chrome-arg']; }
     const result = await launchBrowser(options);
     console.log(result);
     return;
@@ -245,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') {
@@ -280,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/client.mjs

@@ -16,6 +16,7 @@ export class CDP {
   }
 
   async connect(wsUrl) {
+    this.wsUrl = wsUrl;
     return new Promise((res, rej) => {
       this.#ws = new WebSocket(wsUrl);
       this.#ws.onopen = () => res();

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

@@ -0,0 +1,182 @@
+// Lighthouse audit via subprocess (zero deps -- invokes npx lighthouse externally)
+// Chrome: connects to existing browser via --port (reuses session)
+// Other browsers (Brave, Edge, etc.): Lighthouse launches its own headless Chrome
+
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { evalStr } from './evaluate.mjs';
+
+const VALID_CATEGORIES = ['performance', 'accessibility', 'seo', 'best-practices'];
+
+// Find any Chromium-based browser for CHROME_PATH env var
+function findChromiumPath() {
+  const paths = process.platform === 'darwin' ? [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  ] : [
+    '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable',
+    '/usr/bin/brave-browser', '/usr/bin/chromium-browser', '/usr/bin/chromium',
+    '/usr/bin/microsoft-edge',
+  ];
+  for (const p of paths) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+// Check if Chrome's HTTP debug endpoint is available (Brave/Edge don't expose it)
+function isHttpDebugAvailable(port) {
+  try {
+    const result = execSync(`curl -sf http://127.0.0.1:${port}/json/version`, {
+      encoding: 'utf8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return result.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export async function auditStr(cdp, sid, categories, device, reportPath) {
+  // Get current page URL
+  const url = await evalStr(cdp, sid, 'window.location.href');
+  if (!url || url === 'about:blank') {
+    throw new Error('Navigate to a page first before running audit.');
+  }
+
+  // Validate categories
+  const cats = categories
+    ? categories.split(',').map(c => c.trim().toLowerCase()).filter(c => VALID_CATEGORIES.includes(c))
+    : VALID_CATEGORIES;
+
+  if (cats.length === 0) {
+    throw new Error(`Invalid categories. Valid: ${VALID_CATEGORIES.join(', ')}`);
+  }
+
+  // Build base args
+  const args = [
+    '--output=json',
+    `--only-categories=${cats.join(',')}`,
+    '--quiet',
+  ];
+
+  if (device === 'desktop') args.push('--preset=desktop');
+
+  if (reportPath) {
+    args.push(`--output-path=${reportPath}`);
+    args.push('--output=html');
+    args.push('--output=json');
+  }
+
+  // Detect: Chrome (has /json/version) vs other browsers (Brave, Edge, etc.)
+  let port;
+  if (cdp.wsUrl) {
+    const m = cdp.wsUrl.match(/:(\d+)\//);
+    if (m) port = m[1];
+  }
+
+  let mode;
+  if (port && isHttpDebugAvailable(port)) {
+    // Chrome: reuse existing browser session
+    args.push(`--port=${port}`);
+    mode = 'connected (existing browser)';
+  } else {
+    // Brave/Edge/other: Lighthouse launches its own headless Chrome
+    args.push('--chrome-flags=--headless=new');
+    mode = 'standalone (headless Chrome)';
+  }
+
+  const cmd = `npx --yes lighthouse ${JSON.stringify(url)} ${args.join(' ')}`;
+
+  // Set CHROME_PATH for standalone mode (Lighthouse uses chrome-launcher which reads it)
+  const env = { ...process.env };
+  if (mode.startsWith('standalone')) {
+    const chromePath = findChromiumPath();
+    if (chromePath) env.CHROME_PATH = chromePath;
+  }
+
+  let jsonOutput;
+  try {
+    jsonOutput = execSync(cmd, {
+      encoding: 'utf8',
+      timeout: 120000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      maxBuffer: 50 * 1024 * 1024,
+      env,
+    });
+  } catch (e) {
+    const stderr = e.stderr?.toString().trim() || '';
+    if (stderr.includes('not found') || stderr.includes('ENOENT')) {
+      throw new Error('lighthouse not found. Install: npm i -g lighthouse');
+    }
+    if (stderr.includes('No Chrome installations found')) {
+      throw new Error('Lighthouse needs Chrome installed to run in standalone mode. Install Google Chrome or run against a Chrome instance with debug port.');
+    }
+    throw new Error(`Lighthouse failed: ${stderr || e.message}`);
+  }
+
+  // Parse JSON output
+  let report;
+  try {
+    report = JSON.parse(jsonOutput);
+  } catch {
+    const jsonStart = jsonOutput.lastIndexOf('{"');
+    if (jsonStart > 0) {
+      report = JSON.parse(jsonOutput.slice(jsonStart));
+    } else {
+      throw new Error('Failed to parse Lighthouse output.');
+    }
+  }
+
+  // Format results
+  const lines = [];
+
+  // Scores
+  const scores = {};
+  for (const cat of cats) {
+    const c = report.categories?.[cat];
+    if (c) scores[c.title] = Math.round((c.score || 0) * 100);
+  }
+  const scoreStr = Object.entries(scores).map(([k, v]) => `${k}: ${v}`).join(' | ');
+  lines.push(`Lighthouse Audit: ${scoreStr}`);
+  lines.push(`URL: ${url}`);
+  lines.push(`Device: ${device || 'mobile'} | Mode: ${mode}`);
+  lines.push('');
+
+  // Top opportunities
+  const audits = report.audits || {};
+  const opportunities = Object.values(audits)
+    .filter(a => a.details?.type === 'opportunity' && a.details?.overallSavingsMs > 0)
+    .sort((a, b) => (b.details.overallSavingsMs || 0) - (a.details.overallSavingsMs || 0))
+    .slice(0, 5);
+
+  if (opportunities.length > 0) {
+    lines.push('Top Opportunities:');
+    for (const opp of opportunities) {
+      const savings = (opp.details.overallSavingsMs / 1000).toFixed(1);
+      lines.push(`  - ${opp.title} (savings: ${savings}s)`);
+    }
+    lines.push('');
+  }
+
+  // Critical diagnostics
+  const diagnostics = Object.values(audits)
+    .filter(a => a.score !== null && a.score < 0.5 && a.details?.type !== 'opportunity')
+    .sort((a, b) => (a.score || 0) - (b.score || 0))
+    .slice(0, 5);
+
+  if (diagnostics.length > 0) {
+    lines.push('Critical Issues:');
+    for (const diag of diagnostics) {
+      lines.push(`  - ${diag.title}: ${diag.displayValue || 'needs improvement'}`);
+    }
+  }
+
+  if (reportPath) {
+    lines.push('');
+    lines.push(`Full report saved to: ${reportPath}`);
+  }
+
+  return lines.join('\n');
+}