craftdriver 0.1.0 → 0.2.0

package/docs/keyboard-mouse.md

@@ -0,0 +1,250 @@
+# Keyboard & Mouse
+
+CraftDriver provides low-level keyboard and mouse APIs for complex interaction scenarios.
+
+## Keyboard
+
+Access the keyboard API via `browser.keyboard`.
+
+### press(key)
+
+Press and release a key.
+
+```typescript
+await browser.keyboard.press('Enter');
+await browser.keyboard.press('Tab');
+await browser.keyboard.press('Escape');
+```
+
+Common key names:
+
+- Navigation: `'Tab'`, `'Enter'`, `'Escape'`, `'Backspace'`, `'Delete'`
+- Arrows: `'ArrowUp'`, `'ArrowDown'`, `'ArrowLeft'`, `'ArrowRight'`
+- Modifiers: `'Shift'`, `'Control'`, `'Alt'`, `'Meta'`
+- Function: `'F1'` through `'F12'`
+- Special: `'Home'`, `'End'`, `'PageUp'`, `'PageDown'`, `'Insert'`
+
+### type(text)
+
+Type a string of text character by character.
+
+```typescript
+await browser.keyboard.type('Hello, World!');
+```
+
+### down(key)
+
+Press and hold a key.
+
+```typescript
+await browser.keyboard.down('Shift');
+```
+
+### up(key)
+
+Release a held key.
+
+```typescript
+await browser.keyboard.up('Shift');
+```
+
+### Key Combinations
+
+Combine `down()` and `up()` for modifier key combinations:
+
+```typescript
+// Ctrl+A (select all)
+await browser.keyboard.down('Control');
+await browser.keyboard.press('a');
+await browser.keyboard.up('Control');
+
+// Shift+Tab (reverse tab)
+await browser.keyboard.down('Shift');
+await browser.keyboard.press('Tab');
+await browser.keyboard.up('Shift');
+```
+
+### Examples
+
+#### Search and Submit
+
+```typescript
+await browser.find('#search').click();
+await browser.keyboard.type('craftdriver');
+await browser.keyboard.press('Enter');
+```
+
+#### Form Navigation with Tab
+
+```typescript
+await browser.find('#first-name').fill('John');
+await browser.keyboard.press('Tab');
+await browser.keyboard.type('Doe'); // Now in last-name field
+await browser.keyboard.press('Tab');
+await browser.keyboard.type('john@example.com');
+```
+
+#### Select All and Delete
+
+```typescript
+await browser.find('#input').click();
+await browser.keyboard.down('Control');
+await browser.keyboard.press('a');
+await browser.keyboard.up('Control');
+await browser.keyboard.press('Backspace');
+```
+
+---
+
+## Mouse
+
+Access the mouse API via `browser.mouse`.
+
+### click(x, y)
+
+Click at specific coordinates.
+
+```typescript
+await browser.mouse.click(100, 200);
+```
+
+### move(x, y)
+
+Move the mouse to coordinates.
+
+```typescript
+await browser.mouse.move(150, 300);
+```
+
+### down()
+
+Press the mouse button.
+
+```typescript
+await browser.mouse.down();
+```
+
+### up()
+
+Release the mouse button.
+
+```typescript
+await browser.mouse.up();
+```
+
+### wheel(deltaX, deltaY)
+
+Scroll the page.
+
+```typescript
+// Scroll down
+await browser.mouse.wheel(0, 100);
+
+// Scroll up
+await browser.mouse.wheel(0, -100);
+
+// Scroll right
+await browser.mouse.wheel(100, 0);
+```
+
+### dragAndDrop(from, to)
+
+Drag from one position to another.
+
+```typescript
+await browser.mouse.dragAndDrop(
+  { x: 100, y: 100 }, // Start position
+  { x: 300, y: 300 } // End position
+);
+```
+
+### Examples
+
+#### Custom Drag Operation
+
+```typescript
+// Get element positions
+const source = await browser.find('#draggable').boundingBox();
+const target = await browser.find('#drop-zone').boundingBox();
+
+// Calculate centers
+const startX = source.x + source.width / 2;
+const startY = source.y + source.height / 2;
+const endX = target.x + target.width / 2;
+const endY = target.y + target.height / 2;
+
+// Perform drag
+await browser.mouse.dragAndDrop({ x: startX, y: startY }, { x: endX, y: endY });
+```
+
+#### Canvas Drawing
+
+```typescript
+// Move to start position
+await browser.mouse.move(100, 100);
+await browser.mouse.down();
+
+// Draw a line
+await browser.mouse.move(200, 100);
+await browser.mouse.move(200, 200);
+await browser.mouse.move(100, 200);
+await browser.mouse.move(100, 100);
+
+await browser.mouse.up();
+```
+
+#### Scroll Through Content
+
+```typescript
+// Navigate to page
+await browser.navigateTo('https://example.com/long-page');
+
+// Scroll down gradually
+for (let i = 0; i < 5; i++) {
+  await browser.mouse.wheel(0, 200);
+  await browser.pause(500);
+}
+```
+
+---
+
+## Element-Level Keyboard Shortcuts
+
+For element-scoped key presses, use the `press()` method on ElementHandle:
+
+```typescript
+// Press Enter in a specific input
+await browser.find('#search').fill('query').press('Enter');
+
+// Tab out of a field
+await browser.find('#username').fill('user').press('Tab');
+```
+
+This is often more convenient than using the global keyboard API.
+
+---
+
+## Touch gestures (mobile emulation)
+
+When running with `mobileEmulation`, two convenience gestures are
+exposed under `browser.gesture`:
+
+```typescript
+// Swipe from one point to another (px coordinates).
+await browser.gesture.swipe({
+  from: [200, 600],
+  to:   [200, 200],
+  durationMs: 300,
+});
+
+// Pinch / zoom centered on a point.
+await browser.gesture.pinch({
+  center: [200, 400],
+  scale: 0.5,      // < 1 zooms out, > 1 zooms in
+  distance: 100,   // initial finger separation, px
+  durationMs: 250,
+});
+```
+
+These wrap the W3C Pointer Actions API with two simulated touch
+pointers. They work whether or not BiDi is enabled.

package/docs/mcp.md

@@ -0,0 +1,250 @@
+# MCP server
+
+`craftdriver` ships a [Model Context Protocol](https://modelcontextprotocol.io)
+server so hosted / sandboxed AI agents (Claude Desktop, Claude Code,
+Cursor, Windsurf, Zed, Goose, Gemini CLI, …) can drive a real browser
+without managing a daemon, a socket, or filesystem access.
+
+It is a **peer to the CLI**, not a wrapper. Both share the same
+dispatcher and error codes, but the MCP server returns a richer
+post-action payload (compact a11y snapshot, diffed from the previous
+turn) that text models can act on directly.
+
+```bash
+# Start once via your MCP client — examples below
+npx -y craftdriver mcp
+```
+
+The server speaks JSON-RPC 2.0 on stdio. The browser launches lazily
+on the first tool call and shuts down when the client disconnects.
+
+## Install snippets
+
+### Claude Code / Claude Desktop
+
+```bash
+claude mcp add craftdriver -- npx -y craftdriver mcp
+```
+
+### Cursor / Windsurf / Zed (`.cursor/mcp.json` and similar)
+
+```json
+{
+  "mcpServers": {
+    "craftdriver": {
+      "command": "npx",
+      "args": ["-y", "craftdriver", "mcp"]
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+```bash
+gemini mcp add craftdriver npx -y craftdriver mcp
+```
+
+### Goose
+
+```bash
+goose configure   # add craftdriver as a stdio server
+```
+
+## Tools
+
+Compact set — 14 tools, one line each. Long help lives in the schema
+description; clients render it in the model's context once per session.
+
+| Tool                     | Purpose                                                                |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `browser_navigate`       | Go to a URL (waits for load).                                          |
+| `browser_click`          | Click an element. Auto-waits visible+enabled.                          |
+| `browser_fill`           | Fill an input/textarea/select.                                         |
+| `browser_press`          | Press a keyboard key (`Enter`, `Tab`, `Control+A`).                    |
+| `browser_hover`          | Hover over an element.                                                 |
+| `browser_find`           | Locate elements without acting (returns tag/text/visibility).          |
+| `browser_exists`         | **0-wait probe.** Returns `{exists, count}` in one BiDi roundtrip.     |
+| `browser_wait`           | Wait for selector state or load state.                                 |
+| `browser_read`           | Read `text` / `attr` / `value` / `is(visible|enabled|checked)`.        |
+| `browser_pages`          | List open pages (id, url, title).                                      |
+| `browser_snapshot`       | **Sanitized DOM summary with refs.** Use `ref=eN` as the selector for subsequent calls. |
+| `browser_screenshot`     | Capture PNG to a file (auto-allocated under the per-session artifact dir; never inlined). |
+| `browser_status`         | Browser up? Which URL is active?                                       |
+| `browser_advanced_eval`  | Evaluate JS in the page. Last resort.                                  |
+
+`browser_trace` (start/stop/explain) and trace resources are slated
+for a future release alongside richer trace introspection.
+
+## Selector syntax
+
+Identical to the CLI. CSS by default; switch with a `prefix=value`
+form:
+
+```
+role=button[name=Submit]   text=Sign In            text*=Sign
+label=Email                placeholder=Search…     testid=login-btn
+alt=Logo                   title=Help              xpath=//div[1]
+id=submit                  name=email              tag=h1
+ref=e5                     (← from browser_snapshot, see below)
+```
+
+## Refs — the token-efficient locator
+
+Call `browser_snapshot` (or just navigate — the post-action diff
+carries refs too) and you get a sanitized accessibility-tree summary
+where each visible interactive element is numbered:
+
+```
+page: Login — http://…/login.html
+e1: heading "Login"
+e2: form "Username Password Sign in" #login-form
+e3: label "Username"
+e4: textbox "Username" #username
+e5: label "Password"
+e6: textbox "Password" #password
+e7: button "Sign in" #submit
+```
+
+Use `ref=eN` as the selector for the next call:
+
+```jsonc
+{ "name": "browser_fill",  "arguments": { "selector": "ref=e4", "value": "alice" } }
+{ "name": "browser_fill",  "arguments": { "selector": "ref=e6", "value": "hunter2" } }
+{ "name": "browser_click", "arguments": { "selector": "ref=e7" } }
+```
+
+**Why this is a big deal for AI test generation**
+
+- **No selector hallucination.** The agent picks a number, not a
+  CSS/XPath/role expression. The element is already on the page —
+  there is nothing to guess wrong.
+- **Token efficient.** `ref=e7` is 5 characters; `role=button[name=Sign in]`
+  is 26. Over a 50-step flow that adds up.
+- **Auto-waiting still works.** Internally `ref=eN` resolves to a CSS
+  attribute selector (`[data-craftdriver-ref="eN"]`); every action
+  takes the normal visible+enabled wait path.
+
+**Invalidation rules**
+
+- Refs are re-allocated on **every** `browser_snapshot` call.
+- The post-action a11y diff after a mutating tool also re-runs the
+  snapshot, so refs renumber on every turn.
+- Navigating to a new URL invalidates all refs.
+- A stale ref just fails with `NO_MATCH` — take a fresh snapshot.
+
+## Post-action payload
+
+Every tool returns a content array. Mutating tools (`navigate`,
+`click`, `fill`, `press`, `hover`, `advanced_eval`) additionally
+include a **compact a11y snapshot, diffed from the previous turn**:
+
+```jsonc
+{
+  "content": [
+    { "type": "text", "text": "{\"ok\":true,\"selector\":\"css selector=button[type=submit]\"}" },
+    {
+      "type": "text",
+      "text": "page: Login — http://…/login.html\n- form \"Username Password Sign in\" #login-form\n- textbox \"Username\" #username\n- button \"Sign in\" #submit\n+ button \"Logout\" #logout"
+    }
+  ],
+  "structuredContent": { "result": { "ok": true, "selector": "css selector=button[type=submit]" } }
+}
+```
+
+- **First call in a session** returns the full snapshot (one line per
+  visible interactive element: role + accessible name + locator hint).
+- **Subsequent calls** return only the lines that appeared (`+`) or
+  disappeared (`-`).
+- **URL change** triggers a fresh full snapshot.
+- Capped at 80 nodes / 80 chars per name so the payload stays bounded
+  regardless of page complexity.
+
+This is the MCP server's "killer feature" over the CLI: the agent sees
+what changed without a follow-up `read` call, in ~50–500 text tokens
+instead of 800–1500 image tokens for a screenshot.
+
+## Artifact spilling (token efficiency)
+
+MCP content blocks count against the model's context window on every
+turn. To keep the per-call cost bounded, large payloads are **written
+to disk** and the inline block becomes a short preview plus the
+absolute path:
+
+```
+heading "Selectors Playground"
+textbox "by id" #by-id
+textbox "by name" #by-name
+img "Logo ALT" #by-alt
+button "Click me" #by-text
+…
+(full output: /tmp/craftdriver-mcp-1234-abc/0001-snapshot.txt, 1872 bytes)
+```
+
+Applies to:
+
+- **Screenshots** — always written to a file. If you pass `path`, that
+  path is used; otherwise an artifact path is auto-allocated. The
+  inline block carries the absolute path and byte count — **zero**
+  image tokens.
+- **A11y snapshot diffs** — spill when the rendered diff exceeds the
+  threshold (typically only the full first-call snapshot on big pages).
+- **Tool results** — `browser_read`, `browser_advanced_eval`, etc. spill
+  when the JSON-stringified result exceeds the threshold. No more silent
+  truncation.
+
+Configuration:
+
+| Env var                            | Default          | Effect                                            |
+| ---------------------------------- | ---------------- | ------------------------------------------------- |
+| `CRAFTDRIVER_MCP_ARTIFACTS_DIR`    | `os.tmpdir()`    | Root directory for the per-session artifact dir.  |
+| `CRAFTDRIVER_MCP_SPILL_BYTES`      | `2048` (~500 tk) | Inline content blocks larger than this spill.     |
+
+The per-session directory (`<root>/craftdriver-mcp-<pid>-<stamp>/`) is
+not deleted on shutdown — agents may still be reading past artifacts.
+Use `$CRAFTDRIVER_MCP_ARTIFACTS_DIR` to point at a dir with your own
+cleanup policy.
+
+The `structuredContent` field is unaffected by spilling — small results
+still round-trip in full there for programmatic consumers.
+
+## Errors
+
+Errors are returned as `isError: true` content (per MCP spec), **not**
+as JSON-RPC errors. JSON-RPC errors are reserved for protocol-level
+failures (unknown method, malformed request).
+
+```jsonc
+{
+  "isError": true,
+  "content": [
+    { "type": "text", "text": "error: click: no element matches css selector=#nope\ncode:  NO_MATCH" }
+  ],
+  "structuredContent": {
+    "error": { "code": "NO_MATCH", "message": "click: no element matches css selector=#nope" }
+  }
+}
+```
+
+Match on `structuredContent.error.code` — full list in
+[error-codes.md](./error-codes.md).
+
+## Fail-fast defaults
+
+Same rules as the CLI:
+
+- Default per-call timeout: **5 s** (override per call with
+  `timeout_ms`, globally with `CRAFTDRIVER_AGENT_TIMEOUT`).
+- `browser_exists` is a **0-wait probe**. Call it before `browser_click`
+  / `browser_wait` when you're guessing.
+- `browser_click` / `browser_fill` reject immediately with `NO_MATCH`
+  when the selector matches zero elements at `t=0` — no burning the
+  full timeout on a typo.
+
+## When to use MCP vs. the CLI
+
+- **MCP** — your agent runs in a hosted or sandboxed environment that
+  can't spawn child processes per call, or you want tool discovery via
+  `tools/list`. Schema-typed args, structured errors, snapshot diffing.
+- **CLI** — your agent has a shell. Same surface, leaner per-call cost,
+  also great for humans.

package/docs/mobile-emulation.md

@@ -0,0 +1,194 @@
+# Mobile Emulation
+
+CraftDriver supports mobile device emulation using Chrome's built-in mobile emulation feature. This allows you to test responsive designs and mobile-specific behavior.
+
+> **Chrome / Chromium only.** Mobile emulation maps to the
+> `goog:chromeOptions.mobileEmulation` capability — a Chromium-specific
+> extension to WebDriver. Firefox / geckodriver expose no equivalent
+> API, so passing `mobileEmulation` together with
+> `browserName: 'firefox'` throws a clear error at launch. For mobile
+> testing on Firefox, use a real device or Firefox's responsive design
+> mode manually.
+
+## Quick Start
+
+```typescript
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  mobileEmulation: 'iPhone 14',
+});
+
+await browser.navigateTo('https://example.com');
+// Page loads with iPhone 14 viewport, touch events, and mobile user agent
+```
+
+## Using Device Presets
+
+CraftDriver includes presets for popular devices:
+
+```typescript
+// Use preset by name
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  mobileEmulation: 'iPhone 14',
+});
+```
+
+### Available Presets
+
+| Device             | Width | Height | Pixel Ratio | Platform |
+| ------------------ | ----- | ------ | ----------- | -------- |
+| iPhone 14          | 390   | 844    | 3           | iOS      |
+| iPhone 14 Pro Max  | 430   | 932    | 3           | iOS      |
+| iPhone SE          | 375   | 667    | 2           | iOS      |
+| Pixel 7            | 412   | 915    | 2.625       | Android  |
+| Pixel 7 Pro        | 412   | 892    | 3.5         | Android  |
+| Samsung Galaxy S23 | 360   | 780    | 3           | Android  |
+| iPad Pro 11        | 834   | 1194   | 2           | iPadOS   |
+| iPad Mini          | 768   | 1024   | 2           | iPadOS   |
+
+You can also access presets programmatically:
+
+```typescript
+import { devices } from 'craftdriver';
+
+console.log(devices['iPhone 14']);
+// { deviceMetrics: { width: 390, height: 844, pixelRatio: 3, ... }, userAgent: '...' }
+```
+
+## Custom Device Configuration
+
+For custom devices or specific testing needs:
+
+```typescript
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  mobileEmulation: {
+    deviceMetrics: {
+      width: 320,
+      height: 568,
+      pixelRatio: 2,
+      mobile: true, // Enable mobile mode
+      touch: true, // Enable touch events
+    },
+    userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) ...',
+  },
+});
+```
+
+### Device Metrics Options
+
+| Option     | Type    | Default | Description                             |
+| ---------- | ------- | ------- | --------------------------------------- |
+| width      | number  | -       | Viewport width in pixels                |
+| height     | number  | -       | Viewport height in pixels               |
+| pixelRatio | number  | -       | Device pixel ratio (e.g., 2 for Retina) |
+| mobile     | boolean | true    | Enable mobile mode                      |
+| touch      | boolean | true    | Enable touch event emulation            |
+
+## Using Chrome's Built-in Devices
+
+Chrome has its own device database. You can use any device name Chrome recognizes:
+
+```typescript
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  mobileEmulation: {
+    deviceName: 'Nexus 5', // Any device Chrome knows
+  },
+});
+```
+
+> **Note:** Chrome's device names are case-sensitive. Check Chrome DevTools for available names.
+
+## What Gets Emulated
+
+When mobile emulation is enabled:
+
+- **Viewport**: Set to device dimensions
+- **Device Pixel Ratio**: High DPI rendering
+- **Touch Events**: `touchstart`, `touchend`, `touchmove` work
+- **User Agent**: Reflects mobile browser
+- **CSS Media Queries**: `@media (max-width: ...)` respond correctly
+- **`navigator.maxTouchPoints`**: Reports touch capability
+
+## Examples
+
+### Test Responsive Breakpoints
+
+```typescript
+import { Browser } from 'craftdriver';
+
+const viewports = [
+  { name: 'Mobile', width: 375, height: 667 },
+  { name: 'Tablet', width: 768, height: 1024 },
+  { name: 'Desktop', width: 1280, height: 800 },
+];
+
+for (const vp of viewports) {
+  const browser = await Browser.launch({
+    browserName: 'chrome',
+    mobileEmulation: {
+      deviceMetrics: { width: vp.width, height: vp.height, pixelRatio: 2 },
+    },
+  });
+
+  await browser.navigateTo('https://example.com');
+  await browser.screenshot({ path: `screenshot-${vp.name}.png` });
+  await browser.quit();
+}
+```
+
+### Test Mobile Navigation Menu
+
+```typescript
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  mobileEmulation: 'iPhone 14',
+});
+
+await browser.navigateTo('https://example.com');
+
+// Mobile hamburger menu should be visible
+await browser.expect('#mobile-menu-button').toBeVisible();
+
+// Desktop nav should be hidden
+const desktopNav = await browser.find('#desktop-nav').isVisible();
+expect(desktopNav).toBe(false);
+
+// Open mobile menu
+await browser.click('#mobile-menu-button');
+await browser.expect('#mobile-menu').toBeVisible();
+```
+
+### Combine with BiDi Features
+
+Mobile emulation works alongside BiDi features:
+
+```typescript
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  mobileEmulation: 'Pixel 7',
+});
+
+// Mock mobile-specific API
+await browser.network.mock('**/api/mobile-config', {
+  status: 200,
+  body: { mobileOptimized: true },
+});
+
+await browser.navigateTo('https://example.com');
+
+// Check for console errors
+const errors = browser.logs.getErrors();
+expect(errors).toHaveLength(0);
+```
+
+## Limitations
+
+- **Chrome/Chromium only**: Mobile emulation uses Chrome-specific capabilities
+- **Not real device**: Some mobile behaviors can't be emulated (e.g., actual Safari rendering)
+- **Fixed at launch**: Device configuration is set when the browser launches and can't be changed mid-session
+- **No orientation change**: To test landscape, specify a wider width than height in deviceMetrics