chromex-mcp 1.3.0 → 1.4.0

package/README.md

@@ -1,10 +1,10 @@
 # Chromex
 
-Zero-dependency Chrome DevTools Protocol toolkit for AI agents. 52 typed MCP tools + CLI. Connects directly to Chrome, Brave, Edge, or Chromium via WebSocket. No Puppeteer, no bloat.
+Zero-dependency Chrome DevTools Protocol toolkit for AI agents. 56 typed MCP tools + CLI. Connects directly to Chrome, Brave, Edge, or Chromium via WebSocket. No Puppeteer, no bloat.
 
 ## Features
 
-- **52 MCP tools** -- typed JSON Schema, annotations (`readOnlyHint`, `destructiveHint`), inline screenshots (base64)
+- **56 MCP tools** -- typed JSON Schema, annotations (`readOnlyHint`, `destructiveHint`), inline screenshots (base64)
 - **Zero dependencies** -- uses only Node.js 22+ built-in modules (WebSocket, fs, net, crypto)
 - **Ref-based selection** -- `snap --refs` assigns `@e1`, `@e2`... to interactive elements, then `click @e5` or `fill @e3 "value"`. No fragile CSS selectors
 - **Incremental snapshots** -- second snapshot returns only changed nodes (diff), reducing output from thousands of lines to just what changed
@@ -45,7 +45,7 @@ Add to `~/.claude/settings.json`:
 }
 ```
 
-This approves all 52 MCP tools at once. For granular control, approve individual tools:
+This approves all 56 MCP tools at once. For granular control, approve individual tools:
 
 ```json
 {
@@ -141,6 +141,10 @@ chromex close  <target>                            # Close tab
 chromex focus  <target>                            # Activate/focus tab
 chromex launch                                     # Launch browser with debugging
 chromex launch --incognito --browser brave          # Launch Brave in incognito
+chromex launch --headless --url https://example.com # Headless mode for CI/CD
+chromex launch --proxy socks5://localhost:1080      # Launch with proxy
+chromex launch --insecure                           # Ignore certificate errors
+chromex launch --chrome-arg --disable-web-security  # Pass custom Chrome flag
 chromex launch --profile testing --url https://...  # Isolated profile + URL
 chromex incognito https://example.com               # Isolated context (no relaunch)
 chromex stop                                        # Stop all daemons
@@ -156,9 +160,14 @@ chromex snap    <target> --full             # Force full snapshot (skip diff)
 chromex html    <target> "#main"            # Element HTML by selector
 chromex shot    <target> /tmp/page.png      # Viewport screenshot
 chromex shot    <target> /tmp/full.png --full  # Full page screenshot
-chromex net     <target>                    # Network resource timing
+chromex shot    <target> --format=jpeg --quality=80  # JPEG/WebP with quality control
+chromex shot    <target> @e5               # Screenshot of specific element by ref
+chromex net     <target>                    # List network requests (CDP tracked)
+chromex net     <target> <requestId>        # Request detail: headers, timing, body
 chromex perf    <target>                    # Core Web Vitals + memory + DOM stats
 chromex console <target> 5000               # Capture console.log/error for 5s
+chromex console <target> list               # Show stored messages since daemon start
+chromex console <target> detail <id>        # Message detail with stack trace
 chromex domsnapshot <target>                # Structured DOM with bounding rects
 chromex domsnapshot <target> --styles       # Include computed styles
 chromex highlight <target> "h1"             # Highlight element with overlay
@@ -178,6 +187,10 @@ chromex evalraw <target> "Page.getLayoutMetrics"                   # Layout info
 
 ```bash
 chromex nav     <target> "https://example.com"    # Navigate + wait for load
+chromex nav     <target> back                      # Go back in history
+chromex nav     <target> forward                   # Go forward in history
+chromex nav     <target> reload                    # Reload page
+chromex nav     <target> reload-hard               # Reload ignoring cache
 chromex waitfor <target> ".results" 10000          # Wait for CSS selector (10s)
 chromex wait    <target> networkidle               # Wait for network idle
 chromex wait    <target> load                      # Wait for page load
@@ -195,7 +208,12 @@ chromex scroll  <target> to "#footer"              # Scroll to element
 ```bash
 chromex click   <target> "button.submit"           # Click by CSS selector
 chromex click   <target> @e5                       # Click by ref (from snap --refs)
+chromex click   <target> @e5 --dbl                 # Double-click
 chromex clickxy <target> 100 200                   # Click at CSS pixel coords
+chromex clickxy <target> 100 200 --dbl             # Double-click at coords
+chromex key     <target> Enter                     # Press key
+chromex key     <target> "Control+A"               # Key combination
+chromex key     <target> "Control+Shift+R"         # Multi-modifier combo
 chromex type    <target> "hello world"             # Type text (works cross-origin)
 chromex hover   <target> @e12                      # Hover element by ref
 chromex drag    <target> "#source" "#dest"         # Drag & drop by selector
@@ -268,6 +286,8 @@ chromex emulate  <target> macbook-air              # 1440x900 @2x laptop
 chromex emulate  <target> desktop-1080p            # 1920x1080 @1x
 chromex emulate  <target> desktop-4k               # 3840x2160 @1x
 chromex emulate  <target> reset                    # Reset to default
+chromex resize   <target> 1280 720                 # Custom viewport dimensions
+chromex resize   <target> 1440 900 2               # Custom with DPR (retina)
 chromex geo      <target> -23.55 -46.63            # Set geolocation (Sao Paulo)
 chromex geo      <target> reset                    # Clear geolocation
 chromex timezone <target> "America/Sao_Paulo"      # Set timezone
@@ -295,6 +315,18 @@ chromex webauthn <target> creds                    # List stored credentials
 chromex webauthn <target> disable                  # Remove authenticator
 ```
 
+### Audit & Analytics
+
+```bash
+chromex audit   <target>                           # Full Lighthouse audit (all categories)
+chromex audit   <target> performance,seo           # Specific categories
+chromex audit   <target> accessibility desktop     # Accessibility on desktop
+chromex stats   <target>                           # Session analytics (command counts, timing)
+chromex stats   <target> --full                    # Full action timeline
+chromex stats   <target> --reset                   # Reset counters
+chromex stats   <target> --export=/tmp/stats.json  # Export as JSON
+```
+
 ## Ref-Based Selection
 
 The killer feature for AI agents. Instead of fragile CSS selectors, use numbered refs:
@@ -379,7 +411,7 @@ chromex click <target> @e3
 #   ...
 ```
 
-Commands that trigger auto-snapshot: `click`, `clickxy`, `type`, `fill`, `clear`, `select`, `check`, `form`, `nav`, `dialog`, `loadall`, `drag`, `touch`, `upload`.
+Commands that trigger auto-snapshot: `click`, `clickxy`, `type`, `key`, `fill`, `clear`, `select`, `check`, `form`, `nav`, `dialog`, `loadall`, `drag`, `touch`, `upload`.
 
 Suppress with `--no-snap` for scripts doing rapid sequential actions:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chromex-mcp",
-  "version": "1.3.0",
-  "description": "Zero-dependency Chrome DevTools Protocol MCP server for AI agents. 52 typed tools, per-tab daemons, security hardened.",
+  "version": "1.4.0",
+  "description": "Zero-dependency Chrome DevTools Protocol MCP server for AI agents. 56 typed tools, per-tab daemons, security hardened.",
   "type": "module",
   "bin": {
     "chromex": "./bin/chromex.mjs",

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

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

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

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

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

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

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

@@ -1,4 +1,4 @@
-// Captura de console.log/error/warn
+// Console: live capture, stored message list, and detail with stack traces
 
 import { sleep } from '../utils.mjs';
 
@@ -9,7 +9,7 @@ export async function consoleStr(cdp, sid, durationMs = 5000) {
   await cdp.send('Runtime.enable', {}, sid);
 
   const off = cdp.onEvent('Runtime.consoleAPICalled', (params) => {
-    const type = params.type; // log, error, warn, info, debug
+    const type = params.type;
     const args = (params.args || []).map(a => {
       if (a.type === 'string') return a.value;
       if (a.type === 'number') return String(a.value);
@@ -35,3 +35,33 @@ export async function consoleStr(cdp, sid, durationMs = 5000) {
     return `[${e.ts}] ${prefix.padEnd(3)}  ${e.msg.substring(0, 200)}`;
   }).join('\n');
 }
+
+export function consoleListStr(consoleMessages) {
+  if (consoleMessages.length === 0) return 'No console messages captured since daemon started.';
+  const msgs = consoleMessages.slice(-50);
+  return msgs.map(e => {
+    const ts = new Date(e.ts).toISOString().slice(11, 23);
+    const prefix = e.type === 'error' ? 'ERR' : e.type === 'warn' ? 'WRN' : e.type.toUpperCase().slice(0, 3);
+    return `[${e.id}] ${ts} ${prefix.padEnd(3)}  ${e.args.join(' ').substring(0, 200)}`;
+  }).join('\n');
+}
+
+export function consoleDetailStr(consoleMessages, msgId) {
+  const id = parseInt(msgId);
+  const msg = consoleMessages.find(m => m.id === id);
+  if (!msg) return `Message #${msgId} not found. Use "console list" to see stored messages.`;
+
+  const lines = [];
+  lines.push(`${msg.type.toUpperCase()} #${msg.id} at ${new Date(msg.ts).toISOString()}`);
+  lines.push(msg.args.join(' '));
+
+  if (msg.stackTrace?.callFrames?.length) {
+    lines.push('\nStack Trace:');
+    for (const f of msg.stackTrace.callFrames) {
+      const loc = f.url ? `${f.url}:${f.lineNumber + 1}:${f.columnNumber + 1}` : '(native)';
+      lines.push(`  at ${f.functionName || '(anonymous)'} (${loc})`);
+    }
+  }
+
+  return lines.join('\n');
+}

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

@@ -42,3 +42,18 @@ export async function emulateStr(cdp, sid, device) {
 
   return `Emulating ${device}: ${preset.width}x${preset.height} @${preset.deviceScaleFactor}x${preset.mobile ? ' (mobile)' : ''}`;
 }
+
+export async function resizeStr(cdp, sid, widthStr, heightStr, dprStr) {
+  const width = parseInt(widthStr);
+  const height = parseInt(heightStr);
+  if (!width || !height || width < 1 || height < 1) {
+    throw new Error('Width and height required (e.g. resize 1280 720)');
+  }
+  const dpr = dprStr ? parseFloat(dprStr) : 1;
+
+  await cdp.send('Emulation.setDeviceMetricsOverride', {
+    width, height, deviceScaleFactor: dpr, mobile: false,
+  }, sid);
+
+  return `Viewport resized to ${width}x${height} @${dpr}x`;
+}

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

@@ -3,33 +3,43 @@
 import { sleep } from '../utils.mjs';
 import { evalStr } from './evaluate.mjs';
 
-export async function clickStr(cdp, sid, selector) {
+export async function clickStr(cdp, sid, selector, dbl = false) {
   if (!selector) throw new Error('CSS selector required');
+  const dblStr = dbl ? 'true' : 'false';
   const expr = `
     (function() {
       const el = document.querySelector(${JSON.stringify(selector)});
       if (!el) return { ok: false, error: 'Element not found: ' + ${JSON.stringify(selector)} };
       el.scrollIntoView({ block: 'center' });
       el.click();
+      if (${dblStr}) el.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
       return { ok: true, tag: el.tagName, text: el.textContent.trim().substring(0, 80) };
     })()
   `;
   const result = await evalStr(cdp, sid, expr);
   const r = JSON.parse(result);
   if (!r.ok) throw new Error(r.error);
-  return `Clicked <${r.tag}> "${r.text}"`;
+  const verb = dbl ? 'Double-clicked' : 'Clicked';
+  return `${verb} <${r.tag}> "${r.text}"`;
 }
 
-export async function clickXyStr(cdp, sid, x, y) {
+export async function clickXyStr(cdp, sid, x, y, dbl = false) {
   const cx = parseFloat(x);
   const cy = parseFloat(y);
   if (isNaN(cx) || isNaN(cy)) throw new Error('x and y must be numbers (CSS pixels)');
-  const base = { x: cx, y: cy, button: 'left', clickCount: 1, modifiers: 0 };
+  const clickCount = dbl ? 2 : 1;
+  const base = { x: cx, y: cy, button: 'left', clickCount, modifiers: 0 };
   await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mouseMoved' }, sid);
   await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mousePressed' }, sid);
   await sleep(50);
   await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mouseReleased' }, sid);
-  return `Clicked at CSS (${cx}, ${cy})`;
+  if (dbl) {
+    await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mousePressed' }, sid);
+    await sleep(50);
+    await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mouseReleased' }, sid);
+  }
+  const verb = dbl ? 'Double-clicked' : 'Clicked';
+  return `${verb} at CSS (${cx}, ${cy})`;
 }
 
 export async function typeStr(cdp, sid, text) {

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

@@ -0,0 +1,123 @@
+// Keyboard input: press keys and key combinations via CDP Input.dispatchKeyEvent
+
+// Key name -> { key, code, keyCode } mapping for CDP
+const KEY_MAP = {
+  enter:      { key: 'Enter',     code: 'Enter',       keyCode: 13 },
+  tab:        { key: 'Tab',       code: 'Tab',         keyCode: 9  },
+  escape:     { key: 'Escape',    code: 'Escape',      keyCode: 27 },
+  backspace:  { key: 'Backspace', code: 'Backspace',   keyCode: 8  },
+  delete:     { key: 'Delete',    code: 'Delete',      keyCode: 46 },
+  space:      { key: ' ',         code: 'Space',       keyCode: 32 },
+  arrowup:    { key: 'ArrowUp',   code: 'ArrowUp',     keyCode: 38 },
+  arrowdown:  { key: 'ArrowDown', code: 'ArrowDown',   keyCode: 40 },
+  arrowleft:  { key: 'ArrowLeft', code: 'ArrowLeft',   keyCode: 37 },
+  arrowright: { key: 'ArrowRight',code: 'ArrowRight',  keyCode: 39 },
+  home:       { key: 'Home',      code: 'Home',        keyCode: 36 },
+  end:        { key: 'End',       code: 'End',         keyCode: 35 },
+  pageup:     { key: 'PageUp',    code: 'PageUp',      keyCode: 33 },
+  pagedown:   { key: 'PageDown',  code: 'PageDown',    keyCode: 34 },
+  insert:     { key: 'Insert',    code: 'Insert',      keyCode: 45 },
+  // Modifier keys (needed for keyDown/keyUp dispatch of modifiers themselves)
+  control:    { key: 'Control',   code: 'ControlLeft',  keyCode: 17 },
+  ctrl:       { key: 'Control',   code: 'ControlLeft',  keyCode: 17 },
+  shift:      { key: 'Shift',     code: 'ShiftLeft',    keyCode: 16 },
+  alt:        { key: 'Alt',       code: 'AltLeft',      keyCode: 18 },
+  meta:       { key: 'Meta',      code: 'MetaLeft',     keyCode: 91 },
+  cmd:        { key: 'Meta',      code: 'MetaLeft',     keyCode: 91 },
+  command:    { key: 'Meta',      code: 'MetaLeft',     keyCode: 91 },
+};
+
+// F1-F12
+for (let i = 1; i <= 12; i++) {
+  KEY_MAP[`f${i}`] = { key: `F${i}`, code: `F${i}`, keyCode: 111 + i };
+}
+
+// Modifier name -> CDP modifier bitfield
+const MODIFIERS = {
+  alt: 1, control: 2, ctrl: 2, meta: 4, cmd: 4, command: 4, shift: 8,
+};
+
+function resolveKey(name) {
+  const lower = name.toLowerCase();
+  const mapped = KEY_MAP[lower];
+  if (mapped) return mapped;
+
+  // Single letter a-z
+  if (lower.length === 1 && lower >= 'a' && lower <= 'z') {
+    return { key: lower, code: `Key${lower.toUpperCase()}`, keyCode: lower.charCodeAt(0) - 32 };
+  }
+  // Single digit 0-9
+  if (lower.length === 1 && lower >= '0' && lower <= '9') {
+    return { key: lower, code: `Digit${lower}`, keyCode: lower.charCodeAt(0) };
+  }
+  // Single special char (pass through)
+  if (name.length === 1) {
+    return { key: name, code: '', keyCode: name.charCodeAt(0) };
+  }
+
+  throw new Error(`Unknown key: "${name}". Common keys: Enter, Tab, Escape, Backspace, Delete, Space, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown, F1-F12, a-z, 0-9`);
+}
+
+// Parse "Control+Shift+A" -> { modifiers: 10, modifierNames: [...], key: {...} }
+function parseKeyCombo(combo) {
+  if (!combo) throw new Error('Key combination required (e.g. "Enter", "Control+A", "Control+Shift+R")');
+
+  // Split on + but handle edge case "Control++" (last + is the key)
+  const parts = [];
+  let buf = '';
+  for (const ch of combo) {
+    if (ch === '+' && buf) {
+      parts.push(buf);
+      buf = '';
+    } else {
+      buf += ch;
+    }
+  }
+  if (buf) parts.push(buf);
+
+  let modBits = 0;
+  const modNames = [];
+  const keyParts = [];
+
+  for (const part of parts) {
+    const mod = MODIFIERS[part.toLowerCase()];
+    if (mod !== undefined) {
+      modBits |= mod;
+      modNames.push(part);
+    } else {
+      keyParts.push(part);
+    }
+  }
+
+  if (keyParts.length === 0) throw new Error(`No key found in combination: "${combo}". Modifiers alone are not valid.`);
+  if (keyParts.length > 1) throw new Error(`Multiple non-modifier keys in "${combo}": ${keyParts.join(', ')}. Use only one primary key.`);
+
+  return { modifiers: modBits, modifierNames: modNames, key: resolveKey(keyParts[0]) };
+}
+
+// Exported for testing
+export { parseKeyCombo };
+
+export async function pressKeyStr(cdp, sid, combo) {
+  const { modifiers, modifierNames, key } = parseKeyCombo(combo);
+
+  const base = { modifiers, key: key.key, code: key.code, windowsVirtualKeyCode: key.keyCode };
+
+  // Press modifier keys down
+  for (const name of modifierNames) {
+    const modKey = resolveKey(name);
+    await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key: modKey.key, code: modKey.code, modifiers }, sid);
+  }
+
+  // Press and release the primary key
+  await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', ...base }, sid);
+  await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', ...base }, sid);
+
+  // Release modifier keys in reverse order
+  for (const name of modifierNames.toReversed()) {
+    const modKey = resolveKey(name);
+    await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key: modKey.key, code: modKey.code, modifiers: 0 }, sid);
+  }
+
+  return `Pressed ${combo}`;
+}