craftdriver 1.8.0 → 1.9.0

package/dist/lib/shadowRoot.js

@@ -0,0 +1,29 @@
+/** W3C WebDriver shadow-root reference key. */
+export const W3C_SHADOW_ROOT_KEY = 'shadow-6066-11e4-a52e-4f735466cecf';
+/**
+ * A WebDriver Classic shadow-root search context.
+ *
+ * This is intentionally internal. The public API exposes the lazy
+ * `ShadowRootLocator`, not a cacheable wire reference that can detach.
+ */
+export class ClassicShadowRoot {
+    driver;
+    shadowRootId;
+    constructor(driver, shadowRootId) {
+        this.driver = driver;
+        this.shadowRootId = shadowRootId;
+    }
+    getId() {
+        return this.shadowRootId;
+    }
+    findElement(locator) {
+        return this.driver.findElementFromShadowRoot(this.shadowRootId, locator);
+    }
+    findElements(locator) {
+        return this.driver.findElementsFromShadowRoot(this.shadowRootId, locator);
+    }
+    toJSON() {
+        return { [W3C_SHADOW_ROOT_KEY]: this.shadowRootId };
+    }
+}
+//# sourceMappingURL=shadowRoot.js.map

package/dist/lib/shadowRoot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadowRoot.js","sourceRoot":"","sources":["../../src/lib/shadowRoot.ts"],"names":[],"mappings":"AAIA,+CAA+C;AAC/C,MAAM,CAAC,MAAM,mBAAmB,GAAG,oCAAoC,CAAC;AAExE;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IAElB;IACA;IAFV,YACU,MAAc,EACd,YAAoB;QADpB,WAAM,GAAN,MAAM,CAAQ;QACd,iBAAY,GAAZ,YAAY,CAAQ;IAC3B,CAAC;IAEJ,KAAK;QACH,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,WAAW,CAAC,OAAW;QACrB,OAAO,IAAI,CAAC,MAAM,CAAC,yBAAyB,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC3E,CAAC;IAED,YAAY,CAAC,OAAW;QACtB,OAAO,IAAI,CAAC,MAAM,CAAC,0BAA0B,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM;QACJ,OAAO,EAAE,CAAC,mBAAmB,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;IACtD,CAAC;CACF"}

package/dist/lib/shadowRootLocator.d.ts

@@ -0,0 +1,31 @@
+import { By, type ExactLocatorOptions, type RoleLocatorOptions } from './by.js';
+import type { Driver } from './driver.js';
+import { ElementHandle } from './elementHandle.js';
+import { Locator } from './locator.js';
+import { QueryEnvironment, type SearchRootPlan } from './query.js';
+/**
+ * Lazy, explicit search context for one open ShadowRoot.
+ *
+ * It deliberately exposes lookup methods only: a ShadowRoot is a document
+ * fragment, not an actionable element.
+ */
+export declare class ShadowRootLocator {
+    private driver;
+    private root;
+    private getDefaultTimeout;
+    private environment;
+    constructor(driver: Driver, root: SearchRootPlan, getDefaultTimeout: () => number, environment: QueryEnvironment);
+    locator(selector: string | By): Locator;
+    find(selector: string | By): ElementHandle;
+    findAll(selector: string | By): Promise<ElementHandle[]>;
+    getByRole(role: string, options?: RoleLocatorOptions): Locator;
+    getByText(text: string, options?: {
+        exact?: boolean;
+    }): Locator;
+    getByLabel(text: string, options?: ExactLocatorOptions): Locator;
+    getByPlaceholder(text: string, options?: ExactLocatorOptions): Locator;
+    getByAltText(text: string, options?: ExactLocatorOptions): Locator;
+    getByTitle(text: string, options?: ExactLocatorOptions): Locator;
+    getByTestId(id: string): Locator;
+}
+//# sourceMappingURL=shadowRootLocator.d.ts.map

package/dist/lib/shadowRootLocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadowRootLocator.d.ts","sourceRoot":"","sources":["../../src/lib/shadowRootLocator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAChF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EACL,gBAAgB,EAEhB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,iBAAiB;IACzB,OAAO,CAAC,WAAW;gBAHX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,cAAc,EACpB,iBAAiB,EAAE,MAAM,MAAM,EAC/B,WAAW,EAAE,gBAAgB;IAGvC,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,EAAE,GAAG,OAAO;IAUvC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,EAAE,GAAG,aAAa;IAUpC,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAI9D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO;IAI9D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO;IAI/D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO;IAIhE,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO;IAItE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO;IAIlE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO;IAIhE,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAGjC"}

package/dist/lib/shadowRootLocator.js

@@ -0,0 +1,55 @@
+import { By } from './by.js';
+import { ElementHandle } from './elementHandle.js';
+import { Locator } from './locator.js';
+import { createLocatorPlan, } from './query.js';
+/**
+ * Lazy, explicit search context for one open ShadowRoot.
+ *
+ * It deliberately exposes lookup methods only: a ShadowRoot is a document
+ * fragment, not an actionable element.
+ */
+export class ShadowRootLocator {
+    driver;
+    root;
+    getDefaultTimeout;
+    environment;
+    constructor(driver, root, getDefaultTimeout, environment) {
+        this.driver = driver;
+        this.root = root;
+        this.getDefaultTimeout = getDefaultTimeout;
+        this.environment = environment;
+    }
+    locator(selector) {
+        const by = typeof selector === 'string' ? By.css(selector) : selector;
+        return Locator.fromPlan(this.driver, createLocatorPlan(by, this.root), this.getDefaultTimeout, this.environment);
+    }
+    find(selector) {
+        const locator = this.locator(selector);
+        return ElementHandle.fromTarget(this.driver, { kind: 'locator', plan: locator._queryPlan() }, this.getDefaultTimeout, this.environment);
+    }
+    async findAll(selector) {
+        return this.locator(selector).all();
+    }
+    getByRole(role, options) {
+        return this.locator(By.role(role, options));
+    }
+    getByText(text, options) {
+        return this.locator(By.text(text, options));
+    }
+    getByLabel(text, options) {
+        return this.locator(By.labelText(text, options));
+    }
+    getByPlaceholder(text, options) {
+        return this.locator(By.placeholder(text, options));
+    }
+    getByAltText(text, options) {
+        return this.locator(By.altText(text, options));
+    }
+    getByTitle(text, options) {
+        return this.locator(By.title(text, options));
+    }
+    getByTestId(id) {
+        return this.locator(By.testId(id));
+    }
+}
+//# sourceMappingURL=shadowRootLocator.js.map

package/dist/lib/shadowRootLocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadowRootLocator.js","sourceRoot":"","sources":["../../src/lib/shadowRootLocator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAqD,MAAM,SAAS,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAEL,iBAAiB,GAElB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IAElB;IACA;IACA;IACA;IAJV,YACU,MAAc,EACd,IAAoB,EACpB,iBAA+B,EAC/B,WAA6B;QAH7B,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAgB;QACpB,sBAAiB,GAAjB,iBAAiB,CAAc;QAC/B,gBAAW,GAAX,WAAW,CAAkB;IACpC,CAAC;IAEJ,OAAO,CAAC,QAAqB;QAC3B,MAAM,EAAE,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACtE,OAAO,OAAO,CAAC,QAAQ,CACrB,IAAI,CAAC,MAAM,EACX,iBAAiB,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,EAChC,IAAI,CAAC,iBAAiB,EACtB,IAAI,CAAC,WAAW,CACjB,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,QAAqB;QACxB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvC,OAAO,aAAa,CAAC,UAAU,CAC7B,IAAI,CAAC,MAAM,EACX,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,UAAU,EAAE,EAAE,EAC/C,IAAI,CAAC,iBAAiB,EACtB,IAAI,CAAC,WAAW,CACjB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,QAAqB;QACjC,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,EAAE,CAAC;IACtC,CAAC;IAED,SAAS,CAAC,IAAY,EAAE,OAA4B;QAClD,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,SAAS,CAAC,IAAY,EAAE,OAA6B;QACnD,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,UAAU,CAAC,IAAY,EAAE,OAA6B;QACpD,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,CAAC;IAED,gBAAgB,CAAC,IAAY,EAAE,OAA6B;QAC1D,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,YAAY,CAAC,IAAY,EAAE,OAA6B;QACtD,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,UAAU,CAAC,IAAY,EAAE,OAA6B;QACpD,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,WAAW,CAAC,EAAU;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACrC,CAAC;CACF"}

package/dist/lib/timing.d.ts

@@ -117,8 +117,8 @@ export declare const SESSION_CREATE_BACKOFF_STEP_MS = 500;
  * a barrier the BiDi side respects — an immediately following `{ context }`
  * script call can land while BiDi is still swapping the old realm for the new
  * one. The error is pre-execution (the script never ran, no side effects), so a
- * short retry that re-resolves the context is safe. See
- * plans/TODO-bidi-first-navigation.md (Option A).
+ * short retry that re-resolves the context is safe. The injected-error
+ * regression case lives in `tests/evaluate.test.ts`.
  */
 export declare const EVAL_REALM_RETRY_ATTEMPTS = 3;
 export declare const EVAL_REALM_RETRY_DELAY_MS = 25;

package/dist/lib/timing.js

@@ -121,8 +121,8 @@ export const SESSION_CREATE_BACKOFF_STEP_MS = 500;
  * a barrier the BiDi side respects — an immediately following `{ context }`
  * script call can land while BiDi is still swapping the old realm for the new
  * one. The error is pre-execution (the script never ran, no side effects), so a
- * short retry that re-resolves the context is safe. See
- * plans/TODO-bidi-first-navigation.md (Option A).
+ * short retry that re-resolves the context is safe. The injected-error
+ * regression case lives in `tests/evaluate.test.ts`.
  */
 export const EVAL_REALM_RETRY_ATTEMPTS = 3;
 export const EVAL_REALM_RETRY_DELAY_MS = 25;

package/docs/accessibility.md

@@ -130,7 +130,12 @@ interface A11yViolation {
   impact: 'minor' | 'moderate' | 'serious' | 'critical';
   description: string;
   helpUrl: string;
-  nodes: Array<{ target: string[]; html: string; failureSummary: string }>;
+  nodes: Array<{
+    // A nested string[] is axe's selector path through open shadow roots.
+    target: Array<string | [string, string, ...string[]]>;
+    html: string;
+    failureSummary: string;
+  }>;
 }
 ```
 
@@ -175,3 +180,6 @@ a `window` flag so subsequent audits in the same document skip the
 inject step). The audit itself uses Classic WebDriver
 `execute/async` so the underlying `axe.run()` promise is awaited
 before the result is shipped back — works with or without BiDi.
+axe-core traverses open Shadow DOM itself. CraftDriver preserves axe's nested
+cross-tree selector paths in `node.target`; closed roots remain outside the
+audit, matching axe-core's support boundary.

package/docs/api-reference.md

@@ -30,6 +30,7 @@ Find page content with semantic locators and selector helpers.
 |---|---|---|---|
 | `By` | class | — | [selectors](selectors.md) |
 | `Locator` | class | — | [selectors](selectors.md) |
+| `ShadowRootLocator` | class | Lazy, explicit search context for one open ShadowRoot. | [selectors](selectors.md) |
 
 ## Input
 
@@ -149,6 +150,8 @@ Run axe-core accessibility checks and inspect violation details.
 | `A11yImpact` | type | Severity buckets reported by axe-core. | [accessibility](accessibility.md) |
 | `A11yOptions` | type | — | [accessibility](accessibility.md) |
 | `A11yResult` | type | — | [accessibility](accessibility.md) |
+| `A11yShadowSelector` | type | axe-core selector path through one or more open shadow boundaries. | [accessibility](accessibility.md) |
+| `A11yTarget` | type | A light-DOM selector or axe-core's nested selector path for Shadow DOM. | [accessibility](accessibility.md) |
 | `A11yViolation` | type | — | [accessibility](accessibility.md) |
 | `A11yViolationNode` | type | — | [accessibility](accessibility.md) |
 
@@ -185,4 +188,4 @@ Exports that are public but not yet assigned to a feature group.
 | `RemoteWebDriverOptions` | type | Options for connecting to any W3C-compatible remote WebDriver endpoint — a self-hosted Selenium Grid, BrowserStack, or another cloud provider. Provider-specific detail (BrowserStack's `bstack:options`, etc.) is forwarded through `capabilities` without schema conversion. | — |
 | `SessionStateCookie` | type | — | — |
 
-Total exports: **94**.
+Total exports: **97**.

package/docs/browser-api.md

@@ -19,7 +19,7 @@ const browser = await Browser.launch({ browserName: 'chrome' });
 // With pre-loaded session state
 const browser = await Browser.launch({
   browserName: 'chrome',
-  storageState: './auth.json',
+  storageState: '.auth/session.json',
 });
 ```
 
@@ -385,10 +385,10 @@ See [Session Management](./session-management.md) for full details.
 const storage = browser.storage;
 
 // Save current session to file
-await browser.saveState('./session.json');
+await browser.saveState('.auth/session.json');
 
 // Load session from file
-await browser.loadState('./session.json');
+await browser.loadState('.auth/session.json');
 
 // Or use an in-memory SessionState object
 await browser.loadState(await browser.storage.getState());

package/docs/browser-context.md

@@ -80,13 +80,13 @@ await page.find('#submit').click();
 await page.expect('#welcome').toBeVisible();
 
 // Cookies + localStorage for every origin the context has visited.
-await ctx.saveStorageState('auth/alice.json');
+await ctx.saveStorageState('.auth/alice.json');
 await browser.quit();
 ```
 
 ```typescript
 // every other test:
-const ctx = await browser.newContext({ storageState: 'auth/alice.json' });
+const ctx = await browser.newContext({ storageState: '.auth/alice.json' });
 const page = await ctx.newPage({ url: 'https://app.example.com/dashboard' });
 // Already logged in — no form, no waiting.
 ```
@@ -135,7 +135,7 @@ Create a new isolated user context. Backed by BiDi
 const ctx = await browser.newContext({
   baseURL: 'https://staging.example.com',
   extraHTTPHeaders: { 'x-test-tenant': 'acme', 'x-staging-token': process.env.STAGING_TOKEN! },
-  storageState: 'auth/alice.json',
+  storageState: '.auth/alice.json',
 });
 const page = await ctx.newPage({ url: '/dashboard' }); // resolves against baseURL
 ```

package/docs/cli.md

@@ -139,9 +139,10 @@ Anything else is treated as a CSS selector, so attribute selectors with
 
 ## Snapshot — sanitized DOM with refs
 
-`craftdriver snapshot` returns one line per visible interactive element
-on the active page, with a stable ref (`e1`, `e2`, …) that you can
-use as a selector for the next command:
+`craftdriver snapshot` returns visible semantic elements on the active page,
+with a stable ref (`e1`, `e2`, …) that you can use as a selector for the next
+command. Open Shadow DOM is traversed recursively and shown with indented
+`#shadow-root (open)` boundaries; closed roots are never inspected:
 
 ```bash
 $ craftdriver snapshot
@@ -166,7 +167,7 @@ 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
+- if the element is removed, or the page navigates or
   reloads, the ref fails with `STALE_REF` instead of resolving to
   whatever now sits in that position.
 
@@ -175,9 +176,11 @@ 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"]`) after craftdriver has checked the ref
-still identifies exactly one element; auto-waiting works unchanged.
+Internally `ref=eN` returns the exact element from the page's identity registry,
+including elements inside open shadow roots. The diagnostic
+`data-craftdriver-ref` attribute is never used for lookup or uniqueness, so an
+authored or cloned marker cannot redirect or invalidate a ref. Auto-waiting and
+native WebDriver actions work unchanged after identity resolution.
 
 ## Tabs
 

package/docs/error-codes.md

@@ -47,8 +47,10 @@ try {
 | `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…). 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()`. |
+| `NO_OPEN_SHADOW_ROOT` | A shadow host resolved, but its public `shadowRoot` getter returned `null`. This intentionally covers both an unattached root and a closed root. | Verify the host is correct and the component uses `mode: "open"`. |
+| `DETACHED_SHADOW_ROOT` | A shadow root detached while resolving a query and full-plan retries could not recover. | Recreate the component or use a stable host locator; inspect `detail.queryPath` and `detail.attempts`. |
 | `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. |
+| `STALE_REF` | An agent-surface snapshot ref (`ref=eN`) no longer identifies one live registry 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` (corrupt/legacy identity registry), `no-snapshot` (none taken yet). Diagnostic marker attributes do not resolve refs, so cloning one cannot redirect or invalidate a live ref. |
 | `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. |

package/docs/getting-started.md

@@ -87,7 +87,7 @@ Pick a browser with `browserName`:
 const browser = await Browser.launch({
   browserName: 'firefox', // 'chrome' | 'chromium' | 'firefox' | 'safari'
   // BiDi: restore cookies + multi-origin localStorage before first navigation.
-  storageState: './session.json', // path or in-memory SessionState
+  storageState: '.auth/session.json', // path or in-memory SessionState
 });
 ```
 

package/docs/mcp.md

@@ -182,15 +182,15 @@ Use `ref=eN` as the selector for the next call:
 
 - **A ref names one element for as long as it lives.** A surviving node keeps
   its ref across snapshots, and refs are never reused — so a ref cannot drift
-  onto a different element. If it is removed, duplicated, or the page
+  onto a different element. If it is removed or the page
   navigates, the call fails `STALE_REF`; take a fresh snapshot then.
 - **Never copy refs into test code.** Convert live role/name, label, test ID,
   text, or DOM evidence into a durable selector and validate it.
 - **Token efficient.** `ref=e7` is 5 characters; `role=button[name=Sign in]`
   is 26. Over a 50-step flow that adds up.
-- **Auto-waiting still works.** Internally `ref=eN` resolves to a CSS
-  attribute selector (`[data-craftdriver-ref="eN"]`); every action
-  takes the normal visible+enabled wait path.
+- **Auto-waiting still works.** `ref=eN` resolves directly to the exact element
+  in the page identity registry, including inside an open shadow root; every
+  action takes the normal visible+enabled wait path.
 
 **Invalidation rules**
 
@@ -198,13 +198,17 @@ Use `ref=eN` as the selector for the next call:
   its ref across snapshots; snapshots do **not** renumber it.
 - New elements get fresh numbers. Refs are never reused, including after a
   navigation or reload.
-- A ref whose element was removed or duplicated, or that was issued before
+- A ref whose element was removed, or that was issued before
   the page navigated or reloaded, fails with `STALE_REF` — take a fresh
   snapshot. It never resolves to a different element.
 - `error.detail.reason` distinguishes `detached`, `document-changed`,
   `unknown-ref`, `ambiguous`, and `no-snapshot`.
 - Refs are exploration state and must never appear in committed tests.
 
+Snapshots recursively enter open Shadow DOM, mark each boundary with an
+indented `#shadow-root (open)` line, flatten slot assignment without duplicate
+entries, and never inspect closed roots.
+
 ## Post-action payload
 
 Every tool returns a content array. Mutating tools (`navigate`,

package/docs/public/examples/iframe-child.html

@@ -38,7 +38,18 @@
   <p id="child-result"></p>
   <input id="child-input" type="text" placeholder="type here" />
   <p id="child-value"></p>
+  <frame-widget id="frame-widget"></frame-widget>
   <script>
+    customElements.define('frame-widget', class extends HTMLElement {
+      constructor() {
+        super();
+        const root = this.attachShadow({ mode: 'open' });
+        root.innerHTML = '<button id="shadow-frame-button" type="button">Shadow frame action</button>';
+        root.querySelector('button').addEventListener('click', () => {
+          document.querySelector('#child-result').textContent = 'shadow-clicked';
+        });
+      }
+    });
     document.getElementById('child-btn').addEventListener('click', function () {
       document.getElementById('child-result').textContent = 'clicked';
     });
@@ -48,4 +59,4 @@
   </script>
 </body>
 
-</html>
+</html>

package/docs/public/examples/shadow-dom.html

@@ -0,0 +1,137 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>CraftDriver Shadow DOM fixture</title>
+    <style>
+      body { font-family: sans-serif; margin: 24px; }
+      user-card, closed-card, no-root { display: block; margin: 12px 0; }
+      #status { min-height: 20px; }
+    </style>
+  </head>
+  <body>
+    <h1>Shadow DOM fixture</h1>
+    <div id="status">idle</div>
+    <button id="replace-card" type="button">Replace card</button>
+
+    <!-- Open, nested, and slotted happy path -->
+    <user-card id="card">
+      <span slot="summary" id="slotted-summary" role="note">Slotted summary</span>
+      <img slot="summary" id="slotted-image" src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==" />
+    </user-card>
+
+    <!-- Async-host, closed-root, and missing-root cases -->
+    <div id="late-card-container"></div>
+    <closed-card id="closed-card"></closed-card>
+    <no-root id="no-root"></no-root>
+
+    <script>
+      // Nested open-root form control.
+      class AddressForm extends HTMLElement {
+        constructor() {
+          super();
+          const root = this.attachShadow({ mode: 'open' });
+          root.innerHTML = `
+            <style>:host { display:block; padding:8px; border:1px solid #aaa }</style>
+            <label for="city">City</label>
+            <input id="city" data-testid="city" placeholder="Enter city" title="Delivery city" />
+            <span id="save-address-label">Save address</span>
+            <button id="nested-save" type="button" aria-labelledby="save-address-label">Save</button>
+            <img id="shadow-image" src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==" />
+          `;
+          root.querySelector('#nested-save').addEventListener('click', () => {
+            document.querySelector('#status').textContent = 'saved:' + root.querySelector('#city').value;
+          });
+          setTimeout(() => {
+            const delayed = document.createElement('button');
+            delayed.id = 'delayed-shadow-action';
+            delayed.type = 'button';
+            delayed.textContent = 'Delayed shadow action';
+            delayed.addEventListener('click', () => {
+              document.querySelector('#status').textContent = 'delayed';
+            });
+            root.appendChild(delayed);
+          }, 250);
+        }
+      }
+
+      // Open-root host with slots, semantic content, and actions.
+      class UserCard extends HTMLElement {
+        constructor() {
+          super();
+          const root = this.attachShadow({ mode: 'open' });
+          root.innerHTML = `
+            <style>:host { display:block; padding:8px; border:1px solid #444 }</style>
+            <section role="region" aria-label="Account">
+              <slot name="summary"><span>Fallback summary</span></slot>
+              <slot><button id="fallback-control" type="button">Fallback action</button></slot>
+              <a id="profile-link" href="#profile">Profile link</a>
+              <img id="avatar" alt="User avatar" src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==" />
+              <button class="action" id="edit" type="button">Edit</button>
+              <button class="action" id="delete" type="button">Delete</button>
+              <address-form id="address"></address-form>
+            </section>
+          `;
+          root.querySelector('#edit').addEventListener('click', () => {
+            document.querySelector('#status').textContent = 'edited';
+          });
+          root.querySelector('#delete').addEventListener('click', () => {
+            document.querySelector('#status').textContent = 'deleted';
+          });
+          setTimeout(() => {
+            const delayed = document.createElement('button');
+            delayed.id = 'delayed-card-action';
+            delayed.type = 'button';
+            delayed.textContent = 'Delayed card action';
+            delayed.addEventListener('click', () => {
+              document.querySelector('#status').textContent = 'delayed-card';
+            });
+            root.appendChild(delayed);
+          }, 250);
+        }
+      }
+
+      // Closed-root privacy boundary.
+      class ClosedCard extends HTMLElement {
+        constructor() {
+          super();
+          const root = this.attachShadow({ mode: 'closed' });
+          root.innerHTML = `
+            <button id="closed-false-positive" type="button">Edit</button>
+            <img id="closed-image" src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==" />
+          `;
+        }
+      }
+
+      customElements.define('address-form', AddressForm);
+      customElements.define('user-card', UserCard);
+      customElements.define('closed-card', ClosedCard);
+
+      document.querySelector('#replace-card').addEventListener('click', () => {
+        const replacement = document.createElement('user-card');
+        replacement.id = 'card';
+        const summary = document.createElement('span');
+        summary.slot = 'summary';
+        summary.id = 'slotted-summary';
+        summary.setAttribute('role', 'note');
+        summary.textContent = 'Replacement summary';
+        replacement.appendChild(summary);
+        document.querySelector('#card').replaceWith(replacement);
+      });
+
+      setTimeout(() => {
+        const late = document.createElement('user-card');
+        late.id = 'late-card';
+        document.querySelector('#late-card-container').appendChild(late);
+      }, 250);
+
+      setTimeout(() => {
+        const delayed = document.createElement('button');
+        delayed.id = 'delayed-flat-action';
+        delayed.type = 'button';
+        delayed.textContent = 'Delayed flat action';
+        document.body.appendChild(delayed);
+      }, 250);
+    </script>
+  </body>
+</html>

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

@@ -68,7 +68,7 @@ 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                                            |