cdp-skill 1.0.2 → 1.0.4

package/README.md

@@ -56,11 +56,13 @@ node src/cdp-skill.js '{"steps":[{"goto":"https://google.com"}]}'
 - **CSS queries** - Traditional selector-based queries
 - **Multi-query** - Batch multiple queries in one step
 - **Page inspection** - Quick overview of page structure
+- **Coordinate discovery** - `refAt`, `elementsAt`, `elementsNear` for visual-based targeting
 
 ### Frame Support
 - **List frames** - Enumerate all iframes
 - **Switch context** - Execute in iframe by selector, index, or name
 - **Cross-origin detection** - Identifies cross-origin frames in snapshots
+- **Shadow DOM** - Pierce shadow roots with `pierceShadow` option in snapshots
 
 ### Screenshots & PDF
 - **Viewport capture** - Current view
@@ -115,6 +117,7 @@ src/
 ├── dom.js         # Element location, input emulation, clicks
 ├── aria.js        # Accessibility snapshots, role queries
 ├── capture.js     # Screenshots, PDF, console, network
+├── diff.js        # Snapshot diffing, context capture
 ├── runner.js      # Step validation and execution
 ├── utils.js       # Errors, key validation, device presets
 └── index.js       # Public API exports

package/SKILL.md

@@ -87,13 +87,18 @@ node src/cdp-skill.js '{"steps":[{"closeTab":"t1"}]}'
     "host": "localhost",
     "port": 9222,
     "tab": "t1",
-    "timeout": 10000
+    "timeout": 10000,
+    "headless": false
   },
   "steps": [...]
 }
 ```
 
-Config is optional on first call. `tab` required on subsequent calls.
+Config options:
+- `host`, `port` - CDP connection (default: localhost:9222)
+- `tab` - Tab ID to use (required on subsequent calls)
+- `timeout` - Command timeout in ms (default: 30000)
+- `headless` - Run Chrome in headless mode (default: false). Prevents Chrome from stealing focus. Chrome auto-launches if not running.
 
 ## Output Schema
 
@@ -394,9 +399,28 @@ Returns: `{frameId, url, name}`
 {"click": {"ref": "e4"}}
 {"click": {"x": 450, "y": 200}}
 ```
-Options: `selector`, `ref`, `x`/`y`, `verify`, `force`, `debug`, `timeout`
+Options: `selector`, `ref`, `x`/`y`, `force`, `debug`, `timeout`, `jsClick`, `nativeOnly`
 
-Returns: `{clicked: true}`. With `verify`: adds `{targetReceived: true/false}`. With navigation: adds `{navigated: true, newUrl: "..."}`.
+Returns: `{clicked: true, method: "cdp"|"jsClick"|"jsClick-auto"}`. With navigation: adds `{navigated: true, newUrl: "..."}`.
+
+**Automatic Click Verification**
+Clicks are automatically verified - if CDP mouse events don't reach the target element (common on React, Vue, Next.js sites), the system automatically falls back to JavaScript click. The `method` field shows what was used:
+- `"cdp"` - CDP mouse events worked
+- `"jsClick"` - User requested `jsClick: true`
+- `"jsClick-auto"` - CDP failed, automatic fallback to JavaScript click
+
+**click** - Force JavaScript click
+```json
+{"click": {"selector": "#submit", "jsClick": true}}
+{"click": {"ref": "e4", "jsClick": true}}
+```
+Use `jsClick: true` to skip CDP and use JavaScript `element.click()` directly.
+
+**click** - Disable auto-fallback
+```json
+{"click": {"selector": "#btn", "nativeOnly": true}}
+```
+Use `nativeOnly: true` to disable the automatic jsClick fallback. The click will use CDP only and report `targetReceived: false` if the click didn't reach the element.
 
 **click** - Multi-selector fallback
 ```json
@@ -538,7 +562,12 @@ Options:
 - `offsetX`/`offsetY`: offset from element center (default: 0)
 - `steps` (default: 10), `delay` (ms, default: 0)
 
-Returns: `{dragged: true, source: {x, y}, target: {x, y}, steps}`
+Returns: `{dragged: true, method: "html5-dnd"|"range-input"|"mouse-events", source: {x, y}, target: {x, y}, steps}`
+
+The `method` field indicates which drag strategy was used:
+- `"html5-dnd"` - HTML5 Drag and Drop API (for draggable elements)
+- `"range-input"` - Direct value manipulation (for `<input type="range">` sliders)
+- `"mouse-events"` - JavaScript mouse event simulation (for custom drag implementations)
 
 **selectOption** - Select option(s) in a native `<select>` dropdown
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-skill",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Browser automation skill using Chrome DevTools Protocol for Claude Code and AI agents",
   "type": "module",
   "main": "src/index.js",
@@ -41,6 +41,7 @@
     "browser",
     "automation",
     "claude-code",
+    "codex",
     "ai-agent",
     "skill",
     "testing",

package/src/capture/console-capture.js

@@ -0,0 +1,241 @@
+/**
+ * Console Capture Module
+ * Captures browser console messages and exceptions during test execution
+ *
+ * PUBLIC EXPORTS:
+ * - createConsoleCapture(session, options?) - Factory for console capture
+ *
+ * @module cdp-skill/capture/console-capture
+ */
+
+const DEFAULT_MAX_MESSAGES = 10000;
+
+/**
+ * Create a console capture utility for capturing console messages and exceptions
+ * Listens only to Runtime.consoleAPICalled to avoid duplicate messages
+ * @param {import('../types.js').CDPSession} session - CDP session
+ * @param {Object} [options] - Configuration options
+ * @param {number} [options.maxMessages=10000] - Maximum messages to store
+ * @returns {Object} Console capture interface
+ */
+export function createConsoleCapture(session, options = {}) {
+  const maxMessages = options.maxMessages || DEFAULT_MAX_MESSAGES;
+  let messages = [];
+  let capturing = false;
+  const handlers = {
+    consoleAPICalled: null,
+    exceptionThrown: null
+  };
+
+  function mapConsoleType(type) {
+    const mapping = {
+      'log': 'log',
+      'debug': 'debug',
+      'info': 'info',
+      'error': 'error',
+      'warning': 'warning',
+      'warn': 'warning',
+      'dir': 'log',
+      'dirxml': 'log',
+      'table': 'log',
+      'trace': 'log',
+      'assert': 'error',
+      'count': 'log',
+      'timeEnd': 'log'
+    };
+    return mapping[type] || 'log';
+  }
+
+  function formatArgs(args) {
+    if (!Array.isArray(args)) return '[invalid args]';
+    return args.map(arg => {
+      try {
+        if (arg.value !== undefined) return String(arg.value);
+        if (arg.description) return arg.description;
+        if (arg.unserializableValue) return arg.unserializableValue;
+        if (arg.preview?.description) return arg.preview.description;
+        return `[${arg.type || 'unknown'}]`;
+      } catch {
+        return '[unserializable]';
+      }
+    }).join(' ');
+  }
+
+  function extractExceptionMessage(exceptionDetails) {
+    if (exceptionDetails.exception?.description) return exceptionDetails.exception.description;
+    if (exceptionDetails.text) return exceptionDetails.text;
+    return 'Unknown exception';
+  }
+
+  function addMessage(message) {
+    messages.push(message);
+    if (messages.length > maxMessages) {
+      messages.shift();
+    }
+  }
+
+  /**
+   * Start capturing console messages
+   * @returns {Promise<void>}
+   */
+  async function startCapture() {
+    if (capturing) return;
+
+    await session.send('Runtime.enable');
+
+    handlers.consoleAPICalled = (params) => {
+      addMessage({
+        type: 'console',
+        level: mapConsoleType(params.type),
+        text: formatArgs(params.args),
+        args: params.args,
+        stackTrace: params.stackTrace,
+        timestamp: params.timestamp
+      });
+    };
+
+    handlers.exceptionThrown = (params) => {
+      const exception = params.exceptionDetails;
+      addMessage({
+        type: 'exception',
+        level: 'error',
+        text: exception.text || extractExceptionMessage(exception),
+        exception: exception.exception,
+        stackTrace: exception.stackTrace,
+        url: exception.url,
+        line: exception.lineNumber,
+        column: exception.columnNumber,
+        timestamp: params.timestamp
+      });
+    };
+
+    session.on('Runtime.consoleAPICalled', handlers.consoleAPICalled);
+    session.on('Runtime.exceptionThrown', handlers.exceptionThrown);
+
+    capturing = true;
+  }
+
+  /**
+   * Stop capturing console messages
+   * @returns {Promise<void>}
+   */
+  async function stopCapture() {
+    if (!capturing) return;
+
+    if (handlers.consoleAPICalled) {
+      session.off('Runtime.consoleAPICalled', handlers.consoleAPICalled);
+      handlers.consoleAPICalled = null;
+    }
+    if (handlers.exceptionThrown) {
+      session.off('Runtime.exceptionThrown', handlers.exceptionThrown);
+      handlers.exceptionThrown = null;
+    }
+
+    await session.send('Runtime.disable');
+
+    capturing = false;
+  }
+
+  /**
+   * Get all captured messages
+   * @returns {import('../types.js').ConsoleMessage[]}
+   */
+  function getMessages() {
+    return [...messages];
+  }
+
+  /**
+   * Get messages since a timestamp
+   * @param {number} timestamp - CDP timestamp
+   * @returns {import('../types.js').ConsoleMessage[]}
+   */
+  function getMessagesSince(timestamp) {
+    return messages.filter(m => m.timestamp && m.timestamp >= timestamp);
+  }
+
+  /**
+   * Get messages between timestamps
+   * @param {number} startTimestamp - Start timestamp
+   * @param {number} endTimestamp - End timestamp
+   * @returns {import('../types.js').ConsoleMessage[]}
+   */
+  function getMessagesBetween(startTimestamp, endTimestamp) {
+    return messages.filter(m =>
+      m.timestamp && m.timestamp >= startTimestamp && m.timestamp <= endTimestamp
+    );
+  }
+
+  /**
+   * Get messages by log level
+   * @param {string|string[]} levels - Log level(s) to filter
+   * @returns {import('../types.js').ConsoleMessage[]}
+   */
+  function getMessagesByLevel(levels) {
+    const levelSet = new Set(Array.isArray(levels) ? levels : [levels]);
+    return messages.filter(m => levelSet.has(m.level));
+  }
+
+  /**
+   * Get messages by type
+   * @param {string|string[]} types - Message type(s) to filter
+   * @returns {import('../types.js').ConsoleMessage[]}
+   */
+  function getMessagesByType(types) {
+    const typeSet = new Set(Array.isArray(types) ? types : [types]);
+    return messages.filter(m => typeSet.has(m.type));
+  }
+
+  /**
+   * Get error messages only
+   * @returns {import('../types.js').ConsoleMessage[]}
+   */
+  function getErrors() {
+    return messages.filter(m => m.level === 'error' || m.type === 'exception');
+  }
+
+  /**
+   * Get warning messages only
+   * @returns {import('../types.js').ConsoleMessage[]}
+   */
+  function getWarnings() {
+    return messages.filter(m => m.level === 'warning');
+  }
+
+  /**
+   * Check if any errors were captured
+   * @returns {boolean}
+   */
+  function hasErrors() {
+    return messages.some(m => m.level === 'error' || m.type === 'exception');
+  }
+
+  /**
+   * Clear captured messages
+   */
+  function clear() {
+    messages = [];
+  }
+
+  /**
+   * Clear browser console
+   * @returns {Promise<void>}
+   */
+  async function clearBrowserConsole() {
+    await session.send('Console.clearMessages');
+  }
+
+  return {
+    startCapture,
+    stopCapture,
+    getMessages,
+    getMessagesSince,
+    getMessagesBetween,
+    getMessagesByLevel,
+    getMessagesByType,
+    getErrors,
+    getWarnings,
+    hasErrors,
+    clear,
+    clearBrowserConsole
+  };
+}

package/src/capture/debug-capture.js

@@ -0,0 +1,144 @@
+/**
+ * Debug Capture Module
+ * Captures debugging state (screenshots, DOM) before/after actions
+ *
+ * PUBLIC EXPORTS:
+ * - createDebugCapture(session, screenshotCapture, options?) - Factory for debug capture
+ *
+ * @module cdp-skill/capture/debug-capture
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Create a debug capture utility for capturing debugging state before/after actions
+ * @param {import('../types.js').CDPSession} session - CDP session
+ * @param {Object} screenshotCapture - Screenshot capture instance
+ * @param {Object} [options] - Configuration options
+ * @param {string} [options.outputDir] - Output directory (defaults to platform temp dir)
+ * @param {boolean} [options.captureScreenshots=true] - Whether to capture screenshots
+ * @param {boolean} [options.captureDom=true] - Whether to capture DOM
+ * @returns {Object} Debug capture interface
+ */
+export function createDebugCapture(session, screenshotCapture, options = {}) {
+  // Default to platform-specific temp directory
+  const defaultOutputDir = path.join(os.tmpdir(), 'cdp-skill', 'debug-captures');
+  const outputDir = options.outputDir || defaultOutputDir;
+  const captureScreenshots = options.captureScreenshots !== false;
+  const captureDom = options.captureDom !== false;
+  let stepIndex = 0;
+
+  async function ensureOutputDir() {
+    try {
+      await fs.mkdir(outputDir, { recursive: true });
+    } catch (e) {
+      // Ignore if already exists
+    }
+  }
+
+  /**
+   * Capture current state
+   * @param {string} prefix - File name prefix
+   * @returns {Promise<{timestamp: string, screenshot?: string, screenshotError?: string, dom?: string, domError?: string}>}
+   */
+  async function captureState(prefix) {
+    await ensureOutputDir();
+    const result = { timestamp: new Date().toISOString() };
+
+    if (captureScreenshots) {
+      try {
+        const screenshotPath = path.join(outputDir, `${prefix}.png`);
+        const buffer = await screenshotCapture.captureViewport();
+        await fs.writeFile(screenshotPath, buffer);
+        result.screenshot = screenshotPath;
+      } catch (e) {
+        result.screenshotError = e.message;
+      }
+    }
+
+    if (captureDom) {
+      try {
+        const domPath = path.join(outputDir, `${prefix}.html`);
+        const domResult = await session.send('Runtime.evaluate', {
+          expression: 'document.documentElement.outerHTML',
+          returnByValue: true
+        });
+        if (domResult.result && domResult.result.value) {
+          await fs.writeFile(domPath, domResult.result.value);
+          result.dom = domPath;
+        }
+      } catch (e) {
+        result.domError = e.message;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Capture state before an action
+   * @param {string} action - Action name
+   * @param {Object} [params] - Action parameters
+   * @returns {Promise<Object>} Capture result
+   */
+  async function captureBefore(action, params) {
+    stepIndex++;
+    const prefix = `step-${String(stepIndex).padStart(3, '0')}-${action}-before`;
+    return captureState(prefix);
+  }
+
+  /**
+   * Capture state after an action
+   * @param {string} action - Action name
+   * @param {Object} [params] - Action parameters
+   * @param {string} status - Action status ('ok' or 'error')
+   * @returns {Promise<Object>} Capture result
+   */
+  async function captureAfter(action, params, status) {
+    const prefix = `step-${String(stepIndex).padStart(3, '0')}-${action}-after-${status}`;
+    return captureState(prefix);
+  }
+
+  /**
+   * Get current page info
+   * @returns {Promise<{url: string, title: string, readyState: string, scrollX: number, scrollY: number, innerWidth: number, innerHeight: number, documentWidth: number, documentHeight: number} | {error: string}>}
+   */
+  async function getPageInfo() {
+    try {
+      const result = await session.send('Runtime.evaluate', {
+        expression: `({
+          url: window.location.href,
+          title: document.title,
+          readyState: document.readyState,
+          scrollX: window.scrollX,
+          scrollY: window.scrollY,
+          innerWidth: window.innerWidth,
+          innerHeight: window.innerHeight,
+          documentWidth: document.documentElement.scrollWidth,
+          documentHeight: document.documentElement.scrollHeight
+        })`,
+        returnByValue: true
+      });
+      return result.result.value;
+    } catch (e) {
+      return { error: e.message };
+    }
+  }
+
+  /**
+   * Reset step counter
+   */
+  function reset() {
+    stepIndex = 0;
+  }
+
+  return {
+    captureBefore,
+    captureAfter,
+    captureState,
+    getPageInfo,
+    reset
+  };
+}

package/src/capture/error-aggregator.js

@@ -0,0 +1,151 @@
+/**
+ * Error Aggregator Module
+ * Combines console and network errors into unified reports
+ *
+ * PUBLIC EXPORTS:
+ * - createErrorAggregator(consoleCapture, networkCapture) - Factory for aggregator
+ * - aggregateErrors(consoleCapture, networkCapture) - Convenience function
+ *
+ * @module cdp-skill/capture/error-aggregator
+ */
+
+/**
+ * Create an error aggregator that combines console and network errors
+ * @param {Object} consoleCapture - Console capture instance
+ * @param {Object} networkCapture - Network capture instance
+ * @returns {Object} Error aggregator interface
+ */
+export function createErrorAggregator(consoleCapture, networkCapture) {
+  if (!consoleCapture) throw new Error('consoleCapture is required');
+  if (!networkCapture) throw new Error('networkCapture is required');
+
+  /**
+   * Get summary of all errors
+   * @returns {{hasErrors: boolean, hasWarnings: boolean, counts: Object, errors: Object}}
+   */
+  function getSummary() {
+    const consoleErrors = consoleCapture.getErrors();
+    const consoleWarnings = consoleCapture.getWarnings();
+    const networkFailures = networkCapture.getNetworkFailures();
+    const httpErrs = networkCapture.getHttpErrors();
+
+    return {
+      hasErrors: consoleErrors.length > 0 || networkFailures.length > 0 ||
+                 httpErrs.some(e => e.status >= 500),
+      hasWarnings: consoleWarnings.length > 0 ||
+                   httpErrs.some(e => e.status >= 400 && e.status < 500),
+      counts: {
+        consoleErrors: consoleErrors.length,
+        consoleWarnings: consoleWarnings.length,
+        networkFailures: networkFailures.length,
+        httpClientErrors: httpErrs.filter(e => e.status >= 400 && e.status < 500).length,
+        httpServerErrors: httpErrs.filter(e => e.status >= 500).length
+      },
+      errors: {
+        console: consoleErrors,
+        network: networkFailures,
+        http: httpErrs
+      }
+    };
+  }
+
+  /**
+   * Get all errors sorted by timestamp
+   * @returns {Array} Combined errors with source annotation
+   */
+  function getAllErrorsChronological() {
+    const all = [
+      ...consoleCapture.getErrors().map(e => ({ ...e, source: 'console' })),
+      ...networkCapture.getAllErrors().map(e => ({ ...e, source: 'network' }))
+    ];
+
+    return all.sort((a, b) => (a.timestamp || 0) - (b.timestamp || 0));
+  }
+
+  /**
+   * Get critical errors only (exceptions, network failures, 5xx)
+   * @returns {Array}
+   */
+  function getCriticalErrors() {
+    return [
+      ...consoleCapture.getErrors().filter(e => e.type === 'exception'),
+      ...networkCapture.getNetworkFailures(),
+      ...networkCapture.getHttpErrors().filter(e => e.status >= 500)
+    ];
+  }
+
+  /**
+   * Generate formatted error report
+   * @returns {string} Formatted report text
+   */
+  function formatReport() {
+    const summary = getSummary();
+    const lines = ['=== Error Report ==='];
+
+    if (summary.counts.consoleErrors > 0) {
+      lines.push('\n## Console Errors');
+      for (const error of summary.errors.console) {
+        lines.push(`  [${error.level.toUpperCase()}] ${error.text}`);
+        if (error.url) {
+          lines.push(`    at ${error.url}:${error.line || '?'}`);
+        }
+      }
+    }
+
+    if (summary.counts.networkFailures > 0) {
+      lines.push('\n## Network Failures');
+      for (const error of summary.errors.network) {
+        lines.push(`  [FAILED] ${error.method} ${error.url}`);
+        lines.push(`    Error: ${error.errorText}`);
+      }
+    }
+
+    if (summary.counts.httpServerErrors > 0 || summary.counts.httpClientErrors > 0) {
+      lines.push('\n## HTTP Errors');
+      for (const error of summary.errors.http) {
+        lines.push(`  [${error.status}] ${error.method} ${error.url}`);
+      }
+    }
+
+    if (!summary.hasErrors && !summary.hasWarnings) {
+      lines.push('\nNo errors or warnings captured.');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Get JSON representation
+   * @returns {Object} JSON-serializable report
+   */
+  function toJSON() {
+    return {
+      timestamp: new Date().toISOString(),
+      summary: getSummary(),
+      all: getAllErrorsChronological()
+    };
+  }
+
+  return {
+    getSummary,
+    getAllErrorsChronological,
+    getCriticalErrors,
+    formatReport,
+    toJSON
+  };
+}
+
+/**
+ * Aggregate errors from console and network captures
+ * @param {Object} consoleCapture - Console capture instance
+ * @param {Object} networkCapture - Network capture instance
+ * @returns {{summary: Object, critical: Array, report: string}}
+ */
+export function aggregateErrors(consoleCapture, networkCapture) {
+  const aggregator = createErrorAggregator(consoleCapture, networkCapture);
+  return {
+    summary: aggregator.getSummary(),
+    critical: aggregator.getCriticalErrors(),
+    report: aggregator.formatReport()
+  };
+}