craftdriver 1.7.0 → 1.9.0

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,9 +38,37 @@ 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.
+- Add `.auth/` to `.gitignore`; generated state contains live session cookies.
 - Regenerate auth state when the app changes its login or session behavior.
 - Use separate files such as `.auth/admin.json` and `.auth/customer.json` for different roles.
 

package/docs/selectors.md

@@ -435,6 +435,67 @@ await card.getByRole('button', { name: 'Buy' }).click();
 await card.getByText('In stock').expect().toBeVisible();
 ```
 
+## Open Shadow DOM
+
+CraftDriver crosses Shadow DOM with an explicit, lazy `shadowRoot()` boundary.
+Call it on the locator or element handle for the shadow host, then locate within
+the returned `ShadowRootLocator`:
+
+```typescript
+const card = browser.locator('user-card#account').shadowRoot();
+
+await card.getByRole('button', { name: 'Edit' }).click();
+await card.getByLabel('Display name').fill('Alice');
+await card.locator('.status').expect().toHaveText('Saved');
+```
+
+The boundary is explicit: `browser.locator('user-card .status')` does not pierce
+the root and ordinary CSS keeps its normal tree scope. Both API styles work:
+
+```typescript
+// Lazy Locator host — re-resolves the host and root for every operation.
+const lazyRoot = browser.locator('#account').shadowRoot();
+
+// ElementHandle style — browser.find() is locator-backed and auto-waits too.
+const handleRoot = browser.find('#account').shadowRoot();
+await handleRoot.find(By.testId('save')).click();
+```
+
+Nested open roots compose by crossing each boundary in order:
+
+```typescript
+const address = browser
+  .locator('checkout-shell')
+  .shadowRoot()
+  .locator('address-form')
+  .shadowRoot();
+
+await address.getByPlaceholder('City').fill('Sofia');
+await address.getByRole('button', { name: 'Save address' }).click();
+```
+
+`ShadowRootLocator` is a search context, not an element. It provides
+`locator()`, `find()`, `findAll()`, and all `getBy*()` helpers; actions and
+assertions live on the descendant `Locator`/`ElementHandle`. Filters, indexing,
+auto-waiting, assertions, locator-scoped accessibility audits, `Page`, and
+`Frame` contexts retain the complete root-aware query chain.
+
+The host follows normal locator cardinality: when it matches more than one
+element, use `first()`, `last()`, or `nth()` before `shadowRoot()` to select the
+intended host. Descendant `count()` returns `0` for no current matches, while
+actions and positive assertions auto-wait using the configured timeout.
+
+Only roots exposed by the page's public `host.shadowRoot` getter are supported.
+A missing or closed root throws `NO_OPEN_SHADOW_ROOT`; CraftDriver does not use
+WebDriver as a closed-root backdoor. Detached roots restart the complete lazy
+query and end with `DETACHED_SHADOW_ROOT` only when a stable root cannot be
+established. Raw XPath inside a shadow root is transport-dependent; CSS and the
+semantic `getBy*`/`By.*` helpers are the portable choices.
+
+The same API is covered on Chrome, Firefox, and Safari. CraftDriver uses
+WebDriver BiDi shadow primitives when the session supports them and falls back
+to the standard WebDriver Classic shadow-root endpoints otherwise.
+
 ### Locator actions and state
 
 | Method                          | Description                                            |

package/docs/session-management.md

@@ -9,14 +9,25 @@ 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.
+
+State files contain live session cookies. Keep them in a dedicated ignored
+directory:
+
+```text
+.auth/
+```
+
 ## Saving Session State
 
 ```typescript
 // Save all cookies and localStorage to a file
-await browser.saveState('./session.json');
+await browser.saveState('.auth/session.json');
 
 // Save with options
-await browser.saveState('./session.json', {
+await browser.saveState('.auth/session.json', {
   includeCookies: true, // default: true
   includeLocalStorage: true, // default: true
   includeSessionStorage: false, // default: false
@@ -51,7 +62,10 @@ The saved file contains:
 
 ```typescript
 // Load state into current browser
-await browser.loadState('./session.json');
+await browser.loadState('.auth/session.json');
+
+// Paths and in-memory state objects are equivalent
+await browser.loadState(await browser.storage.getState());
 ```
 
 ## Working With State Objects
@@ -63,6 +77,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:
@@ -70,7 +89,7 @@ The most common pattern - launch a browser with existing session:
 ```typescript
 const browser = await Browser.launch({
   browserName: 'chrome',
-  storageState: './session.json',
+  storageState: '.auth/session.json',
 });
 
 // Navigate directly to authenticated page
@@ -78,6 +97,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('.auth/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:
@@ -134,10 +202,10 @@ async function generateAuth() {
   await browser.expect('#dashboard').toBeVisible();
 
   // Save the authenticated state
-  await browser.saveState('./auth.json');
+  await browser.saveState('.auth/session.json');
 
   await browser.quit();
-  console.log('Auth state saved to auth.json');
+  console.log('Auth state saved to .auth/session.json');
 }
 
 generateAuth();
@@ -157,7 +225,7 @@ describe('Dashboard', () => {
     // Launch with saved auth - already logged in!
     browser = await Browser.launch({
       browserName: 'chrome',
-      storageState: './auth.json',
+      storageState: '.auth/session.json',
     });
   });
 
@@ -196,13 +264,13 @@ async function testLoginPersistence() {
   await browser.click('#submit');
   await browser.expect('#welcome').toBeVisible();
 
-  await browser.saveState('./session.json');
+  await browser.saveState('.auth/session.json');
   await browser.quit();
 
   // Second browser: Load state and verify logged in
   browser = await Browser.launch({
     browserName: 'chrome',
-    storageState: './session.json',
+    storageState: '.auth/session.json',
   });
 
   await browser.navigateTo('http://localhost:3000/login');
@@ -221,7 +289,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 +309,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/why-craftdriver.md

@@ -16,7 +16,7 @@ CraftDriver is for writing boringly reliable automation against real browsers, w
 - 🧾 **Trace evidence** - capture actions, console output, errors, network events, and screenshots.
 - ☁️ **Remote WebDriver** - use the Browser API with a self-hosted Selenium Grid or a cloud provider like [BrowserStack](https://www.browserstack.com/).
 - ⚛️ **Electron apps** - drive packaged Electron desktop apps and mock native OS dialogs (open/save, message boxes).
-- 🤖 **Agent-friendly** - CLI, MCP, and assistant rules when coding agents need the browser.
+- 🤖 **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.7.0",
+  "version": "1.9.0",
   "description": "Modern WebDriver automation library for NodeJS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,10 +14,12 @@
     "lint": "eslint . --ext .ts",
     "format": "prettier --write .",
     "test": "HEADLESS=true vitest run",
-    "test:firefox": "BROWSER_NAME=firefox HEADLESS=true vitest run --maxWorkers=2",
+    "test:firefox": "BROWSER_NAME=firefox HEADLESS=true vitest run",
     "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",
@@ -108,7 +110,7 @@
     "yazl": "^3.3.1"
   },
   "overrides": {
-    "brace-expansion": "5.0.6",
+    "brace-expansion": "5.0.7",
     "ip-address": "10.1.1",
     "npm": "^11.18.0",
     "undici": "7.28.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