chromex-mcp 1.7.0 → 1.8.0

package/README.md

@@ -4,14 +4,26 @@
 [![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Chromex is a zero-dependency Chrome DevTools Protocol toolkit for AI agents. It connects directly to Chrome, Brave, Edge, Chromium, and Vivaldi through CDP, exposing a token-efficient CLI and an optional MCP server with 78 typed tools.
+Chromex is an agent-first browser automation and DevTools toolkit that connects directly to Chrome, Brave, Edge, Chromium, and Vivaldi through CDP. It exposes the complete capability set through a token-efficient CLI and 85 typed MCP tools, with zero runtime dependencies.
 
-Use Chromex when an agent needs to inspect pages, take screenshots, navigate, click, fill forms, read console/network activity, emulate devices, throttle network/CPU, export PDFs, or run browser diagnostics without pulling in heavy browser automation runtimes.
+Use Chromex when an agent needs to automate a real logged-in browser, inspect page and Application state, debug console/network failures, profile performance or memory, test extensions and WebMCP, or collect reproducible evidence without pulling in a heavy browser automation runtime.
+
+## Quick Start
+
+```bash
+npm install -g chromex-mcp
+chromex --version
+chromex launch --pipe --url https://example.com
+chromex list
+chromex snap <target> --refs
+```
+
+`launch --pipe` is the recommended path for repeatable AI sessions: it starts an isolated Chromex profile and avoids Chrome's recurring debugging approval prompt. Use the normal WebSocket mode only when access to an already-running personal browser is intentional.
 
 ## Why Chromex
 
 - **CLI-first for lower token usage**: terminal commands return compact plain text and avoid MCP tool-schema overhead.
-- **Optional MCP server**: 78 typed tools for Claude Code and other MCP clients when tool discovery, typed parameters, and inline screenshots matter more than token budget.
+- **Optional MCP server**: 85 typed tools in the full set, plus focused `core` and `devtools` toolsets for sessions where schema cost matters.
 - **No runtime dependencies**: Node.js 22+ built-ins only, including native WebSocket support.
 - **Agent-friendly page model**: accessibility snapshots, `@eN` refs, incremental diffs, query filters, auto-snapshots, and contextual hints.
 - **Persistent per-tab daemons**: one CDP session per tab, held open through an authenticated Unix socket.
@@ -28,11 +40,23 @@ Use Chromex when an agent needs to inspect pages, take screenshots, navigate, cl
 - Debug production behavior with console history, network request details, response bodies, HAR export, request blocking, API mocking, throttling, and offline mode.
 - Test browser conditions with device presets, viewport resizing, DPR, geolocation, timezone, locale, CPU throttling, incognito contexts, proxies, and custom Chrome flags.
 - Diagnose performance and quality with Core Web Vitals, transfer size, DOM/memory counters, Lighthouse audits, JS/CSS coverage, Chrome traces, and heap snapshots.
+- Inspect Browser Issues, computed and matched CSS, event listeners, box models, prioritized runtime diagnoses, CPU profiles, heap retaining paths, duplicate strings, and trace insights.
+- Capture bounded screencasts with a local replay, manage extensions in trusted pipe mode, and discover or execute WebMCP and page-exposed developer tools.
 - Build evidence packs with screenshots, snapshots, HTML, console, network timeline, action timeline, and replay HTML.
 - Validate modern browser flows such as passkey/WebAuthn registration and login, downloads, cookies, portable storage state, PDF export, and isolated profiles.
 - Inspect Application panel state from the terminal: origin quota, storage usage breakdown, Cache Storage entries/bodies, IndexedDB schemas/rows, and Service Worker registrations.
 - Turn `@eN` refs into locators and optional `chromex-test` action code.
 
+The CLI and the default MCP `full` toolset expose the same capability families. CLI commands group related operations into subcommands, while MCP presents 85 individually typed tools.
+
+| Capability | CLI | MCP `full` |
+|------------|-----|------------|
+| Input, navigation, forms, uploads, dialogs, and emulation | Yes | Yes |
+| Console, network, Application state, interception, HAR, and audits | Yes | Yes |
+| Browser Issues, CSS/listener/box inspection, and runtime diagnosis | Yes | Yes |
+| Web Vitals, CPU profiles, heap sampling, traces, and heap analysis | Yes | Yes |
+| Screencasts, extensions, page developer tools, and WebMCP | Yes | Yes |
+
 ## Positioning
 
 Chromex is a direct CDP layer for coding agents. It sits between raw Chrome DevTools Protocol and heavier browser automation frameworks.
@@ -77,11 +101,16 @@ chromex launch --browser brave --url https://example.com
 chromex launch --profile testing --url https://example.com
 chromex launch --incognito --browser chrome
 chromex launch --headless --url https://example.com
+chromex launch --pipe --url https://example.com
+chromex launch --extension-tools --url about:blank
+chromex launch --webmcp --url https://example.com
 chromex launch --browser-path "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary"
 ```
 
 Named profiles are stored under `~/.chromex/profiles/` and keep test sessions isolated from your daily browser profile.
 
+`chromex launch --pipe` is the preferred mode for repeated AI sessions. It uses one permission-protected local Unix-socket broker over Chrome's remote-debugging pipe, avoids approval modals, and lets CLI and MCP clients share the same browser connection. `--extension-tools` implies pipe mode because Chrome restricts extension lifecycle APIs to trusted debugging sessions. WebMCP requires a visible supported Chrome build, so do not combine `--webmcp` with `--headless` when the page tools must execute.
+
 Chrome for Testing also works well with Chromex. Download it manually from Google's official Chrome for Testing channel, then point Chromex at the executable with `--browser-path` or `CHROMEX_BROWSER_PATH`. Chromex does not download or bundle a browser.
 
 ### Option B: Connect to an Already-Running Browser
@@ -101,7 +130,9 @@ Important notes:
 
 - Without remote debugging enabled, Chromex cannot discover or control your open tabs.
 - The browser setting is usually persistent across restarts.
-- The first command that attaches to a tab may show an "Allow debugging" prompt. Accept it once for that tab; Chromex keeps the daemon session alive after that.
+- Chrome may show an "Allow debugging" prompt for each new DevTools WebSocket connection to a normal browser profile. This is browser security behavior, so reconnecting from a new CLI or agent process can show it again.
+- Per-tab daemons and the persistent MCP connection reduce reconnections, but they do not bypass Chrome's protection for a personal browser profile.
+- Use `chromex launch --pipe` with a Chromex-managed isolated profile when a modal-free persistent AI connection is required.
 
 If your browser uses a custom profile or a non-standard `DevToolsActivePort` location, set:
 
@@ -133,6 +164,15 @@ npm install -g chromex-mcp
 bun add -g chromex-mcp
 ```
 
+Verify which installation every terminal and agent session will use:
+
+```bash
+command -v chromex
+chromex --version
+```
+
+Cloning the repository does not replace an existing global installation. To test the current checkout directly, run `node bin/chromex.mjs`. To deliberately install the current checkout globally, run `npm install -g .` from the repository root and verify the path and version again.
+
 The package installs three binaries:
 
 | Binary | Purpose |
@@ -221,26 +261,49 @@ Global, available in all projects:
 
 ```bash
 # npm
-claude mcp add chromex -s user npx chromex-mcp@latest
+claude mcp add chromex --scope user -- npx -y chromex-mcp@latest
 
 # Bun
-claude mcp add chromex -s user bunx chromex-mcp@latest
+claude mcp add chromex --scope user -- bunx chromex-mcp@latest
 ```
 
 Project-only:
 
 ```bash
 # npm
-claude mcp add chromex npx chromex-mcp@latest
+claude mcp add chromex -- npx -y chromex-mcp@latest
 
 # Bun
-claude mcp add chromex bunx chromex-mcp@latest
+claude mcp add chromex -- bunx chromex-mcp@latest
+```
+
+For MCP clients that accept a standard stdio configuration, point the client at the installed binary:
+
+```json
+{
+  "mcpServers": {
+    "chromex": {
+      "command": "chromex-mcp",
+      "args": []
+    }
+  }
+}
 ```
 
-After setup, the MCP client can call tools such as `chromex_list`, `chromex_snapshot`, `chromex_click`, `chromex_fill`, `chromex_screenshot`, `chromex_console`, `chromex_network`, `chromex_app_summary`, `chromex_cache_entries`, `chromex_indexeddb_rows`, `chromex_sessions`, `chromex_show`, `chromex_locator`, `chromex_state`, and `chromex_evidence`.
+After setup, the MCP client can call tools such as `chromex_list`, `chromex_snapshot`, `chromex_click`, `chromex_fill`, `chromex_network`, `chromex_issues`, `chromex_inspect`, `chromex_diagnose`, `chromex_perf`, `chromex_trace`, `chromex_heap`, `chromex_screencast`, `chromex_extensions`, `chromex_third_party`, `chromex_webmcp`, `chromex_app_summary`, `chromex_cache_entries`, `chromex_indexeddb_rows`, and `chromex_evidence`.
 
 Tools that produce machine-readable data or artifacts also include MCP `structuredContent`, so agents can read paths and metadata without parsing the human text block.
 
+The default `full` toolset exposes all 85 tools. Use a focused toolset when the MCP client sends every schema into the model context:
+
+```bash
+chromex-mcp --toolset=core
+chromex-mcp --toolset=devtools
+CHROMEX_TOOLSET=full chromex-mcp
+```
+
+`core` exposes 24 navigation, inspection, input, form, and emulation tools. `devtools` exposes 26 browser-diagnostics, performance, trace, heap, Application, and audit tools. This selection changes discovery only; the complete CLI and the default MCP toolset retain every capability.
+
 ### Claude Code Auto-Approve
 
 To approve all Chromex MCP tools at once, add this to `~/.claude/settings.json`:
@@ -294,6 +357,7 @@ claude mcp remove chromex
 
 ```bash
 chromex list
+chromex list --include-sensitive
 chromex open "https://example.com"
 chromex -s auth open "https://example.com/login"
 chromex -s auth snap --refs
@@ -304,6 +368,9 @@ chromex focus <target>
 chromex launch --url https://example.com
 chromex launch --browser brave --incognito
 chromex launch --headless --url https://example.com
+chromex launch --pipe --url https://example.com
+chromex launch --extension-tools --url about:blank
+chromex launch --webmcp --url https://example.com
 chromex launch --browser-path /path/to/chrome --url https://example.com
 chromex doctor
 chromex incognito https://example.com
@@ -322,8 +389,14 @@ chromex shot <target> ~/.chromex/screenshots/full.png --full
 chromex shot <target> @e5
 chromex console <target> list
 chromex net <target>
+chromex net <target> <requestId> --include-sensitive
+chromex net <target> <requestId> --body-limit=100000
 chromex perf <target>
 chromex domsnapshot <target> --styles
+chromex issues <target> enable
+chromex issues <target> list
+chromex inspect <target> all "#checkout"
+chromex diagnose <target>
 chromex evidence <target> start checkout-flow
 chromex evidence <target> mark "after login"
 chromex evidence <target> stop
@@ -415,7 +488,13 @@ chromex inject <target> "window.DEBUG=true"
 chromex download <target> allow ~/.chromex/downloads
 chromex coverage <target> start
 chromex trace <target> start
+chromex trace <target> insights
 chromex heap <target> snapshot ~/.chromex/heap/heap.heapsnapshot
+chromex heap <target> summary
+chromex screencast <target> start --max-frames=120
+chromex extensions <target> list
+chromex third-party <target> list
+chromex webmcp <target> list
 chromex webauthn <target> enable
 ```
 
@@ -498,7 +577,7 @@ chromex -s auth click @e3
 chromex sessions
 chromex show --annotate
 chromex close-all
-chromex delete-data
+chromex delete-data auth
 ```
 
 `CHROMEX_SESSION=auth` can replace `-s auth` for shell scripts.
@@ -583,7 +662,24 @@ Chromex creates `~/.chromex/config.json` on first run:
   "idleTimeout": 1200000,
   "allowedDomains": [],
   "blockedDomains": [],
-  "blockedCdpMethods": ["Browser.close", "Storage.getCookies"],
+  "blockedCdpMethods": [
+    "Network.enable",
+    "Network.setRequestInterception",
+    "Network.setCacheDisabled",
+    "Page.setDocumentContent",
+    "Security.disable",
+    "Security.setIgnoreCertificateErrors",
+    "Fetch.enable",
+    "Fetch.fulfillRequest",
+    "Fetch.continueRequest",
+    "Browser.close",
+    "Browser.crashGpuProcess",
+    "Target.disposeBrowserContext",
+    "SystemInfo.getProcessInfo",
+    "Storage.clearDataForOrigin",
+    "Storage.getCookies",
+    "IndexedDB.requestData"
+  ],
   "auditLog": true,
   "socketAuth": true
 }
@@ -597,18 +693,21 @@ Recommended security practices:
 - Keep `auditLog` enabled and review `~/.chromex/audit.log` when needed.
 - Prefer `chromex launch --profile testing` for isolated browser state.
 
+Page URLs, network, console, extension-storage, third-party, and WebMCP outputs redact secret-shaped headers and fields by default. The browser still sends and receives the original values. Use CLI `--include-sensitive` or MCP `includeSensitive: true` only on the specific live call that needs exact values. Audit logs, page caches, stats, HAR, and structured evidence timelines, network data, and console data remain redacted even when a live response is revealed. Screenshots, screencasts, snapshots, HTML, traces, heap snapshots, and raw page content can still contain sensitive information and should be handled accordingly.
+
 See [docs/security.md](docs/security.md) for the full security model.
 
 ## How It Works
 
 ```text
 CLI or MCP client -> authenticated Unix socket -> per-tab daemon -> CDP WebSocket -> browser
+                                                        \-> pipe broker -> Chrome debugging pipe
 ```
 
-1. Chromex finds the browser DevTools endpoint from `DevToolsActivePort` or `CDP_PORT_FILE`.
+1. Chromex finds a browser DevTools endpoint or a Chromex pipe-broker marker.
 2. The first tab command starts a detached daemon for that tab.
 3. The daemon attaches once through CDP and keeps the session open.
-4. CLI and MCP commands talk to the daemon through an authenticated Unix socket.
+4. CLI and MCP commands talk to the daemon through an authenticated Unix socket; pipe mode multiplexes CDP through a second local socket restricted to the current OS user.
 5. Daemons exit after the configured idle timeout.
 
 See [docs/architecture.md](docs/architecture.md) for implementation details.
@@ -618,15 +717,16 @@ See [docs/architecture.md](docs/architecture.md) for implementation details.
 | Guide | Description |
 |-------|-------------|
 | [Getting Started](docs/getting-started.md) | Installation, browser setup, first commands. |
-| [Inspect and Debug](docs/inspect.md) | Screenshots, accessibility tree, refs, HTML, eval, network, performance, console. |
+| [Inspect and Debug](docs/inspect.md) | Screenshots, accessibility tree, refs, Browser Issues, CSS/listener inspection, diagnostics, performance, and console. |
 | [Navigate and Interact](docs/navigate.md) | Navigation, clicking, typing, scrolling, drag and drop, touch, dialogs. |
 | [Form Filling](docs/forms.md) | Fill, clear, select, check, upload, batch form examples. |
 | [Data Access](docs/data.md) | Cookies, localStorage, sessionStorage, Application state, Cache Storage, IndexedDB, Service Workers, PDF export. |
-| [Network Control](docs/network.md) | Throttling, interception, mocking, HAR recording. |
+| [Network Control](docs/network.md) | Live request history and bodies, filtering, redaction, throttling, interception, mocking, and HAR. |
 | [Device Emulation](docs/emulation.md) | Responsive testing, geolocation, timezone, CPU throttling. |
 | [Security](docs/security.md) | Domain filtering, CDP blocklist, audit log, best practices. |
-| [Advanced](docs/advanced.md) | Script injection, code coverage, tracing, heap snapshots, WebAuthn. |
+| [Advanced](docs/advanced.md) | CPU and heap profiles, trace insights, heap graph analysis, screencasts, extensions, page tools, WebMCP, and WebAuthn. |
 | [Architecture](docs/architecture.md) | Daemon model, connection modes, and file layout. |
+| [Troubleshooting](docs/troubleshooting.md) | Installation drift, connection failures, debugging prompts, Node warnings, extensions, and WebMCP. |
 
 ## Development
 

package/docs/advanced.md

@@ -0,0 +1,301 @@
+# Advanced Features
+
+Power-user commands for script injection, code coverage, performance and memory profiling, trace insights, heap graph analysis, screencasts, Chrome extensions, page-exposed tools, WebMCP, and WebAuthn testing.
+
+## Script Injection
+
+Inject JavaScript that runs **before** any page scripts on every navigation. Useful for polyfills, monitoring, API overrides, or anti-detection.
+
+```bash
+# Inject inline script
+chromex inject <target> "window.__TESTING = true"
+
+# Inject from file
+chromex inject <target> --file /tmp/preload.js
+
+# List injected scripts
+chromex inject <target> --list
+# Output:
+# 1  window.__TESTING = true
+# 2  (function() { // contents of preload.js... })()
+
+# Remove a specific injection
+chromex inject <target> --remove 1
+```
+
+### Use Cases
+
+```bash
+# Override navigator properties (anti-detection)
+chromex inject <target> "Object.defineProperty(navigator, 'webdriver', {get: () => false})"
+
+# Add performance monitoring
+chromex inject <target> --file /tmp/monitor.js
+
+# Mock browser APIs
+chromex inject <target> "window.confirm = () => true; window.alert = () => {}"
+```
+
+Scripts persist across navigations within the same daemon session. They're removed when the daemon stops or when explicitly removed with `--remove`.
+
+## Download Control
+
+Control how the browser handles file downloads.
+
+```bash
+# Auto-accept downloads to a specific directory
+chromex download <target> allow ~/.chromex/downloads
+
+# Block all downloads
+chromex download <target> deny
+
+# Reset to default behavior
+chromex download <target> reset
+```
+
+## Code Coverage
+
+Measure how much of the loaded JavaScript and CSS is actually used.
+
+```bash
+# Start collecting coverage
+chromex coverage <target> start
+
+# Navigate and interact with the page
+chromex nav <target> "https://example.com"
+chromex click <target> ".menu-toggle"
+chromex waitfor <target> ".dropdown-open"
+
+# Stop and get report
+chromex coverage <target> stop
+```
+
+**Output:**
+```
+## JavaScript Coverage
+Total: 1.2MB, Used: 340.5KB (28%)
+
+Files with <50% usage:
+   12%    245.3KB  https://example.com/vendor.js
+   23%    189.1KB  https://example.com/analytics.js
+   45%     98.7KB  https://example.com/app.js
+
+## CSS Coverage
+Rules: 1523 total, 412 used (27%)
+```
+
+### Use Cases
+
+```bash
+# Identify dead code in production
+chromex coverage <target> start
+chromex nav <target> "https://example.com"
+chromex wait <target> networkidle
+chromex coverage <target> stop
+
+# Measure coverage for a specific user flow
+chromex coverage <target> start
+chromex nav <target> "https://app.example.com/login"
+chromex fill <target> "#email" "user@test.com"
+chromex fill <target> "#password" "secret"
+chromex click <target> "button[type=submit]"
+chromex waitfor <target> ".dashboard"
+chromex coverage <target> stop
+```
+
+## Performance and Allocation Profiles
+
+The performance summary reports LCP, INP, FCP, CLS, TTFB, long tasks, long animation frames, layout shifts, navigation timing, transfer size, heap counters, DOM nodes, documents, frames, and listeners.
+
+```bash
+chromex perf <target> summary
+chromex perf <target> start
+chromex perf <target> stop
+```
+
+Use an explicit collection window when the metric depends on an interaction. CPU and allocation profiles are written under `~/.chromex/artifacts/<workspace>/profiles/` unless a path is provided.
+
+```bash
+chromex perf <target> cpu-start
+chromex click <target> "#expensive-action"
+chromex perf <target> cpu-stop
+
+chromex perf <target> heap-sampling-start
+chromex click <target> "#allocate"
+chromex perf <target> heap-sampling-stop
+```
+
+CPU profiles use the `.cpuprofile` format. Heap allocation sampling uses `.heapprofile`; both can be loaded into compatible Chrome DevTools panels.
+
+## Performance Tracing
+
+Capture a full Chrome performance trace and analyze common bottlenecks without loading the complete trace into the agent context.
+
+```bash
+chromex trace <target> start
+chromex nav <target> "https://example.com"
+chromex scroll <target> bottom
+chromex click <target> ".load-more"
+chromex trace <target> stop
+chromex trace <target> insights
+```
+
+The default artifact path is `~/.chromex/artifacts/<workspace>/traces/trace-<timestamp>.json`. The capture streams through CDP instead of retaining the complete trace in memory.
+
+Use custom categories or inspect one finding type:
+
+```bash
+chromex trace <target> start "devtools.timeline,v8.execute,blink.user_timing"
+chromex trace <target> stop ~/.chromex/custom/checkout-trace.json
+chromex trace <target> insight long-task ~/.chromex/custom/checkout-trace.json
+```
+
+Available insight families depend on the trace and include long tasks, expensive layouts, GC pauses, and layout shifts. Full trace files can also be loaded into [Perfetto UI](https://ui.perfetto.dev/).
+
+## Heap Snapshots and Graph Analysis
+
+Heap snapshots default to `~/.chromex/artifacts/<workspace>/heap/`. Chromex analyzes them in a worker so the CLI and MCP server remain responsive.
+
+```bash
+chromex heap <target> snapshot
+chromex heap <target> summary
+chromex heap <target> duplicate-strings
+chromex heap <target> class-nodes <snapshot> HTMLDivElement 50
+chromex heap <target> dominators <snapshot> <nodeId> 50
+chromex heap <target> retainers <snapshot> <nodeId> 50
+chromex heap <target> retaining-paths <snapshot> <nodeId> 20 8
+chromex heap <target> edges <snapshot> <nodeId> 100
+chromex heap <target> details <snapshot> <nodeId>
+chromex heap <target> close <snapshot>
+```
+
+`summary` and other analysis commands reuse the most recent snapshot when the file is omitted. `close` releases its parsed graph from the analysis worker.
+
+### Memory Leak Workflow
+
+```bash
+chromex heap <target> snapshot ~/.chromex/heap/before.heapsnapshot
+
+for i in $(seq 1 10); do
+  chromex click <target> ".open-modal"
+  chromex click <target> ".close-modal"
+done
+
+chromex heap <target> snapshot ~/.chromex/heap/after.heapsnapshot
+chromex heap <target> compare ~/.chromex/heap/before.heapsnapshot ~/.chromex/heap/after.heapsnapshot 50
+```
+
+Snapshots can still be loaded into the Chrome DevTools Memory panel for manual exploration. They may contain strings and object data from the page and should be treated as sensitive artifacts.
+
+## Bounded Screencasts
+
+Screencasts capture individual frames, a manifest, and a local replay instead of producing an opaque video file.
+
+```bash
+chromex screencast <target> start --format=jpeg --quality=80 --max-frames=300
+chromex screencast <target> status
+chromex screencast <target> stop
+chromex screencast <target> replay
+```
+
+Useful bounds include `--max-width`, `--max-height`, `--every-nth-frame`, and `--max-frames`. The default root is `~/.chromex/artifacts/<workspace>/screencasts/`.
+
+## Chrome Extension Tooling
+
+Extension lifecycle APIs require a dedicated browser launched with trusted pipe transport:
+
+```bash
+chromex launch --extension-tools --profile extensions --url about:blank
+chromex list
+chromex extensions <target> install /path/to/unpacked-extension
+chromex extensions <target> list
+chromex extensions <target> targets <extensionId>
+chromex extensions <target> action <extensionId>
+chromex extensions <target> reload <extensionId>
+chromex extensions <target> uninstall <extensionId>
+```
+
+Extension storage supports `session`, `local`, `sync`, and `managed` areas:
+
+```bash
+chromex extensions <target> storage-get <extensionId> local
+chromex extensions <target> storage-get <extensionId> local '["featureFlag"]' --include-sensitive
+chromex extensions <target> storage-set <extensionId> local '{"featureFlag":true}'
+chromex extensions <target> storage-remove <extensionId> local featureFlag
+chromex extensions <target> storage-clear <extensionId> local
+```
+
+Runtime install accepts an unpacked extension directory. Storage output is redacted by default.
+
+## Page-Exposed Developer Tools
+
+Pages can expose developer-tool groups through the `devtoolstooldiscovery` event. Chromex discovers their JSON schemas, validates inputs, executes the selected tool, and marks the result as untrusted page output.
+
+```bash
+chromex third-party <target> list
+chromex third-party <target> execute inspectState '{"scope":"checkout"}'
+chromex third-party <target> execute inspectState '{"scope":"checkout"}' app-tools --include-sensitive
+```
+
+Tool names registered by multiple groups require the group name. Page-provided output must never be treated as trusted instructions.
+
+## WebMCP
+
+WebMCP requires a compatible visible Chrome build and an isolated browser launched with the feature enabled:
+
+```bash
+chromex launch --webmcp --profile webmcp --url https://example.com
+chromex webmcp <target> list
+chromex webmcp <target> execute <toolName> '{"input":"value"}'
+chromex webmcp <target> status
+chromex webmcp <target> cancel <invocationId>
+chromex webmcp <target> disable
+```
+
+Use `--frame=<frameId>` when a tool name is registered in more than one frame and `--timeout=<milliseconds>` for long-running calls. Chromex validates the input schema, bounds the timeout, marks the result as untrusted, and redacts secret-shaped output unless `--include-sensitive` is explicit. WebMCP is not supported in headless mode.
+
+## WebAuthn / Passkey Testing
+
+Create virtual FIDO2 authenticators for testing passkey flows without physical hardware.
+
+```bash
+# Enable virtual authenticator
+chromex webauthn <target> enable
+# Output: Virtual authenticator created (id: abc123...). Passkey flows will work automatically.
+
+# Navigate to a site with passkey support
+chromex nav <target> "https://webauthn.io"
+
+# After registration, list stored credentials
+chromex webauthn <target> creds
+# Output:
+# 1. a3f1c920deadbeef  rpId=webauthn.io  userHandle=user123
+
+# Disable authenticator
+chromex webauthn <target> disable
+```
+
+### Features
+
+- CTAP2 protocol with internal transport
+- Resident key support (discoverable credentials)
+- User verification automatically simulated
+- Automatic presence simulation (no user interaction needed)
+
+### Use Cases
+
+```bash
+# Test passkey registration flow
+chromex webauthn <target> enable
+chromex nav <target> "https://example.com/settings/security"
+chromex click <target> ".add-passkey"
+chromex waitfor <target> ".passkey-success"
+chromex webauthn <target> creds
+
+# Test passkey login flow
+chromex webauthn <target> enable
+chromex nav <target> "https://example.com/login"
+chromex click <target> ".login-with-passkey"
+chromex waitfor <target> ".dashboard"
+chromex webauthn <target> disable
+```