@crouton-kit/capture 1.3.1

package/src/cdp.ts

@@ -0,0 +1,2389 @@
+#!/usr/bin/env tsx
+/**
+ * CDP (Chrome DevTools Protocol) — browser automation via exec-first design.
+ *
+ * The agent writes arbitrary JS and passes it to `exec`. No training-wheel
+ * commands for click/type/wait — the agent composes whatever it needs.
+ *
+ * Commands:
+ *   capture exec <code>         Execute JS in a tab (the primary interface)
+ *   capture exec --file <path>  Execute JS from file
+ *   capture detect              Detect CDP port
+ *   capture list                List all browser tabs
+ *   capture open <url>          Open URL in browser (returns tab ID)
+ *   capture reset-tab <url>    Abandon stuck tab, open fresh one
+ *   capture screenshot          Capture screenshot
+ *   capture a11y                Get accessibility tree
+ *   capture record              Passive HAR recording
+ *   capture navigate <url>      Navigate + record HAR
+ *   capture har create|read|delete  Manage HAR recordings
+ *
+ * Options:
+ *   --port <port>       Override CDP port (auto-detects if not specified)
+ *   --target <tabId>    Target tab by exact ID (preferred, parallel-safe)
+ *   --new               Force open a new tab (open command)
+ *   --record            Enable HAR recording (exec)
+ *   --har <id>          Append traffic to a HAR recording
+ *   --har-out <path>    HAR output path
+ *   --file <path>       Read JS from file (exec)
+ *   --duration <secs>   Recording duration (record, default: 10)
+ *   --settle <ms>       Settle time after navigation (navigate, default: 2000)
+ *   --out <path>        Output path (screenshot)
+ *   --height <px>       Override viewport height (screenshot)
+ *   --full-page         Capture entire scrollable page (screenshot)
+ *   --json              JSON output (a11y)
+ *   --interactive       Interactive elements only (a11y)
+ */
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import WebSocket from 'ws';
+import {
+  type HAREntry,
+  harFilePath,
+  readHarRecording as readHarFile,
+  appendToHarRecording as appendToHar,
+  createHarRecording,
+  deleteHarRecording,
+} from './har-manager.js';
+import {
+  getActiveSession,
+  updateActiveSession,
+  nextStepPath,
+} from './session-context.js';
+import { clickByName, typeText, focusAndType } from './interact.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CDPTarget {
+  id: string;
+  title: string;
+  url: string;
+  type: string;
+  webSocketDebuggerUrl?: string;
+}
+
+interface ParsedArgs {
+  command: string;
+  positional: string[];
+  port?: number;
+  out?: string;
+  json?: boolean;
+  interactive?: boolean;
+  harOut?: string;
+  record?: boolean;
+  duration?: number;
+  settle?: number;
+  file?: string;
+  nested?: boolean;
+  har?: string;
+  new?: boolean;
+  target?: string;
+  role?: string;
+  into?: string;
+  noScreenshot?: boolean;
+  viewport?: string;
+  fullPage?: boolean;
+  height?: number;
+  help?: boolean;
+  filterUrl?: string;
+  filterStatus?: string;
+  filterMethod?: string;
+  limit?: number;
+}
+
+interface NetworkRequest {
+  requestId: string;
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  postData?: string;
+  timestamp: number;
+}
+
+interface NetworkResponse {
+  requestId: string;
+  url: string;
+  status: number;
+  headers: Record<string, string>;
+  body?: string;
+  timestamp: number;
+}
+
+// HAREntry imported from ./har-manager.ts
+
+// ============================================================================
+// HAR Recording
+// ============================================================================
+
+const SKIP_EXTENSIONS =
+  /\.(png|jpg|jpeg|gif|webp|svg|ico|woff2?|ttf|eot|css|mp4|webm|mp3)(\?|$)/i;
+const SKIP_DOMAINS =
+  /(google-analytics|googletagmanager|doubleclick|facebook\.com\/tr|px\.ads|analytics|tracking|beacon|telemetry)/i;
+const MAX_BODY_SIZE = 256 * 1024; // 256KB per response body in HAR
+
+function shouldRecordRequest(url: string): boolean {
+  if (SKIP_EXTENSIONS.test(url)) return false;
+  if (SKIP_DOMAINS.test(url)) return false;
+  return true;
+}
+
+export class HARRecorder {
+  private requests = new Map<string, NetworkRequest>();
+  private responses = new Map<string, NetworkResponse>();
+
+  constructor(private client: CDPClient) {}
+
+  get responseCount(): number {
+    return this.responses.size;
+  }
+
+  async start(): Promise<void> {
+    await this.client.send('Network.enable');
+
+    this.client.on('Network.requestWillBeSent', (params: unknown) => {
+      const p = params as {
+        requestId: string;
+        request: {
+          url: string;
+          method: string;
+          headers: Record<string, string>;
+          postData?: string;
+        };
+        timestamp: number;
+      };
+      if (!shouldRecordRequest(p.request.url)) return;
+      this.requests.set(p.requestId, {
+        requestId: p.requestId,
+        url: p.request.url,
+        method: p.request.method,
+        headers: p.request.headers,
+        postData: p.request.postData,
+        timestamp: p.timestamp,
+      });
+    });
+
+    this.client.on('Network.responseReceived', (params: unknown) => {
+      const p = params as {
+        requestId: string;
+        response: {
+          url: string;
+          status: number;
+          headers: Record<string, string>;
+        };
+        timestamp: number;
+      };
+      if (!this.requests.has(p.requestId)) return;
+      this.responses.set(p.requestId, {
+        requestId: p.requestId,
+        url: p.response.url,
+        status: p.response.status,
+        headers: p.response.headers,
+        timestamp: p.timestamp,
+      });
+    });
+  }
+
+  private buildHar(): { log: { entries: HAREntry[] } } {
+    return {
+      log: {
+        entries: Array.from(this.responses.values()).map((resp) => {
+          const req = this.requests.get(resp.requestId);
+          return {
+            startedDateTime: new Date(resp.timestamp * 1000).toISOString(),
+            request: {
+              method: req?.method ?? 'GET',
+              url: resp.url,
+              headers: Object.entries(req?.headers ?? {}).map(
+                ([name, value]) => ({ name, value }),
+              ),
+              postData: req?.postData ? { text: req.postData } : undefined,
+            },
+            response: {
+              status: resp.status,
+              headers: Object.entries(resp.headers).map(([name, value]) => ({
+                name,
+                value,
+              })),
+              content: { text: resp.body },
+            },
+          };
+        }),
+      },
+    };
+  }
+
+  async finish(): Promise<{ log: { entries: HAREntry[] } }> {
+    // Fetch response bodies in parallel — sequential fetches with 5s timeouts
+    // were causing ~50s hangs when many responses had evicted bodies
+    await Promise.allSettled(
+      Array.from(this.responses.entries()).map(async ([reqId, resp]) => {
+        const bodyResult = (await this.client.send('Network.getResponseBody', {
+          requestId: reqId,
+        }, 5000)) as {
+          body: string;
+          base64Encoded: boolean;
+        };
+        const decoded = bodyResult.base64Encoded
+          ? Buffer.from(bodyResult.body, 'base64').toString()
+          : bodyResult.body;
+        resp.body = decoded.length > MAX_BODY_SIZE
+          ? decoded.slice(0, MAX_BODY_SIZE) + `\n[truncated: ${decoded.length} bytes]`
+          : decoded;
+      }),
+    );
+
+    return this.buildHar();
+  }
+
+  finishPartial(): { log: { entries: HAREntry[] } } {
+    return this.buildHar();
+  }
+}
+
+// ============================================================================
+// Console Capture
+// ============================================================================
+
+export interface ConsoleEntry {
+  level: 'log' | 'warning' | 'error' | 'info' | 'debug';
+  text: string;
+  timestamp: number;
+  source?: string;
+}
+
+export class ConsoleRecorder {
+  private entries: ConsoleEntry[] = [];
+
+  constructor(private client: CDPClient) {}
+
+  async start(): Promise<void> {
+    await this.client.send('Runtime.enable');
+
+    this.client.on('Runtime.consoleAPICalled', (params: unknown) => {
+      const p = params as {
+        type: string;
+        args: Array<{ type: string; value?: unknown; description?: string }>;
+        timestamp: number;
+      };
+      const text = p.args
+        .map((a) =>
+          a.value !== undefined ? String(a.value) : (a.description ?? ''),
+        )
+        .join(' ');
+      this.entries.push({
+        level: p.type as ConsoleEntry['level'],
+        text,
+        timestamp: p.timestamp,
+      });
+    });
+
+    this.client.on('Runtime.exceptionThrown', (params: unknown) => {
+      const p = params as {
+        timestamp: number;
+        exceptionDetails: {
+          exception?: { description?: string };
+          text?: string;
+          url?: string;
+          lineNumber?: number;
+        };
+      };
+      this.entries.push({
+        level: 'error',
+        text:
+          p.exceptionDetails.exception?.description ??
+          p.exceptionDetails.text ??
+          'Unknown exception',
+        timestamp: p.timestamp,
+        source: p.exceptionDetails.url
+          ? `${p.exceptionDetails.url}:${p.exceptionDetails.lineNumber}`
+          : undefined,
+      });
+    });
+  }
+
+  finish(): ConsoleEntry[] {
+    return [...this.entries];
+  }
+}
+
+function printConsoleSummary(entries: ConsoleEntry[]): void {
+  const errors = entries.filter((e) => e.level === 'error');
+  const warnings = entries.filter((e) => e.level === 'warning');
+  if (errors.length > 0 || warnings.length > 0) {
+    console.error(
+      `\nConsole: ${errors.length} errors, ${warnings.length} warnings`,
+    );
+    for (const entry of [...errors, ...warnings]) {
+      const prefix = entry.level === 'error' ? 'ERR' : 'WARN';
+      const src = entry.source ? ` (${entry.source})` : '';
+      const text =
+        entry.text.length > 200 ? entry.text.slice(0, 197) + '...' : entry.text;
+      console.error(`  [${prefix}] ${text}${src}`);
+    }
+  }
+}
+
+function writeHarAndPrintSummary(
+  har: { log: { entries: HAREntry[] } },
+  harOutPath?: string,
+): string | undefined {
+  if (har.log.entries.length === 0 && !harOutPath) return undefined;
+
+  const harPath = harOutPath ?? `/tmp/capture-har-${Date.now()}.json`;
+  try {
+    fs.writeFileSync(harPath, JSON.stringify(har, null, 2));
+  } catch (err) {
+    // Fallback: strip response bodies and retry
+    const stripped = {
+      log: {
+        ...har.log,
+        entries: har.log.entries.map((e) => ({
+          ...e,
+          response: { ...e.response, content: { text: '[body stripped — too large to serialize]' } },
+        })),
+      },
+    };
+    fs.writeFileSync(harPath, JSON.stringify(stripped, null, 2));
+    console.error('  WARNING: Response bodies stripped from HAR (too large to serialize)');
+  }
+
+  // Print summary to stderr
+  const errors = har.log.entries.filter((e) => e.response.status >= 400);
+  console.error(
+    `\nHAR: ${har.log.entries.length} requests captured → ${harPath}`,
+  );
+  if (errors.length > 0) {
+    console.error(`  ${errors.length} failed:`);
+    for (const entry of errors) {
+      const method = entry.request.method.padEnd(6);
+      const status = entry.response.status;
+      const url =
+        entry.request.url.length > 100
+          ? entry.request.url.slice(0, 97) + '...'
+          : entry.request.url;
+      console.error(`  ${method} ${status} ${url}`);
+    }
+  }
+
+  return harPath;
+}
+
+// ============================================================================
+// CLI Argument Parser
+// ============================================================================
+
+function parseCliArgs(argv: string[]): ParsedArgs {
+  const command = argv[0] ?? '';
+  const positional: string[] = [];
+  const parsed: Partial<ParsedArgs> = { command, positional };
+
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+
+    if (arg === '--port' && next) {
+      parsed.port = parseInt(next, 10);
+      i++;
+    } else if (arg === '--out' && next) {
+      parsed.out = next;
+      i++;
+    } else if (arg === '--json') {
+      parsed.json = true;
+    } else if (arg === '--interactive') {
+      parsed.interactive = true;
+    } else if (arg === '--har-out' && next) {
+      parsed.harOut = next;
+      i++;
+    } else if (arg === '--record') {
+      parsed.record = true;
+    } else if (arg === '--duration' && next) {
+      parsed.duration = parseInt(next, 10);
+      i++;
+    } else if (arg === '--settle' && next) {
+      parsed.settle = parseInt(next, 10);
+      i++;
+    } else if (arg === '--file' && next) {
+      parsed.file = next;
+      i++;
+    } else if (arg === '--nested') {
+      parsed.nested = true;
+    } else if (arg === '--har' && next) {
+      parsed.har = next;
+      i++;
+    } else if (arg === '--new') {
+      parsed.new = true;
+    } else if (arg === '--target' && next) {
+      parsed.target = next;
+      i++;
+    } else if (arg === '--role' && next) {
+      parsed.role = next;
+      i++;
+    } else if (arg === '--into' && next) {
+      parsed.into = next;
+      i++;
+    } else if (arg === '--no-screenshot') {
+      parsed.noScreenshot = true;
+    } else if (arg === '--viewport' && next) {
+      parsed.viewport = next;
+      i++;
+    } else if (arg === '--full-page') {
+      parsed.fullPage = true;
+    } else if (arg === '--height' && next) {
+      parsed.height = parseInt(next, 10);
+      i++;
+    } else if (arg === '--filter-url' && next) {
+      parsed.filterUrl = next;
+      i++;
+    } else if (arg === '--filter-status' && next) {
+      parsed.filterStatus = next;
+      i++;
+    } else if (arg === '--filter-method' && next) {
+      parsed.filterMethod = next.toUpperCase();
+      i++;
+    } else if (arg === '--limit' && next) {
+      parsed.limit = parseInt(next, 10);
+      i++;
+    } else if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    } else if (arg.startsWith('--')) {
+      console.error(`Unknown flag: ${arg}`);
+      process.exit(1);
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  // Fill gaps from environment variables (set by pipeline orchestrators)
+  if (!parsed.target && process.env.CDP_TARGET) {
+    parsed.target = process.env.CDP_TARGET;
+  }
+  if (!parsed.har && process.env.CDP_HAR_ID) {
+    parsed.har = process.env.CDP_HAR_ID;
+  }
+
+  // Fill remaining gaps from active session context (explicit flags always win)
+  const session = getActiveSession();
+  if (session) {
+    if (!parsed.har && session.harId) parsed.har = session.harId;
+    if (!parsed.target && session.targetId) parsed.target = session.targetId;
+  }
+
+  return parsed as ParsedArgs;
+}
+
+// ============================================================================
+// HAR Recording Management (delegated to har-manager.ts)
+// ============================================================================
+
+// ============================================================================
+// Connection Helpers
+// ============================================================================
+
+async function connectForCommand(
+  parsed: ParsedArgs,
+): Promise<{ client: CDPClient; tab: CDPTarget }> {
+  if (!parsed.target) {
+    throw new Error('Use --target <tabId> to target a tab. Run "capture list" to see available tabs.');
+  }
+
+  // If --port is explicit, search only that port. Otherwise search all endpoints.
+  let tab: CDPTarget | null = null;
+  if (parsed.port) {
+    tab = await findTabById(parsed.port, parsed.target);
+  } else {
+    const endpoints = await detectCdpPortsAsync();
+    for (const ep of endpoints) {
+      try {
+        tab = await findTabById(ep.port, parsed.target);
+        if (tab) break;
+      } catch {
+        // Skip endpoints that fail
+      }
+    }
+  }
+
+  if (!tab) {
+    const query = parsed.target;
+    throw new Error(
+      `No tab found for target "${query}". Run "capture list" to see available tabs.`,
+    );
+  }
+
+  if (!tab.webSocketDebuggerUrl) {
+    throw new Error('Tab has no WebSocket debugger URL');
+  }
+
+  // Lazy-populate targetId in active session if not yet set
+  const activeSession = getActiveSession();
+  if (activeSession && !activeSession.targetId) {
+    updateActiveSession({ targetId: tab.id });
+  }
+
+  const client = new CDPClient(tab.webSocketDebuggerUrl);
+  await client.waitReady();
+
+  return { client, tab };
+}
+
+async function withConnection<T>(
+  parsed: ParsedArgs,
+  fn: (client: CDPClient, tab: CDPTarget) => Promise<T>,
+  opts: { settle?: number } = {},
+): Promise<T> {
+  const { client, tab } = await connectForCommand(parsed);
+
+  const consoleRecorder = new ConsoleRecorder(client);
+  await consoleRecorder.start();
+
+  let harRecorder: HARRecorder | undefined;
+  if (parsed.har) {
+    // Validate HAR ID exists before starting recording
+    const harPath = harFilePath(parsed.har);
+    if (!fs.existsSync(harPath)) {
+      console.error(
+        `ERROR: No HAR recording found for --har "${parsed.har}". Run 'har create' first.`,
+      );
+      process.exit(1);
+    }
+    harRecorder = new HARRecorder(client);
+    await harRecorder.start();
+  }
+
+  try {
+    const result = await fn(client, tab);
+
+    // Wait for network activity triggered by the action, then append to HAR
+    if (harRecorder && parsed.har) {
+      const settle = opts.settle !== undefined ? opts.settle : 3000;
+      if (settle > 0) {
+        await new Promise((r) => setTimeout(r, settle));
+      }
+      const har = await harRecorder.finish();
+      if (har.log.entries.length > 0) {
+        appendToHar(parsed.har, har.log.entries);
+        console.error(
+          `  [har:${parsed.har}] +${har.log.entries.length} entries`,
+        );
+      }
+    }
+
+    printConsoleSummary(consoleRecorder.finish());
+
+    return result;
+  } finally {
+    client.close();
+  }
+}
+
+// ============================================================================
+// A11y Tree Flattening
+// ============================================================================
+
+const INTERACTIVE_ROLES = new Set([
+  'button',
+  'link',
+  'textbox',
+  'searchbox',
+  'combobox',
+  'checkbox',
+  'radio',
+  'menuitem',
+  'tab',
+  'switch',
+  'slider',
+  'spinbutton',
+  'option',
+  'menuitemcheckbox',
+  'menuitemradio',
+]);
+
+function flattenA11yTree(
+  nodes: A11yNode[],
+  opts: { interactive?: boolean } = {},
+  depth = 0,
+): string[] {
+  const lines: string[] = [];
+
+  for (const node of nodes) {
+    // Filter to interactive roles if requested
+    if (opts.interactive && !INTERACTIVE_ROLES.has(node.role)) {
+      lines.push(...flattenA11yTree(node.children, opts, depth));
+      continue;
+    }
+
+    // Skip nodes without meaningful role or name
+    if (!node.role || node.role === 'StaticText') {
+      lines.push(...flattenA11yTree(node.children, opts, depth));
+      continue;
+    }
+
+    const indent = '  '.repeat(depth);
+    const nameStr = node.name ? ` "${node.name}"` : '';
+    lines.push(`${indent}${node.role}${nameStr}`);
+
+    // Recurse
+    lines.push(...flattenA11yTree(node.children, opts, depth + 1));
+  }
+
+  return lines;
+}
+
+// ============================================================================
+// Browser Detection
+// ============================================================================
+
+const BROWSER_PATTERNS: Record<string, string[]> = {
+  'company.thebrowser.browser': ['arc'],
+  'com.google.chrome': ['chrome', 'google chrome'],
+  'com.brave.browser': ['brave'],
+  'com.microsoft.edgemac': ['edge', 'microsoft edge'],
+  'org.chromium.chromium': ['chromium'],
+};
+
+function getDefaultBrowserId(): string | null {
+  try {
+    const output = execSync(
+      'defaults read com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers 2>/dev/null',
+      { encoding: 'utf-8' },
+    );
+    const match = output.match(
+      /LSHandlerRoleAll = "([^"]+)";\s*LSHandlerURLScheme = https;/,
+    );
+    return match?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+interface CdpProbeResult {
+  browser: string;
+  app: string;
+  isElectron: boolean;
+}
+
+async function probeCdpPort(port: number): Promise<CdpProbeResult | null> {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 500);
+    const resp = await fetch(`http://localhost:${port}/json/version`, {
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    if (resp.ok) {
+      const version = (await resp.json()) as {
+        Browser?: string;
+        'User-Agent'?: string;
+      };
+      const browser = version.Browser;
+      const userAgent = version['User-Agent'] ?? '';
+      if (!browser) return null;
+
+      const isElectron = userAgent.includes('Electron');
+
+      // Extract app name from User-Agent for Electron apps
+      // Pattern: "AppName/1.2.3 Chrome/..." in the UA string
+      let app = browser;
+      if (isElectron) {
+        const appMatch = userAgent.match(
+          /(\S+?)\/[\d.]+ Chrome\/[\d.]+ Electron/,
+        );
+        if (appMatch) app = appMatch[1];
+      }
+
+      return { browser, app, isElectron };
+    }
+  } catch {
+    // Not a CDP port or not responding
+  }
+  return null;
+}
+
+function getLocalhostListeningPorts(): number[] {
+  try {
+    // netstat is much faster than lsof on macOS
+    const output = execSync(
+      'netstat -an 2>/dev/null | grep "127.0.0.1.*LISTEN"',
+      { encoding: 'utf-8' },
+    );
+    const ports: number[] = [];
+    for (const line of output.split('\n')) {
+      // Format: tcp4       0      0  127.0.0.1.56192        *.*                    LISTEN
+      const match = line.match(/127\.0\.0\.1\.(\d+)/);
+      if (match) {
+        ports.push(parseInt(match[1], 10));
+      }
+    }
+    return ports;
+  } catch {
+    return [];
+  }
+}
+
+interface CdpEndpoint {
+  port: number;
+  app: string;
+  bundleId: string;
+  isElectron: boolean;
+}
+
+async function detectCdpPortsAsync(): Promise<CdpEndpoint[]> {
+  const ports = getLocalhostListeningPorts();
+  const results: CdpEndpoint[] = [];
+
+  // Probe ports in parallel for speed
+  const probes = ports.map(async (port) => {
+    const probe = await probeCdpPort(port);
+    if (probe) {
+      // Map browser string to bundle ID for default browser matching
+      const lower = probe.browser.toLowerCase();
+      let bundleId = 'unknown';
+      for (const [bid, patterns] of Object.entries(BROWSER_PATTERNS)) {
+        if (patterns.some((p) => lower.includes(p))) {
+          bundleId = bid;
+          break;
+        }
+      }
+      results.push({
+        port,
+        app: probe.app,
+        bundleId,
+        isElectron: probe.isElectron,
+      });
+    }
+  });
+
+  await Promise.all(probes);
+  return results;
+}
+
+export async function detectCdpPort(): Promise<number> {
+  const endpoints = await detectCdpPortsAsync();
+  if (endpoints.length === 0) {
+    throw new Error(
+      'No browser with CDP found. Start your browser with remote debugging enabled:\n' +
+        '  Arc: Already enabled by default\n' +
+        '  Chrome: --remote-debugging-port=9222\n' +
+        '  Electron apps expose CDP automatically',
+    );
+  }
+
+  // Use default browser if available (prefer non-Electron)
+  const defaultBrowser = getDefaultBrowserId();
+  if (defaultBrowser) {
+    const match = endpoints.find(
+      (p) => p.bundleId === defaultBrowser && !p.isElectron,
+    );
+    if (match) return match.port;
+  }
+
+  // Fall back to first non-Electron, then first found
+  const nonElectron = endpoints.find((p) => !p.isElectron);
+  return (nonElectron ?? endpoints[0]).port;
+}
+
+// ============================================================================
+// CDP Connection (Browser-level)
+// ============================================================================
+
+async function getBrowserClient(
+  port: number,
+): Promise<{ client: CDPClient; browserWsUrl: string }> {
+  const versionResp = await fetch(`http://localhost:${port}/json/version`);
+  if (!versionResp.ok) {
+    throw new Error(
+      `Failed to connect to CDP on port ${port}: ${versionResp.status}`,
+    );
+  }
+  const version = (await versionResp.json()) as {
+    webSocketDebuggerUrl: string;
+  };
+  const client = new CDPClient(version.webSocketDebuggerUrl);
+  await client.waitReady();
+  return { client, browserWsUrl: version.webSocketDebuggerUrl };
+}
+
+export async function listTargets(port: number): Promise<CDPTarget[]> {
+  const { client } = await getBrowserClient(port);
+
+  try {
+    // Enable target discovery to get all targets including pages
+    await client.send('Target.setDiscoverTargets', { discover: true });
+    const result = (await client.send('Target.getTargets')) as {
+      targetInfos: Array<{
+        targetId: string;
+        type: string;
+        title: string;
+        url: string;
+      }>;
+    };
+
+    // Convert to CDPTarget format with webSocketDebuggerUrl
+    return result.targetInfos.map((t) => ({
+      id: t.targetId,
+      title: t.title,
+      url: t.url,
+      type: t.type,
+      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${t.targetId}`,
+    }));
+  } finally {
+    client.close();
+  }
+}
+
+export async function findTab(
+  port: number,
+  urlPattern?: string,
+): Promise<CDPTarget | null> {
+  const targets = await listTargets(port);
+  const pages = targets.filter((t) => t.type === 'page');
+
+  if (!urlPattern) {
+    // Return first page
+    return pages[0] ?? null;
+  }
+
+  // Find by URL pattern
+  const pattern = urlPattern.toLowerCase();
+  return pages.find((t) => t.url.toLowerCase().includes(pattern)) ?? null;
+}
+
+export async function findTabById(
+  port: number,
+  targetId: string,
+): Promise<CDPTarget | null> {
+  const targets = await listTargets(port);
+  // Exact match first
+  const exact = targets.find((t) => t.id === targetId);
+  if (exact) return exact;
+  // Prefix match (min 4 chars to avoid ambiguity)
+  if (targetId.length >= 4) {
+    const prefix = targetId.toUpperCase();
+    const matches = targets.filter((t) => t.id.toUpperCase().startsWith(prefix));
+    if (matches.length === 1) return matches[0];
+    if (matches.length > 1) {
+      throw new Error(
+        `Ambiguous target prefix "${targetId}" matches ${matches.length} tabs:\n` +
+          matches.map((t) => `  ${t.id.slice(0, 8)}  ${t.url}`).join('\n'),
+      );
+    }
+  }
+  return null;
+}
+
+export async function openTab(port: number, url: string): Promise<CDPTarget> {
+  const { client } = await getBrowserClient(port);
+
+  try {
+    // Create new target in background to avoid stealing user's focus
+    const result = (await client.send('Target.createTarget', {
+      url,
+      background: true,
+    })) as {
+      targetId: string;
+    };
+
+    // Return target info
+    return {
+      id: result.targetId,
+      title: '',
+      url,
+      type: 'page',
+      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${result.targetId}`,
+    };
+  } finally {
+    client.close();
+  }
+}
+
+// ============================================================================
+// CDP WebSocket Client
+// ============================================================================
+
+export class CDPClient {
+  private ws: WebSocket;
+  private messageId = 0;
+  private pendingRequests = new Map<
+    number,
+    { resolve: (v: unknown) => void; reject: (e: Error) => void }
+  >();
+  private pendingTimeouts = new Map<number, NodeJS.Timeout>();
+  private eventHandlers = new Map<string, Array<(params: unknown) => void>>();
+  private ready: Promise<void>;
+
+  constructor(wsUrl: string, connectTimeout = 5000) {
+    this.ws = new WebSocket(wsUrl);
+    this.ready = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`WebSocket connection timeout (${connectTimeout}ms)`));
+      }, connectTimeout);
+
+      this.ws.on('open', () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+      this.ws.on('error', (err) => {
+        clearTimeout(timeout);
+        reject(err);
+      });
+    });
+
+    this.ws.on('message', (data: Buffer) => {
+      const msg = JSON.parse(data.toString());
+      if (msg.id !== undefined) {
+        const pending = this.pendingRequests.get(msg.id);
+        if (pending) {
+          this.pendingRequests.delete(msg.id);
+          const timer = this.pendingTimeouts.get(msg.id);
+          if (timer) {
+            clearTimeout(timer);
+            this.pendingTimeouts.delete(msg.id);
+          }
+          if (msg.error) {
+            pending.reject(new Error(msg.error.message));
+          } else {
+            pending.resolve(msg.result);
+          }
+        }
+      } else if (msg.method) {
+        const handlers = this.eventHandlers.get(msg.method);
+        handlers?.forEach((h) => h(msg.params));
+      }
+    });
+  }
+
+  async waitReady(): Promise<void> {
+    await this.ready;
+  }
+
+  async send(
+    method: string,
+    params: Record<string, unknown> = {},
+    timeout = 60000,
+  ): Promise<unknown> {
+    await this.ready;
+    const id = ++this.messageId;
+
+    return new Promise((resolve, reject) => {
+      this.pendingRequests.set(id, { resolve, reject });
+      this.ws.send(JSON.stringify({ id, method, params }));
+
+      const timer = setTimeout(() => {
+        if (this.pendingRequests.has(id)) {
+          this.pendingRequests.delete(id);
+          this.pendingTimeouts.delete(id);
+          reject(new Error(`CDP request timeout (${timeout}ms): ${method}`));
+        }
+      }, timeout);
+      this.pendingTimeouts.set(id, timer);
+    });
+  }
+
+  on(event: string, handler: (params: unknown) => void): void {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, []);
+    }
+    this.eventHandlers.get(event)!.push(handler);
+  }
+
+  close(): void {
+    // Clear all pending timeouts to allow process to exit
+    for (const timer of this.pendingTimeouts.values()) {
+      clearTimeout(timer);
+    }
+    this.pendingTimeouts.clear();
+    this.ws.close();
+  }
+}
+
+// ============================================================================
+// Capture Utilities
+// ============================================================================
+
+export async function captureScreenshot(
+  client: CDPClient,
+  viewport?: { width: number; height: number },
+  options?: { fullPage?: boolean },
+): Promise<Buffer> {
+  const MAX_DIM = 1600; // headroom below Anthropic's 2000px many-image limit
+
+  // Apply viewport emulation if requested
+  if (viewport) {
+    await client.send('Emulation.setDeviceMetricsOverride', {
+      width: viewport.width,
+      height: viewport.height,
+      deviceScaleFactor: 1,
+      mobile: false,
+    });
+    // Let the page re-layout at the new size
+    await new Promise((r) => setTimeout(r, 150));
+  }
+
+  // For full-page capture, resize viewport to the full content height
+  if (options?.fullPage) {
+    const layoutMetrics = (await client.send('Page.getLayoutMetrics')) as {
+      contentSize?: { width: number; height: number };
+      cssVisualViewport?: { clientWidth: number };
+    };
+    const contentWidth = layoutMetrics.cssVisualViewport?.clientWidth ?? viewport?.width ?? 1280;
+    const contentHeight = layoutMetrics.contentSize?.height ?? viewport?.height ?? 800;
+    await client.send('Emulation.setDeviceMetricsOverride', {
+      width: contentWidth,
+      height: Math.ceil(contentHeight),
+      deviceScaleFactor: 1,
+      mobile: false,
+    });
+    await new Promise((r) => setTimeout(r, 150));
+  }
+
+  let screenshotOpts: Record<string, unknown> = {
+    format: 'png',
+    captureBeyondViewport: false,
+  };
+
+  try {
+    const metrics = (await client.send('Page.getLayoutMetrics')) as {
+      cssVisualViewport?: { clientWidth: number; clientHeight: number; pageX: number; pageY: number };
+    };
+    const vw = metrics.cssVisualViewport?.clientWidth ?? 0;
+    const vh = metrics.cssVisualViewport?.clientHeight ?? 0;
+    const sx = metrics.cssVisualViewport?.pageX ?? 0;
+    const sy = metrics.cssVisualViewport?.pageY ?? 0;
+
+    const dprResult = (await client.send('Runtime.evaluate', {
+      expression: 'window.devicePixelRatio',
+      returnByValue: true,
+    })) as { result: { value: number } };
+    const dpr = dprResult.result.value ?? 1;
+
+    const actualMaxSide = Math.max(vw, vh) * dpr;
+    const scale = actualMaxSide > MAX_DIM ? MAX_DIM / actualMaxSide : 1 / dpr;
+    screenshotOpts = {
+      ...screenshotOpts,
+      clip: { x: sx, y: sy, width: vw, height: vh, scale },
+    };
+  } catch {
+    // Fallback: capture without downscaling
+  }
+
+  const result = (await client.send(
+    'Page.captureScreenshot',
+    screenshotOpts,
+  )) as { data: string };
+
+  // Reset emulation so the browser window isn't stuck at the overridden size
+  if (viewport || options?.fullPage) {
+    await client.send('Emulation.clearDeviceMetricsOverride');
+  }
+
+  return Buffer.from(result.data, 'base64');
+}
+
+interface AXNode {
+  nodeId: string;
+  role?: { value: string };
+  name?: { value: string };
+  childIds?: string[];
+  properties?: Array<{ name: string; value: { value: unknown } }>;
+}
+
+export interface A11yNode {
+  role: string;
+  name: string;
+  children: A11yNode[];
+}
+
+export async function getAccessibilityTree(
+  client: CDPClient,
+): Promise<A11yNode[]> {
+  await client.send('Accessibility.enable');
+  const result = (await client.send('Accessibility.getFullAXTree')) as {
+    nodes: AXNode[];
+  };
+  await client.send('Accessibility.disable');
+
+  const nodeMap = new Map<string, AXNode>();
+  for (const node of result.nodes) {
+    nodeMap.set(node.nodeId, node);
+  }
+
+  const SKIP_ROLES = new Set(['none', 'generic', 'InlineTextBox']);
+
+  function buildNode(node: AXNode): A11yNode[] {
+    const role = node.role?.value ?? '';
+    const childNodes = (node.childIds ?? []).flatMap((id) => {
+      const child = nodeMap.get(id);
+      return child ? buildNode(child) : [];
+    });
+
+    if (SKIP_ROLES.has(role)) {
+      return childNodes;
+    }
+
+    return [
+      {
+        role,
+        name: node.name?.value ?? '',
+        children: childNodes,
+      },
+    ];
+  }
+
+  const root = result.nodes[0];
+  return root ? buildNode(root) : [];
+}
+
+// ============================================================================
+// Code Execution
+// ============================================================================
+
+export interface ExecuteOptions {
+  port?: number;
+  targetId?: string;
+  record?: boolean;
+  harOutPath?: string;
+  timeoutMs?: number;
+}
+
+export interface ExecuteResult {
+  success: boolean;
+  value?: unknown;
+  error?: string;
+  har?: { log: { entries: HAREntry[] } };
+  console: ConsoleEntry[];
+}
+
+export async function executeInBrowser(
+  code: string,
+  options: ExecuteOptions = {},
+): Promise<ExecuteResult> {
+  const port = options.port ?? (await detectCdpPort());
+
+  if (!options.targetId) {
+    throw new Error('Use --target <tabId> to target a tab. Run "capture list" to see available tabs.');
+  }
+
+  // Find tab by exact/prefix ID
+  let tab: CDPTarget | null = null;
+  tab = await findTabById(port, options.targetId);
+  if (!tab) {
+    throw new Error(
+      `No tab found for target "${options.targetId}". Run "capture list" to see available tabs.`,
+    );
+  }
+
+  if (!tab.webSocketDebuggerUrl) {
+    throw new Error('Tab has no WebSocket debugger URL');
+  }
+
+  const client = new CDPClient(tab.webSocketDebuggerUrl);
+  await client.waitReady();
+
+  // Emulate focus so network requests aren't deferred by the browser,
+  // without actually bringing the tab to the foreground
+  await client.send('Emulation.setFocusEmulationEnabled', { enabled: true });
+
+  const consoleRecorder = new ConsoleRecorder(client);
+  await consoleRecorder.start();
+
+  let harRecorder: HARRecorder | undefined;
+  if (options.record) {
+    harRecorder = new HARRecorder(client);
+    await harRecorder.start();
+  }
+
+  try {
+    // Execute code
+    const result = (await client.send(
+      'Runtime.evaluate',
+      {
+        expression: code,
+        awaitPromise: true,
+        returnByValue: true,
+      },
+      options.timeoutMs,
+    )) as {
+      result?: { value?: unknown };
+      exceptionDetails?: { exception?: { description?: string } };
+    };
+
+    // Build HAR if recording
+    let har: { log: { entries: HAREntry[] } } | undefined;
+    if (harRecorder) {
+      har = await harRecorder.finish();
+      writeHarAndPrintSummary(har, options.harOutPath);
+    }
+
+    const consoleEntries = consoleRecorder.finish();
+    printConsoleSummary(consoleEntries);
+    client.close();
+
+    if (result.exceptionDetails) {
+      return {
+        success: false,
+        error:
+          result.exceptionDetails.exception?.description ?? 'Unknown error',
+        har,
+        console: consoleEntries,
+      };
+    }
+
+    return {
+      success: true,
+      value: result.result?.value,
+      har,
+      console: consoleEntries,
+    };
+  } catch (err) {
+    const consoleEntries = consoleRecorder.finish();
+    client.close();
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+      console: consoleEntries,
+    };
+  }
+}
+
+// ============================================================================
+// Passive HAR Recording
+// ============================================================================
+
+export interface RecordOptions {
+  port?: number;
+  targetId?: string;
+  duration?: number;
+  harOutPath?: string;
+}
+
+export interface RecordResult {
+  harPath: string | undefined;
+  entryCount: number;
+  har: { log: { entries: HAREntry[] } };
+}
+
+export async function recordTraffic(
+  options: RecordOptions,
+): Promise<RecordResult> {
+  const port = options.port ?? (await detectCdpPort());
+  const duration = options.duration ?? 10;
+
+  if (!options.targetId) {
+    throw new Error('Use --target <tabId> to target a tab. Run "capture list" to see available tabs.');
+  }
+
+  const tab = await findTabById(port, options.targetId);
+  if (!tab) {
+    throw new Error(
+      `No tab found for target "${options.targetId}". Run "capture list" to see available tabs.`,
+    );
+  }
+
+  if (!tab.webSocketDebuggerUrl) {
+    throw new Error('Tab has no WebSocket debugger URL');
+  }
+
+  const client = new CDPClient(tab.webSocketDebuggerUrl);
+  await client.waitReady();
+
+  const recorder = new HARRecorder(client);
+  await recorder.start();
+
+  console.error(
+    `Recording traffic on "${tab.url}" for ${duration}s... (click around in the browser)`,
+  );
+
+  await new Promise((r) => setTimeout(r, duration * 1000));
+
+  const har = await recorder.finish();
+  const harPath = writeHarAndPrintSummary(har, options.harOutPath);
+
+  client.close();
+
+  return { harPath, entryCount: har.log.entries.length, har };
+}
+
+// ============================================================================
+// Navigate + Record
+// ============================================================================
+
+export interface NavigateAndRecordOptions {
+  port?: number;
+  url: string;
+  targetId?: string;
+  harOutPath?: string;
+  settle?: number;
+}
+
+export interface NavigateAndRecordResult {
+  harPath: string | undefined;
+  entryCount: number;
+  har: { log: { entries: HAREntry[] } };
+  tab: CDPTarget;
+  timedOut: boolean;
+}
+
+export async function navigateAndRecord(
+  options: NavigateAndRecordOptions,
+): Promise<NavigateAndRecordResult> {
+  const port = options.port ?? (await detectCdpPort());
+  const settle = options.settle ?? 2000;
+
+  // Find tab — prefer targetId (exact) over domain match (fuzzy)
+  let tab: CDPTarget | null = null;
+  let isNewTab = false;
+  if (options.targetId) {
+    tab = await findTabById(port, options.targetId);
+    if (!tab) {
+      throw new Error(
+        `No tab found with target ID "${options.targetId}". Tab may have been closed.`,
+      );
+    }
+  } else {
+    let domain: string;
+    try {
+      domain = new URL(options.url).hostname;
+    } catch {
+      throw new Error(`Invalid URL: ${options.url}`);
+    }
+    tab = await findTab(port, domain);
+    if (!tab) {
+      tab = await openTab(port, options.url);
+      isNewTab = true;
+    }
+  }
+  if (!tab.webSocketDebuggerUrl) {
+    throw new Error('Tab has no WebSocket debugger URL');
+  }
+
+  const client = new CDPClient(tab.webSocketDebuggerUrl);
+  await client.waitReady();
+  await client.send('Page.enable');
+
+  // Start recording BEFORE navigation
+  const recorder = new HARRecorder(client);
+  await recorder.start();
+
+  if (!isNewTab) {
+    // Navigate existing tab
+    console.error(`Navigating to: ${options.url}`);
+    await client.send('Page.navigate', { url: options.url });
+  }
+
+  const deadline = 60_000;
+  const t0 = Date.now();
+  let timedOut = false;
+  let har!: { log: { entries: HAREntry[] } };
+
+  try {
+    await Promise.race([
+      (async () => {
+        // Wait for load event
+        await new Promise<void>((resolve) => {
+          const timer = setTimeout(() => {
+            console.error('Page load timeout (10s), continuing with settle...');
+            resolve();
+          }, 10000);
+          client.on('Page.loadEventFired', () => {
+            clearTimeout(timer);
+            resolve();
+          });
+        });
+
+        // Settle time for SPAs that load after DOMContentLoaded
+        console.error(`Settling for ${settle}ms...`);
+        await new Promise((r) => setTimeout(r, settle));
+
+        har = await recorder.finish();
+      })(),
+      new Promise<never>((_, reject) => {
+        const t = setTimeout(() => reject(new Error('__navigate_timeout__')), deadline - (Date.now() - t0));
+        // Don't keep process alive just for the deadline timer
+        if (typeof t === 'object' && 'unref' in t) t.unref();
+      }),
+    ]);
+  } catch (err) {
+    if (err instanceof Error && err.message === '__navigate_timeout__') {
+      timedOut = true;
+      console.error('Navigate timeout (60s) — returning partial HAR');
+      har = recorder.finishPartial();
+    } else {
+      throw err;
+    }
+  }
+
+  const harPath = writeHarAndPrintSummary(har, options.harOutPath);
+
+  client.close();
+
+  // Refresh target info
+  const updatedTab = (await findTab(port, options.url)) ?? tab;
+
+  return { harPath, entryCount: har.log.entries.length, har, tab: updatedTab, timedOut };
+}
+
+// ============================================================================
+// Navigate and Wait
+// ============================================================================
+
+export async function navigateAndWait(
+  port: number,
+  url: string,
+  options: { timeout?: number; forceNew?: boolean } = {},
+): Promise<CDPTarget> {
+  const timeout = options.timeout ?? 10000;
+
+  // Check if tab already exists (unless forceNew requested)
+  if (!options.forceNew) {
+    const existing = await findTab(port, url);
+    if (existing) {
+      return existing;
+    }
+  }
+
+  // Open new tab
+  const tab = await openTab(port, url);
+  if (!tab.webSocketDebuggerUrl) {
+    throw new Error('New tab has no WebSocket debugger URL');
+  }
+
+  // Wait for page load
+  const client = new CDPClient(tab.webSocketDebuggerUrl);
+  await client.waitReady();
+  await client.send('Page.enable');
+
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`Page load timeout: ${url}`)),
+      timeout,
+    );
+    client.on('Page.loadEventFired', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+
+  client.close();
+
+  // Refresh target info — find by ID to avoid returning a different tab with same URL
+  const targets = await listTargets(port);
+  const refreshed = targets.find((t) => t.id === tab.id);
+  return refreshed ?? tab;
+}
+
+// ============================================================================
+// Tab-Level File Lock
+// ============================================================================
+
+const LOCK_DIR = os.tmpdir();
+const LOCK_STALE_MS = 120_000;
+const LOCK_TIMEOUT_MS = 60_000;
+const LOCK_POLL_BASE_MS = 200;
+
+function lockPath(tabId: string): string {
+  return path.join(LOCK_DIR, `capture-cdp-tab-${tabId}.lock`);
+}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isLockStale(filePath: string): boolean {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const { pid, ts } = JSON.parse(content) as { pid: number; ts: number };
+    if (!isPidAlive(pid)) return true;
+    return Date.now() - ts > LOCK_STALE_MS;
+  } catch {
+    return true;
+  }
+}
+
+// Track locks held by this process for cleanup on exit
+const heldLocks = new Set<string>();
+let cleanupRegistered = false;
+
+function registerCleanup(): void {
+  if (cleanupRegistered) return;
+  cleanupRegistered = true;
+
+  const cleanup = () => {
+    for (const file of heldLocks) {
+      try {
+        fs.unlinkSync(file);
+      } catch {
+        // Best-effort
+      }
+    }
+    heldLocks.clear();
+  };
+
+  process.on('exit', cleanup);
+  process.on('SIGINT', () => {
+    cleanup();
+    process.exit(130);
+  });
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(143);
+  });
+}
+
+export async function acquireTabLock(tabId: string): Promise<void> {
+  registerCleanup();
+  const file = lockPath(tabId);
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  let delay = LOCK_POLL_BASE_MS;
+
+  while (true) {
+    try {
+      const fd = fs.openSync(file, 'wx');
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+      fs.closeSync(fd);
+      heldLocks.add(file);
+      return;
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+    }
+
+    if (isLockStale(file)) {
+      try {
+        fs.unlinkSync(file);
+      } catch {
+        // Another process may have already removed it
+      }
+      continue;
+    }
+
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `Timed out waiting for CDP tab lock (${tabId}). ` +
+          `Another process may be using this tab. Lock file: ${file}`,
+      );
+    }
+
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(delay * 2, 2000);
+  }
+}
+
+export function isTabLocked(tabId: string): boolean {
+  const file = lockPath(tabId);
+  try {
+    fs.accessSync(file);
+    return !isLockStale(file);
+  } catch {
+    return false;
+  }
+}
+
+export function releaseTabLock(tabId: string): void {
+  const file = lockPath(tabId);
+  heldLocks.delete(file);
+  try {
+    fs.unlinkSync(file);
+  } catch {
+    // Already removed — fine
+  }
+}
+
+export async function withTabLock<T>(
+  tabId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  await acquireTabLock(tabId);
+  try {
+    return await fn();
+  } finally {
+    releaseTabLock(tabId);
+  }
+}
+
+// ============================================================================
+// Auto-Screenshot Helper
+// ============================================================================
+
+async function autoScreenshot(
+  client: CDPClient,
+  action: string,
+  label: string,
+  noScreenshot?: boolean,
+): Promise<string | null> {
+  if (noScreenshot) return null;
+  const shotPath = nextStepPath(action, label);
+  if (!shotPath) return null;
+
+  // Brief settle for UI to update
+  await new Promise((r) => setTimeout(r, 300));
+  const png = await captureScreenshot(client);
+  fs.writeFileSync(shotPath, png);
+  console.error(`  [screenshot] ${shotPath}`);
+  return shotPath;
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+async function main() {
+  const args = process.argv.slice(2);
+  const parsed = parseCliArgs(args);
+
+  switch (parsed.command) {
+    case 'detect': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture detect\n\n' +
+            'Detect CDP port (prioritizes default browser).\n' +
+            'Returns JSON with port, app name, and all discovered endpoints.',
+        );
+        process.exit(0);
+      }
+      const endpoints = await detectCdpPortsAsync();
+      if (endpoints.length === 0) {
+        console.error(
+          'ERROR: No browser with CDP found.\n\n' +
+            'Fix: Start a browser with remote debugging enabled:\n' +
+            '  Arc: Already enabled by default\n' +
+            '  Chrome: --remote-debugging-port=9222\n' +
+            '  Electron apps expose CDP automatically',
+        );
+        process.exit(1);
+      }
+      const defaultBrowser = getDefaultBrowserId();
+      const preferred =
+        endpoints.find(
+          (p) => p.bundleId === defaultBrowser && !p.isElectron,
+        ) ??
+        endpoints.find((p) => !p.isElectron) ??
+        endpoints[0];
+      console.log(
+        JSON.stringify(
+          {
+            port: preferred.port,
+            app: preferred.app,
+            isElectron: preferred.isElectron,
+            all: endpoints.map((e) => ({
+              port: e.port,
+              app: e.app,
+              isElectron: e.isElectron,
+            })),
+          },
+          null,
+          2,
+        ),
+      );
+      console.error(
+        `\nFound ${endpoints.length} CDP endpoint${endpoints.length > 1 ? 's' : ''}. Default: port ${preferred.port} (${preferred.app}).` +
+          `\n\nNext: capture list --port ${preferred.port}`,
+      );
+      break;
+    }
+
+    case 'list': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture list [--port <port>]\n\n' +
+            'List all browser tabs across all CDP endpoints (or a specific port).\n' +
+            'Returns JSON array of {id, title, url, port, app}.',
+        );
+        process.exit(0);
+      }
+      if (parsed.port) {
+        // Single port mode
+        const targets = await listTargets(parsed.port);
+        const pages = targets.filter((t) => t.type === 'page');
+        console.log(JSON.stringify(pages.map((t) => ({
+          id: t.id,
+          title: t.title,
+          url: t.url,
+        })), null, 2));
+        console.error(
+          `\n${pages.length} tab${pages.length !== 1 ? 's' : ''} on port ${parsed.port}.` +
+            `\n\nTarget a tab with: --target <id prefix>  (first 8 chars sufficient)`,
+        );
+      } else {
+        // All endpoints mode
+        const endpoints = await detectCdpPortsAsync();
+        if (endpoints.length === 0) {
+          console.error('No CDP endpoints found.');
+          process.exit(1);
+        }
+        const allPages: { id: string; title: string; url: string; port: number; app: string }[] = [];
+        await Promise.all(endpoints.map(async (ep) => {
+          try {
+            const targets = await listTargets(ep.port);
+            const pages = targets.filter((t) => t.type === 'page');
+            for (const t of pages) {
+              allPages.push({ id: t.id, title: t.title, url: t.url, port: ep.port, app: ep.app });
+            }
+          } catch {
+            // Skip endpoints that fail to respond
+          }
+        }));
+        console.log(JSON.stringify(allPages, null, 2));
+        console.error(
+          `\n${allPages.length} tab${allPages.length !== 1 ? 's' : ''} across ${endpoints.length} CDP endpoint${endpoints.length !== 1 ? 's' : ''}.` +
+            `\n\nTarget a tab with: --target <id prefix>  (first 8 chars sufficient)`,
+        );
+      }
+      break;
+    }
+
+    case 'open': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture open <url> [--new] [--port <port>]\n\n' +
+            'Open URL in browser (returns tab ID).\n\n' +
+            'Example: capture open "https://app.example.com" --new',
+        );
+        process.exit(0);
+      }
+      const url = parsed.positional[0];
+      if (!url) {
+        console.error(
+          'ERROR: Missing URL.\n\n' +
+            'Usage: capture open <url> [--new] [--port <port>]\n\n' +
+            'Example: capture open "https://app.example.com" --new',
+        );
+        process.exit(1);
+      }
+      const p = parsed.port ?? (await detectCdpPort());
+      const tab = await navigateAndWait(p, url, { forceNew: parsed.new });
+      console.log(JSON.stringify({
+        id: tab.id,
+        title: tab.title,
+        url: tab.url,
+        port: p,
+      }, null, 2));
+      console.error(
+        `\nOpened: ${tab.title || url}` +
+          `\n\nNext: capture exec "<js>" --port ${p} --target ${tab.id.slice(0, 8)}` +
+          `\n      capture screenshot --port ${p} --target ${tab.id.slice(0, 8)}` +
+          `\n      capture a11y --port ${p} --target ${tab.id.slice(0, 8)}`,
+      );
+      break;
+    }
+
+    case 'exec': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture exec <code> [--target <id>] [--record] [--file <path>] [--har <id>]\n\n' +
+            'Execute JavaScript in a browser tab. Supports await (wrapped in async IIFE).\n\n' +
+            'Examples:\n' +
+            '  capture exec "document.title" --target <id>\n' +
+            '  capture exec "await fetch(\'/api/data\').then(r=>r.json())" --target <id>\n' +
+            '  capture exec "document.querySelector(\'.btn\').click()" --target <id>\n' +
+            '  capture exec --file /tmp/scrape.js --target <id> --record',
+        );
+        process.exit(0);
+      }
+      let code: string;
+      if (parsed.file) {
+        code = fs.readFileSync(parsed.file, 'utf-8');
+      } else {
+        code = parsed.positional[0];
+        if (!code) {
+          console.error(
+            'ERROR: Missing code to execute.\n\n' +
+              'Usage: capture exec <code> [--target <id>] [--record] [--file <path>]\n\n' +
+              'Examples:\n' +
+              '  capture exec "document.title" --target <id>\n' +
+              '  capture exec "document.querySelector(\'.btn\').click()" --target <id>\n' +
+              '  capture exec --file /tmp/scrape.js --target <id> --record',
+          );
+          process.exit(1);
+        }
+      }
+
+      await withConnection(
+        parsed,
+        async (client) => {
+          await client.send('Emulation.setFocusEmulationEnabled', { enabled: true });
+
+          // Standalone HAR recording (--record flag writes its own file)
+          let standaloneRecorder: HARRecorder | undefined;
+          if (parsed.record) {
+            standaloneRecorder = new HARRecorder(client);
+            await standaloneRecorder.start();
+          }
+
+          // Smart wrapping: only use async IIFE when code contains `await`.
+          // Without wrapping, Runtime.evaluate returns the completion value
+          // of the last expression, handling multi-statement code naturally.
+          const needsAsyncWrap = /\bawait\b/.test(code);
+          const expression = needsAsyncWrap
+            ? `(async () => { ${code} })()`
+            : code;
+
+          const evalResult = (await client.send('Runtime.evaluate', {
+            expression,
+            awaitPromise: true,
+            returnByValue: true,
+          })) as {
+            result?: { value?: unknown };
+            exceptionDetails?: { exception?: { description?: string } };
+          };
+
+          if (standaloneRecorder) {
+            const har = await standaloneRecorder.finish();
+            writeHarAndPrintSummary(har, parsed.harOut);
+          }
+
+          if (evalResult.exceptionDetails) {
+            console.error(
+              `ERROR: ${evalResult.exceptionDetails.exception?.description ?? 'Unknown error'}`,
+            );
+            process.exit(1);
+          }
+
+          console.log(JSON.stringify(evalResult.result?.value));
+        },
+        { settle: 3000 },
+      );
+      break;
+    }
+
+    case 'record': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture record --target <id> [--duration <secs>] [--har-out <path>]\n\n' +
+            'Passive HAR recording for the specified duration (default: 10s).',
+        );
+        process.exit(0);
+      }
+      if (!parsed.target) {
+        console.error(
+          'Usage: capture record --target <id> [--duration <secs>] [--har-out <path>]',
+        );
+        process.exit(1);
+      }
+
+      const result = await recordTraffic({
+        port: parsed.port,
+        targetId: parsed.target,
+        duration: parsed.duration,
+        harOutPath: parsed.harOut,
+      });
+      console.log(
+        JSON.stringify(
+          { entryCount: result.entryCount, harPath: result.harPath },
+          null,
+          2,
+        ),
+      );
+      break;
+    }
+
+    case 'reset-tab': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture reset-tab <url> [--port <port>]\n\n' +
+            'Abandon a stuck/unresponsive tab and open a fresh one.\n' +
+            'Updates session context so subsequent commands auto-target the new tab.\n\n' +
+            'Example: capture reset-tab "https://www.instagram.com/"',
+        );
+        process.exit(0);
+      }
+      const url = parsed.positional[0];
+      if (!url) {
+        console.error(
+          'Usage: capture reset-tab <url> [--port <port>]',
+        );
+        process.exit(1);
+      }
+      const p = parsed.port ?? (await detectCdpPort());
+      const tab = await openTab(p, url);
+
+      // Wait for page load
+      if (tab.webSocketDebuggerUrl) {
+        const client = new CDPClient(tab.webSocketDebuggerUrl);
+        await client.waitReady();
+        await client.send('Page.enable');
+        await new Promise<void>((resolve) => {
+          const timer = setTimeout(() => resolve(), 10000);
+          client.on('Page.loadEventFired', () => {
+            clearTimeout(timer);
+            resolve();
+          });
+        });
+        client.close();
+      }
+
+      // Update session context so subsequent commands auto-target the new tab
+      updateActiveSession({ targetId: tab.id });
+
+      console.log(JSON.stringify({ id: tab.id, url: tab.url, port: p }, null, 2));
+      console.error(`\nNew tab opened. Session context updated.`);
+      console.error(`Use --target ${tab.id.slice(0, 8)} if passing target explicitly.`);
+      break;
+    }
+
+    case 'navigate': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture navigate <url> [--har-out <path>] [--settle <ms>] [--har <id>]\n\n' +
+            'Navigate to URL and record HAR. Appends to session HAR if --har is set.\n\n' +
+            'Example: capture navigate "https://app.example.com/dashboard" --settle 3000',
+        );
+        process.exit(0);
+      }
+      const url = parsed.positional[0];
+      if (!url) {
+        console.error(
+          'Usage: capture navigate <url> [--har-out <path>] [--settle <ms>]',
+        );
+        process.exit(1);
+      }
+
+      const result = await navigateAndRecord({
+        port: parsed.port,
+        url,
+        targetId: parsed.target,
+        harOutPath: parsed.har ? undefined : parsed.harOut,
+        settle: parsed.settle,
+      });
+
+      // Append to session HAR if active
+      if (parsed.har && result.har.log.entries.length > 0) {
+        appendToHar(parsed.har, result.har.log.entries);
+        console.error(`  [har:${parsed.har}] +${result.har.log.entries.length} entries`);
+      }
+
+      console.log(
+        JSON.stringify(
+          {
+            entryCount: result.entryCount,
+            harPath: result.harPath,
+            tabUrl: result.tab.url,
+            timedOut: result.timedOut,
+          },
+          null,
+          2,
+        ),
+      );
+      break;
+    }
+
+    case 'screenshot': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture screenshot [--target <id>] [--out <path>] [--viewport <preset>] [--height <px>] [--full-page]\n\n' +
+            'Capture a screenshot of the targeted tab. Saves to --out or auto-generates a path.\n\n' +
+            'Options:\n' +
+            '  --viewport <preset>  Viewport preset (default: desktop)\n' +
+            '                       desktop-wide  1920x1080\n' +
+            '                       desktop       1280x800\n' +
+            '                       tablet        768x1024\n' +
+            '                       mobile        390x844\n' +
+            '  --height <px>        Override viewport height (e.g. 1600)\n' +
+            '  --full-page          Capture the entire scrollable page',
+        );
+        process.exit(0);
+      }
+      const VIEWPORTS: Record<string, { width: number; height: number }> = {
+        'desktop-wide': { width: 1920, height: 1080 },
+        'desktop': { width: 1280, height: 800 },
+        'tablet': { width: 768, height: 1024 },
+        'mobile': { width: 390, height: 844 },
+      };
+      const viewportName = parsed.viewport ?? 'desktop';
+      const viewport = VIEWPORTS[viewportName];
+      if (!viewport) {
+        console.error(`Unknown viewport "${viewportName}". Options: ${Object.keys(VIEWPORTS).join(', ')}`);
+        process.exit(1);
+      }
+      // Allow --height to override the viewport preset height
+      if (parsed.height) {
+        viewport.height = parsed.height;
+      }
+      const result = await withConnection(
+        parsed,
+        async (client) => {
+          const png = await captureScreenshot(client, viewport, { fullPage: parsed.fullPage });
+          const outPath = parsed.out
+            ? parsed.out
+            : (nextStepPath('screenshot', 'manual') ?? `/tmp/capture-screenshot-${Date.now()}.png`);
+          fs.writeFileSync(outPath, png);
+          return { path: outPath, bytes: png.length };
+        },
+        { settle: 0 },
+      );
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+
+    case 'click': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture click "name" [--role button|link|...] [--no-screenshot]\n\n' +
+            'Click an element by its accessible name. Auto-captures a screenshot after clicking.',
+        );
+        process.exit(0);
+      }
+      const name = parsed.positional[0];
+      if (!name) {
+        console.error('Usage: capture click "name" [--role button|link|...] [--no-screenshot]');
+        process.exit(1);
+      }
+      const clickSettle = parsed.settle !== undefined ? parsed.settle : (parsed.har ? 2500 : 1000);
+      const result = await withConnection(
+        parsed,
+        async (client) => {
+          const clickResult = await clickByName(client, name, parsed.role);
+          const screenshot = await autoScreenshot(client, 'click', name, parsed.noScreenshot);
+          return { ...clickResult, screenshot };
+        },
+        { settle: clickSettle },
+      );
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+
+    case 'type': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture type "text" [--into "field name"] [--no-screenshot]\n\n' +
+            'Type text into the focused element, or into a named field with --into.',
+        );
+        process.exit(0);
+      }
+      const text = parsed.positional[0];
+      if (!text) {
+        console.error('Usage: capture type "text" [--into "field name"] [--no-screenshot]');
+        process.exit(1);
+      }
+      const result = await withConnection(
+        parsed,
+        async (client) => {
+          let field: string | null = null;
+          if (parsed.into) {
+            await focusAndType(client, parsed.into, text, parsed.role);
+            field = parsed.into;
+          } else {
+            await typeText(client, text);
+          }
+          const label = field ?? text;
+          const screenshot = await autoScreenshot(client, 'type', label, parsed.noScreenshot);
+          return { typed: text, field, screenshot };
+        },
+        { settle: parsed.settle !== undefined ? parsed.settle : (parsed.har ? 1500 : 500) },
+      );
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+
+    case 'a11y': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture a11y [--target <id>] [--json] [--interactive]\n\n' +
+            'Get the accessibility tree. Use --interactive for interactive elements only.\n' +
+            'Use --json for structured JSON output.',
+        );
+        process.exit(0);
+      }
+      const result = await withConnection(
+        parsed,
+        async (client) => {
+          const tree = await getAccessibilityTree(client);
+
+          if (parsed.json) {
+            return tree;
+          }
+
+          // Flat text output
+          const lines = flattenA11yTree(tree, {
+            interactive: parsed.interactive,
+          });
+          return lines.join('\n');
+        },
+        { settle: 0 },
+      );
+
+      if (parsed.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(result);
+      }
+
+      // Hint when a11y tree is sparse
+      if (!parsed.json) {
+        const lineCount = typeof result === 'string' ? result.split('\n').filter(Boolean).length : 0;
+        if (lineCount === 0) {
+          console.error(
+            '\nNo elements found.' +
+            (parsed.interactive ? ' Try without --interactive to see all nodes.' : '') +
+            '\n\nIf this page is part of your project, consider adding ARIA attributes:\n' +
+            '  - role="button|link|textbox" on interactive elements\n' +
+            '  - aria-label="..." on elements without visible text\n' +
+            '  - Semantic HTML (<button>, <input>, <nav>) provides roles automatically',
+          );
+        } else if (parsed.interactive && lineCount < 5) {
+          console.error(
+            `\nOnly ${lineCount} interactive element${lineCount === 1 ? '' : 's'} found. ` +
+            'If this seems low, the page may lack ARIA markup.\n' +
+            'Consider adding role and aria-label attributes to interactive elements in your frontend code.',
+          );
+        }
+      }
+
+      break;
+    }
+
+    case 'har': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture har <create|read|delete>\n\n' +
+            '  create                      Create a new HAR recording (returns id)\n' +
+            '  read [id]                   Read accumulated HAR entries (id optional in active session)\n' +
+            '  delete <id>                 Delete a HAR recording\n\n' +
+            'Filters (read):\n' +
+            '  --filter-url <pattern>      Substring or regex match on URL\n' +
+            '  --filter-status <code>      Status code, prefix (e.g. 4), or range (e.g. 400-499)\n' +
+            '  --filter-method <method>    HTTP method (GET, POST, ...)\n' +
+            '  --limit <N>                 Return only the first N matching entries\n\n' +
+            'Pass --har <id> to exec/navigate commands to append traffic to a recording.',
+        );
+        process.exit(0);
+      }
+      const subcommand = args[1];
+
+      if (subcommand === 'create') {
+        // Generate a short random ID
+        const { id, path: harPath } = createHarRecording();
+        console.log(JSON.stringify({ id, path: harPath }, null, 2));
+        console.error(
+          `\nPass --har ${id} to subsequent commands to record traffic.`,
+        );
+        break;
+      }
+
+      if (subcommand === 'read') {
+        // ID is optional — fall back to active session's harId
+        let id = args[2];
+        if (id && id.startsWith('--')) id = undefined as unknown as string;
+        if (!id) {
+          const session = getActiveSession();
+          if (session?.harId) {
+            id = session.harId;
+          } else {
+            console.error('Usage: capture har read [id]\n' +
+              '  ID is optional when a capture session is active.');
+            process.exit(1);
+          }
+        }
+
+        const har = readHarFile(id);
+        if (!har) {
+          console.error(`No HAR recording found for id: ${id}`);
+          process.exit(1);
+        }
+
+        let entries = har.log.entries;
+        const total = entries.length;
+        const filters: string[] = [];
+
+        if (parsed.filterUrl) {
+          const pattern = parsed.filterUrl;
+          let re: RegExp | null = null;
+          try { re = new RegExp(pattern, 'i'); } catch { re = null; }
+          entries = entries.filter((e) =>
+            re ? re.test(e.request.url) : e.request.url.toLowerCase().includes(pattern.toLowerCase()),
+          );
+          filters.push(`url~${pattern}`);
+        }
+        if (parsed.filterStatus) {
+          const s = parsed.filterStatus;
+          let matcher: (code: number) => boolean;
+          if (/^\d+-\d+$/.test(s)) {
+            const [lo, hi] = s.split('-').map((n) => parseInt(n, 10));
+            matcher = (c) => c >= lo && c <= hi;
+          } else if (/^\d+$/.test(s)) {
+            if (s.length < 3) {
+              matcher = (c) => String(c).startsWith(s);
+            } else {
+              const n = parseInt(s, 10);
+              matcher = (c) => c === n;
+            }
+          } else {
+            matcher = () => true;
+          }
+          entries = entries.filter((e) => matcher(e.response.status));
+          filters.push(`status=${s}`);
+        }
+        if (parsed.filterMethod) {
+          const m = parsed.filterMethod;
+          entries = entries.filter((e) => e.request.method.toUpperCase() === m);
+          filters.push(`method=${m}`);
+        }
+        if (typeof parsed.limit === 'number' && parsed.limit > 0) {
+          entries = entries.slice(0, parsed.limit);
+          filters.push(`limit=${parsed.limit}`);
+        }
+
+        const filtersLabel = filters.length > 0 ? `  [${filters.join(', ')}]` : '';
+        console.error(
+          `HAR: ${harFilePath(id)} (${entries.length}/${total} entries)${filtersLabel}`,
+        );
+        console.log(JSON.stringify({ log: { entries } }, null, 2));
+        break;
+      }
+
+      if (subcommand === 'delete') {
+        const id = args[2];
+        if (!id) {
+          console.error('Usage: capture har delete <id>');
+          process.exit(1);
+        }
+
+        deleteHarRecording(id);
+        console.log(JSON.stringify({ deleted: true, id }, null, 2));
+        break;
+      }
+
+      console.error(
+        'Usage: capture har <create|read|delete>\n' +
+          '  create              Create a new HAR recording (returns id)\n' +
+          '  read <id>           Read accumulated HAR entries\n' +
+          '  delete <id>         Delete a HAR recording',
+      );
+      process.exit(1);
+      break;
+    }
+
+    case 'network': {
+      if (parsed.help) {
+        console.log(
+          'Usage: capture network <offline|online> [--target <id>]\n\n' +
+            'Toggle network connectivity for a tab. Use "offline" to simulate\n' +
+            'network failure (kills WebSocket connections, blocks HTTP requests).\n' +
+            'Use "online" to restore connectivity.',
+        );
+        process.exit(0);
+      }
+      const mode = parsed.positional[0];
+      if (!mode || !['offline', 'online'].includes(mode)) {
+        console.error('Usage: capture network <offline|online> [--target <id>]');
+        process.exit(1);
+      }
+      const offline = mode === 'offline';
+      const result = await withConnection(
+        parsed,
+        async (client) => {
+          await client.send('Network.enable');
+          await client.send('Network.emulateNetworkConditions', {
+            offline,
+            latency: offline ? -1 : 0,
+            downloadThroughput: offline ? 0 : -1,
+            uploadThroughput: offline ? 0 : -1,
+          });
+          return { network: mode, offline };
+        },
+        { settle: 0 },
+      );
+      console.log(JSON.stringify(result, null, 2));
+      if (offline) {
+        console.error('\nNetwork disabled. WebSocket connections will drop.');
+        console.error('Restore with: capture network online');
+      } else {
+        console.error('\nNetwork restored.');
+      }
+      break;
+    }
+
+    default:
+      console.log(`CDP — browser automation via exec, a11y interactions, and screenshots.
+
+Commands:
+  exec <code>         Execute JavaScript in a browser tab
+  exec --file <path>  Execute JS from file
+  detect              Detect CDP port (prioritizes default browser)
+  list                List all browser tabs
+  open <url>          Open URL in browser (returns tab ID)
+  reset-tab <url>     Abandon stuck tab, open fresh one (updates session)
+  screenshot          Capture screenshot
+  click "name"        Click element by accessible name
+  type "text"         Type text into focused element
+  a11y                Get accessibility tree
+  record              Passive HAR recording
+  navigate <url>      Navigate to URL and record HAR
+  network <offline|online>  Toggle network (simulate disconnect)
+  har create          Create a HAR recording (returns id)
+  har read [id]       Read accumulated HAR entries (id optional in active session)
+  har delete <id>     Delete a HAR recording
+
+Options:
+  --port <port>       Override CDP port
+  --target <tabId>    Target tab by exact ID (preferred, parallel-safe)
+  --new               Force new tab (open)
+  --record            Enable HAR recording (exec)
+  --har <id>          Append traffic to a HAR recording
+  --har-out <path>    HAR output path
+  --file <path>       Read JS from file (exec)
+  --duration <secs>   Recording duration (record, default: 10)
+  --settle <ms>       Settle time override (navigate, click, type)
+  --filter-url <pat>  Filter HAR entries by URL substring/regex (har read)
+  --filter-status <s> Filter HAR by status: code, prefix (4), or range (400-499)
+  --filter-method <m> Filter HAR by HTTP method (har read)
+  --limit <N>         Return only first N matching HAR entries (har read)
+  --out <path>        Output path (screenshot)
+  --viewport <preset> Viewport preset: desktop-wide|desktop|tablet|mobile (default: desktop)
+  --height <px>       Override viewport height (screenshot)
+  --full-page         Capture entire scrollable page (screenshot)
+  --json              JSON output (a11y)
+  --interactive       Interactive elements only (a11y)
+  --role <role>       ARIA role filter (click)
+  --into "field"      Target field by name (type)
+  --no-screenshot     Skip auto-screenshot (click, type)
+
+Console output (errors, warnings) is always captured and printed to stderr.
+
+Examples:
+  capture detect
+  capture list
+  capture open "https://app.example.com" --new
+  capture exec "document.title" --target <id>
+  capture exec "document.querySelector('.btn').click()" --target <id>
+  capture exec "fetch('/api/data').then(r=>r.json())" --target <id> --record
+  capture exec --file /tmp/scrape.js --target <id>
+  capture screenshot --target <id> --out /tmp/shot.png
+  capture a11y --target <id> --interactive
+  capture record --target <id> --duration 15
+  capture navigate "https://app.example.com/dashboard"
+  capture har create
+  capture exec "document.querySelector('form').submit()" --target <id> --har <id>
+  capture har read <id>
+`);
+  }
+}
+
+export { main as cdpMain };
+
+// Only run CLI when executed directly (not imported via capture.ts)
+const isMainModule =
+  process.argv[1]?.endsWith('cdp.ts') ||
+  process.argv[1]?.endsWith('cdp.mjs');
+if (isMainModule) {
+  main()
+    .then(() => {
+      // Flush stdout before exiting — process.exit() doesn't wait for stream drain
+      if (process.stdout.writableNeedDrain) {
+        process.stdout.once('drain', () => process.exit(0));
+      } else {
+        process.exit(0);
+      }
+    })
+    .catch((err) => {
+      console.error(err.message);
+      process.exit(1);
+    });
+}