chromex-mcp 1.2.0 → 1.4.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. 56 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
+- **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
+- **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
+
+# Or project-only
+claude mcp add chromex npx chromex-mcp@latest
+```
 
-# Install
-/plugin install chromex
+### Auto-Approve (recommended)
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": ["mcp__chromex"]
+  }
+}
+```
+
+This approves all 56 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"
+    ]
+  }
+}
 ```
 
-### Standalone
+### 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:
 
-# Optional: create an alias
-alias chromex="node $(pwd)/skills/chromex/scripts/chromex.mjs"
+| 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 |
+
+```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
@@ -110,6 +141,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
@@ -118,14 +153,21 @@ 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
-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
@@ -145,14 +187,20 @@ 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
 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
@@ -160,7 +208,12 @@ chromex scroll  <target> top                       # Scroll to top
 ```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
@@ -207,6 +260,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,10 +278,16 @@ 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 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
@@ -236,8 +296,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
@@ -257,6 +315,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:
@@ -278,73 +348,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.
+
+### Incremental Diff
+
+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
 
-Chromex also ships as an MCP server -- typed tools, auto-approve with one line, no Bash globs.
+### Depth Limiting
 
-### Setup
+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`, `key`, `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
+
+Both interfaces call the same core, same daemons, same commands. The difference is how they integrate with Claude Code.
 
-| | CLI (Bash) | MCP Server |
+| | 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
+
+You can enable and disable the MCP server at any time. The CLI always works regardless.
+
+**Disable MCP** (saves ~3-5k tokens per session):
 
-The CLI still works and is useful for terminal, scripts, and CI/CD. The MCP server is the recommended interface for Claude Code.
+```bash
+claude mcp remove chromex
+```
 
-### npm
+The CLI (`chromex-cli`) continues working normally -- same commands, same daemons, no change.
+
+**Re-enable MCP:**
 
 ```bash
-npm install -g chromex-mcp    # Global install
-chromex-mcp                    # Run MCP server
-chromex-cli list               # CLI also available
+# Global (all projects)
+claude mcp add chromex -s user npx chromex-mcp@latest
+
+# Project-only
+claude mcp add chromex npx chromex-mcp@latest
 ```
 
-## Auto-Approve for CLI (Alternative)
+**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 +476,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 +498,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 +533,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.2.0",
-  "description": "Zero-dependency Chrome DevTools Protocol MCP server for AI agents. 52 typed tools, per-tab daemons, security hardened.",
+  "version": "1.4.0",
+  "description": "Zero-dependency Chrome DevTools Protocol MCP server for AI agents. 56 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

@@ -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,25 @@ 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)
     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 +71,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 +110,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,6 +120,13 @@ 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)
 
@@ -166,7 +185,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;

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();