craftdriver 1.7.0 → 1.8.0

package/docs/browser-context.md

@@ -120,9 +120,8 @@ Create a new isolated user context. Backed by BiDi
 `browser.createUserContext`. Throws in Classic mode.
 
 - `opts.storageState`: a `SessionState` object **or** a path to a JSON
-  file produced by `BrowserContext.saveStorageState()`. Cookies are
-  applied immediately; localStorage entries land on first navigation to
-  each captured origin via an internal preload script.
+  file produced by `BrowserContext.saveStorageState()`. Cookies and every
+  captured localStorage origin are restored before `newContext()` resolves.
 - `opts.baseURL`: a base URL applied to every relative `url` passed to
   `ctx.newPage()` or `page.navigateTo()` inside the context. Absolute
   URLs pass through unchanged. Lets your tests say `'/login'` instead
@@ -230,11 +229,17 @@ snapshot for inspection. See the auth-fixture example above.
 ### `BrowserContext.loadStorageState(source): Promise<void>`
 
 Apply a previously-captured snapshot. `source` is a `SessionState`
-object or a path to JSON produced by `saveStorageState`. Cookies are
-applied immediately; localStorage entries are installed via a preload
-script that runs on first navigation to each captured origin. Calling
-`loadStorageState` again replaces the previous preload — it does not
-stack.
+object or a path to JSON produced by `saveStorageState`. localStorage is
+seeded once per captured origin through a private, locally fulfilled document;
+cookies are then applied to the same user-context partition. The method resolves
+after hydration and cleanup, so the first real page script sees the state.
+Calling `loadStorageState` again applies another ordered overlay; application
+changes remain owned by the application and survive reload.
+
+Restores in one context are serialized. Different user contexts may restore in
+parallel. A runtime protocol failure on an existing context throws
+`DRIVER_ERROR` with `detail.phase` and `detail.partialApplied`; use a newly
+created context when failure isolation is required.
 
 ### `BrowserContext.close(): Promise<void>`
 
@@ -479,10 +484,11 @@ A default `browser.newContext()` (no options) is always cross-browser.
 
 A few things that aren't bugs but bite if you don't know them:
 
-- **`storageState` covers cookies + localStorage only.** Not
-  sessionStorage, not IndexedDB, not Cache Storage. Apps that put their
-  auth token in sessionStorage (some Auth0 / MSAL fallback configs) will
-  need a custom restore step.
+- **`storageState` covers cookies + localStorage only.** Not reusable
+  sessionStorage, IndexedDB, or Cache Storage. A non-empty sessionStorage
+  section is rejected by context/launch APIs rather than ignored. Use the
+  active-page `browser.loadState()` fallback for one matching sessionStorage
+  origin, or a custom login step.
 - **Browser-level vs context-level emulation race.** `browser.setGeolocation(...)`
   is a session-wide override; `ctx.setGeolocation(...)` is a per-context
   override. If both are set, the context-level one wins inside the

package/docs/cli.md

@@ -55,10 +55,24 @@ text "#result"
 craftdriver go <url>
 craftdriver find <selector> [--all] [--limit N] [--offset M]
 craftdriver click <selector>
-craftdriver fill <selector> <value>
+craftdriver dblclick <selector>
+craftdriver fill <selector> <value>    # clear, then enter the value
+craftdriver type <text>                # type into the focused element
+craftdriver clear <selector>
+craftdriver check <selector> | craftdriver uncheck <selector>
+craftdriver select <selector> <value>  # <option> by its value attribute
+craftdriver focus <selector>           # caret to end, ready to type
+craftdriver scroll <selector>
 craftdriver press <key> [selector]
 craftdriver hover <selector>
 
+craftdriver key press|down|up <key> [--selector S]
+craftdriver mouse move|click [selector] [--x N --y N] [--button b]
+craftdriver mouse down|up [--button left|middle|right]
+craftdriver mouse wheel [selector] [--delta-x N] [--delta-y N]
+craftdriver dialog inspect | craftdriver dialog accept [text] | craftdriver dialog dismiss
+craftdriver upload <selector> <file> [file...]
+
 craftdriver text [selector] [--limit N]
 craftdriver attr <selector> <name>
 craftdriver value <selector>
@@ -69,11 +83,32 @@ craftdriver wait load [--state load|domcontentloaded|networkidle]
 craftdriver exists <selector>          # 0-wait probe; exit 0 if any match
 
 craftdriver pages
+craftdriver page list                  # open tabs, marking the active one
+craftdriver page open [url]            # open a tab and select it
+craftdriver page select <index|id>     # send later commands to that tab
+craftdriver page close <index|id>
 craftdriver snapshot                   # sanitized DOM summary with refs
+craftdriver locators <selector>        # durable selectors, live-validated
 craftdriver screenshot [-o file.png] [--full-page] [--selector S]
+                                       # without -o, lands in
+                                       # .craftdriver/screenshots as
+                                       # screenshot-<session>.png (overwritten)
 craftdriver eval <js>                  # last resort
 craftdriver back | forward | reload | status | quit
 
+craftdriver logs [list]                # console + network history
+craftdriver logs wait --contains <text>
+craftdriver logs clear
+craftdriver mock add <pattern> [--status N] [--body S]
+craftdriver mock block <pattern>
+craftdriver mock list | remove <id> | clear
+craftdriver trace start [name] [--no-screenshots]
+craftdriver trace stop [--zip]         # then open the NDJSON or zip
+craftdriver trace status
+craftdriver state save <name> [--session-storage]
+craftdriver state load <name>          # load before navigation on BiDi
+craftdriver state list
+
 craftdriver daemon start|status|stop
 ```
 
@@ -124,12 +159,74 @@ $ craftdriver fill ref=e6 hunter2
 $ craftdriver click ref=e7
 ```
 
-Refs are recomputed on every `snapshot` call and invalidated on
-navigation. A stale ref just returns `NO_MATCH` — take a fresh
-snapshot.
+### Refs bind to an element, not to a position
+
+A ref names one specific element for as long as that element lives:
+
+- a node that survives a DOM change keeps its ref across snapshots;
+- a new node always gets a fresh number — refs are never reused, not even
+  after a navigation;
+- if the element is removed, duplicated, or the page navigates or
+  reloads, the ref fails with `STALE_REF` instead of resolving to
+  whatever now sits in that position.
+
+That last point is the reason to trust them. Take a fresh `snapshot`
+when you see `STALE_REF`; craftdriver will not guess a replacement.
+`error.detail.reason` says which case fired (`detached`,
+`document-changed`, `unknown-ref`, `ambiguous`, `no-snapshot`).
 
 Internally `ref=eN` resolves to a CSS attribute selector
-(`[data-craftdriver-ref="eN"]`); auto-waiting works unchanged.
+(`[data-craftdriver-ref="eN"]`) after craftdriver has checked the ref
+still identifies exactly one element; auto-waiting works unchanged.
+
+## Tabs
+
+Commands act on one tab — the active one. A tab that opens on its own
+(`window.open`, `target=_blank`) is listed but is *not* selected, so nothing
+switches under you:
+
+```bash
+$ craftdriver page list
+[0] http://127.0.0.1:8080/checkout.html  —  Checkout   (active)
+[1] http://127.0.0.1:8080/help.html      —  Help
+
+$ craftdriver page select 1
+$ craftdriver text h1        # reads the help tab
+```
+
+Select by index or by the id from `page list`. An unknown id or an
+out-of-range index is an error rather than a fallback to the active tab —
+acting on the wrong tab is the confusion this exists to remove.
+
+Selecting, opening, or closing a tab clears the ref registry, so a ref from
+the previous tab fails `STALE_REF` instead of resolving against the new
+document. Take a fresh `snapshot` after switching.
+
+## Locators — durable selectors for a test
+
+Refs are for exploring a live page. Never put one in a committed test:
+it means nothing in a later session. `craftdriver locators` turns an
+element into selectors that do survive, and re-resolves each one against
+the current page before offering it:
+
+```bash
+$ craftdriver locators ref=e7
+best: role=button[name=Sign in]
+✓ role=button[name=Sign in]
+    By.role('button', { name: "Sign in" })
+✓ testid=login-btn
+    By.testId("login-btn")
+~ text=Sign in  (3 matches)
+    By.text("Sign in")
+```
+
+`✓` unique, `~` ambiguous, `✗` no longer matches. Candidates are ordered
+by durability: role + accessible name, associated label, test id, unique
+text, then minimal CSS. Obviously generated ids (`#a1b2c3d4e5f6`) are
+never offered as CSS candidates — they look stable and are not.
+
+If nothing resolves uniquely, that is reported rather than papered over;
+the fix is a `data-testid` in the application, not a cleverer selector.
 
 ## Output: pretty on a TTY, JSON when piped
 
@@ -165,10 +262,236 @@ learn from failures fast.
 - Use `exists` as a 0-wait probe before `click` / `wait` when you're not
   sure a selector matches.
 
+## Named sessions
+
+One daemon, several independent browsers. Pass `--session <name>` and the
+command runs against that session's own browser, page selection, cookies,
+snapshot baseline and refs:
+
+```bash
+npx craftdriver go http://127.0.0.1:8080/login.html --session shopper
+npx craftdriver go http://127.0.0.1:8080/login.html --session admin
+
+# separate browsers, so separate logins
+npx craftdriver fill '#username' alice --session shopper
+npx craftdriver fill '#username' root  --session admin
+
+npx craftdriver session list
+npx craftdriver session close admin
+```
+
+Commands with no `--session` use the session named `default`, which is why
+everything above still works if you never pass the flag.
+
+Worth knowing:
+
+- **Sessions are created on first use.** Naming one costs nothing until a
+  command actually needs a browser.
+- **They run independently.** Each session has its own FIFO queue, so a
+  slow command in one does not hold up another.
+- **Up to 8 at a time**, because each is a real browser process. Past that,
+  creating a new one fails and tells you which are open rather than
+  quietly quitting someone else's browser. `session close <name>` frees a
+  slot; `craftdriver quit --session <name>` just closes that session's
+  browser and keeps the slot.
+- **A ref belongs to the session that issued it.** `e4` in one session and
+  `e4` in another are different elements, and craftdriver cannot tell you
+  that you mixed them up — it sees a valid ref either way. Keep `snapshot`
+  and the commands that spend its refs on the same `--session`.
+- **Names** are 1–32 characters of letters, digits, `-` and `_`, starting
+  with a letter or digit. Anything else is rejected before a socket is
+  opened.
+- **Not available with `--ephemeral`**, which is one browser that exits
+  with the command; a name there would promise a continuity that does not
+  exist, so the combination is an error rather than a no-op.
+
+## Console and network history
+
+What the page logged and requested, asked for *after* the fact:
+
+```bash
+npx craftdriver go http://127.0.0.1:8080/checkout.html
+npx craftdriver click '#pay'
+
+npx craftdriver logs --kind error           # exceptions + console.error
+npx craftdriver logs --kind request,response --contains /api/
+npx craftdriver logs wait --contains 'payment ok' --timeout 10000
+```
+
+Capture starts when the browser starts, not when you ask — so an error thrown
+during the first navigation is still there when you go looking. You do not
+arrange capture in advance, and you do not re-run the flow with a listener
+attached.
+
+Worth knowing:
+
+- **`--kind error` means both** an uncaught exception and a `console.error`.
+  They are recorded as different entries, but a caller asking for errors wants
+  each of them, and an empty answer on a page that loudly logged one would be
+  the most misleading result on offer.
+- **Ask "what changed since", not "what happened".** Every entry has a
+  monotonic `seq`, and each result carries a `cursor`. Pass it back as
+  `--since` and you get only what is new:
+
+  ```bash
+  CURSOR=$(npx craftdriver logs --json | jq .result.cursor)
+  npx craftdriver click '#submit'
+  npx craftdriver logs --since "$CURSOR"
+  ```
+
+- **`logs wait` checks what already arrived before it waits.** By the time an
+  agent asks, the event has usually already happened; a wait that only
+  subscribed would time out on the common case. It waits only if the entry is
+  not already there.
+- **History is bounded and eviction is counted.** 500 entries or 512 KB,
+  oldest first. The result reports `dropped`, and `droppedBeforeCursor` is
+  non-zero when the page you asked for has a hole — so "no errors" and "the
+  errors scrolled off" never look alike.
+- **Network rows are summaries, not captures.** URL, method, status, MIME type
+  and time. No bodies, no cookies, no headers of any kind — a journal an agent
+  pastes into a transcript cannot carry an `Authorization` header. URLs are
+  kept whole, including query strings, so a query token can still enter a
+  CLI/MCP transcript when logs are requested. The journal is memory-only; use
+  `logs clear` after inspecting sensitive development traffic.
+- **Responses are attributed browser-wide.** The response event carries no
+  browsing context, so only requests report a page. That is the protocol's
+  limit, reported honestly rather than guessed.
+- **Requires BiDi**, which Chrome and Firefox negotiate by default. Where it is
+  unavailable the result says `capturing: false` rather than returning an empty
+  list that reads like a quiet page.
+
+## Traces and network mocking
+
+A trace records actions, console output, network events and screenshots to a
+file you can read afterwards — useful when a failure is not reproducible by
+staring at the page:
+
+```bash
+npx craftdriver trace start checkout
+npx craftdriver go http://127.0.0.1:8080/checkout.html
+npx craftdriver click '#pay'
+npx craftdriver trace stop --zip
+```
+
+Output lands under `.craftdriver/traces/<name>/` (override with
+`CRAFTDRIVER_TRACE_DIR`): `trace.ndjson` plus a `screenshots/` directory.
+`--zip` also writes a Vibium/Playwright-compatible archive. `--no-screenshots`
+turns off the bulk of the size when you only want the event log.
+
+Only one trace records at a time; starting a second is an error rather than a
+silent replacement. Quitting the browser aborts a running trace, so an
+abandoned session leaves nothing dangling.
+
+Mocking covers the two rule shapes that are expressible as data:
+
+```bash
+npx craftdriver mock add '**/api/orders*' --status 500 --body '{"error":"nope"}'
+npx craftdriver mock block '**/analytics/**'
+npx craftdriver mock list
+npx craftdriver mock clear
+```
+
+Worth knowing:
+
+- **`mock add` replies; `mock block` fails the request.** Both take a URL
+  pattern, and both return an id you can `mock remove`.
+- **Everything is validated before installation.** A bad status or an
+  oversized body is refused up front — a mock installed wrong surfaces much
+  later as an unexplained page error, which is far harder to diagnose.
+- **Up to 20 active at once**, each bounded to a 64 KB body. craftdriver is
+  not a fixture server; mock the one call you are testing.
+- **No handler functions.** The library's `network.intercept()` takes a
+  callback, which a command line cannot express. Rather than invent a rule
+  language, the CLI offers only the flat cases — reach for the library API when
+  you need dynamic behaviour.
+- **Requires BiDi**, and says so with `UNSUPPORTED` rather than silently doing
+  nothing.
+
+## Saved login state
+
+Log in once, then reuse it instead of replaying the form on every run:
+
+```bash
+# log in by hand, once
+npx craftdriver go http://127.0.0.1:8080/login.html
+npx craftdriver fill '#username' alice
+npx craftdriver fill '#password' secret
+npx craftdriver click '#submit'
+npx craftdriver state save alice
+
+# later, in a fresh BiDi browser — load before the first real navigation
+npx craftdriver state load alice
+npx craftdriver go http://127.0.0.1:8080/login.html
+```
+
+On Chrome/Chromium and Firefox BiDi, `state load` restores cookies and all
+captured localStorage origins through the same library hydrator as
+`Browser.launch({ storageState })`; no navigate-before-load workaround is
+needed. If a page is already open and must react to the overlay, reload it.
+
+WebDriver Classic (including Safari) has a smaller contract: `go <url>` →
+`state load <name>` → `reload`. The active page must match the snapshot's sole
+storage origin and every cookie must be settable there. Broader state fails
+before mutation instead of being partially ignored. A snapshot saved with
+`--session-storage` also uses this active-page path because sessionStorage is
+tab-scoped, even when BiDi is available.
+
+Worth knowing:
+
+- **State files are credentials.** They hold live session cookies. They are
+  written to `.craftdriver/state/` (override with `CRAFTDRIVER_STATE_DIR`,
+  which the daemon reads from its own working directory — every `state`
+  result reports the `root` it used, so check there if a file is not where
+  you expected),
+  created owner-only (`0600`) inside an owner-only directory, and written via
+  a temp file and a rename so a crash cannot leave a half-written one. Add
+  `.craftdriver/` to `.gitignore`.
+- **A save captures every cookie in that browser, not just the current
+  site's.** Cookies are stored per browser profile, so `state save` on one
+  site also writes any other site you happen to be logged into in that
+  session. Local storage is the narrow half — only the current origin's. Use a
+  separate `--session` for a login you do not want mixed in.
+- **Nothing is ever printed back.** `state save` reports counts and origins —
+  never a cookie value, token, storage value or file path contents.
+- **Pass a name, not a path.** `state save alice` writes `alice.json` under the
+  state root. Names are letters, digits, `-` and `_`; a path, a `..`, or a
+  leading `-` is rejected, and a symlink inside the state directory cannot
+  redirect a write outside it.
+- **Sessions each have their own cookies**, so `state save --session shopper`
+  captures that browser's login and no other's.
+- **`state load` clears refs.** The document you snapshotted was a different
+  logged-out page; take a fresh `snapshot` afterwards.
+- `--session-storage` adds `sessionStorage` to a save. It is off by default,
+  since most apps keep nothing durable there.
+
+The library equivalent is `browser.saveState(path)` and
+`Browser.launch({ storageState: path })`. On supported BiDi sessions that launch
+form restores cookies plus multi-origin localStorage before the first real
+navigation. Non-empty state at Classic launch is rejected; use the explicit
+active-origin fallback above.
+
 ## Daemon details
 
-- Socket: `~/.craftdriver/sock` (override with `CRAFTDRIVER_SOCKET`).
-- PID file: `~/.craftdriver/pid` (override with `CRAFTDRIVER_PID`).
+- One daemon per project. The socket and PID file live in
+  `~/.craftdriver/projects/<project>-<hash>/`, where the hash is derived from
+  the project root — the nearest ancestor directory holding a `package.json`
+  or `.git`. Running from a subdirectory reaches the same daemon; running in a
+  different project reaches a different one, with its own browser, cookies and
+  refs. Override the paths with `CRAFTDRIVER_SOCKET` / `CRAFTDRIVER_PID`.
+- Saved state and traces are anchored to that same project root
+  (`<project>/.craftdriver/{state,traces}`), not to the working directory the
+  daemon was started from. Override with `CRAFTDRIVER_STATE_DIR` /
+  `CRAFTDRIVER_TRACE_DIR`.
+- A screenshot without `-o` overwrites
+  `<project>/.craftdriver/screenshots/screenshot-<session>.png`, so repeated
+  exploratory captures stay bounded. Pass `-o` when you intentionally want to
+  keep multiple images.
+- **Not available on Windows.** The daemon binds a Unix domain socket, which
+  Windows does not provide. `craftdriver daemon …` and any command that would
+  auto-start it exit with `UNSUPPORTED` there. The two socket-free modes work
+  on every platform: `craftdriver --ephemeral < script.txt` for a one-shot run,
+  and `craftdriver mcp` for an agent session over stdio. The library itself is
+  unaffected and runs on Windows normally.
 - Wire: line-delimited JSON, one request per connection.
 - First request after `daemon start` triggers the browser launch; later
   requests reuse the same browser, page and cookies.
@@ -193,27 +516,25 @@ npx craftdriver daemon start --browser firefox
 Both share the same underlying Browser API and the same error codes, so
 findings transfer directly between the two.
 
-## Teach your AI assistant (`craftdriver init`)
+## Install the project skill (`craftdriver init`)
 
-For every supported assistant, the CLI can drop an opinionated rules
-file into the **current project** so the assistant picks up
-craftdriver conventions (selector preference, auto-waiting, error
-codes, CLI usage) on every turn:
+Install the package-shipped CraftDriver skill in the nearest project root:
 
 ```bash
-npx craftdriver init copilot   # .github/copilot-instructions.md
-npx craftdriver init claude    # CLAUDE.md
-npx craftdriver init cursor    # .cursor/rules/craftdriver.mdc
-npx craftdriver init gemini    # GEMINI.md
-npx craftdriver init agents    # AGENTS.md (Codex, OpenCode, Aider, Amp, Cursor)
-npx craftdriver init all       # every file above
+npx craftdriver init codex
+npx craftdriver init codex --dry-run
 ```
 
-Files are per-project (commit them to git so the team's agents share
-the rules). Pre-existing files are skipped unless you pass `--force`;
-use `--dry-run` to see what would be written. The body is identical
-across flavors, only the file name and any tool-specific header
-(e.g. Cursor's `.mdc` frontmatter) differ.
+The destination is `.agents/skills/craftdriver/`. An ownership manifest makes
+repeat installation deterministic and prevents updates from overwriting user
+edits or unowned files. There is no destructive `--force` mode.
+
+The installer never reads or changes `AGENTS.md`, `CLAUDE.md`, Copilot
+instructions, Cursor rules, `GEMINI.md`, or `.codex/config.toml`. Legacy init
+flavors return a migration error and write nothing.
+
+To use optional MCP, run `npx craftdriver init codex --mcp`. It prints a
+project-pinned snippet for manual configuration; it does not configure MCP.
 
 ## Skill pack
 
@@ -228,6 +549,5 @@ ships a tiered skill pack under `skills/craftdriver/`:
 | [`patterns.md`](https://github.com/dtopuzov/craftdriver/blob/main/skills/craftdriver/patterns.md)     | Worked recipes (login, upload, network-wait, a11y, tracing, clock).   |
 | [`cli.md`](https://github.com/dtopuzov/craftdriver/blob/main/skills/craftdriver/cli.md)               | Agent-facing CLI reference.                                           |
 
-Point your agent at `node_modules/craftdriver/skills/craftdriver/SKILL.md`
-or copy it into your project. The other files are referenced from
-`SKILL.md` and loaded on demand.
+Use `npx craftdriver init codex` to install these files safely. The other files
+are referenced from `SKILL.md` and loaded on demand.

package/docs/error-codes.md

@@ -45,10 +45,11 @@ try {
 | `A11Y_VIOLATIONS` | `browser.a11y.check()` (or scoped variants) found axe-core violations. | Iterate over `error.violations` — each has an `id`, `impact`, and `helpUrl`. |
 | `EVAL_THREW` | The function passed to `evaluate()` threw inside the page. Also fires for `browser.clock` methods (`tick()`, `setSystemTime()`, `runFor()`) called before `install()` — they run as in-page scripts under the hood. | The page-side exception text is in `error.detail.exception`. |
 | `EVAL_BAD_ARG` | `evaluate()` / `addInitScript()` received a non-JSON-serializable argument (function, Symbol, DOM node…). | Pass plain JSON values. |
-| `INVALID_ARGUMENT` | Caller passed an invalid value (bad enum, wrong shape, unparseable duration…). | Read the message; it lists the accepted forms. |
-| `UNSUPPORTED` | Feature exists but is unavailable on this browser/transport (e.g. Chromium-only over Firefox, or a BiDi-only feature with BiDi disabled). | Enable BiDi (`enableBiDi: true`) or switch browser. |
-| `STATE_INVALID` | Method called in the wrong state (e.g. `stopTrace()` without `startTrace()`). | Call the prerequisite first. |
-| `DRIVER_ERROR` | A WebDriver command returned a protocol error (non-200 response) — e.g. `stale element reference`, `element click intercepted`, `invalid selector` — or a transport-level failure. | `error.detail.webDriverError` carries the W3C JSON error code and `error.detail.webDriverMessage` the driver's message; recovery loops match on `webDriverError`. Also inspect `error.cause`. |
+| `INVALID_ARGUMENT` | Caller passed an invalid value (bad enum, wrong shape, unparseable duration…). For storage-state restore this includes malformed JSON/native schema, invalid cookies/origins, or multi-origin sessionStorage. | Read the message; it lists the accepted forms. Re-save a corrupt or hand-edited state file. |
+| `UNSUPPORTED` | Feature exists but is unavailable on this browser/transport (e.g. Chromium-only over Firefox, or a BiDi-only feature with BiDi disabled). Storage-state launch/context APIs also reject non-empty sessionStorage rather than silently dropping it, and Classic launch rejects non-empty state. | Enable BiDi (`enableBiDi: true`) or switch browser. For sessionStorage or Classic, launch without state, navigate to its sole origin, then call `browser.loadState()`. |
+| `STATE_INVALID` | Method called in the wrong state (e.g. `stopTrace()` without `startTrace()`). A Classic/active-page state restore also uses this when there is no active HTTP(S) origin or its origin cannot accept every requested storage entry and cookie. | Call the prerequisite first. For active-page restore, navigate to the state’s sole origin before loading it. |
+| `STALE_REF` | An agent-surface snapshot ref (`ref=eN`) no longer identifies exactly one live element. | Take a fresh `snapshot` and use the new ref. `error.detail.reason` says which case fired: `detached` (element removed), `document-changed` (page navigated or reloaded), `unknown-ref` (never issued for this document), `ambiguous` (duplicated, e.g. by `cloneNode`), `no-snapshot` (none taken yet). craftdriver never guesses a replacement element — refs are for exploration; use a durable locator (`craftdriver locators`) in committed tests. |
+| `DRIVER_ERROR` | A WebDriver command returned a protocol error (non-200 response) — e.g. `stale element reference`, `element click intercepted`, `invalid selector` — or a transport-level failure. A live-context state overlay can also fail after some entries were applied. | `error.detail.webDriverError` carries the W3C JSON error code and `error.detail.webDriverMessage` the driver's message; recovery loops match on `webDriverError`. For storage restore inspect `phase` and `partialApplied`; use a fresh context when failure isolation matters. Also inspect `error.cause`. |
 | `ELECTRON_DRIVER_MISMATCH` | The resolved chromedriver can't drive the Electron app, caught **before** a session is created. | `error.detail.kind` is `'chromium-major'` (driver major ≠ the app's bundled Chromium; see `driverMajor` / `expectedChromiumMajor` / `electronVersion`) or `'arch'` (`driverArch` ≠ `runtimeArch`). The `hint` names the fix. |
 | `ELECTRON_LAUNCH_FAILED` | The Electron app process exited during session creation ("Chrome instance exited"). | `error.detail` carries the diagnosed cause (`macSigning: 'unsigned'`/`'adhoc'` on macOS, `sandboxDisabled: false` on Linux); `hint` is the top remediation; the message appends the chromedriver output tail; `error.cause` is the original driver error. |
 | `ELECTRON_MAIN_UNAVAILABLE` | `browser.electron.executeMain(...)` couldn't reach the app's main process. | Launch with `electron: { mainProcess: true }`; ensure the app build keeps the `EnableNodeCliInspectArguments` fuse enabled (default). `hint` names the fix. |

package/docs/getting-started.md

@@ -86,10 +86,15 @@ Pick a browser with `browserName`:
 ```typescript
 const browser = await Browser.launch({
   browserName: 'firefox', // 'chrome' | 'chromium' | 'firefox' | 'safari'
-  storageState: './session.json', // optional: pre-load saved session state
+  // BiDi: restore cookies + multi-origin localStorage before first navigation.
+  storageState: './session.json', // path or in-memory SessionState
 });
 ```
 
+WebDriver Classic cannot restore non-empty state at launch. For its strict
+single-origin fallback, navigate first and call `browser.loadState()`; see
+[Session Management](./session-management.md#webdriver-classic).
+
 To switch browsers from an environment variable in your own tests, read it
 yourself and pass it to `browserName` — craftdriver doesn't read any browser
 env var for you:

package/docs/index.md

@@ -30,7 +30,7 @@ features:
   - 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.
+    details: CLI, a safe project-local skill, and optional MCP are there when you want coding agents to drive the browser too.
 ---
 
 ## Quick Start