craftdriver 1.7.0 → 1.8.0

package/dist/lib/sessionStateValidation.d.ts

@@ -0,0 +1,35 @@
+import { CraftdriverError } from './errors.js';
+import type { CookieInput, SessionState } from './bidi/types.js';
+export interface StorageStateErrorContext {
+    operation?: string;
+    browserName?: string;
+    protocol?: 'bidi' | 'classic' | string;
+}
+export declare function storageStateDetail(context: StorageStateErrorContext | undefined, phase: string, extra?: Record<string, unknown>): Record<string, unknown>;
+/** True for an error already carrying this feature's structured contract. */
+export declare function isStorageStateError(error: unknown): error is CraftdriverError;
+/** A canonical http(s) origin: `scheme://host[:port]`, no path or trailing slash. */
+export declare function isHttpOrigin(origin: string): boolean;
+/**
+ * Parse `source` (a path or an in-memory object) into a validated
+ * {@link SessionState}. Malformed shapes throw `INVALID_ARGUMENT`; unknown or
+ * legacy sections throw `UNSUPPORTED`.
+ */
+export declare function parseSessionState(source: SessionState | string, context?: StorageStateErrorContext): Promise<SessionState>;
+/** Origins in `map` that actually carry at least one entry. */
+export declare function nonEmptyOrigins(map?: Record<string, Record<string, string>>): string[];
+/** True when the state carries at least one origin with ≥1 sessionStorage entry. */
+export declare function hasNonEmptySessionStorage(state: SessionState): boolean;
+/** True when a valid state has no cookie or storage mutations to apply. */
+export declare function isSessionStateEmpty(state: SessionState): boolean;
+/**
+ * Convert a captured cookie into the one canonical restore shape used by every
+ * protocol path. Browser read APIs may report `sameSite: 'default'`, and some
+ * engines report insecure `sameSite: 'none'`; neither can be replayed literally
+ * through all WebDriver cookie commands, so omit sameSite and let the engine
+ * apply its default consistently. `size` is capture-only and is never written.
+ */
+export declare function normalizeCookieForRestore(cookie: CookieInput & {
+    size?: number;
+}): CookieInput;
+//# sourceMappingURL=sessionStateValidation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessionStateValidation.d.ts","sourceRoot":"","sources":["../../src/lib/sessionStateValidation.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,gBAAgB,EAAa,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAQjE,MAAM,WAAW,wBAAwB;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;CACxC;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,wBAAwB,GAAG,SAAS,EAC7C,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE7E;AAkBD,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOpD;AAwGD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,YAAY,GAAG,MAAM,EAC7B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,YAAY,CAAC,CAuCvB;AAED,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,EAAE,CAGtF;AAED,oFAAoF;AACpF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAEtE;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAMhE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,WAAW,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAkB9F"}

package/dist/lib/sessionStateValidation.js

@@ -0,0 +1,223 @@
+/**
+ * Parsing and validation for saved session state, shared by every restore entry
+ * point. The whole state is validated *before* any browser mutation, so a
+ * malformed or unsupported file fails loudly and leaves the browser untouched.
+ *
+ * Unknown or unsupported sections (including the legacy Playwright `origins`
+ * field) are rejected rather than silently ignored — a saved snapshot must mean
+ * exactly what it says.
+ */
+import fs from 'fs/promises';
+import { CraftdriverError, ErrorCode } from './errors.js';
+const KNOWN_SECTIONS = new Set(['cookies', 'localStorage', 'sessionStorage']);
+const COOKIE_FIELDS = new Set([
+    'name', 'value', 'domain', 'path', 'httpOnly', 'secure', 'sameSite', 'expiry', 'size',
+]);
+const SAME_SITE_VALUES = new Set(['strict', 'lax', 'none', 'default']);
+export function storageStateDetail(context, phase, extra) {
+    return {
+        feature: 'storageState',
+        operation: context?.operation ?? 'restore',
+        browserName: context?.browserName ?? 'unknown',
+        protocol: context?.protocol ?? 'unknown',
+        phase,
+        ...extra,
+    };
+}
+/** True for an error already carrying this feature's structured contract. */
+export function isStorageStateError(error) {
+    return CraftdriverError.is(error) && error.detail?.feature === 'storageState';
+}
+function invalid(message, context, extra) {
+    throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, message, {
+        detail: storageStateDetail(context, 'validation', extra),
+    });
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** A canonical http(s) origin: `scheme://host[:port]`, no path or trailing slash. */
+export function isHttpOrigin(origin) {
+    try {
+        const u = new URL(origin);
+        return (u.protocol === 'http:' || u.protocol === 'https:') && u.origin === origin;
+    }
+    catch {
+        return false;
+    }
+}
+function validateOriginMap(section, map, context) {
+    if (map === undefined)
+        return;
+    if (!isPlainObject(map)) {
+        invalid(`state.${section} must be an object keyed by origin`, context, { section });
+    }
+    for (const [origin, entries] of Object.entries(map)) {
+        if (!isHttpOrigin(origin)) {
+            invalid(`state.${section} contains a non-canonical HTTP(S) origin`, context, {
+                section,
+                origin,
+            });
+        }
+        if (!isPlainObject(entries)) {
+            invalid(`state.${section} entries must be maps of string keys to string values`, context, {
+                section,
+                origin,
+            });
+        }
+        for (const value of Object.values(entries)) {
+            if (typeof value !== 'string') {
+                invalid(`state.${section} values must be strings`, context, { section, origin });
+            }
+        }
+    }
+}
+function validateCookies(cookies, context) {
+    if (cookies === undefined)
+        return;
+    if (!Array.isArray(cookies))
+        invalid('state.cookies must be an array', context, { section: 'cookies' });
+    for (const entry of cookies) {
+        if (!isPlainObject(entry)) {
+            invalid('state.cookies entries must be plain objects', context, { section: 'cookies' });
+        }
+        const cookie = entry;
+        // BiDi implementations may attach namespaced, capture-only metadata
+        // (`goog:priority`, etc.). Preserve compatibility with files CraftDriver
+        // previously emitted; normalization drops these fields before mutation.
+        const unknown = Object.keys(cookie).find((key) => !COOKIE_FIELDS.has(key) && !key.includes(':'));
+        if (unknown) {
+            invalid('state.cookies contains an unsupported cookie field', context, {
+                section: 'cookies',
+                field: unknown,
+            });
+        }
+        if (typeof cookie.name !== 'string' || cookie.name.length === 0) {
+            invalid('each cookie needs a non-empty string name', context, { section: 'cookies' });
+        }
+        if (/[^\u0021-\u007E]|[()<>@,;:\\"/\[\]?={}]/.test(cookie.name)) {
+            invalid('cookie name contains characters WebDriver cannot set', context, { section: 'cookies' });
+        }
+        if (typeof cookie.value !== 'string') {
+            invalid('each cookie value must be a string', context, { section: 'cookies' });
+        }
+        if (typeof cookie.domain !== 'string' || cookie.domain.trim().length === 0) {
+            invalid('each cookie needs a non-empty string domain', context, { section: 'cookies' });
+        }
+        if (typeof cookie.domain === 'string' &&
+            (/\s/.test(cookie.domain) || cookie.domain.includes('/') || cookie.domain.endsWith('.'))) {
+            invalid('cookie domain is not a valid host or domain suffix', context, { section: 'cookies' });
+        }
+        if (cookie.path !== undefined &&
+            (typeof cookie.path !== 'string' || !cookie.path.startsWith('/'))) {
+            invalid('cookie path must be a string beginning with "/"', context, { section: 'cookies' });
+        }
+        for (const field of ['httpOnly', 'secure']) {
+            if (cookie[field] !== undefined && typeof cookie[field] !== 'boolean') {
+                invalid(`cookie ${field} must be a boolean`, context, { section: 'cookies', field });
+            }
+        }
+        if (cookie.sameSite !== undefined &&
+            (typeof cookie.sameSite !== 'string' || !SAME_SITE_VALUES.has(cookie.sameSite))) {
+            invalid('cookie sameSite must be strict, lax, none, or default', context, {
+                section: 'cookies',
+            });
+        }
+        if (cookie.expiry !== undefined &&
+            (typeof cookie.expiry !== 'number' || !Number.isFinite(cookie.expiry))) {
+            invalid('cookie expiry must be a finite number', context, { section: 'cookies' });
+        }
+        if (cookie.size !== undefined &&
+            (typeof cookie.size !== 'number' || !Number.isInteger(cookie.size) || cookie.size < 0)) {
+            invalid('cookie size must be a non-negative integer', context, { section: 'cookies' });
+        }
+    }
+}
+/**
+ * Parse `source` (a path or an in-memory object) into a validated
+ * {@link SessionState}. Malformed shapes throw `INVALID_ARGUMENT`; unknown or
+ * legacy sections throw `UNSUPPORTED`.
+ */
+export async function parseSessionState(source, context) {
+    let raw;
+    if (typeof source === 'string') {
+        let text;
+        try {
+            text = await fs.readFile(source, 'utf-8');
+        }
+        catch (err) {
+            invalid(`could not read state file ${source}: ${err.message}`, context);
+        }
+        try {
+            raw = JSON.parse(text);
+        }
+        catch {
+            invalid(`state file ${source} is not valid JSON`, context);
+        }
+    }
+    else {
+        raw = source;
+    }
+    if (!isPlainObject(raw)) {
+        invalid('session state must be a plain JSON object', context);
+    }
+    const obj = raw;
+    for (const key of Object.keys(obj)) {
+        if (!KNOWN_SECTIONS.has(key)) {
+            throw new CraftdriverError(ErrorCode.UNSUPPORTED, `unsupported state section ${JSON.stringify(key)} — craftdriver restores ` +
+                `cookies, localStorage, and sessionStorage only`, { detail: storageStateDetail(context, 'validation', { section: key }) });
+        }
+    }
+    validateCookies(obj.cookies, context);
+    validateOriginMap('localStorage', obj.localStorage, context);
+    validateOriginMap('sessionStorage', obj.sessionStorage, context);
+    return obj;
+}
+/** Origins in `map` that actually carry at least one entry. */
+export function nonEmptyOrigins(map) {
+    if (!map)
+        return [];
+    return Object.keys(map).filter((origin) => map[origin] && Object.keys(map[origin]).length > 0);
+}
+/** True when the state carries at least one origin with ≥1 sessionStorage entry. */
+export function hasNonEmptySessionStorage(state) {
+    return nonEmptyOrigins(state.sessionStorage).length > 0;
+}
+/** True when a valid state has no cookie or storage mutations to apply. */
+export function isSessionStateEmpty(state) {
+    return ((state.cookies?.length ?? 0) === 0 &&
+        nonEmptyOrigins(state.localStorage).length === 0 &&
+        nonEmptyOrigins(state.sessionStorage).length === 0);
+}
+/**
+ * Convert a captured cookie into the one canonical restore shape used by every
+ * protocol path. Browser read APIs may report `sameSite: 'default'`, and some
+ * engines report insecure `sameSite: 'none'`; neither can be replayed literally
+ * through all WebDriver cookie commands, so omit sameSite and let the engine
+ * apply its default consistently. `size` is capture-only and is never written.
+ */
+export function normalizeCookieForRestore(cookie) {
+    const normalized = {
+        name: cookie.name,
+        value: cookie.value,
+        domain: cookie.domain,
+    };
+    if (cookie.path !== undefined)
+        normalized.path = cookie.path;
+    if (cookie.httpOnly !== undefined)
+        normalized.httpOnly = cookie.httpOnly;
+    if (cookie.secure !== undefined)
+        normalized.secure = cookie.secure;
+    if (cookie.expiry !== undefined)
+        normalized.expiry = cookie.expiry;
+    if (cookie.sameSite !== undefined &&
+        cookie.sameSite !== 'default' &&
+        !(cookie.sameSite === 'none' && !cookie.secure)) {
+        normalized.sameSite = cookie.sameSite;
+    }
+    return normalized;
+}
+//# sourceMappingURL=sessionStateValidation.js.map

package/dist/lib/sessionStateValidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionStateValidation.js","sourceRoot":"","sources":["../../src/lib/sessionStateValidation.ts"],"names":[],"mappings":"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"}

package/dist/lib/tracing.d.ts

@@ -97,6 +97,7 @@ export type TraceEvent = {
 };
 export declare class Tracer {
     private browserName;
+    private isInternalContext;
     private browser;
     private conn;
     private startedAtMs;
@@ -113,7 +114,7 @@ export declare class Tracer {
     private actionIndex;
     /** Tracks in-flight screenshot captures so `stop()` can drain them. */
     private pendingCaptures;
-    constructor(browser: Browser, conn: BiDiConnection, browserName: string);
+    constructor(browser: Browser, conn: BiDiConnection, browserName: string, isInternalContext?: (context: string | null | undefined) => boolean);
     get isRunning(): boolean;
     start(opts: TraceStartOptions): Promise<void>;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/lib/tracing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/lib/tracing.ts"],"names":[],"mappings":"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"}

package/dist/lib/tracing.js

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 import { writeVibiumTraceZip } from './vibiumTrace.js';
 export class Tracer {
     browserName;
+    isInternalContext;
     browser;
     conn;
     startedAtMs = 0;
@@ -32,8 +33,9 @@ export class Tracer {
     actionIndex = 0;
     /** Tracks in-flight screenshot captures so `stop()` can drain them. */
     pendingCaptures = [];
-    constructor(browser, conn, browserName) {
+    constructor(browser, conn, browserName, isInternalContext = () => false) {
         this.browserName = browserName;
+        this.isInternalContext = isInternalContext;
         this.browser = browser;
         this.conn = conn;
     }
@@ -86,6 +88,9 @@ export class Tracer {
         if (consoleOn) {
             this.unsubs.push(this.conn.on('log.entryAdded', (params) => {
                 const p = params;
+                const source = (p.source ?? {});
+                if (this.isInternalContext(source.context))
+                    return;
                 const text = String(p.text ?? '');
                 if (p.type === 'console') {
                     this.push({ type: 'console', level: String(p.level ?? 'info'), text });
@@ -100,6 +105,8 @@ export class Tracer {
         if (networkOn) {
             this.unsubs.push(this.conn.on('network.beforeRequestSent', (params) => {
                 const p = params;
+                if (this.isInternalContext(p.context))
+                    return;
                 const req = (p.request ?? {});
                 this.push({
                     type: 'request',
@@ -110,6 +117,8 @@ export class Tracer {
             }));
             this.unsubs.push(this.conn.on('network.responseCompleted', (params) => {
                 const p = params;
+                if (this.isInternalContext(p.context))
+                    return;
                 const req = (p.request ?? {});
                 const res = (p.response ?? {});
                 const ev = {
@@ -128,6 +137,8 @@ export class Tracer {
         }
         this.unsubs.push(this.conn.on('browsingContext.navigationStarted', (params) => {
             const p = params;
+            if (this.isInternalContext(p.context))
+                return;
             this.push({
                 type: 'navigation',
                 url: String(p.url ?? ''),

package/dist/lib/tracing.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../src/lib/tracing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../src/lib/tracing.ts"],"names":[],"mappings":"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"}

package/docs/agents.md

@@ -1,24 +1,37 @@
 # AI Agent Guide
 
-CraftDriver ships agent-facing tooling in the npm package. You can use the library directly, drive the browser from the shell, expose tools through MCP, or drop assistant rules into a project.
+CraftDriver's recommended agent surface is the CLI plus a project-local skill.
+The agent explores the running application, learns its DOM and accessibility
+structure, validates durable selectors, and then writes and runs ordinary
+CraftDriver tests. MCP is optional.
 
-## Which Surface Should I Use?
+## Install safely
 
-| Agent environment          | Best surface       | Why                                                                              |
-| -------------------------- | ------------------ | -------------------------------------------------------------------------------- |
-| Shell-capable coding agent | CLI                | Simple commands, persistent daemon, JSON output when piped.                      |
-| MCP-aware host             | MCP server         | Typed tools, compact accessibility snapshots, artifact spilling for screenshots. |
-| Code-writing assistant     | `craftdriver init` | Project rules teach selector preference, auto-waiting, and error-code handling.  |
-| Custom orchestrator        | Skill pack         | Small always-on `SKILL.md` with deeper references loaded on demand.              |
+From a project that already has a `package.json`:
 
-## CLI
+```bash
+npm install --save-dev craftdriver
+npx craftdriver init codex
+```
+
+This installs `.agents/skills/craftdriver/` with an ownership manifest. It does
+not read or change `AGENTS.md`, `CLAUDE.md`, Copilot instructions, Cursor rules,
+`GEMINI.md`, or `.codex/config.toml`. It refuses user-edited, unowned, extra, or
+symlinked destination content instead of overwriting it.
 
-The CLI is good for agents that can run shell commands.
+Preview without writes:
+
+```bash
+npx craftdriver init codex --dry-run
+```
+
+## Explore, then write the test
 
 ```bash
 npx craftdriver daemon start
 npx craftdriver go http://127.0.0.1:8080/login.html
 npx craftdriver snapshot
+npx craftdriver find 'label=Username' --all
 npx craftdriver fill 'label=Username' alice
 npx craftdriver fill 'label=Password' hunter2
 npx craftdriver click 'role=button[name=Sign in]'
@@ -26,67 +39,49 @@ npx craftdriver text '#result'
 npx craftdriver daemon stop
 ```
 
-State survives between calls while the daemon is running, so an agent can explore, act, inspect, and refine.
-
-Read the full [CLI reference](./cli.md).
-
-## MCP Server
+The daemon keeps the page and cookies between commands. Snapshot refs are
+ephemeral exploration state in the current release: take a fresh snapshot
+immediately before one ref action, and never copy `ref=eN` into a test. Validate
+role/name, label, test ID, text, or stable CSS selectors against the live page,
+then use those durable locators in test source.
 
-MCP-aware hosts can use `craftdriver mcp`.
+The daemon uses a Unix socket and is not available on Windows. Windows agents
+should use the optional MCP server for a persistent session, or run the whole
+flow as one `craftdriver --ephemeral` script.
 
-```bash
-claude mcp add craftdriver -- npx -y craftdriver mcp
-```
-
-```jsonc
-{
-  "mcpServers": {
-    "craftdriver": {
-      "command": "npx",
-      "args": ["-y", "craftdriver", "mcp"],
-    },
-  },
-}
-```
-
-Mutating tools return compact accessibility snapshot diffs, so the agent can see what changed without a separate read. Large artifacts such as screenshots are written to disk instead of inlined into model context.
+The installed `workflow.md` guides the full loop: inspect existing project test
+conventions, explore, validate selectors, write the smallest test, run the
+focused command, and debug from fresh browser evidence.
 
-Read the full [MCP reference](./mcp.md).
+Read the [CLI reference](./cli.md) for all current commands.
 
-## Assistant Bootstrap Files
+## Optional MCP
 
-Use `craftdriver init` inside a project that uses CraftDriver:
+CLI + Skill does not require MCP. For a host that prefers structured tool
+calls, print the local project-pinned configuration:
 
 ```bash
-npx craftdriver init agents
-npx craftdriver init copilot
-npx craftdriver init claude
-npx craftdriver init cursor
-npx craftdriver init gemini
-npx craftdriver init all
+npx craftdriver init codex --mcp
 ```
 
-The generated files tell assistants to:
+The command prints:
 
-- prefer semantic selectors before brittle CSS
-- rely on auto-waiting instead of sleeps
-- inspect stable `CraftdriverError.code` values
-- use the CLI or MCP server for live browser work
-- keep test code aligned with the public TypeScript API
-
-## Skill Pack
-
-The npm tarball includes a tiered skill pack under `skills/craftdriver/`:
+```toml
+[mcp_servers.craftdriver]
+command = "npx"
+args = ["--no-install", "craftdriver", "mcp"]
+```
 
-| File            | Purpose                                                                                |
-| --------------- | -------------------------------------------------------------------------------------- |
-| `SKILL.md`      | Always-on rules and routing, kept small for model context.                             |
-| `cheatsheet.md` | Fast command and API reference for tests.                                              |
-| `patterns.md`   | Worked recipes such as login, uploads, network waits, a11y, tracing, and virtual time. |
-| `cli.md`        | Agent-facing CLI reference.                                                            |
+Add it manually to the host configuration. CraftDriver never reads or writes
+that configuration. See the [MCP reference](./mcp.md) for the current optional
+tool surface and protocol bounds.
 
-Point compatible agents at:
+## Installed skill files
 
-```text
-node_modules/craftdriver/skills/craftdriver/SKILL.md
-```
+| File | Purpose |
+| --- | --- |
+| `SKILL.md` | Short browser-to-test rules and routing. |
+| `workflow.md` | Exploration, selector validation, test authoring, and debugging loop. |
+| `cli.md` | Current shell command reference for agent exploration. |
+| `cheatsheet.md` | Public TypeScript API reference for writing tests. |
+| `patterns.md` | Focused library recipes loaded on demand. |

package/docs/api-reference.md

@@ -183,5 +183,6 @@ Exports that are public but not yet assigned to a feature group.
 | `PageMatcher` | type | Selects a top-level page by `url` and/or `title` for {@link Browser.waitForPage}. A string matches as a substring; a `RegExp` is tested. When both fields are given, both must match. | [browser-api](browser-api.md) |
 | `RemoteAuth` | type | — | — |
 | `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: **93**.
+Total exports: **94**.

package/docs/browser-api.md

@@ -29,7 +29,7 @@ const browser = await Browser.launch({
 |--------|------|---------|-------------|
 | `browserName` | `'chrome' \| 'chromium' \| 'firefox' \| 'safari'`; any non-empty `string` remotely | `'chrome'` | Local browser to launch or provider-facing remote browser name |
 | `enableBiDi` | `boolean` | browsers: `true`; Electron: `false` | Use WebDriver BiDi. Electron requires an explicit opt-in because negotiation resets its initial renderer to `about:blank`. |
-| `storageState` | `string` | — | Path to a session-state JSON file to load on startup |
+| `storageState` | `string \| SessionState` | — | Native session-state path/object. Full cookies + multi-origin localStorage on supported BiDi; non-empty state is rejected at Classic launch. |
 | `mobileEmulation` | `MobileEmulation \| DeviceName` | — | Mobile device emulation settings (Chrome/Chromium only) |
 | `downloadsDir` | `string` | temp dir | Directory where downloaded files are saved |
 | `browserPath` | `string` | — | Custom browser binary to launch (Chrome/Chromium/Firefox) — see [Driver Configuration → Browser Binary Configuration](./driver-configuration.md#browser-binary-configuration) |
@@ -334,9 +334,20 @@ await popup.waitForLoadState('load');
 const heading = await popup.find('h1').text();
 console.log(heading);
 
-await popup.evaluate(() => {
-  window.close();
-});
+// Close it. Prefer this over `popup.evaluate(() => window.close())`, which
+// leaves no window focused — every later command then fails with
+// "no such window". `close()` switches to a surviving page for you.
+await popup.close();
+```
+
+Use `page.activate()` to make a page the target of browser-level helpers.
+Most page methods switch to their window and switch back, so they never
+disturb `browser.activePage()`; `activate()` is the deliberate exception:
+
+```ts
+const [, second] = await browser.pages();
+await second.activate();
+await browser.click('#confirm');   // acts on the second tab
 ```
 
 > **Note.** `browser.openPage()` requires BiDi (the default). In Classic
@@ -378,8 +389,17 @@ await browser.saveState('./session.json');
 
 // Load session from file
 await browser.loadState('./session.json');
+
+// Or use an in-memory SessionState object
+await browser.loadState(await browser.storage.getState());
 ```
 
+On Chrome/Chromium and Firefox BiDi, launch and `browser.loadState()` restore
+cookies plus multi-origin localStorage before the first real navigation. In
+Classic mode, launch rejects non-empty state; navigate to the sole origin, call
+`browser.loadState()`, then reload. See
+[Session Management](./session-management.md#browser-and-transport-support).
+
 ## Evaluate
 
 Run JavaScript in the page and get the result back. Useful for reading app state,