cdp-skill 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,130 @@
+# CDP Browser Automation Skill
+
+A lightweight, zero-dependency browser automation library using Chrome DevTools Protocol (CDP). Designed for AI agents like Claude Code to control Chrome through simple JSON commands.
+
+## Why CDP Skill?
+
+- **Zero dependencies** - Pure Node.js, no Playwright/Puppeteer overhead
+- **AI-agent optimized** - JSON in, JSON out; designed for LLM tool use
+- **Auto-launch Chrome** - Detects and starts Chrome automatically on macOS, Linux, Windows
+- **Accessibility-first** - ARIA snapshots with element refs for resilient automation
+- **Battle-tested** - 600+ unit tests
+
+## Quick Start
+
+```bash
+# Check Chrome status (auto-launches if needed)
+node src/cdp-skill.js '{"steps":[{"chromeStatus":true}]}'
+
+# Navigate to a page
+node src/cdp-skill.js '{"steps":[{"goto":"https://google.com"}]}'
+```
+
+## Features
+
+### Chrome Management
+- **Auto-launch** - Detects Chrome path on macOS/Linux/Windows, launches with remote debugging
+- **Status check** - `chromeStatus` step reports running state, version, and open tabs
+- **Multi-agent safe** - Multiple agents can share Chrome; each manages their own tabs
+- **Headless support** - Run Chrome without UI via `{"chromeStatus":{"headless":true}}`
+
+### Navigation
+- **URL navigation** - `goto`, `back`, `forward`
+- **Wait conditions** - Network idle, DOM ready, element visible, text appears, URL changes
+- **Navigation detection** - Automatic navigation tracking after clicks
+
+### Element Interaction
+- **Click** - CSS selectors, ARIA refs, or x/y coordinates
+- **Fill & Type** - Input filling with React/controlled component support
+- **Keyboard** - Key presses, combos (`Control+a`, `Meta+Shift+Enter`)
+- **Hover** - Mouse over with configurable duration
+- **Drag & Drop** - Source to target with step interpolation
+- **Select** - Text selection within inputs
+- **Scroll** - To element, coordinates, or page top/bottom
+
+### Smart Waiting (Auto-Actionability)
+- **Visible** - Element in DOM with dimensions, not hidden
+- **Enabled** - Not disabled or aria-disabled
+- **Stable** - Position unchanged for 3 animation frames
+- **Unobscured** - Not covered by overlays/modals
+- **Pointer events** - CSS pointer-events not disabled
+- **Auto-force** - Retries with force when actionability times out
+
+### Accessibility & Queries
+- **ARIA snapshots** - Get accessibility tree as YAML with clickable refs
+- **Role queries** - Find elements by ARIA role (`button`, `textbox`, `link`, etc.)
+- **CSS queries** - Traditional selector-based queries
+- **Multi-query** - Batch multiple queries in one step
+- **Page inspection** - Quick overview of page structure
+
+### 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
+
+### Screenshots & PDF
+- **Viewport capture** - Current view
+- **Full page** - Entire scrollable area
+- **Element capture** - Specific element by selector
+- **PDF generation** - With metadata (page count, dimensions)
+- **Temp directory** - Auto-saves to platform temp dir for relative paths
+
+### Data Extraction
+- **Text/HTML/attributes** - Extract content from elements
+- **Console logs** - Capture browser console output
+- **Cookies** - Get, set, delete with expiration support
+- **JavaScript eval** - Execute code in page context with serialization
+
+### Form Handling
+- **Fill form** - Multiple fields in one step
+- **Validation** - Check HTML5 constraint validation state
+- **Submit** - With validation error reporting
+
+### Assertions
+- **URL checks** - Contains, equals, matches regex
+- **Text presence** - Verify text on page
+- **Element state** - Check element properties
+
+### Device Emulation
+- **Viewport presets** - iPhone, iPad, Pixel, Galaxy, desktop sizes
+- **Custom dimensions** - Width, height, scale factor
+- **Mobile mode** - Touch events, mobile user agent
+
+### Tab Management
+- **List tabs** - See all open tabs with targetId
+- **Close tabs** - Clean up when done
+- **Tab reuse** - Pass targetId to reuse existing tab
+
+### Debug Mode
+- **Before/after screenshots** - Capture state around each action
+- **DOM snapshots** - HTML at each step
+- **Output to temp dir** - Automatic cleanup-friendly location
+
+## Documentation
+
+- **[SKILL.md](./SKILL.md)** - Complete step reference and API documentation
+- **[src/](./src/)** - Source code with JSDoc comments
+
+## Architecture
+
+```
+src/
+├── cdp-skill.js   # CLI entry point
+├── cdp.js         # CDP connection, discovery, Chrome launcher
+├── page.js        # Page controller, navigation, cookies
+├── dom.js         # Element location, input emulation, clicks
+├── aria.js        # Accessibility snapshots, role queries
+├── capture.js     # Screenshots, PDF, console, network
+├── runner.js      # Step validation and execution
+├── utils.js       # Errors, key validation, device presets
+└── index.js       # Public API exports
+```
+
+## Requirements
+
+- Node.js 22+
+- Chrome or Chromium (auto-detected)
+
+## License
+
+MIT

package/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: cdp-skill
-description: Automate Chrome browser interactions via JSON piped to a Node.js CLI. Use when you need to navigate websites, fill forms, click elements, take screenshots, extract data, or run end-to-end browser tests. Supports accessibility snapshots for resilient element targeting.
+description: Automate Chrome browser interactions via JSON passed to a Node.js CLI. Use when you need to navigate websites, fill forms, click elements, take screenshots, extract data, or run end-to-end browser tests. Supports accessibility snapshots for resilient element targeting.
 license: MIT
-compatibility: Requires Chrome/Chromium running with --remote-debugging-port=9222 and Node.js.
+compatibility: Requires Chrome/Chromium (auto-launched if not running) and Node.js.
 ---
 
 # CDP Browser Automation Skill
 
-Automate Chrome browser interactions via JSON piped to a Node.js CLI. Produce JSON step definitions, not JavaScript code.
+Automate Chrome browser interactions via JSON passed to a Node.js CLI. Produce JSON step definitions, not JavaScript code.
 
 ## Purpose
 
@@ -19,34 +19,49 @@ This skill enables **AI-powered browser automation**. The intended workflow:
 
 ## Quick Start
 
-Chrome must be running with remote debugging:
+**Step 1: Check Chrome status (auto-launches if needed)**
 ```bash
-# macOS
-/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+node src/cdp-skill.js '{"steps":[{"chromeStatus":true}]}'
+```
 
-# Linux
-google-chrome --remote-debugging-port=9222
+Returns:
+```json
+{
+  "status": "passed",
+  "chrome": {
+    "running": true,
+    "launched": true,
+    "version": "Chrome/120.0.6099.109",
+    "port": 9222,
+    "tabs": [{"targetId": "ABC123", "url": "about:blank", "title": ""}]
+  }
+}
+```
 
-# Windows
-chrome.exe --remote-debugging-port=9222
+The skill auto-detects Chrome location on macOS, Linux, and Windows. Set `CHROME_PATH` environment variable for custom installations.
+
+**Step 2: Execute automation steps**
+```bash
+node src/cdp-skill.js '{"steps":[{"goto":"https://google.com"}]}'
 ```
 
-Execute steps:
+Stdin pipe also works:
 ```bash
-echo '{"steps":[{"goto":"https://example.com"}]}' | node src/cli.js
+echo '{"steps":[{"goto":"https://google.com"}]}' | node src/cdp-skill.js
 ```
 
 ### Tab Reuse (Critical)
 
-The first invocation creates a new tab and returns a `targetId`. **Include this in ALL subsequent calls** to reuse the same tab:
+Use a `targetId` from `chromeStatus` response or previous step output. **Include targetId in ALL subsequent calls** to reuse the same tab:
 
 ```bash
-# First call - extract targetId from response
-RESULT=$(echo '{"steps":[{"goto":"https://example.com"}]}' | node src/cli.js)
-TARGET_ID=$(echo "$RESULT" | jq -r '.tab.targetId')
+# Get available tabs from chromeStatus
+RESULT=$(node src/cdp-skill.js '{"steps":[{"chromeStatus":true}]}')
+TARGET_ID=$(echo "$RESULT" | jq -r '.chrome.tabs[0].targetId')
 
-# All subsequent calls - include targetId
-echo "{\"config\":{\"targetId\":\"$TARGET_ID\"},\"steps\":[{\"click\":\"#btn\"}]}" | node src/cli.js
+# Use targetId for all subsequent calls
+node src/cdp-skill.js "{\"config\":{\"targetId\":\"$TARGET_ID\"},\"steps\":[{\"goto\":\"https://google.com\"}]}"
+node src/cdp-skill.js "{\"config\":{\"targetId\":\"$TARGET_ID\"},\"steps\":[{\"click\":\"#btn\"}]}"
 ```
 
 Omitting `targetId` creates orphan tabs that accumulate until Chrome restarts.
@@ -130,11 +145,38 @@ Refs work with: `click`, `fill`, `hover`.
 
 ## Step Reference
 
+### Chrome Management
+
+**chromeStatus** - Check if Chrome is running, auto-launch if not
+```json
+{"chromeStatus": true}
+{"chromeStatus": {"autoLaunch": false}}
+{"chromeStatus": {"headless": true}}
+```
+Options: `autoLaunch` (default: true), `headless` (default: false)
+
+Returns:
+```json
+{
+  "running": true,
+  "launched": false,
+  "version": "Chrome/120.0.6099.109",
+  "port": 9222,
+  "tabs": [
+    {"targetId": "ABC123...", "url": "https://google.com", "title": "Google"}
+  ]
+}
+```
+
+If Chrome cannot be found: `{running: false, launched: false, error: "Chrome not found..."}`
+
+**Note:** This step is lightweight - it doesn't create a session. Use it as your first call to ensure Chrome is ready, then use a `targetId` from the tabs list for subsequent calls.
+
 ### Navigation
 
 **goto** - Navigate to URL
 ```json
-{"goto": "https://example.com"}
+{"goto": "https://google.com"}
 ```
 
 **back** / **forward** - History navigation
@@ -339,9 +381,9 @@ Note: Console logs don't persist across CLI invocations.
 
 **screenshot**
 ```json
-{"screenshot": "./result.png"}
-{"screenshot": {"path": "./full.png", "fullPage": true}}
-{"screenshot": {"path": "./element.png", "selector": "#header"}}
+{"screenshot": "result.png"}
+{"screenshot": {"path": "full.png", "fullPage": true}}
+{"screenshot": {"path": "/absolute/path/element.png", "selector": "#header"}}
 ```
 Options: `path`, `fullPage`, `selector`, `format` (png|jpeg|webp), `quality`, `omitBackground`, `clip`
 
@@ -349,13 +391,15 @@ Returns: `{path, viewport: {width, height}, format, fullPage, selector}`
 
 **pdf**
 ```json
-{"pdf": "./report.pdf"}
-{"pdf": {"path": "./report.pdf", "landscape": true, "printBackground": true}}
+{"pdf": "report.pdf"}
+{"pdf": {"path": "/absolute/path/report.pdf", "landscape": true, "printBackground": true}}
 ```
 Options: `path`, `selector`, `landscape`, `printBackground`, `scale`, `paperWidth`, `paperHeight`, margins, `pageRanges`, `validate`
 
 Returns: `{path, fileSize, fileSizeFormatted, pageCount, dimensions, validation?}`
 
+**Note:** Relative paths are saved to the platform temp directory (`$TMPDIR/cdp-skill/` on macOS/Linux, `%TEMP%\cdp-skill\` on Windows). Use absolute paths to save elsewhere.
+
 
 ### JavaScript Execution
 
@@ -368,13 +412,13 @@ Options: `expression`, `await`, `timeout`, `serialize`
 
 **Shell escaping tip:** For complex expressions with quotes or special characters, use a heredoc or JSON file:
 ```bash
-# Heredoc approach
-node src/cli.js <<'EOF'
+# Heredoc approach (Unix)
+node src/cdp-skill.js <<'EOF'
 {"steps":[{"eval":"document.querySelectorAll('button').length"}]}
 EOF
 
 # Or save to file and pipe
-cat steps.json | node src/cli.js
+cat steps.json | node src/cdp-skill.js
 ```
 
 Returns typed results:
@@ -433,7 +477,7 @@ Presets: `iphone-se`, `iphone-14`, `iphone-15-pro`, `ipad`, `ipad-pro-11`, `pixe
 **cookies** - Get/set/clear cookies
 ```json
 {"cookies": {"get": true}}
-{"cookies": {"get": ["https://example.com"], "name": "session_id"}}
+{"cookies": {"get": ["https://google.com"], "name": "session_id"}}
 {"cookies": {"set": [{"name": "token", "value": "abc", "domain": "example.com", "expires": "7d"}]}}
 {"cookies": {"delete": "session_id"}}
 {"cookies": {"clear": true}}
@@ -505,12 +549,14 @@ Capture screenshots/DOM before and after each action:
 {
   "config": {
     "debug": true,
-    "debugOptions": {"outputDir": "./debug", "captureScreenshots": true, "captureDom": true}
+    "debugOptions": {"captureScreenshots": true, "captureDom": true}
   },
   "steps": [...]
 }
 ```
 
+Debug output goes to the platform temp directory by default. Set `"outputDir": "/path/to/dir"` to override.
+
 
 ## Not Supported
 
@@ -526,16 +572,19 @@ Handle via multiple invocations:
 | Issue | Solution |
 |-------|----------|
 | Tabs accumulating | Include `targetId` in config |
-| CONNECTION error | Start Chrome with `--remote-debugging-port=9222` |
+| CONNECTION error | Use `chromeStatus` first - it auto-launches Chrome |
+| Chrome not found | Set `CHROME_PATH` environment variable |
 | Element not found | Add `wait` step first |
 | Clicks not working | Scroll element into view first |
 
 ## Best Practices
 
-1. **Discover before interacting** - Use `inspect` and `snapshot` to understand page structure
-2. **Use website navigation** - Click links and submit forms; don't guess URLs
-3. **Be persistent** - Try alternative selectors, add waits, scroll first
-4. **Prefer refs** - Use `snapshot` + refs over brittle CSS selectors
+1. **Start with chromeStatus** - Ensures Chrome is running and gives you available tabs
+2. **Reuse only your own tabs** - Always pass `targetId` from your previous response; other agents may be using the same browser
+3. **Discover before interacting** - Use `inspect` and `snapshot` to understand page structure
+4. **Use website navigation** - Click links and submit forms; don't guess URLs
+5. **Be persistent** - Try alternative selectors, add waits, scroll first
+6. **Prefer refs** - Use `snapshot` + refs over brittle CSS selectors
 
 ## Feedback
 

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "cdp-skill",
-  "version": "1.0.0",
-  "description": "Browser automation skill using Chrome DevTools Protocol for Claude Code and Codex",
+  "version": "1.0.1",
+  "description": "Browser automation skill using Chrome DevTools Protocol for Claude Code and AI agents",
   "type": "module",
   "main": "src/index.js",
   "bin": {
-    "cdp-skill": "src/cli.js"
+    "cdp-skill": "src/cdp-skill.js"
   },
   "exports": {
     ".": "./src/index.js",
@@ -26,6 +26,14 @@
     "SKILL.md",
     "src/"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lotreace/cdp-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lotreace/cdp-skill/issues"
+  },
+  "homepage": "https://github.com/lotreace/cdp-skill#readme",
   "keywords": [
     "cdp",
     "chrome",
@@ -33,7 +41,11 @@
     "browser",
     "automation",
     "claude-code",
-    "skill"
+    "ai-agent",
+    "skill",
+    "testing",
+    "e2e",
+    "web-scraping"
   ],
   "skill": {
     "name": "cdp-skill",

package/src/{cli.js → cdp-skill.js}

@@ -2,14 +2,15 @@
 /**
  * CDP Skill CLI
  *
- * JSON interpreter for browser automation. Reads JSON from stdin,
- * executes browser automation steps, and outputs JSON results.
+ * JSON interpreter for browser automation. Accepts JSON as argument (preferred)
+ * or reads from stdin (fallback).
  *
  * Usage:
- *   echo '{"steps":[{"goto":"https://example.com"}]}' | node src/cli.js
+ *   node src/cdp-skill.js '{"steps":[{"goto":"https://google.com"}]}'
+ *   echo '{"steps":[...]}' | node src/cdp-skill.js
  */
 
-import { createBrowser } from './cdp.js';
+import { createBrowser, getChromeStatus } from './cdp.js';
 import { createPageController } from './page.js';
 import { createElementLocator, createInputEmulator } from './dom.js';
 import { createScreenshotCapture, createConsoleCapture, createPdfCapture } from './capture.js';
@@ -25,15 +26,23 @@ const ErrorType = {
 };
 
 /**
- * Reads entire stdin and returns as string
+ * Reads entire stdin and returns as string (with timeout for TTY detection)
  */
 async function readStdin() {
   return new Promise((resolve, reject) => {
+    // If stdin is a TTY (interactive terminal) with no data, don't wait
+    if (process.stdin.isTTY) {
+      resolve('');
+      return;
+    }
+
     const chunks = [];
+    let hasData = false;
 
     process.stdin.setEncoding('utf8');
 
     process.stdin.on('data', chunk => {
+      hasData = true;
       chunks.push(chunk);
     });
 
@@ -44,9 +53,36 @@ async function readStdin() {
     process.stdin.on('error', err => {
       reject(err);
     });
+
+    // Timeout if no data arrives (handles edge cases)
+    setTimeout(() => {
+      if (!hasData) {
+        resolve('');
+      }
+    }, 100);
   });
 }
 
+/**
+ * Get input from argument or stdin
+ * Prefers argument for cross-platform compatibility
+ */
+async function getInput() {
+  // Check for JSON argument (skip node and script path)
+  const args = process.argv.slice(2);
+
+  if (args.length > 0) {
+    // Join all args in case JSON was split by shell
+    const argInput = args.join(' ').trim();
+    if (argInput) {
+      return argInput;
+    }
+  }
+
+  // Fallback to stdin
+  return readStdin();
+}
+
 /**
  * Parses JSON input and validates basic structure
  */
@@ -93,6 +129,37 @@ function errorResponse(type, message) {
   };
 }
 
+/**
+ * Check if steps contain only chromeStatus (lightweight query)
+ */
+function isChromeStatusOnly(steps) {
+  return steps.length === 1 && steps[0].chromeStatus !== undefined;
+}
+
+/**
+ * Handle chromeStatus step - lightweight, no session needed
+ */
+async function handleChromeStatus(config, step) {
+  const host = config.host || 'localhost';
+  const port = config.port || 9222;
+  const autoLaunch = step.chromeStatus === true || step.chromeStatus?.autoLaunch !== false;
+  const headless = step.chromeStatus?.headless || false;
+
+  const status = await getChromeStatus({ host, port, autoLaunch, headless });
+
+  return {
+    status: status.running ? 'passed' : 'failed',
+    chrome: status,
+    steps: [{
+      action: 'chromeStatus',
+      status: status.running ? 'passed' : 'failed',
+      output: status
+    }],
+    outputs: [{ step: 0, action: 'chromeStatus', output: status }],
+    errors: status.error ? [{ step: 0, action: 'chromeStatus', error: status.error }] : []
+  };
+}
+
 /**
  * Main CLI execution
  */
@@ -101,8 +168,8 @@ async function main() {
   let pageController = null;
 
   try {
-    // Read and parse input
-    const input = await readStdin();
+    // Read and parse input (argument preferred, stdin fallback)
+    const input = await getInput();
     const json = parseInput(input);
 
     // Extract config with defaults
@@ -111,6 +178,13 @@ async function main() {
     const port = config.port || 9222;
     const timeout = config.timeout || 30000;
 
+    // Handle chromeStatus specially - no session needed
+    if (isChromeStatusOnly(json.steps)) {
+      const result = await handleChromeStatus(config, json.steps[0]);
+      console.log(JSON.stringify(result));
+      process.exit(result.status === 'passed' ? 0 : 1);
+    }
+
     // Connect to browser
     browser = createBrowser({ host, port, connectTimeout: timeout });
 

package/src/cdp.js

@@ -3,7 +3,10 @@
  * Core CDP connection, discovery, target management, and browser client
  */
 
-import { timeoutError } from './utils.js';
+import { spawn, execSync } from 'child_process';
+import os from 'os';
+import fs from 'fs';
+import { timeoutError, sleep } from './utils.js';
 
 // ============================================================================
 // Connection
@@ -903,3 +906,204 @@ export function createBrowser(options = {}) {
     get sessions() { return sessionRegistry; }
   };
 }
+
+// ============================================================================
+// Chrome Launcher
+// ============================================================================
+
+const CHROME_PATHS = {
+  darwin: [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary'
+  ],
+  linux: [
+    'google-chrome',
+    'google-chrome-stable',
+    'chromium-browser',
+    'chromium',
+    '/usr/bin/google-chrome',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/chromium',
+    '/snap/bin/chromium'
+  ],
+  win32: [
+    process.env.LOCALAPPDATA + '\\Google\\Chrome\\Application\\chrome.exe',
+    process.env.PROGRAMFILES + '\\Google\\Chrome\\Application\\chrome.exe',
+    process.env['PROGRAMFILES(X86)'] + '\\Google\\Chrome\\Application\\chrome.exe',
+    process.env.LOCALAPPDATA + '\\Chromium\\Application\\chrome.exe'
+  ]
+};
+
+/**
+ * Find Chrome executable on the system
+ * @returns {string|null} Path to Chrome executable or null if not found
+ */
+export function findChromePath() {
+  // Check environment variable first
+  if (process.env.CHROME_PATH) {
+    if (fs.existsSync(process.env.CHROME_PATH)) {
+      return process.env.CHROME_PATH;
+    }
+  }
+
+  const platform = os.platform();
+  const paths = CHROME_PATHS[platform] || [];
+
+  for (const chromePath of paths) {
+    try {
+      // For Linux, check if command exists in PATH
+      if (platform === 'linux' && !chromePath.startsWith('/')) {
+        try {
+          const result = execSync(`which ${chromePath}`, { encoding: 'utf8' }).trim();
+          if (result) return result;
+        } catch {
+          continue;
+        }
+      } else if (fs.existsSync(chromePath)) {
+        return chromePath;
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Launch Chrome with remote debugging enabled
+ * @param {Object} [options] - Launch options
+ * @param {number} [options.port=9222] - Debugging port
+ * @param {string} [options.chromePath] - Custom Chrome path
+ * @param {boolean} [options.headless=false] - Run in headless mode
+ * @param {string} [options.userDataDir] - Custom user data directory
+ * @returns {Promise<{process: ChildProcess, port: number}>}
+ */
+export async function launchChrome(options = {}) {
+  const {
+    port = 9222,
+    chromePath = findChromePath(),
+    headless = false,
+    userDataDir = null
+  } = options;
+
+  if (!chromePath) {
+    throw new Error(
+      'Chrome not found. Install Google Chrome or set CHROME_PATH environment variable.\n' +
+      'Download: https://www.google.com/chrome/'
+    );
+  }
+
+  const args = [
+    `--remote-debugging-port=${port}`,
+    '--no-first-run',
+    '--no-default-browser-check'
+  ];
+
+  if (headless) {
+    args.push('--headless=new');
+  }
+
+  if (userDataDir) {
+    args.push(`--user-data-dir=${userDataDir}`);
+  }
+
+  const chromeProcess = spawn(chromePath, args, {
+    detached: true,
+    stdio: 'ignore'
+  });
+
+  // Don't let this process keep Node alive
+  chromeProcess.unref();
+
+  // Wait for Chrome to be ready
+  const discovery = createDiscovery('localhost', port, 1000);
+  const maxWait = 10000;
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < maxWait) {
+    if (await discovery.isAvailable()) {
+      return { process: chromeProcess, port };
+    }
+    await sleep(100);
+  }
+
+  // Kill process if it didn't start properly
+  try {
+    chromeProcess.kill();
+  } catch { /* ignore */ }
+
+  throw new Error(`Chrome failed to start within ${maxWait}ms`);
+}
+
+/**
+ * Get Chrome status - check if running, optionally launch if not
+ * @param {Object} [options] - Options
+ * @param {string} [options.host='localhost'] - Chrome host
+ * @param {number} [options.port=9222] - Chrome debugging port
+ * @param {boolean} [options.autoLaunch=true] - Auto-launch if not running
+ * @param {boolean} [options.headless=false] - Launch in headless mode
+ * @returns {Promise<{running: boolean, launched?: boolean, version?: string, tabs?: Array, error?: string}>}
+ */
+export async function getChromeStatus(options = {}) {
+  const {
+    host = 'localhost',
+    port = 9222,
+    autoLaunch = true,
+    headless = false
+  } = options;
+
+  const discovery = createDiscovery(host, port, 2000);
+
+  // Check if already running
+  let wasRunning = await discovery.isAvailable();
+  let launched = false;
+
+  // Auto-launch if not running
+  if (!wasRunning && autoLaunch && host === 'localhost') {
+    try {
+      await launchChrome({ port, headless });
+      launched = true;
+      wasRunning = true;
+    } catch (err) {
+      return {
+        running: false,
+        launched: false,
+        error: err.message
+      };
+    }
+  }
+
+  if (!wasRunning) {
+    return {
+      running: false,
+      launched: false,
+      error: `Chrome not running on ${host}:${port}`
+    };
+  }
+
+  // Get version and tabs
+  try {
+    const version = await discovery.getVersion();
+    const pages = await discovery.getPages();
+
+    return {
+      running: true,
+      launched,
+      version: version.browser,
+      port,
+      tabs: pages.map(p => ({
+        targetId: p.id,
+        url: p.url,
+        title: p.title
+      }))
+    };
+  } catch (err) {
+    return {
+      running: false,
+      launched,
+      error: err.message
+    };
+  }
+}

package/src/index.js

@@ -15,7 +15,10 @@ export {
   createTargetManager,
   createSessionRegistry,
   createPageSession,
-  createBrowser
+  createBrowser,
+  findChromePath,
+  launchChrome,
+  getChromeStatus
 } from './cdp.js';
 
 // ============================================================================