craftdriver 1.6.0 → 1.8.0

package/docs/session-management.md

@@ -9,6 +9,10 @@ CraftDriver supports Playwright-style session persistence, allowing you to save
 Session management is the user-facing feature. Under the hood, CraftDriver uses
 the best available WebDriver transport for the browser you launched.
 
+`storageState` is CraftDriver's native cookies-plus-localStorage format. It is
+not a promise of Playwright JSON compatibility and does not include IndexedDB,
+Cache Storage, service workers, or reusable sessionStorage.
+
 ## Saving Session State
 
 ```typescript
@@ -52,6 +56,9 @@ The saved file contains:
 ```typescript
 // Load state into current browser
 await browser.loadState('./session.json');
+
+// Paths and in-memory state objects are equivalent
+await browser.loadState(await browser.storage.getState());
 ```
 
 ## Working With State Objects
@@ -63,6 +70,11 @@ const state = await browser.storage.getState();
 await browser.storage.setState(state);
 ```
 
+`browser.storage.setState()` is an active-page operation: navigate to the
+state's sole HTTP(S) origin first. `browser.loadState()` uses the full
+multi-origin hydrator on BiDi when the state has no sessionStorage; otherwise it
+uses the same strict active-page rules.
+
 ## Launching with Pre-loaded State
 
 The most common pattern - launch a browser with existing session:
@@ -78,6 +90,55 @@ await browser.navigateTo('https://example.com/dashboard');
 // Already logged in!
 ```
 
+On supported BiDi sessions, cookies and every captured localStorage origin are
+ready before the first real navigation. A private intercepted document seeds
+each origin once; application changes are not overwritten on reload.
+
+## Browser and Transport Support
+
+| Surface | Chrome/Chromium BiDi | Firefox BiDi | Chrome/Firefox/Safari Classic |
+| --- | --- | --- | --- |
+| `Browser.launch({ storageState })` | Full cookies + multi-origin localStorage | Full cookies + multi-origin localStorage | Non-empty state rejected before mutation |
+| `browser.newContext({ storageState })` | Full isolated restore | Full isolated restore | Unavailable (Classic has no user contexts) |
+| `context.loadStorageState()` | Full multi-origin overlay | Full multi-origin overlay | Unavailable |
+| `browser.loadState()` | Full multi-origin overlay without sessionStorage; strict active page with it | Same | Strict single-active-origin restore |
+| Save | Cookies + current/open-page localStorage origins | Same | Cookies + current-page localStorage |
+
+Chrome and Firefox BiDi and the Chrome/Firefox Classic fallback are covered by
+the integration suite. Chromium uses the same Chrome-family BiDi implementation.
+Safari is Classic-only and therefore receives the standards-only active-origin
+contract, not launch-time restore.
+
+### WebDriver Classic
+
+Classic cannot write arbitrary-origin localStorage at launch. Use the explicit
+fallback instead:
+
+```typescript
+const browser = await Browser.launch({ enableBiDi: false });
+await browser.navigateTo('https://example.com');
+await browser.loadState('./session.json');
+await browser.reload(); // the app can now read the restored state
+```
+
+CraftDriver validates the entire snapshot before mutation. `about:blank`,
+multiple storage origins, a mismatched cookie domain, or a secure cookie that
+cannot be set from the active page fails with `STATE_INVALID`. Non-empty
+`storageState` at Classic launch fails with `UNSUPPORTED` instead of pretending
+that a partial restore succeeded.
+
+### sessionStorage and runtime failure semantics
+
+`sessionStorage` capture is opt-in diagnostic state. Context and launch APIs
+reject a non-empty `sessionStorage` section because it cannot be transferred to
+future tabs. Active-page APIs can restore one matching origin after navigation.
+
+Fresh launch and `newContext` restoration clean up the new session/context on
+failure. An overlay into an existing context is not rollback-safe across
+multiple protocol calls. A runtime failure throws `DRIVER_ERROR` with
+`detail.phase` and `detail.partialApplied`; use a fresh context when failure
+isolation matters.
+
 ## Cookie Management API
 
 Direct cookie manipulation is also available:
@@ -221,7 +282,7 @@ async function testLoginPersistence() {
 | Method                      | Description                        |
 | --------------------------- | ---------------------------------- |
 | `saveState(path, options?)` | Save cookies and storage to file   |
-| `loadState(path)`           | Load cookies and storage from file |
+| `loadState(source)`         | Load cookies and storage from a path or object |
 
 ### StorageStateOptions
 
@@ -241,6 +302,6 @@ async function testLoginPersistence() {
 | `setCookies(cookies)`       | Set multiple cookies               |
 | `clearCookies(filter?)`     | Clear cookies, optionally filtered |
 | `getState(options?)`        | Get current state as object        |
-| `setState(state)`           | Set state from object              |
+| `setState(source)`          | Set active-page state from path or object |
 | `saveState(path, options?)` | Save state to file                 |
-| `loadState(path)`           | Load state from file               |
+| `loadState(source)`         | Load active-page state from path or object |

package/docs/visual-testing.md

@@ -0,0 +1,254 @@
+# Visual testing
+
+`browser.expectScreenshot()` compares a fresh browser screenshot against a PNG
+baseline in your repository, retrying until it matches or a timeout elapses. On
+a mismatch it throws a typed error carrying the final screenshot and a generated
+diff image so you can see exactly what changed.
+
+Baselines are managed for you, so the first run of a new test just works:
+
+- **No baseline yet** — the screenshot is captured until two consecutive frames
+  are identical (so a mid-animation frame isn't enshrined) or `timeout` elapses,
+  then written to the path you gave, and the assertion passes. Commit that PNG.
+  If the page never settled before the timeout, the write is an arbitrary frame
+  and the stderr line says so (`… page did not settle …`) — review it first.
+- **Baseline matches** — passes.
+- **Baseline differs** — throws `VisualMismatchError`. It is **never** rewritten
+  unless you explicitly ask (see [Updating baselines](#updating-baselines)).
+
+Behaviour is identical on your laptop and in CI — there is no "CI mode" that
+does something different. One tradeoff comes with the convenience: if a
+committed baseline is *deleted*, the next run recreates it and passes. Every
+create and update is printed to stderr (`[craftdriver] Created visual
+baseline: …`) so it shows up in your logs, but the real guard is committing your
+baselines and reviewing the diff whenever one changes.
+
+## The shortest thing that works
+
+```typescript
+// First run creates baselines/home.png; commit it. Every run after asserts
+// against it — same call, no separate bootstrap step.
+await browser.expectScreenshot('baselines/home.png', {
+  screenshot: { fullPage: true },
+});
+```
+
+`expectScreenshot()` returns a result object on success (`baseline`, `matches`,
+`diffPixels`, `diffPercentage`, `attempts`, `elapsedMs`, and both images'
+dimensions) and throws [`VisualMismatchError`](./error-codes.md) on failure.
+`result.baseline` is `'created'`, `'matched'`, or `'updated'` — what happened to
+the file on disk this run.
+
+## Capture scope
+
+`screenshot` chooses what to capture and is passed straight through to
+`browser.screenshot()`. The three forms mirror that method and are mutually
+exclusive:
+
+| `screenshot`                 | Captures                        | Notes                                  |
+| ---------------------------- | ------------------------------- | -------------------------------------- |
+| omitted                      | the visible viewport            | Classic or BiDi.                       |
+| `{ fullPage: true }`         | the full scrollable document    | Requires BiDi (`enableBiDi: true`, the default). |
+| `{ selector: '#chart' }`     | one element                     | Auto-waits for the element like `find()`. |
+
+`fullPage` and `selector` together are rejected — by the TypeScript types and,
+for JavaScript callers, at runtime with `INVALID_ARGUMENT`. Always baseline and
+assert with the same scope; a full-page baseline compared against a viewport
+capture is just a dimension mismatch.
+
+## Thresholds
+
+By default the comparison is exact: any differing pixel fails. Loosen it with
+three independent policies.
+
+```typescript
+await browser.expectScreenshot('baselines/home.png', {
+  pixelTolerance: 5,       // per-channel RGB slack, 0..255 (default 0)
+  maxDiffPixels: 100,      // allow up to 100 differing pixels
+  maxDiffPercentage: 0.1,  // …and no more than 0.1% of all pixels
+});
+```
+
+- **`pixelTolerance`** — a pixel counts as equal when the absolute difference of
+  every visible R, G and B channel is `<= pixelTolerance`. Use it to absorb tiny
+  codec/renderer noise.
+- **`maxDiffPixels`** / **`maxDiffPercentage`** — budgets for how many pixels may
+  still differ after `pixelTolerance` is applied. Each boundary is **inclusive**.
+- If you set **neither** budget, the image must have zero differing pixels.
+- If you set **both**, **both** must pass.
+- Dimensions are never resized to match. Different dimensions always fail,
+  regardless of tolerance — resizing would hide the layout regressions you are
+  trying to catch.
+
+All values are validated, never clamped: a non-integer `pixelTolerance`, a
+percentage above 100, an `interval` below 10 ms, and similar out-of-range inputs
+throw `INVALID_ARGUMENT`.
+
+### Ignoring anti-aliasing
+
+Anti-aliasing along text and edges is the most common source of
+platform-to-platform noise. `ignoreAntialiasing` classifies edge-smoothing
+pixels and excludes them from the difference count (reporting them separately as
+`ignoredAntialiasPixels`):
+
+```typescript
+await browser.expectScreenshot('baselines/home.png', {
+  ignoreAntialiasing: true,
+});
+```
+
+It is **off by default on purpose**. Silently ignoring pixels is a policy
+decision that can hide thin, genuine regressions, so you opt in explicitly. It
+ignores edge smoothing but still counts moved edges, missing glyphs, and
+one-pixel layout shifts.
+
+## Handling a mismatch
+
+`VisualMismatchError` carries the two things you actually want when a visual
+test fails: the final screenshot and a diff image. Persist them as CI artifacts:
+
+```typescript
+import { writeFile } from 'node:fs/promises';
+import { VisualMismatchError } from 'craftdriver';
+
+try {
+  await browser.expectScreenshot('baselines/home.png', { timeout: 3_000 });
+} catch (error) {
+  if (error instanceof VisualMismatchError) {
+    await writeFile('artifacts/home.actual.png', error.actual);
+    await writeFile('artifacts/home.diff.png', error.diff);
+  }
+  throw error;
+}
+```
+
+In the diff image, unchanged areas appear as a dimmed grayscale copy of the
+actual screenshot, counted differences are red, ignored anti-aliased pixels are
+yellow, and regions present in only one image (a dimension mismatch) are
+magenta. `error.detail` holds the JSON-safe summary (path, dimensions, counts,
+percentage, attempts, elapsed time) for logs and agents; the two `Buffer`s live
+on `error.actual` / `error.diff`.
+
+Baseline read/decode failures are treated as configuration errors, not visual
+mismatches — they are not retried, and their cause is preserved.
+
+## Updating baselines
+
+When a change is intentional, re-run with the update flag set and craftdriver
+overwrites the differing baselines with the new screenshots instead of failing:
+
+```bash
+CRAFTDRIVER_UPDATE_VISUAL_BASELINES=true npm test
+```
+
+There is no separate "save" API and no CLI flag — craftdriver has no test runner
+of its own, so the switch is one environment variable you set for a single run.
+While it is set:
+
+- A **missing** baseline is still created and passes (that never needed the flag).
+- A **matching** baseline passes untouched.
+- A **differing** baseline is captured until the deadline, then overwritten with
+  the final screenshot; the assertion passes with `result.baseline === 'updated'`.
+  A page that settles back into a match passes *without* rewriting, so you don't
+  get spurious baseline churn.
+
+Every rewrite is printed — `[craftdriver] Updated visual baseline: <path> (<n>
+px, <p>% changed)`. Review the resulting diff in version control before you
+commit it; that review is the safety net this flag deliberately leaves to you.
+
+Rewrites are atomic: the new baseline is written to a temporary file and renamed
+into place, so an interrupted run or disk error can never leave a truncated or
+half-updated committed baseline — the existing one survives intact.
+
+Parsing is strict, because the flag mutates files on disk: `true` turns it on,
+`false` or unset leaves it off, and any other value (`1`, `yes`, …) throws
+`INVALID_ARGUMENT` rather than being quietly ignored. A baseline that exists but
+can't be decoded stays a hard error even here — it is never overwritten. To
+replace a corrupt baseline, delete it and let the next run recreate it.
+
+## Retries and timing
+
+Each assertion reads the baseline once, then screenshots and compares on a loop
+until it matches or `timeout` (default: the browser's default timeout, 5000 ms)
+expires, waiting `interval` ms (default 50) between attempts. The first
+screenshot is always taken immediately, even with `timeout: 0`. This absorbs a
+page that is still settling — a chart finishing its layout, a font swapping in.
+
+```typescript
+await browser.expectScreenshot('baselines/chart.png', {
+  screenshot: { selector: '#chart' },
+  timeout: 3_000,
+  interval: 100,
+});
+```
+
+The happy path is cheap: an identical screenshot matches on a byte comparison
+without ever decoding a PNG. But **byte equality is only a fast _positive_
+path** — two genuinely-equivalent renders can still produce different bytes, so
+a mismatch always falls back to a real pixel comparison.
+
+## Making CI deterministic
+
+Most visual-test pain is non-determinism, not craftdriver. The same page renders
+differently across machines — **macOS and Linux genuinely rasterize different
+pixels**, so a baseline captured on your Mac will not match a Linux CI runner.
+Pin the environment:
+
+- Capture baselines in the **same OS image** you run CI on (or keep per-platform
+  baselines). This is the big one.
+- Fix the **browser and version**, the **viewport size**, and the **device pixel
+  ratio** (a HiDPI runner captures twice the pixels of a 1× one).
+- Freeze **fonts** (ship them with the app/test image so font substitution can't
+  shift text), **locale**, and **timezone**.
+- Disable **animations** and honor **reduced motion**; freeze time with the
+  [virtual clock](./clock.md) when content is time-dependent.
+- Prefer a headless, consistent rendering path over whatever is on a developer
+  laptop.
+
+Start strict (`pixelTolerance: 0`) and only add tolerance once you understand
+which pixels move and why. A large blanket tolerance turns a visual test into a
+test that passes no matter what.
+
+## Comparing buffers directly
+
+If you already have two PNG buffers and just want the comparison — no disk, no
+browser, no retries — use `compareScreenshots(actual, expected, options)`. It
+applies the same threshold semantics and input limits and returns the result
+instead of throwing on a normal mismatch:
+
+```typescript
+import { compareScreenshots } from 'craftdriver';
+
+const result = await compareScreenshots(actualPng, expectedPng, {
+  pixelTolerance: 3,
+  maxDiffPixels: 50,
+});
+console.log(result.matches, result.diffPixels, result.diffPercentage);
+```
+
+The argument order is always `(actual, expected)` — everywhere in the API.
+
+## Input limits and scope
+
+Before decoding, both images are checked against `maxImagePixels` (default 20
+million pixels) and `maxInputBytes` (default 50 MiB), with the size validated
+from the PNG header before any large allocation. Decoded RGBA is ~4 bytes per
+pixel, and an assertion may hold the expected image, the latest actual image, and
+a diff at once, so raise `maxImagePixels` deliberately for unusually long
+full-page screenshots — and consider lowering it when many test workers run in
+parallel.
+
+This feature is built for a developer-controlled baseline and a screenshot
+produced by the browser under test. The low-level comparator is **not** a
+hardened service for arbitrary user-uploaded images; if that ever becomes a
+requirement, decoding needs to move to a terminable worker with a hard CPU
+deadline (an in-process timeout cannot interrupt a synchronous parser).
+
+## Under the hood
+
+PNG decoding and encoding go through a single pinned dependency, `pngjs`, behind
+an internal codec seam. It is a pure-JavaScript package with no native addon,
+WASM, install script, or transitive runtime dependencies — chosen so the
+security and packaging story stays simple. The optional anti-alias detector is
+adapted from [Pixelmatch](https://github.com/mapbox/pixelmatch) (ISC licensed;
+attribution is preserved in the source).

package/docs/why-craftdriver.md

@@ -11,11 +11,12 @@ CraftDriver is for writing boringly reliable automation against real browsers, w
 - 📡 **Network control** - mock, block, intercept, and wait for browser requests and responses.
 - 🔐 **Reusable sessions** - save cookies and localStorage, then launch already signed in.
 - ⏱️ **Virtual clock** - freeze or fast-forward `Date`, timers, and time-sensitive UI.
-- ♿ **Accessibility audits** - run axe-core checks on pages, elements, and locators.
+- ♿ **Accessibility audits** - find WCAG 2.2 and Section 508 violations with built-in axe-core checks.
+- 🖼️ **Visual testing** - catch visual regressions against baselines, without fighting anti-aliasing flakiness.
 - 🧾 **Trace evidence** - capture actions, console output, errors, network events, and screenshots.
-- ⚛️ **Electron apps** - drive packaged Electron desktop app renderers, matched to the app's bundled Chromium.
 - ☁️ **Remote WebDriver** - use the Browser API with a self-hosted Selenium Grid or a cloud provider like [BrowserStack](https://www.browserstack.com/).
-- 🤖 **Agent-friendly** - CLI, MCP, and assistant rules when coding agents need the browser.
+- ⚛️ **Electron apps** - drive packaged Electron desktop apps and mock native OS dialogs (open/save, message boxes).
+- 🤖 **Agent-friendly** - CLI, a project-local skill, and optional MCP when coding agents need the browser.
 
 ## Good Fits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craftdriver",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Modern WebDriver automation library for NodeJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,6 +18,8 @@
     "test:chrome": "BROWSER_NAME=chrome vitest run",
     "test:chromium": "BROWSER_NAME=chromium vitest run",
     "test:safari": "BROWSER_NAME=safari vitest run tests/safari.test.ts --maxWorkers=1",
+    "test:cli": "HEADLESS=true vitest run --config vitest.cli.config.ts",
+    "test:release": "vitest run --config vitest.release.config.ts",
     "test:recipes": "HEADLESS=true vitest run --config vitest.recipes.config.ts",
     "test:electron": "vitest run --config vitest.electron.config.ts",
     "test:browserstack": "vitest run --config vitest.browserstack.config.ts",
@@ -88,6 +90,7 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/node": "^20.0.0",
+    "@types/pngjs": "6.0.5",
     "@types/ws": "^8.18.1",
     "@types/yazl": "^3.3.1",
     "@typescript-eslint/parser": "^8.1.0",
@@ -102,6 +105,7 @@
   },
   "dependencies": {
     "axe-core": "^4.12.1",
+    "pngjs": "7.0.0",
     "ws": "^8.21.0",
     "yazl": "^3.3.1"
   },

package/skills/craftdriver/SKILL.md

@@ -1,89 +1,73 @@
-# craftdriver — SKILL
+---
+name: craftdriver
+description: Explore live web applications with the CraftDriver CLI, validate durable selectors, and write, run, and debug CraftDriver tests. Use when a coding agent needs to inspect a page, drive browser flows, choose locators, author browser automation, or diagnose a failing CraftDriver test.
+---
 
-Modern WebDriver library for Node.js — picks the fastest correct protocol
-(Classic or BiDi) per command. Playwright ergonomics, WebDriver
-standards-compliance, no AI in the hot path.
+# CraftDriver browser workflow
+
+Use CraftDriver's CLI to inspect and exercise the running application, then use
+the public TypeScript API to write and run durable tests. Chrome is the default
+agent workflow.
 
 ## Core loop
 
-```
-navigate → find → action → assert
+```text
+start app → navigate → snapshot → inspect → act → validate selector
+          → write test → run focused test → debug from fresh evidence
 ```
 
-Every action and every `expect(locator).to…()` **auto-waits** up to the
-default timeout (30 s in-library, 5 s on agent surfaces). Never add
-`sleep()` / `setTimeout()` — it's a footgun.
+Actions and `expect(locator).to…()` auto-wait. Do not add sleeps or hand-written
+polling loops.
 
-## Selector preference order
+## Selector order
 
-```
-By.testId  >  By.role({name})  >  By.labelText  >
-By.text({exact:true})  >  By.css  >  By.xpath
+Prefer evidence from the live page in this order:
+
+```text
+By.role({ name }) / By.labelText / By.testId
+→ exact visible text → stable CSS → XPath only as a last resort
 ```
 
-`testId` and `role` are stable across DOM refactors; CSS and XPath
-break the moment markup shifts.
-
-## Five rules
-
-1. Use `expect(locator).to…()` for assertions. Never hand-roll
-   `while (...) { ... sleep(100) }` retry loops — they auto-wait.
-2. Read errors by `code`, not by prose. Every public throw is a
-   `CraftdriverError` with a stable `code`. See
-   [docs/error-codes.md](../../docs/error-codes.md).
-3. `instanceof CraftdriverError` is true on every public throw;
-   `instanceof Error` is also true.
-4. BiDi features (`network`, `logs`, tracing, init scripts, true load
-   events) work out of the box — `enableBiDi` defaults to `true`. They only
-   break if you explicitly pass `enableBiDi: false`; the error code on the
-   wrong transport is `UNSUPPORTED`. Exception: `browserName: 'safari'`
-   defaults `enableBiDi` to `false` and rejects `true` — Safari is
-   Classic-only (macOS, headed, one session at a time). See
-   [docs/safari.md](../../docs/safari.md).
-5. Tests fetch from the example server. Start it in a separate
-   terminal: `npm run examples:start` before `npm test`.
-
-## When you reach for more
-
-- **Writing tests, looking for a method** → read
-  [skills/craftdriver/cheatsheet.md](cheatsheet.md). Also see
-  [docs/api-reference.md](../../docs/api-reference.md) — every public
-  export, one row each.
-- **Login, upload, wait-for-network, etc.** → read
-  [skills/craftdriver/patterns.md](patterns.md).
-- **Driving the browser from a shell or agent loop** → read
-  [skills/craftdriver/cli.md](cli.md). Same Browser API, exposed as a
-  `craftdriver` binary with daemon + ephemeral modes.
-- **Driving from an MCP-aware AI host** (Claude Desktop / Code, Cursor,
-  Windsurf, Zed, Goose, Gemini CLI) → `craftdriver mcp` is a stdio
-  JSON-RPC server with 14 schema-typed tools. Mutating tools return a
-  compact a11y snapshot **diffed from the previous turn** — you see
-  what changed without a follow-up read. See
-  [docs/mcp.md](../../docs/mcp.md).
-- **An error code you don't recognise** → read
-  [docs/error-codes.md](../../docs/error-codes.md).
-
-## Probing rule
-
-When unsure a selector exists, check before acting. Today: call
-`await locator.count()` (zero-wait, returns the current match count).
-Acting on a hallucinated selector wastes the whole auto-wait budget.
-
-For the **CLI and MCP**, the cheapest way to drive a page is to take a
-snapshot first and use refs:
+Confirm a selector against the live page with `craftdriver exists` or
+`craftdriver find` before putting it in a test.
 
-```
-$ craftdriver snapshot
-e4: textbox "Username" #username
-e7: button "Sign in" #submit
-$ craftdriver fill ref=e4 alice
-$ craftdriver click ref=e7
-```
+## Snapshot refs are exploration-only
 
-`ref=eN` resolves to a CSS attribute selector, auto-waits like any
-other selector, and re-allocates on every snapshot. No hallucination.
+CLI snapshots show `ref=eN`. A ref binds to one element for as long as that
+element lives, and is never reassigned to another one: if the element is removed
+or duplicated, or the page navigates or reloads, the command fails with
+`STALE_REF`. Take a fresh snapshot when that happens — CraftDriver will not
+guess a replacement.
 
-## Imports
+A ref still means nothing outside the current session, so never copy one into
+test source. Convert the element into a durable locator and let CraftDriver
+check it against the live page:
+
+```bash
+npx craftdriver locators ref=e7
+```
 
-Always `import { ... } from 'craftdriver'`. Never reach into
-`craftdriver/src/lib/...` — internals are unstable.
+Use a candidate reported `unique` (ordered by durability: role + accessible
+name, label, test ID, unique text, minimal CSS). If none is unique, add a
+`data-testid` to the application instead of committing a positional selector.
+
+## Test rules
+
+1. Inspect the repository's existing tests and package scripts before choosing
+   a test location or command.
+2. Import only from `craftdriver`, never from `craftdriver/src/...`.
+3. Use public locators and `expect(locator)` assertions.
+4. Read failures by stable `CraftdriverError.code`, then gather a fresh
+   snapshot and focused page evidence.
+5. Make ordinary reviewable source changes. Never hide a failure with runtime
+   locator repair.
+6. Always close the browser in `finally` or the repository's existing fixture.
+
+## Focused references
+
+- Explore and write a test: [workflow.md](workflow.md)
+- Shell commands: [cli.md](cli.md)
+- TypeScript API cheatsheet: [cheatsheet.md](cheatsheet.md)
+- Worked library recipes: [patterns.md](patterns.md)
+- Full installed package docs: `node_modules/craftdriver/docs/`
+- Optional MCP adapter: `node_modules/craftdriver/docs/mcp.md`

package/skills/craftdriver/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CraftDriver Browser Testing"
+  short_description: "Explore apps and author CraftDriver tests"
+  default_prompt: "Use $craftdriver to explore this app and write a durable browser test."

package/skills/craftdriver/cheatsheet.md

@@ -1,8 +1,7 @@
 # craftdriver — cheatsheet
 
-Compact reference for writing tests. Pair with
-[docs/api-reference.md](../../docs/api-reference.md) for the full export
-list.
+Compact reference for writing tests. The full installed API reference is
+`node_modules/craftdriver/docs/api-reference.md`.
 
 ## Launch & teardown
 
@@ -111,7 +110,7 @@ Codes: `NO_MATCH`, `TIMEOUT_WAITING_VISIBLE`, `TIMEOUT_WAITING_STATE`,
 `TIMEOUT_WAITING_DIALOG`, `TIMEOUT`, `EXPECT_MISMATCH`,
 `A11Y_VIOLATIONS`, `EVAL_THREW`, `EVAL_BAD_ARG`, `INVALID_ARGUMENT`,
 `UNSUPPORTED`, `STATE_INVALID`, `DRIVER_ERROR`. Full table:
-[docs/error-codes.md](../../docs/error-codes.md).
+`node_modules/craftdriver/docs/error-codes.md`.
 
 ## Pages and contexts
 
@@ -124,6 +123,21 @@ const pages = browser.pages();
 const fresh = await browser.waitForPage(() => browser.click('a[target=_blank]'));
 ```
 
+## Reusable login state
+
+```ts
+// Save after login (atomic file, mode 0600 where supported).
+await browser.saveState('.auth/alice.json');
+
+// BiDi: cookies + multi-origin localStorage are ready before navigation.
+const reused = await Browser.launch({ storageState: '.auth/alice.json' });
+await reused.navigateTo('https://app.example.com/dashboard');
+```
+
+Classic launch rejects non-empty state. Use `Browser.launch()`, navigate to the
+sole captured HTTP(S) origin, then `browser.loadState(...)`. State containing
+sessionStorage always uses that active-origin flow.
+
 ## Network (BiDi)
 
 ```ts