craftdriver 1.7.0 → 1.8.0

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

package/skills/craftdriver/cli.md

@@ -1,104 +1,230 @@
-# craftdriver CLI
+# CraftDriver CLI for agent exploration
 
-The `craftdriver` binary is what you reach for from a **shell**, not from
-TypeScript. Use it for probing, debugging, and agent-driven exploration.
+Use the CLI to learn the live page and exercise a flow. Use the TypeScript
+library for committed tests.
 
-## Install once
+## Safe setup
 
 ```bash
-npm install craftdriver
+npm install --save-dev craftdriver
+npx craftdriver init codex
 npx craftdriver --help
 ```
 
-## Daemon model (preferred)
+The init command installs `.agents/skills/craftdriver/`. It never reads or
+changes `AGENTS.md`, `CLAUDE.md`, other assistant instructions, or
+`.codex/config.toml`. `--dry-run` previews the installation. `--mcp` only prints
+an optional project-pinned MCP snippet.
 
-Long-lived browser; each command is a one-shot RPC. State (page,
-cookies, storage) survives between calls.
+## Persistent browser
 
 ```bash
 npx craftdriver daemon start
 npx craftdriver go http://127.0.0.1:8080/login.html
-npx craftdriver click 'button[type=submit]'
+npx craftdriver snapshot
 npx craftdriver daemon stop
 ```
 
-If no daemon is running, the first command auto-starts one. Use
-`daemon start` explicitly when you want a non-default browser
-(`--browser firefox`) or a specific timing.
+The first ordinary command auto-starts the daemon when needed. State, cookies,
+and the active page survive between commands.
+
+The daemon uses a Unix socket and is not available on Windows. On Windows, use
+the configured MCP server for a persistent agent session, or send the whole
+flow in one `--ephemeral` script.
+
+## Current commands
+
+```text
+go <url>
+find <selector> [--all] [--limit N] [--offset N]
+exists <selector>
+click <selector>
+dblclick <selector>
+fill <selector> <value>
+type <text>
+clear <selector>
+check <selector> | uncheck <selector>
+select <selector> <value>
+focus <selector> | scroll <selector>
+press <key> [selector]
+hover <selector>
+key press|down|up <key> [--selector S]
+mouse move|click [selector] [--x N --y N] [--button left|middle|right]
+mouse down|up [--button left|middle|right]
+mouse wheel [selector] [--delta-x N] [--delta-y N]
+dialog inspect | dialog accept [text] | dialog dismiss
+upload <selector> <file> [file...]
+text [selector] [--limit N]
+attr <selector> <name>
+value <selector>
+is visible|enabled|checked <selector>
+wait <selector> [--state visible|hidden|attached|detached] [--timeout ms]
+wait load [--state load|domcontentloaded|networkidle]
+pages
+page list | open [url] | select <index|id> | close <index|id>
+snapshot
+locators <selector>
+screenshot [-o out.png] [--full-page] [--selector selector]
+eval <javascript>
+back | forward | reload | status | quit
+daemon start | status | stop
+session list | close [name]
+state save <name> [--session-storage] | load <name> | list
+logs [list] [--kind console,error,request,response] [--level l]
+     [--contains s] [--since N] [--limit N] | wait ... | clear
+mock add <pattern> [--status N] [--body S] | block <pattern>
+     | list | remove <id> | clear
+trace start [name] [--no-screenshots] | stop [--zip] | status
+```
+
+## Named sessions
 
-## Ephemeral mode (sandboxed agents)
+Add `--session <name>` to any command to run it against its own browser,
+cookies, page selection, snapshot baseline and refs. Omitting the flag means
+the session named `default`.
 
 ```bash
-printf 'go http://127.0.0.1:8080/login.html
-fill "#user" alice
-click "button[type=submit]"
-text "#result"
-' | npx craftdriver --ephemeral
+npx craftdriver go http://127.0.0.1:8080/login.html --session shopper
+npx craftdriver go http://127.0.0.1:8080/admin.html  --session admin
+npx craftdriver session list
+npx craftdriver session close admin
 ```
 
-One short-lived browser for the whole script. No daemon, no socket.
+Use this when one workflow needs two logged-in identities at once, not as a
+default habit — each session is a real browser process and only 8 may be open
+at a time. Sessions start on first use and run independently, so a slow
+command in one does not block another.
 
-## Commands you actually use
+**Refs are per-session.** `e4` in one session and `e4` in another are
+different elements, and nothing will warn you if you mix them up. Run
+`snapshot` and the commands that use its refs with the same `--session`.
 
-```
-go <url>                navigate active page
-find <sel> [--all]      first match (or all); pretty-prints index + tag + text
-exists <sel>            0-wait probe; exit 0 = match, exit 1 = none
-click <sel>
-fill <sel> <value>
-press <key> [sel]
-hover <sel>
-text [sel]              page text or element text
-attr <sel> <name>
-value <sel>
-is visible|enabled|checked <sel>
-wait <sel> [--state visible|hidden|attached|detached] [--timeout ms]
-wait load [--state load|domcontentloaded|networkidle]
-pages
-screenshot [-o out.png] [--full-page] [--selector sel]
-eval <js>               last resort
-back | forward | reload | status | quit
-daemon start|status|stop
-```
+`--session` is not available with `--ephemeral`, which is a single browser
+that exits with the command.
+
+`select` matches an `<option>` by its `value` attribute, not its label.
+
+Use `fill <selector> <value>` to put a value in a field — it clears first and
+delivers real key events, so fields with key handlers work. `type <text>` takes
+no selector and types into whatever holds focus, mapping onto
+`browser.keyboard.type()`; reach for `focus <selector>` then `type` only when
+you need to append to existing text. `focus` leaves the caret at the end.
+
+`eval` is a last resort for inspection, not a replacement for public test APIs.
 
 ## Selector syntax
 
-CSS by default. Switch kind with `prefix=value`:
+CSS is the default. Prefix semantic selectors:
 
+```text
+role=button[name=Submit]   label=Email          testid=login-btn
+text=Sign In              text*=Sign           placeholder=Search…
+alt=Logo                  title=Help           xpath=//div[1]
+id=submit                 name=email           tag=h1
 ```
-role=button[name=Submit]   text=Sign In            text*=Sign
-label=Email                placeholder=Search…     testid=login-btn
-alt=Logo                   title=Help              xpath=//div[1]
-id=submit                  name=email              tag=h1
-```
 
-Anything else (including CSS attribute selectors like
-`button[type=submit]`) is parsed as CSS.
+Use `exists` as a zero-wait uniqueness probe and `find --all` to inspect
+ambiguous matches.
+
+## Tabs
+
+Commands act on the active tab. A tab the application opens by itself is
+listed by `page list` but is not selected, so nothing switches under you —
+use `page select <index|id>` first. An unknown target is an error rather than
+a fallback to the active tab. Switching, opening, or closing a tab clears
+refs, so take a fresh `snapshot` afterwards.
+
+## Console and network evidence
 
-## Output
+`logs` answers what the page logged and requested, after the fact — capture is
+already running before your first command, so you never arrange it in advance
+or re-run a flow to observe it.
 
-- TTY → human-readable text.
-- Piped or redirected → `{"ok":true,"result":…}` per line.
-- Force with `--json` or `--pretty`.
-- Errors include a stable `code:` line (same codes as the library
-  — see `docs/error-codes.md`). Use the code, not the prose.
+Use it to check your work: after a click, `logs --kind error` tells you whether
+the app threw, and `logs --kind request,response --contains /api/` shows what it
+called. This is the evidence to cite when explaining a failure.
 
-## Exit codes
+Ask for deltas, not dumps: every result carries a `cursor`; pass it back as
+`--since` to get only what happened since. `logs wait --contains <text>` scans
+what already arrived before waiting, so it resolves immediately when the event
+has already happened.
 
-- `0` success (or `exists` matched ≥ 1)
-- `1` assertion / timeout / `NO_MATCH` / `exists` matched zero
-- `2` usage error
+History is bounded (500 entries / 512 KB, oldest evicted). Check `dropped` and
+`droppedBeforeCursor` before concluding that nothing happened — a non-zero
+`droppedBeforeCursor` means the page you asked for has a hole in it.
+
+Network rows carry URL, method, status, MIME type and time only. No bodies,
+cookies or headers — do not report them as if they were a full capture. URLs
+include query strings, so avoid echoing sensitive query tokens into a report.
+
+## Traces and mocking
+
+`trace start <name>` … `trace stop --zip` records actions, console, network and
+screenshots under `.craftdriver/traces/`. Reach for it when a failure is not
+explicable from a snapshot — not by default, since it costs size and time.
+One trace at a time; a second `start` is an error.
+
+`mock add <pattern> --status N --body S` serves a fixed response and
+`mock block <pattern>` fails matching requests, so you can drive error paths
+without touching the application. `mock list` and `mock clear` manage them;
+clear them when done, since they outlive the command that added them.
+
+Only these flat shapes exist. The library's `network.intercept()` takes a
+handler function that no command line can express — if you need dynamic
+behaviour, write it in a test with the library API instead of asking for a
+CLI flag that does not exist.
+
+## Saved login state
+
+`state save <name>` captures the current browser's cookies and local storage;
+`state load <name>` puts them back. Use it so you log in once instead of
+replaying the form for every exploration.
+
+On Chrome/Chromium and Firefox BiDi, load before the first real navigation:
+`state load <name>` → `go <url>`. Cookies plus all captured localStorage origins
+are ready for the page's first script. If a page is already open, reload it
+after the overlay.
+
+Classic browsers (including Safari) require `go <url>` → `state load <name>` →
+`reload`, and only a single matching origin is supported. State saved with
+`--session-storage` also requires that active-page order because sessionStorage
+is tab-scoped. Unsupported combinations fail before mutation rather than
+silently restoring only cookies.
+
+State files are credentials — cookies included. They live under
+`.craftdriver/state/`, owner-only. Never print one, commit one, or paste its
+contents into a test; pass a bare name (`alice`), never a path. `state save`
+reports counts and origins only, and that is all you should report onward.
+
+`state load` clears refs, so take a fresh `snapshot` after it.
+
+## Refs vs. durable locators
+
+A `ref=eN` from `snapshot` names one element for as long as it lives. It cannot
+drift onto a different element: if the element is removed or duplicated, or the
+page navigates or reloads, the command fails with `STALE_REF` and you take a
+fresh snapshot. Refs are never reused, so an old ref never matches a new page.
+
+Refs are still exploration state and never belong in test code. To write a test,
+turn the element into a durable selector and let CraftDriver check it against
+the live page first:
+
+```bash
+npx craftdriver locators ref=e7
+```
 
-## Defaults
+Each candidate is reported `unique`, `ambiguous`, or `missing`, ordered by
+durability (role + name, label, test id, unique text, minimal CSS). Use one
+reported `unique`. If none is, add a `data-testid` to the application rather
+than committing a positional selector.
 
-- 5 s per-call timeout (override with `--timeout ms` or
-  `CRAFTDRIVER_AGENT_TIMEOUT`).
-- Probe with `exists` before `click`/`wait` when you're guessing.
-- Don't `sleep`. `wait <sel>` is auto-waiting; `wait load` waits on
-  document state.
+## Output and failures
 
-## When NOT to use the CLI
+- TTY output is concise text; piped output is JSON per line.
+- `--json` and `--pretty` force the output format.
+- Exit `0` is success, `1` is action/assertion/no-match failure, and `2` is
+  invalid CLI usage.
+- Errors carry the same stable codes as the public library.
 
-Writing a test suite. Use the library (`import { Browser } from
-'craftdriver'`) — it has 30 s default timeouts, full TS types, and
-chainable `Locator` ergonomics.
+Do not add sleeps. CLI actions already auto-wait, and `wait` expresses explicit
+page conditions.

package/skills/craftdriver/patterns.md

@@ -1,7 +1,6 @@
-# craftdriver — patterns
+# CraftDriver — patterns
 
-Worked recipes. Each is ≤ ~200 tokens; load on demand from
-[SKILL.md](SKILL.md).
+Worked recipes, each kept compact. Load on demand from [SKILL.md](SKILL.md).
 
 ## 1. Login, save storage state for reuse
 
@@ -13,21 +12,28 @@ await browser.locator(By.labelText('Password')).fill(process.env.PW!);
 await browser.locator(By.role('button', { name: 'Sign in' })).click();
 await browser.locator(By.testId('dashboard')).expect().toBeVisible();
 
-// Persist for fast subsequent runs.
-const state = await browser.defaultContext.storageState();
-await fs.writeFile('.auth/state.json', JSON.stringify(state));
+// Persist atomically with owner-only permissions where supported.
+await browser.saveState('.auth/state.json');
 await browser.quit();
 ```
 
 ## 2. Re-use saved login
 
+On a BiDi session, launch restores cookies and every captured localStorage
+origin before the first real navigation. Application changes then survive
+reload because the state is seeded once, not replayed on every document.
+
 ```ts
-const state = JSON.parse(await fs.readFile('.auth/state.json', 'utf8'));
-const browser = await Browser.launch({ storageState: state });
+const browser = await Browser.launch({ storageState: '.auth/state.json' });
 await browser.navigateTo('https://app.example.com/dashboard');
 await browser.locator(By.testId('dashboard')).expect().toBeVisible();
 ```
 
+Classic WebDriver cannot seed arbitrary origins before navigation: launch
+rejects non-empty state. Launch first, navigate to the sole captured origin,
+then call `browser.loadState('.auth/state.json')`. Snapshots containing
+sessionStorage also require that active-origin flow, including on BiDi.
+
 ## 3. Wait for a network response after a click
 
 ```ts