craftdriver 1.6.0 → 1.8.0

package/docs/mcp.md

@@ -1,29 +1,31 @@
 # 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.
+`craftdriver` ships an optional [Model Context Protocol](https://modelcontextprotocol.io)
+STDIO adapter so MCP-aware coding agents can drive the same local session and
+dispatcher as the CLI.
 
-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.
+CLI plus the installed CraftDriver skill is the recommended workflow. MCP is
+not required for exploration or test authoring.
 
 ```bash
 # Start once via your MCP client — examples below
-npx -y craftdriver mcp
+npx --no-install 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.
+Each newline-delimited input frame is limited to 1 MiB (1,048,576 UTF-8
+bytes); oversized frames return a parse error and are discarded.
 
-## Install snippets
+## Manual project-pinned setup
+
+Run `npx craftdriver init codex --mcp` to print the exact snippet. The installer
+does not read or change MCP configuration.
 
 ### Claude Code / Claude Desktop
 
 ```bash
-claude mcp add craftdriver -- npx -y craftdriver mcp
+claude mcp add craftdriver -- npx --no-install craftdriver mcp
 ```
 
 ### Cursor / Windsurf / Zed (`.cursor/mcp.json` and similar)
@@ -33,7 +35,7 @@ claude mcp add craftdriver -- npx -y craftdriver mcp
   "mcpServers": {
     "craftdriver": {
       "command": "npx",
-      "args": ["-y", "craftdriver", "mcp"]
+      "args": ["--no-install", "craftdriver", "mcp"]
     }
   }
 }
@@ -42,7 +44,7 @@ claude mcp add craftdriver -- npx -y craftdriver mcp
 ### Gemini CLI
 
 ```bash
-gemini mcp add craftdriver npx -y craftdriver mcp
+gemini mcp add craftdriver npx --no-install craftdriver mcp
 ```
 
 ### Goose
@@ -53,42 +55,90 @@ goose configure   # add craftdriver as a stdio server
 
 ## Tools
 
-Compact set — 15 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_trace`          | Start/stop tracing and export a Vibium Player compatible zip.            |
-| `browser_status`         | Browser up? Which URL is active?                                       |
-| `browser_advanced_eval`  | Evaluate JS in the page. Last resort.                                  |
-
-Trace a complete agent-driven session with two calls:
+One line each; the long help lives in the schema description, which clients
+render into the model's context once per session. Every tool dispatches a
+command the CLI also has — there are no MCP-only browser semantics.
+
+| Tool                    | Purpose                                                                |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `browser_navigate`      | Go to a URL (waits for load).                                          |
+| `browser_click`         | Click an element; set `double` for a double-click.                     |
+| `browser_fill`          | Fill an input/textarea (clears first, real key events).                |
+| `browser_type`          | Type into whatever holds focus (no selector).                          |
+| `browser_element`       | `dblclick`/`focus`/`scroll`/`clear`/`check`/`uncheck`/`select`.        |
+| `browser_press`         | Press a key (`Enter`, `Tab`, `Control+A`).                             |
+| `browser_key`           | Low-level `press`/`down`/`up` for modifier combinations.               |
+| `browser_mouse`         | `move`/`click`/`down`/`up`/`wheel`, by element or coordinate.          |
+| `browser_hover`         | Hover over an element.                                                 |
+| `browser_upload`        | Set files on a file input (bounded; paths never echoed).               |
+| `browser_dialog`        | `inspect`/`accept`/`dismiss` a native dialog.                          |
+| `browser_find`          | Locate elements without acting (tag/text/visibility).                  |
+| `browser_exists`        | **0-wait probe.** Returns `{exists, count}` in one roundtrip.          |
+| `browser_wait`          | Wait for a selector state or a load state.                             |
+| `browser_read`          | Read `text` / `attr` / `value` / `is(visible\|enabled\|checked)`.      |
+| `browser_snapshot`      | **Sanitized DOM summary with refs.** Use `ref=eN` as a selector.       |
+| `browser_locators`      | **Turn an element into durable selectors for a test.** Never a ref.    |
+| `browser_page`          | `list`/`open`/`select`/`close` tabs.                                   |
+| `browser_logs`          | Console + network history, with cursors. See below.                    |
+| `browser_mock`          | Serve a fixed response or block matching requests.                     |
+| `browser_state`         | Save/restore cookies and local storage (a login, once).                |
+| `browser_trace`         | Record a run to an owned directory; `zip` for a Vibium archive.        |
+| `browser_screenshot`    | Capture PNG to a file under the artifact dir; never inlined.           |
+| `browser_status`        | Browser up? Which URL is active?                                       |
+| `browser_advanced_eval` | Evaluate JS in the page. Last resort.                                  |
+
+Each tool carries MCP `annotations` — `title`, `readOnlyHint`,
+`destructiveHint`, `idempotentHint`, `openWorldHint` — and they are accurate:
+a tool marked read-only never dispatches a command the dispatcher treats as
+page-mutating, which is asserted by test rather than by review.
+
+### Debugging with evidence
+
+`browser_logs` captures console and network from launch, so an error thrown
+during the first navigation is still answerable afterwards. Every result
+carries a `cursor`; pass it back as `since` for only what is new. `kind=error`
+covers both uncaught exceptions and `console.error`. Network rows are
+summaries — url, method, status, mime type — and never carry bodies, cookies,
+or headers.
 
 ```jsonc
-{ "name": "browser_trace", "arguments": {
-  "action": "start", "out_dir": "./traces/agent-raw", "title": "Agent flow"
+{ "name": "browser_logs", "arguments": { "action": "list", "kind": "error" } }
+{ "name": "browser_logs", "arguments": {
+  "action": "wait", "contains": "checkout ok", "timeout_ms": 10000
 } }
+```
+
+### Tracing
+
+```jsonc
+{ "name": "browser_trace", "arguments": { "action": "start", "name": "agentflow" } }
 // ...browser_navigate / browser_fill / browser_click calls...
-{ "name": "browser_trace", "arguments": {
-  "action": "stop", "path": "./traces/agent-flow.zip"
-} }
+{ "name": "browser_trace", "arguments": { "action": "stop", "zip": true } }
 ```
 
-The zip opens at [player.vibium.dev](https://player.vibium.dev/). The raw
-directory remains available if the MCP client disconnects before the stop
-call; in that case there is no finalized zip.
+The response reports where the trace and archive landed; the zip opens at
+[player.vibium.dev](https://player.vibium.dev/). Output goes to an owned
+directory (`CRAFTDRIVER_TRACE_DIR`), and `name` is a bare name rather than a
+path — an earlier version accepted an arbitrary filesystem path straight off
+the wire. If the client disconnects before `stop`, the raw NDJSON is still
+valid, just without a finalized zip.
+
+## Argument validation
+
+Every tool declares its arguments once; that declaration produces both the
+advertised `inputSchema` and the runtime check, so a tool cannot promise a
+constraint it does not enforce. Invalid arguments are rejected as JSON-RPC
+`-32602` **before** anything reaches the browser:
+
+- an unknown field (rather than being silently ignored — a misspelled required
+  argument would otherwise look like a successful call that did something else);
+- a wrong type, a non-finite number, an out-of-range number, an invalid enum;
+- an oversized string or array.
+
+`-32602` also covers an unknown tool name. Ordinary browser failures — a
+missing element, a timeout — are **not** protocol errors; they come back as
+successful responses with `isError: true`, which is what keeps the two
+distinguishable.
 
 ## Selector syntax
 
@@ -128,11 +178,14 @@ Use `ref=eN` as the selector for the next call:
 { "name": "browser_click", "arguments": { "selector": "ref=e7" } }
 ```
 
-**Why this is a big deal for AI test generation**
+**Use refs only for immediate exploration**
 
-- **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.
+- **A ref names one element for as long as it lives.** A surviving node keeps
+  its ref across snapshots, and refs are never reused — so a ref cannot drift
+  onto a different element. If it is removed, duplicated, or the page
+  navigates, the call fails `STALE_REF`; take a fresh snapshot then.
+- **Never copy refs into test code.** Convert live role/name, label, test ID,
+  text, or DOM evidence into a durable selector and validate it.
 - **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
@@ -141,11 +194,16 @@ Use `ref=eN` as the selector for the next call:
 
 **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.
+- A ref binds to one element. An element that survives a DOM change keeps
+  its ref across snapshots; snapshots do **not** renumber it.
+- New elements get fresh numbers. Refs are never reused, including after a
+  navigation or reload.
+- A ref whose element was removed or duplicated, or that was issued before
+  the page navigated or reloaded, fails with `STALE_REF` — take a fresh
+  snapshot. It never resolves to a different element.
+- `error.detail.reason` distinguishes `detached`, `document-changed`,
+  `unknown-ref`, `ambiguous`, and `no-snapshot`.
+- Refs are exploration state and must never appear in committed tests.
 
 ## Post-action payload
 
@@ -197,10 +255,10 @@ button "Click me" #by-text
 
 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.
+- **Screenshots** — always written to a server-allocated file under the
+  per-session artifact directory. The inline block carries the absolute path
+  and byte count — **zero** image tokens. The tool accepts no destination
+  path, so it cannot write outside that directory.
 - **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
@@ -213,20 +271,29 @@ Configuration:
 | ---------------------------------- | ---------------- | ------------------------------------------------- |
 | `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.     |
+| `CRAFTDRIVER_MCP_MAX_RESPONSE_BYTES` | `32768`        | Maximum serialized result from one tool call.     |
 
 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.
+cleanup policy. Each server process refuses more than 500 artifacts or 256 MiB
+in its session directory; browser-written screenshots are counted by their
+actual file size after capture.
 
-The `structuredContent` field is unaffected by spilling — small results
-still round-trip in full there for programmatic consumers.
+Small results still round-trip in full through `structuredContent`. When the
+complete result would exceed the response cap, it becomes explicit truncation
+metadata and a bounded preview rather than duplicating the full spilled value.
 
 ## 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).
+Browser and action failures are returned as `isError: true` content (per MCP
+spec), **not** as JSON-RPC errors. JSON-RPC errors are reserved for
+protocol-level failures: a malformed request (`-32700`/`-32600`), an unknown
+method (`-32601`), and an unknown tool or invalid arguments (`-32602`).
+
+The split matters: "the element was not there" is a fact about the page that an
+agent should reason about, while "you sent an argument that does not exist" is
+a mistake about the protocol that it should correct.
 
 ```jsonc
 {

package/docs/public/examples/agent-actions.html

@@ -0,0 +1,48 @@
+<!doctype html>
+<!--
+  Agent-surface fixture for the common action set and for durable locator
+  candidates. Deliberately mixes elements that offer good evidence (role +
+  name, label, test id) with ones that offer only generated attributes, so
+  tests can prove `locators` tells the truth in both cases.
+-->
+<html><head><title>Agent actions</title></head>
+<body>
+  <h1>Account settings</h1>
+
+  <label for="nickname">Nickname</label>
+  <input id="nickname" name="nickname" type="text" value="preset" />
+
+  <label for="newsletter">Newsletter</label>
+  <input id="newsletter" name="newsletter" type="checkbox" />
+
+  <label for="plan">Plan</label>
+  <select id="plan" name="plan">
+    <option value="free">Free</option>
+    <option value="pro">Pro</option>
+  </select>
+
+  <button id="save" data-testid="save-button" type="button">Save changes</button>
+  <button id="a1b2c3d4e5f6" type="button">Generated id</button>
+
+  <p id="dbl-count">0</p>
+  <button id="counter" type="button">Count me</button>
+
+  <div style="height: 1500px"></div>
+  <button id="far-below" type="button">Far below</button>
+
+  <p id="log"></p>
+  <script>
+    const log = document.getElementById('log');
+    let dbl = 0;
+    document.getElementById('counter').addEventListener('dblclick', () => {
+      dbl += 1;
+      document.getElementById('dbl-count').textContent = String(dbl);
+    });
+    document.getElementById('nickname').addEventListener('keydown', () => {
+      log.textContent = 'keydown seen';
+    });
+    document.getElementById('save').addEventListener('click', () => {
+      log.textContent = 'saved';
+    });
+  </script>
+</body></html>

package/docs/public/examples/agent-debug.html

@@ -0,0 +1,86 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Craftdriver Debug Example</title>
+  <style>
+    body { font-family: system-ui, sans-serif; max-width: 34rem; margin: 3rem auto; padding: 0 1rem; }
+    fieldset { border: 1px solid #ccc; border-radius: 6px; padding: 1rem 1.25rem; }
+    label { display: block; margin: 0.75rem 0 0.25rem; font-weight: 600; }
+    input { width: 100%; padding: 0.5rem; font-size: 1rem; box-sizing: border-box; }
+    button { margin-top: 1rem; padding: 0.6rem 1.2rem; font-size: 1rem; cursor: pointer; }
+    #status { margin-top: 1rem; padding: 0.75rem; border-radius: 6px; }
+    #status.error { background: #fdecea; color: #611a15; }
+    #status.ok { background: #edf7ed; color: #1e4620; }
+    .note { color: #555; font-size: 0.9rem; }
+  </style>
+</head>
+<body>
+  <h1>Checkout</h1>
+  <p class="note">
+    A deliberately opaque failure: the page reports only that something went
+    wrong. What actually failed is visible in the console and network journal,
+    not in the DOM.
+  </p>
+
+  <form id="checkout-form">
+    <fieldset>
+      <legend>Order details</legend>
+      <label for="email">Email</label>
+      <input id="email" name="email" type="email" placeholder="you@example.test" />
+
+      <label for="card">Card number</label>
+      <input id="card" name="card" type="text" placeholder="4242 4242 4242 4242" />
+
+      <button id="place-order" type="submit">Place order</button>
+    </fieldset>
+  </form>
+
+  <div id="status" hidden></div>
+
+  <script>
+    // The endpoint does not exist on the static example server, so this always
+    // fails with the same status. Nothing here is timing- or order-dependent:
+    // the same click produces the same evidence every run.
+    const ENDPOINT = '/api/checkout';
+
+    const form = document.getElementById('checkout-form');
+    const status = document.getElementById('status');
+
+    function show(text, kind) {
+      status.hidden = false;
+      status.className = kind;
+      status.textContent = text;
+    }
+
+    form.addEventListener('submit', async (event) => {
+      event.preventDefault();
+      show('Placing order…', '');
+
+      try {
+        const response = await fetch(ENDPOINT, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ email: document.getElementById('email').value }),
+        });
+
+        if (!response.ok) {
+          // The detail goes to the console, not to the page — which is exactly
+          // the situation `craftdriver logs` exists for.
+          console.error(
+            'checkout failed: HTTP ' + response.status + ' from ' + ENDPOINT
+          );
+          show('Something went wrong. Please try again.', 'error');
+          return;
+        }
+
+        const order = await response.json();
+        show('Order ' + order.orderId + ' confirmed', 'ok');
+      } catch (err) {
+        console.error('checkout request threw: ' + err.message);
+        show('Something went wrong. Please try again.', 'error');
+      }
+    });
+  </script>
+</body>
+</html>

package/docs/public/examples/agent-late-mutation.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<!--
+  Agent-surface fixture: the page mutates itself after load with no agent
+  action involved. Used to prove explicit and automatic snapshots share one
+  baseline — an explicit snapshot must not leave the next post-action diff
+  re-reporting changes the agent has already been shown.
+-->
+<html><head><title>Timer repro</title></head>
+<body>
+  <h1>Dashboard</h1>
+  <div id="slot"></div>
+  <button id="go">Go</button>
+  <script>
+    setTimeout(() => {
+      document.getElementById('slot').innerHTML = '<button id="late">Late arrival</button>';
+    }, 800);
+  </script>
+</body></html>

package/docs/public/examples/agent-ref-shift.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<!--
+  Agent-surface fixture: a DOM reorder that shifts every element's document
+  position. Used to prove snapshot refs bind to element identity, not to
+  document order (a stale ref must fail, never act on a replacement node).
+-->
+<html><head><title>Shift repro</title></head>
+<body>
+  <h1>Checkout</h1>
+  <div id="banner"></div>
+  <form id="f">
+    <label for="coupon">Coupon</label>
+    <input id="coupon" name="coupon" type="text" />
+    <button id="apply" type="button">Apply coupon</button>
+    <label for="email">Email</label>
+    <input id="email" name="email" type="text" />
+    <button id="pay" type="button">Pay now</button>
+    <button id="remove-pay" type="button">Remove pay button</button>
+  </form>
+  <script>
+    // Realistic: applying an invalid coupon renders an inline error with a
+    // help link ABOVE the rest of the form, shifting everything below it.
+    document.getElementById('apply').addEventListener('click', () => {
+      document.getElementById('banner').innerHTML =
+        '<a href="/help" id="help">Why was my coupon rejected?</a>';
+    });
+    // Removing the pay button lets a test prove a removed ref fails rather
+    // than silently resolving to whatever took its place.
+    document.getElementById('remove-pay').addEventListener('click', () => {
+      document.getElementById('pay').remove();
+    });
+  </script>
+</body></html>

package/docs/recipes/login-once-reuse-session.md

@@ -1,11 +1,11 @@
 # Log In Once And Reuse The Session
 
 Signing in through the UI in every test is slow, and for most tests logging in
-is not the thing being proven. Do it once, save the resulting cookies and
-localStorage, then launch later tests already authenticated with `storageState`.
-Both halves below run against the live
+is not the thing being proven. Do it once, save the resulting session, then
+launch later tests already authenticated with `storageState`. Both halves below
+run against the live
 [login example](https://dtopuzov.github.io/craftdriver/examples/login.html),
-which persists its session in a cookie.
+which persists auth in a cookie and user preferences in localStorage.
 
 ## Generate Auth State
 
@@ -38,6 +38,34 @@ await browser.navigateTo('https://dtopuzov.github.io/craftdriver/examples/login.
 await browser.expect('#welcome').toContainText('Welcome back, alice!');
 ```
 
+## What `storageState` Restores
+
+On supported WebDriver BiDi sessions, launch restores cookies **and every
+captured localStorage origin** before the first real navigation. CraftDriver
+uses a private, locally fulfilled same-origin document because BiDi has no
+out-of-band localStorage command. The state is written once, so application
+changes survive reload.
+
+`storageState` does not restore IndexedDB, Cache Storage, service workers, or
+reusable sessionStorage. Context and launch APIs reject non-empty
+sessionStorage rather than silently dropping it.
+
+WebDriver Classic cannot restore arbitrary-origin localStorage at launch, so a
+non-empty launch `storageState` is rejected. Its strict single-origin fallback
+is explicit:
+
+```ts
+const browser = await Browser.launch({ enableBiDi: false });
+
+await browser.navigateTo('https://example.test/app');  // reach the origin
+await browser.loadState('.auth/alice.json');           // now storage can land
+await browser.reload();                                // let the app read it
+```
+
+The fallback validates the complete snapshot before applying anything. A
+second origin or a cookie that cannot be set from the active page fails loudly.
+Chrome/Chromium and Firefox BiDi use the simpler launch form above.
+
 ## Notes
 
 - Keep generated auth files out of source control if they contain real secrets.

package/docs/screenshots.md

@@ -17,6 +17,10 @@ craftdriver exposes a single options-bag `screenshot()` method on both
 
 `fullPage` and `selector` are mutually exclusive.
 
+> To **compare** a screenshot against a committed baseline (with retries and
+> pixel tolerances) rather than just capture one, see
+> [Visual testing](./visual-testing.md) and `browser.expectScreenshot()`.
+
 ```typescript
 // Viewport only (default), buffer
 const buffer = await browser.screenshot();
@@ -78,15 +82,20 @@ afterEach(async (context) => {
 
 ### Visual comparison baseline
 
-```typescript
-await browser.navigateTo('https://example.com');
-await browser.screenshot({ path: 'baseline/homepage.png' });
+For visual regression testing you don't manage baseline and candidate PNGs by
+hand or reach for a separate image-diff library. `browser.expectScreenshot()`
+captures, compares against a committed baseline, retries until it settles, and
+throws a typed diff on a real change — creating the baseline on the first run:
 
-// Later, capture the candidate and diff with an image library:
-await browser.navigateTo('https://example.com');
-await browser.screenshot({ path: 'current/homepage.png' });
+```typescript
+await browser.expectScreenshot('baselines/homepage.png', {
+  screenshot: { fullPage: true },
+});
 ```
 
+See [Visual testing](./visual-testing.md) for baselines, thresholds, ignoring
+anti-aliasing, updating baselines, and making CI deterministic.
+
 ### Component screenshots
 
 ```typescript