craftdriver 1.0.3 → 1.1.0

package/docs/driver-configuration.md

@@ -8,10 +8,11 @@ Craftdriver resolves the WebDriver binary through a chain — first match wins:
 | 2 | `CRAFTDRIVER_CHROMEDRIVER_PATH` / `CRAFTDRIVER_GECKODRIVER_PATH` env var |
 | 3 | `CRAFTDRIVER_DRIVER_PATH` env var (generic fallback for either browser) |
 | 4 | Legacy/Selenium-compatible env vars: `CHROMEDRIVER_PATH`, `SE_CHROMEDRIVER` (chromedriver) or `GECKODRIVER_PATH`, `GECKODRIVER_FILEPATH`, `SE_GECKODRIVER` (geckodriver) |
-| 5 | **Cached auto-resolution** — the path a previous auto-resolve settled on, reused within the `CRAFTDRIVER_DRIVER_TTL` window |
-| 6 | `chromedriver` / `geckodriver` in `node_modules/.bin` |
-| 7 | `chromedriver` / `geckodriver` on `PATH` |
-| 8 | **Auto-download from Chrome for Testing / GitHub** ← the zero-config default |
+| 5 | Known CI-provided driver directories (e.g. GitHub Actions' `CHROMEWEBDRIVER` / `GECKOWEBDRIVER`) — see [CI platform detection](#ci-platform-detection) |
+| 6 | **Cached auto-resolution** — the path a previous auto-resolve settled on, reused within the `CRAFTDRIVER_DRIVER_TTL` window |
+| 7 | `chromedriver` / `geckodriver` in `node_modules/.bin` |
+| 8 | `chromedriver` / `geckodriver` on `PATH` |
+| 9 | **Auto-download from Chrome for Testing / GitHub** ← the zero-config default |
 
 Downloaded drivers are cached in `~/.cache/craftdriver`, and so is the
 *resolution itself* — which driver path to use. Within the
@@ -27,6 +28,87 @@ re-downloaded if needed. Only the driver binary is ever downloaded, never the
 browser itself. Explicit configuration (steps 1–4) always takes precedence over
 the cache.
 
+## CI platform detection
+
+On **GitHub Actions**, craftdriver recognizes the runner's own pre-installed,
+version-matched driver automatically — no configuration needed. GitHub's
+`ubuntu-latest`, `macos-latest`, and `windows-latest` images all publish a
+driver directory via `CHROMEWEBDRIVER` / `GECKOWEBDRIVER` env vars (see
+[actions/runner-images](https://github.com/actions/runner-images)); craftdriver
+checks those directories as step 5 above, before falling back to its own
+cache/PATH-probe/download machinery.
+
+This is best-effort: if a future runner image drops or renames these vars,
+craftdriver falls through safely to the next resolution step rather than
+erroring. No other CI platform is auto-detected yet — set
+`CRAFTDRIVER_CHROMEDRIVER_PATH` / `CRAFTDRIVER_GECKODRIVER_PATH` explicitly on
+other providers (or to pin a non-default driver even on GitHub Actions;
+explicit config always wins, per the chain above).
+
+## Browser Binary Configuration
+
+Everything above resolves the **driver** (chromedriver/geckodriver). A
+separate, independent chain resolves the **browser** binary itself — useful
+for a non-default Chrome/Chromium install or a portable Firefox build.
+
+The `browserPath` option itself is opt-in: craftdriver never sets it for you,
+and omitting it changes nothing. Steps 4–5 below are **not** craftdriver-opt-in
+the same way, though — `CHROME_BIN`, `FIREFOX_BIN`, `SE_CHROME_PATH`, and
+`SE_FIREFOX_PATH` are conventions other tools (Karma, Selenium Manager) already
+set in CI images and local environments for their own purposes. If one of
+those happens to already be exported in your environment, craftdriver will
+start forwarding it as of this version — a behavior change you didn't ask
+craftdriver for, even though you didn't touch any craftdriver config either.
+If you don't want that, set `CRAFTDRIVER_OFFLINE`-style pinning instead, or
+simply don't rely on those four var names for anything craftdriver-adjacent.
+
+| Step | Source |
+|---|---|
+| 1 | `browserPath` option in `Browser.launch()` |
+| 2 | `CRAFTDRIVER_CHROME_PATH` / `CRAFTDRIVER_FIREFOX_PATH` env var |
+| 3 | `CRAFTDRIVER_BROWSER_PATH` env var (generic fallback for either browser) |
+| 4 | `CHROME_BIN` / `FIREFOX_BIN` env var (common CI/tooling convention, e.g. Karma) |
+| 5 | `SE_CHROME_PATH` / `SE_FIREFOX_PATH` env var (Selenium Manager convention) |
+
+Each step is validated (the file must exist) before use; an invalid path falls
+through to the next step rather than being forwarded to the driver as-is (and
+logs a `[craftdriver]` note to stderr when it does, so a typo doesn't silently
+launch the wrong browser).
+
+`CRAFTDRIVER_BROWSER_PATH` (step 3) is forwarded verbatim regardless of
+whether the browser being launched is Chrome or Firefox — it's a single path,
+so it can only ever be correct for one of them. Don't set it in a process or
+CI job that launches both browsers; use the browser-specific `CRAFTDRIVER_CHROME_PATH`
+/ `CRAFTDRIVER_FIREFOX_PATH` instead.
+
+```typescript
+// Launch a custom Chromium build
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  browserPath: '/opt/chromium-custom/chrome',
+});
+```
+
+```bash
+# Equivalent via env var — no code change needed
+CRAFTDRIVER_CHROME_PATH=/opt/chromium-custom/chrome npm test
+```
+
+If chromedriver itself also has to be auto-downloaded (no driver pinned
+anywhere in the chain above), its version is detected from *this* binary
+instead of probing for system Chrome — a custom Chromium build's version
+routinely doesn't match system Chrome, so using the right binary for version
+detection avoids downloading a mismatched chromedriver. Firefox has no
+equivalent concern: geckodriver's own download isn't gated on the Firefox
+version.
+
+Version detection runs the binary with `--version` and parses its output, the
+same way craftdriver already probes system Chrome/Firefox — so `browserPath`
+is supported for Chrome/Chromium and Firefox builds only. Anything that
+doesn't answer `--version` the way those browsers do (Electron apps and other
+Chromium embedders) is out of scope for now; point `CRAFTDRIVER_CHROMEDRIVER_PATH`
+at a pinned driver instead of relying on auto-detection in that case.
+
 ## Environment variables
 
 | Variable | Description | Default |
@@ -34,6 +116,9 @@ the cache.
 | `CRAFTDRIVER_CHROMEDRIVER_PATH` | Absolute path to a chromedriver binary | — |
 | `CRAFTDRIVER_GECKODRIVER_PATH` | Absolute path to a geckodriver binary | — |
 | `CRAFTDRIVER_DRIVER_PATH` | Generic fallback path (either browser) | — |
+| `CRAFTDRIVER_CHROME_PATH` | Absolute path to a Chrome/Chromium binary — see [Browser Binary Configuration](#browser-binary-configuration) | — |
+| `CRAFTDRIVER_FIREFOX_PATH` | Absolute path to a Firefox binary | — |
+| `CRAFTDRIVER_BROWSER_PATH` | Generic browser-binary fallback path (either browser) | — |
 | `CRAFTDRIVER_CACHE_DIR` | Directory for cached driver downloads | `~/.cache/craftdriver` |
 | `CRAFTDRIVER_OFFLINE` | Set to `1` to disable all network calls | — |
 | `CRAFTDRIVER_DRIVER_TTL` | Driver-resolution cache lifetime, in seconds (both browsers). `0` disables the cache | `86400` (24 h) |
@@ -115,6 +200,20 @@ but the direction holds):
 
 Run it yourself with `npm run bench -- launch-critical-path`.
 
+A separate micro-benchmark (`tests/perf/driver-resolution.perf.ts`) isolates
+just the CI-provided driver directory step from the rest of the resolution
+chain — `resolveChromeDriver()` alone, cache isolated so both paths are
+measured cold:
+
+| Scenario | Time |
+|---|---|
+| `CHROMEWEBDRIVER` set (new) | ~0ms (an `fs.existsSync` check) |
+| PATH-probe + Chrome-version-detect fallback (old) | ~360ms |
+
+That's the cost every cold `Browser.launch()` used to pay once per process on
+a GitHub Actions runner before this step existed — now skipped entirely. Run
+it yourself with `npm run bench -- driver-resolution`.
+
 ### Browser startup flags (advanced, opt-in)
 
 craftdriver launches the browser with **no performance flags of its own** — it

package/docs/element-api.md

@@ -9,8 +9,10 @@ The `ElementHandle` provides methods for interacting with individual DOM element
 const element = browser.find('#my-element');
 const button = browser.find(By.text('Submit'));
 
-// Chained operations
-await browser.find('#input').fill('text').press('Enter');
+// Element-scoped operations
+const input = browser.find('#input');
+await input.fill('text');
+await input.press('Enter');
 ```
 
 > **Tip:** Use `browser.locator(selector)` instead of `find()` when you need
@@ -99,6 +101,14 @@ Get the current value of an input element.
 const inputValue = await browser.find('#email').value();
 ```
 
+### tagName()
+
+Get the element tag name.
+
+```typescript
+const tag = await browser.find('#submit').tagName(); // "button"
+```
+
 ### getAttribute(name)
 
 Get an attribute value from the element.
@@ -166,14 +176,35 @@ await browser.find('#message').expect().toHaveText('Success');
 await browser.find('#input').expect().toHaveValue('test@example.com');
 ```
 
-## Method Chaining
+### setInputFiles(filePaths, options?)
+
+Set files on an `<input type="file">`.
+
+```typescript
+await browser.find('#avatar').setInputFiles('/absolute/path/avatar.png');
+await browser.find('#photos').setInputFiles([
+  '/absolute/path/one.jpg',
+  '/absolute/path/two.jpg',
+]);
+```
+
+### evaluate(fn, ...args)
 
-ElementHandle methods that don't return values can be chained:
+Run JavaScript with this element as the first argument.
 
 ```typescript
-await browser.find('#username').fill('testuser').press('Tab');
+const tag = await browser.find('#submit').evaluate(el => el.tagName.toLowerCase());
+const active = await browser
+  .find('#submit')
+  .evaluate((el, cls) => el.classList.contains(cls), 'active');
+```
 
-await browser.find('#password').fill('secret123').press('Enter');
+### a11y
+
+Run an accessibility audit scoped to this element and its descendants.
+
+```typescript
+const result = await browser.find('#checkout').a11y.audit();
 ```
 
 ## Examples

package/docs/emulation.md

@@ -65,7 +65,9 @@ JavaScript-only patch.
 await browser.emulate({ colorScheme: 'dark' });
 await browser.navigateTo('https://app.example.com');
 
-const bg = await browser.find('body').getCssValue('background-color');
+const bg = await browser.evaluate(() =>
+  getComputedStyle(document.body).backgroundColor
+);
 expect(bg).toBe('rgb(17, 17, 17)');
 ```
 
@@ -108,7 +110,9 @@ Confirm animations are actually suppressed for users who request it.
 await browser.emulate({ reducedMotion: 'reduce' });
 await browser.navigateTo('https://app.example.com');
 
-const anim = await browser.find('.hero').getCssValue('animation-name');
+const anim = await browser.evaluate(() =>
+  getComputedStyle(document.querySelector('.hero')!).animationName
+);
 expect(anim).toBe('none');
 ```
 

package/docs/index.md

@@ -0,0 +1,64 @@
+---
+layout: home
+title: CraftDriver
+titleTemplate: false
+hero:
+  name: CraftDriver
+  text: Crafted browser automation for Node.js.
+  tagline: Playwright-style ergonomics. WebDriver standards. AI friendly.
+  image:
+    src: /craftdriver-mark.svg
+    alt: CraftDriver
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /getting-started
+    - theme: alt
+      text: API Reference
+      link: /api-reference
+    - theme: alt
+      text: AI Agent Guide
+      link: /agents
+features:
+  - title: Control network traffic
+    details: Mock APIs, block noisy requests, intercept calls, and wait for real requests or responses.
+  - title: Reuse browser state
+    details: Save cookies and localStorage, launch already signed in, and isolate users with browser contexts.
+  - title: Test time and quality
+    details: Use virtual time, axe-core accessibility checks, traces, screenshots, console logs, and JS error capture.
+  - title: Agent-friendly
+    details: CLI, MCP server, and assistant rules are there when you want coding agents to drive the browser too.
+---
+
+## One Install
+
+```bash
+npm install craftdriver --save-dev
+```
+
+```ts
+import { Browser } from 'craftdriver';
+
+const browser = await Browser.launch({ browserName: 'chrome' });
+
+await browser.navigateTo('https://example.com/login');
+await browser.getByLabel('Username').fill('alice');
+await browser.getByLabel('Password').fill('hunter2');
+await browser.getByRole('button', { name: 'Sign in' }).click();
+await browser.expect('#result').toHaveText('Welcome alice');
+
+await browser.quit();
+```
+
+## Choose Your Path
+
+| You want to...                    | Start                                   |
+| --------------------------------- | --------------------------------------- |
+| Write browser automation          | [Getting Started](./getting-started.md) |
+| Give an AI coding agent a browser | [AI Agent Guide](./agents.md)           |
+
+## Good Stuff To Read Next
+
+- [Zero-Config Drivers](./zero-config-drivers.md) explains driver resolution and caching.
+- [WebDriver Standards](./standards.md) explains how Classic and BiDi work together.
+- [Recipes](./recipes.md) collects KB-style patterns for common real-world workflows.

package/docs/keyboard-mouse.md

@@ -48,6 +48,15 @@ Release a held key.
 await browser.keyboard.up('Shift');
 ```
 
+### chord(...keys)
+
+Press a key combination.
+
+```typescript
+await browser.keyboard.chord('Control', 'a');
+await browser.keyboard.chord('Shift', 'Tab');
+```
+
 ### Key Combinations
 
 Combine `down()` and `up()` for modifier key combinations:
@@ -129,23 +138,25 @@ await browser.mouse.move({ x: 150, y: 300 });
 await browser.mouse.move('#target');
 ```
 
-### down()
+### down(button?)
 
 Press the mouse button.
 
 ```typescript
 await browser.mouse.down();
+await browser.mouse.down('right');
 ```
 
-### up()
+### up(button?)
 
 Release the mouse button.
 
 ```typescript
 await browser.mouse.up();
+await browser.mouse.up('right');
 ```
 
-### wheel(deltaX, deltaY)
+### wheel(deltaX, deltaY, target?)
 
 Scroll the page.
 
@@ -158,6 +169,9 @@ await browser.mouse.wheel(0, -100);
 
 // Scroll right
 await browser.mouse.wheel(100, 0);
+
+// Scroll while targeting an element
+await browser.mouse.wheel(0, 300, '#scroll-panel');
 ```
 
 ### dragAndDrop(from, to)
@@ -194,14 +208,14 @@ await browser.mouse.dragAndDrop({ x: startX, y: startY }, { x: endX, y: endY });
 
 ```typescript
 // Move to start position
-await browser.mouse.move(100, 100);
+await browser.mouse.move({ x: 100, y: 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.move({ x: 200, y: 100 });
+await browser.mouse.move({ x: 200, y: 200 });
+await browser.mouse.move({ x: 100, y: 200 });
+await browser.mouse.move({ x: 100, y: 100 });
 
 await browser.mouse.up();
 ```
@@ -227,10 +241,14 @@ 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');
+const search = browser.find('#search');
+await search.fill('query');
+await search.press('Enter');
 
 // Tab out of a field
-await browser.find('#username').fill('user').press('Tab');
+const username = browser.find('#username');
+await username.fill('user');
+await username.press('Tab');
 ```
 
 This is often more convenient than using the global keyboard API.

package/docs/mobile-emulation.md

@@ -163,9 +163,9 @@ await browser.click('#mobile-menu-button');
 await browser.expect('#mobile-menu').toBeVisible();
 ```
 
-### Combine with BiDi Features
+### Combine With Network Mocking And Logs
 
-Mobile emulation works alongside BiDi features:
+Mobile emulation works alongside network mocking and browser log capture:
 
 ```typescript
 const browser = await Browser.launch({
@@ -186,6 +186,9 @@ const errors = browser.logs.getErrors();
 expect(errors).toHaveLength(0);
 ```
 
+Learn more in [Network Mocking And Request Waiting](./network.md) and
+[Console Logs And JavaScript Errors](./browser-logs.md).
+
 ## Limitations
 
 - **Chrome/Chromium only**: Mobile emulation uses Chrome-specific capabilities

package/docs/network.md

@@ -0,0 +1,203 @@
+# Network Mocking And Request Waiting
+
+Use CraftDriver network tools when a test needs to control or observe HTTP traffic:
+
+- mock an API response without changing the backend
+- block analytics, ads, or flaky third-party services
+- add headers such as auth tokens or test markers
+- wait for the request or response triggered by a click
+- assert that the app sent the right method, URL, or headers
+
+> **Requires the default browser event connection.** Network interception and
+> request/response waiting require `enableBiDi: true` (the default) and a
+> browser that supports WebDriver BiDi. If you launch with
+> `enableBiDi: false`, these methods throw a clear `requires BiDi` error.
+
+## Browser Support
+
+CraftDriver supports these network APIs on Chrome, Chromium, and Firefox.
+
+## Quick Mock
+
+```typescript
+await browser.network.mock('**/api/users', {
+  status: 200,
+  body: {
+    users: [{ id: 1, name: 'Test User' }],
+  },
+});
+
+await browser.navigateTo('https://example.com/dashboard');
+await browser.expect('#users').toContainText('Test User');
+```
+
+The pattern uses URL globs. `**/api/users` matches that path on any host.
+
+## Common Tasks
+
+| Goal | API |
+| ---- | --- |
+| Return a fake response | `browser.network.mock(pattern, response)` |
+| Block matching requests | `browser.network.block(pattern)` |
+| Dynamically inspect and respond | `browser.network.intercept(pattern, handler)` |
+| Remove one route | `browser.network.removeIntercept(id)` |
+| Remove every route | `browser.network.removeAllIntercepts()` |
+| Add headers to outgoing requests | `browser.network.setExtraHeaders(headers)` |
+| Bypass or restore browser cache | `browser.network.setCacheBehavior(behavior)` |
+| Wait until traffic settles | `browser.network.waitForNetworkIdle(opts?)` |
+| Wait for one request | `browser.waitForRequest(patternOrPredicate, opts?)` |
+| Wait for one response | `browser.waitForResponse(patternOrPredicate, opts?)` |
+
+## Mock Responses
+
+### Static response
+
+```typescript
+await browser.network.mock('**/api/login', {
+  status: 401,
+  body: { error: 'Invalid credentials' },
+});
+
+await browser.getByLabel('Username').fill('baduser');
+await browser.getByLabel('Password').fill('wrongpass');
+await browser.getByRole('button', { name: 'Sign in' }).click();
+
+await browser.expect('#error').toHaveText('Invalid credentials');
+```
+
+### Dynamic response
+
+```typescript
+await browser.network.mock('**/api/items/*', (request) => {
+  const id = request.url.split('/').pop();
+
+  return {
+    status: 200,
+    body: { id, name: `Item ${id}`, price: 9.99 },
+  };
+});
+```
+
+## Block Requests
+
+```typescript
+await browser.network.block('**/analytics/**');
+await browser.network.block('**/tracking/**');
+```
+
+This is useful when third-party services make tests slower or less predictable.
+
+## Add Headers
+
+```typescript
+await browser.network.setExtraHeaders({
+  'X-Test-Mode': 'true',
+  Authorization: 'Bearer test-token',
+});
+```
+
+Extra headers are applied to matching browser requests after they are configured.
+
+## Control Cache
+
+```typescript
+await browser.network.setCacheBehavior('bypass');
+
+// Later, restore normal browser caching.
+await browser.network.setCacheBehavior('default');
+```
+
+## Intercept Requests
+
+Use `intercept()` when the response depends on request details or asynchronous
+test setup.
+
+```typescript
+const seen: string[] = [];
+
+const interceptId = await browser.network.intercept('**/api/**', async (request) => {
+  seen.push(`${request.method} ${request.url}`);
+
+  return {
+    status: 200,
+    body: { intercepted: true, originalUrl: request.url },
+  };
+});
+
+// Later, remove only this intercept.
+await browser.network.removeIntercept(interceptId);
+```
+
+You can also delay a response to test loading UI:
+
+```typescript
+await browser.network.intercept('**/api/**', async () => {
+  await new Promise((resolve) => setTimeout(resolve, 3000));
+  return { status: 200, body: { data: 'delayed response' } };
+});
+
+await browser.getByRole('button', { name: 'Load data' }).click();
+await browser.expect('#loading-spinner').toBeVisible();
+```
+
+## Wait For Real Traffic
+
+`browser.waitForRequest()` and `browser.waitForResponse()` observe real network
+traffic without mocking it. Register the wait before the action that triggers the
+request. `Promise.all` is the safest pattern:
+
+```typescript
+const [response] = await Promise.all([
+  browser.waitForResponse('**/api/users'),
+  browser.getByRole('button', { name: 'Load users' }).click(),
+]);
+
+expect(response.status).toBe(200);
+```
+
+Both methods accept a URL glob or a predicate:
+
+```typescript
+const [response] = await Promise.all([
+  browser.waitForResponse((res) => {
+    return res.url.includes('/api/users') && res.status === 200;
+  }),
+  browser.getByRole('button', { name: 'Load users' }).click(),
+]);
+```
+
+### Response shape
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `url` | `string` | Full request URL |
+| `status` | `number` | HTTP status code |
+| `statusText` | `string` | Status text such as `"OK"` |
+| `headers` | `Record<string, string>` | Response headers |
+| `mimeType` | `string` | Response MIME type |
+| `fromCache` | `boolean` | Whether the browser served it from cache |
+| `request` | `{ id, url, method, headers }` | Matching request info |
+
+### Request shape
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `id` | `string` | Browser request id |
+| `url` | `string` | Full URL |
+| `method` | `string` | Request method, such as `"GET"` or `"POST"` |
+| `headers` | `Record<string, string>` | Request headers |
+
+## Timeouts
+
+Both wait methods accept `{ timeout?: number }`. The default is the browser
+navigation timeout, 30 seconds.
+
+```typescript
+await browser.waitForResponse('**/api/users', { timeout: 10_000 });
+```
+
+On timeout, CraftDriver throws a clear error:
+
+```text
+waitForResponse("**/api/users") timed out after 30000ms
+```

package/docs/public/craftdriver-mark.svg

@@ -0,0 +1,15 @@
+<svg width="160" height="160" viewBox="0 0 160 160" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">CraftDriver mark</title>
+  <desc id="desc">A browser window with a command prompt and connection nodes.</desc>
+  <rect x="12" y="24" width="136" height="112" rx="18" fill="#111827"/>
+  <rect x="24" y="42" width="112" height="78" rx="10" fill="#f8fafc"/>
+  <circle cx="34" cy="34" r="5" fill="#f97316"/>
+  <circle cx="50" cy="34" r="5" fill="#f59e0b"/>
+  <circle cx="66" cy="34" r="5" fill="#22c55e"/>
+  <path d="M44 78L60 64L44 50" stroke="#b45309" stroke-width="8" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M70 82H104" stroke="#2563eb" stroke-width="8" stroke-linecap="round"/>
+  <path d="M91 60H112C121.941 60 130 68.0589 130 78V78C130 87.9411 121.941 96 112 96H91" stroke="#94a3b8" stroke-width="6" stroke-linecap="round"/>
+  <circle cx="88" cy="60" r="8" fill="#2563eb"/>
+  <circle cx="88" cy="96" r="8" fill="#f59e0b"/>
+  <circle cx="118" cy="78" r="8" fill="#22c55e"/>
+</svg>

package/docs/public/social-card.svg

@@ -0,0 +1,27 @@
+<svg width="1200" height="630" viewBox="0 0 1200 630" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">CraftDriver social card</title>
+  <desc id="desc">Standards-based browser automation for Node.js, tests, scripts, and AI agents.</desc>
+  <rect width="1200" height="630" fill="#0f172a"/>
+  <rect x="72" y="72" width="1056" height="486" rx="32" fill="#111827" stroke="#334155" stroke-width="2"/>
+  <rect x="116" y="122" width="396" height="276" rx="24" fill="#f8fafc"/>
+  <rect x="116" y="122" width="396" height="54" rx="24" fill="#1f2937"/>
+  <circle cx="154" cy="149" r="9" fill="#f97316"/>
+  <circle cx="184" cy="149" r="9" fill="#f59e0b"/>
+  <circle cx="214" cy="149" r="9" fill="#22c55e"/>
+  <path d="M184 274L230 232L184 190" stroke="#b45309" stroke-width="18" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M264 286H382" stroke="#2563eb" stroke-width="18" stroke-linecap="round"/>
+  <path d="M349 210H414C446.585 210 473 236.415 473 269V269C473 301.585 446.585 328 414 328H349" stroke="#94a3b8" stroke-width="12" stroke-linecap="round"/>
+  <circle cx="346" cy="210" r="17" fill="#2563eb"/>
+  <circle cx="346" cy="328" r="17" fill="#f59e0b"/>
+  <circle cx="432" cy="269" r="17" fill="#22c55e"/>
+  <text x="574" y="212" fill="#f8fafc" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="82" font-weight="800">CraftDriver</text>
+  <text x="578" y="281" fill="#f59e0b" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="34" font-weight="700">WebDriver automation for humans and AI agents</text>
+  <text x="578" y="356" fill="#cbd5e1" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="30">Playwright-style ergonomics. WebDriver standards. AI friendly.</text>
+  <text x="578" y="408" fill="#cbd5e1" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="30">Library API, CLI, MCP server, and packaged agent skills.</text>
+  <rect x="578" y="462" width="156" height="48" rx="24" fill="#b45309"/>
+  <text x="614" y="495" fill="#fff7ed" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="700">Node.js</text>
+  <rect x="754" y="462" width="178" height="48" rx="24" fill="#1d4ed8"/>
+  <text x="790" y="495" fill="#eff6ff" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="700">WebDriver</text>
+  <rect x="952" y="462" width="102" height="48" rx="24" fill="#15803d"/>
+  <text x="984" y="495" fill="#f0fdf4" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="700">MCP</text>
+</svg>