craftdriver 0.2.1 → 1.0.0

package/dist/lib/timing.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Centralized timing constants: poll intervals, timeouts, fixed delays, and
+ * retry policy. Kept in one place so they are easy to find and tune rather than
+ * scattered as magic numbers across the codebase. All values are milliseconds.
+ *
+ * This module intentionally has no imports so any file can depend on it without
+ * risking an import cycle.
+ */
+/**
+ * Base cadence for all auto-wait retry loops. Kept short so a condition that
+ * flips true mid-interval is noticed quickly rather than up to a full interval
+ * late. The first check of every loop runs immediately, so conditions that are
+ * already satisfied never pay it — it only affects genuine waits. Round trips
+ * to a local driver are cheap (~a few ms), so polling this often is fine.
+ *
+ * Used for element visibility/existence waits and `Locator` resolution.
+ */
+export declare const DEFAULT_POLL_INTERVAL_MS = 25;
+/**
+ * How often `expect(...)` assertion retries re-check their matcher (text,
+ * value, class, …). Same responsive cadence as {@link DEFAULT_POLL_INTERVAL_MS}
+ * so an assertion that becomes true shortly after a failed check passes almost
+ * immediately instead of waiting out a long interval.
+ */
+export declare const ASSERTION_POLL_INTERVAL_MS = 25;
+/** Poll interval for the driver service's `/status` readiness check. */
+export declare const DRIVER_READINESS_POLL_INTERVAL_MS = 25;
+/**
+ * Poll interval for state that changes at process/OS speed rather than DOM
+ * speed: Classic `document.readyState`, the Classic `waitForPage`
+ * window-handle fallback, and download-file polling. Kept at the same 25ms
+ * cadence for responsiveness — these checks (a script eval, a window-handle
+ * list, an `fs.stat`) are cheap enough to run this often.
+ */
+export declare const STATE_POLL_INTERVAL_MS = 25;
+/**
+ * Per-attempt cap on how long one `expect(...)` retry waits for the element to
+ * *exist* before looping back to re-run the whole matcher. This does NOT govern
+ * how fast an assertion re-checks — the matcher is re-evaluated every
+ * {@link ASSERTION_POLL_INTERVAL_MS}, and an element that already exists returns
+ * from the existence wait immediately. Existence itself is polled at
+ * {@link DEFAULT_POLL_INTERVAL_MS} inside this window, so a slow-to-appear
+ * element is still caught within ~25ms; the cap only bounds a single attempt so
+ * the outer loop keeps its cadence and honours the overall timeout.
+ */
+export declare const ASSERTION_INNER_WAIT_CAP_MS = 250;
+/** Default timeout for element interactions and waits (click, fill, find, …). */
+export declare const DEFAULT_ELEMENT_TIMEOUT_MS = 5000;
+/**
+ * Default timeout for navigation and network/event waits (navigateTo,
+ * waitForRequest/Response, log waits, download waits).
+ */
+export declare const DEFAULT_NAVIGATION_TIMEOUT_MS = 30000;
+/** Default timeout for the BiDi WebSocket connect and for each BiDi command. */
+export declare const BIDI_TIMEOUT_MS = 30000;
+/** How long to wait for the driver service to report ready after spawning. */
+export declare const DRIVER_READINESS_TIMEOUT_MS = 5000;
+/**
+ * Readiness deadline for geckodriver specifically — it takes longer than
+ * chromedriver to spin up Marionette and start listening.
+ */
+export declare const FIREFOX_READINESS_TIMEOUT_MS = 15000;
+/** Timeout for the `<driver|browser> --version` capability probe spawn. */
+export declare const VERSION_PROBE_TIMEOUT_MS = 5000;
+/** Timeout for the `which` / `where` PATH-probe spawn. */
+export declare const PATH_PROBE_TIMEOUT_MS = 2000;
+/** Best-effort settle used as the Classic fallback for `networkidle`. */
+export declare const NETWORK_IDLE_SETTLE_MS = 500;
+/**
+ * Pause between `driver.quit()` and stopping the driver service, giving the
+ * browser time to release its ports (notably Firefox's BiDi WebSocket) before a
+ * subsequent launch reuses them; without it a fresh launch can hit a 404.
+ */
+export declare const PORT_RELEASE_DELAY_MS = 500;
+/** Delay before a BiDi connection auto-reconnect attempt. */
+export declare const BIDI_RECONNECT_DELAY_MS = 1000;
+/**
+ * BiDi connect retries. Firefox may not have finished binding its BiDi
+ * WebSocket right after the session is created; back off linearly between
+ * attempts (delay = {@link BIDI_CONNECT_BACKOFF_STEP_MS} × attempt).
+ */
+export declare const BIDI_CONNECT_MAX_ATTEMPTS = 8;
+export declare const BIDI_CONNECT_BACKOFF_STEP_MS = 300;
+/**
+ * WebDriver session-creation retries. Firefox's Marionette interface can lag
+ * geckodriver reporting healthy, so retry with linear backoff (delay =
+ * {@link SESSION_CREATE_BACKOFF_STEP_MS} × attempt); Chrome is reliable enough
+ * to need a single attempt.
+ */
+export declare const FIREFOX_SESSION_MAX_ATTEMPTS = 4;
+export declare const CHROME_SESSION_MAX_ATTEMPTS = 1;
+export declare const SESSION_CREATE_BACKOFF_STEP_MS = 500;
+/**
+ * `evaluate()` retries on a transient "execution contexts cleared" BiDi error.
+ * A Classic-first navigate returns at `readyState === 'complete'`, which is not
+ * 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).
+ */
+export declare const EVAL_REALM_RETRY_ATTEMPTS = 3;
+export declare const EVAL_REALM_RETRY_DELAY_MS = 25;
+//# sourceMappingURL=timing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../src/lib/timing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,wEAAwE;AACxE,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAI/C,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD,gFAAgF;AAChF,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC,8EAA8E;AAC9E,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAI3C,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAI7C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAC9C,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAC7C,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,yBAAyB,KAAK,CAAC"}

package/dist/lib/timing.js

@@ -0,0 +1,108 @@
+/**
+ * Centralized timing constants: poll intervals, timeouts, fixed delays, and
+ * retry policy. Kept in one place so they are easy to find and tune rather than
+ * scattered as magic numbers across the codebase. All values are milliseconds.
+ *
+ * This module intentionally has no imports so any file can depend on it without
+ * risking an import cycle.
+ */
+// ── Auto-wait / retry poll intervals ─────────────────────────────────────────
+/**
+ * Base cadence for all auto-wait retry loops. Kept short so a condition that
+ * flips true mid-interval is noticed quickly rather than up to a full interval
+ * late. The first check of every loop runs immediately, so conditions that are
+ * already satisfied never pay it — it only affects genuine waits. Round trips
+ * to a local driver are cheap (~a few ms), so polling this often is fine.
+ *
+ * Used for element visibility/existence waits and `Locator` resolution.
+ */
+export const DEFAULT_POLL_INTERVAL_MS = 25;
+/**
+ * How often `expect(...)` assertion retries re-check their matcher (text,
+ * value, class, …). Same responsive cadence as {@link DEFAULT_POLL_INTERVAL_MS}
+ * so an assertion that becomes true shortly after a failed check passes almost
+ * immediately instead of waiting out a long interval.
+ */
+export const ASSERTION_POLL_INTERVAL_MS = 25;
+/** Poll interval for the driver service's `/status` readiness check. */
+export const DRIVER_READINESS_POLL_INTERVAL_MS = 25;
+/**
+ * Poll interval for state that changes at process/OS speed rather than DOM
+ * speed: Classic `document.readyState`, the Classic `waitForPage`
+ * window-handle fallback, and download-file polling. Kept at the same 25ms
+ * cadence for responsiveness — these checks (a script eval, a window-handle
+ * list, an `fs.stat`) are cheap enough to run this often.
+ */
+export const STATE_POLL_INTERVAL_MS = 25;
+/**
+ * Per-attempt cap on how long one `expect(...)` retry waits for the element to
+ * *exist* before looping back to re-run the whole matcher. This does NOT govern
+ * how fast an assertion re-checks — the matcher is re-evaluated every
+ * {@link ASSERTION_POLL_INTERVAL_MS}, and an element that already exists returns
+ * from the existence wait immediately. Existence itself is polled at
+ * {@link DEFAULT_POLL_INTERVAL_MS} inside this window, so a slow-to-appear
+ * element is still caught within ~25ms; the cap only bounds a single attempt so
+ * the outer loop keeps its cadence and honours the overall timeout.
+ */
+export const ASSERTION_INNER_WAIT_CAP_MS = 250;
+// ── Default timeouts ─────────────────────────────────────────────────────────
+/** Default timeout for element interactions and waits (click, fill, find, …). */
+export const DEFAULT_ELEMENT_TIMEOUT_MS = 5_000;
+/**
+ * Default timeout for navigation and network/event waits (navigateTo,
+ * waitForRequest/Response, log waits, download waits).
+ */
+export const DEFAULT_NAVIGATION_TIMEOUT_MS = 30_000;
+/** Default timeout for the BiDi WebSocket connect and for each BiDi command. */
+export const BIDI_TIMEOUT_MS = 30_000;
+/** How long to wait for the driver service to report ready after spawning. */
+export const DRIVER_READINESS_TIMEOUT_MS = 5_000;
+/**
+ * Readiness deadline for geckodriver specifically — it takes longer than
+ * chromedriver to spin up Marionette and start listening.
+ */
+export const FIREFOX_READINESS_TIMEOUT_MS = 15_000;
+/** Timeout for the `<driver|browser> --version` capability probe spawn. */
+export const VERSION_PROBE_TIMEOUT_MS = 5_000;
+/** Timeout for the `which` / `where` PATH-probe spawn. */
+export const PATH_PROBE_TIMEOUT_MS = 2_000;
+// ── Fixed delays ─────────────────────────────────────────────────────────────
+/** Best-effort settle used as the Classic fallback for `networkidle`. */
+export const NETWORK_IDLE_SETTLE_MS = 500;
+/**
+ * Pause between `driver.quit()` and stopping the driver service, giving the
+ * browser time to release its ports (notably Firefox's BiDi WebSocket) before a
+ * subsequent launch reuses them; without it a fresh launch can hit a 404.
+ */
+export const PORT_RELEASE_DELAY_MS = 500;
+/** Delay before a BiDi connection auto-reconnect attempt. */
+export const BIDI_RECONNECT_DELAY_MS = 1_000;
+// ── Retry policy ─────────────────────────────────────────────────────────────
+/**
+ * BiDi connect retries. Firefox may not have finished binding its BiDi
+ * WebSocket right after the session is created; back off linearly between
+ * attempts (delay = {@link BIDI_CONNECT_BACKOFF_STEP_MS} × attempt).
+ */
+export const BIDI_CONNECT_MAX_ATTEMPTS = 8;
+export const BIDI_CONNECT_BACKOFF_STEP_MS = 300;
+/**
+ * WebDriver session-creation retries. Firefox's Marionette interface can lag
+ * geckodriver reporting healthy, so retry with linear backoff (delay =
+ * {@link SESSION_CREATE_BACKOFF_STEP_MS} × attempt); Chrome is reliable enough
+ * to need a single attempt.
+ */
+export const FIREFOX_SESSION_MAX_ATTEMPTS = 4;
+export const CHROME_SESSION_MAX_ATTEMPTS = 1;
+export const SESSION_CREATE_BACKOFF_STEP_MS = 500;
+/**
+ * `evaluate()` retries on a transient "execution contexts cleared" BiDi error.
+ * A Classic-first navigate returns at `readyState === 'complete'`, which is not
+ * 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).
+ */
+export const EVAL_REALM_RETRY_ATTEMPTS = 3;
+export const EVAL_REALM_RETRY_DELAY_MS = 25;
+//# sourceMappingURL=timing.js.map

package/dist/lib/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/lib/timing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAE7C,wEAAwE;AACxE,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAE/C,gFAAgF;AAEhF,iFAAiF;AACjF,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAC;AAEhD;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAC;AAEpD,gFAAgF;AAChF,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AAEtC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEjD;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC;AAEnD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAE9C,0DAA0D;AAC1D,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAE3C,gFAAgF;AAEhF,yEAAyE;AACzE,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC,6DAA6D;AAC7D,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAE7C,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAC3C,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAC9C,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAC7C,MAAM,CAAC,MAAM,8BAA8B,GAAG,GAAG,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAC3C,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../src/lib/wait.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7C,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IAMtB,OAAO,CAAC,MAAM;IALhB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAC,CAAS;gBAGlB,MAAM,EAAE,MAAM,EACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,WAAW,EACvC,UAAU,CAAC,EAAE,MAAM;IAYf,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CA8BtE;AAOD,eAAO,MAAM,KAAK;8BACU,EAAE,MAAY,QAAQ,MAAM;6BAI7B,EAAE,MAAY,QAAQ,MAAM;gCASzB,EAAE,MAAY,QAAQ,MAAM;+BAS7B,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;kCAUtC,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;CAaxE,CAAC"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../src/lib/wait.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAI7C,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IAMtB,OAAO,CAAC,MAAM;IALhB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAC,CAAS;gBAGlB,MAAM,EAAE,MAAM,EACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,WAAW,EACvC,UAAU,CAAC,EAAE,MAAM;IAYf,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CA8BtE;AAOD,eAAO,MAAM,KAAK;8BACU,EAAE,MAAY,QAAQ,MAAM;6BAI7B,EAAE,MAAY,QAAQ,MAAM;gCASzB,EAAE,MAAY,QAAQ,MAAM;+BAS7B,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;kCAUtC,EAAE,GAAG,UAAU,MAAY,QAAQ,MAAM;CAaxE,CAAC"}

package/dist/lib/wait.js

@@ -1,5 +1,6 @@
 import { WebElement } from './webelement.js';
 import { CraftdriverError, ErrorCode } from './errors.js';
+import { DEFAULT_POLL_INTERVAL_MS, DEFAULT_ELEMENT_TIMEOUT_MS } from './timing.js';
 export class WebDriverWait {
     driver;
     timeoutMs;
@@ -8,13 +9,13 @@ export class WebDriverWait {
     constructor(driver, timeoutOrOptions, intervalMs) {
         this.driver = driver;
         if (typeof timeoutOrOptions === 'object') {
-            this.timeoutMs = timeoutOrOptions?.timeout ?? 5000;
-            this.intervalMs = timeoutOrOptions?.interval ?? 100;
+            this.timeoutMs = timeoutOrOptions?.timeout ?? DEFAULT_ELEMENT_TIMEOUT_MS;
+            this.intervalMs = timeoutOrOptions?.interval ?? DEFAULT_POLL_INTERVAL_MS;
             this.timeoutMsg = timeoutOrOptions?.timeoutMsg;
         }
         else {
-            this.timeoutMs = timeoutOrOptions ?? 5000;
-            this.intervalMs = intervalMs ?? 100;
+            this.timeoutMs = timeoutOrOptions ?? DEFAULT_ELEMENT_TIMEOUT_MS;
+            this.intervalMs = intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         }
     }
     async until(condition, message) {

package/dist/lib/wait.js.map

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

package/docs/bidi-features.md

@@ -19,8 +19,8 @@ in Classic mode.
 |---|---|---|
 | Network mocking / interception | [`browser.network.*`](#network-mocking) | yes |
 | Console & error log capture | [`browser.logs.*`](#console--error-logs) | yes |
-| `waitForLoadState('load' \| 'domcontentloaded' \| 'networkidle')` | `browser.waitForLoadState()` | yes |
-| `navigateTo(..., { waitUntil })` real load events | `browser.navigateTo()` | yes |
+| `waitForLoadState('load' \| 'domcontentloaded' \| 'networkidle')` | `browser.waitForLoadState()` | no — event-driven over BiDi, polls `document.readyState` in Classic |
+| `navigateTo(..., { waitUntil })` real load events | `browser.navigateTo()` | no — event-driven over BiDi, best-effort settle timer in Classic |
 | `waitForRequest()` / `waitForResponse()` | `browser.waitForRequest()` / `waitForResponse()` | yes |
 | Init scripts (run before any page script) | `browser.addInitScript()` | yes |
 | Open new tab / popup | `browser.openPage()` | yes |
@@ -229,6 +229,14 @@ waitForResponse("**/api/users") timed out after 30000ms
 
 Access browser console output and JavaScript errors via `browser.logs`.
 
+> **Capture is lazy by default.** Craftdriver only subscribes to log events
+> the first time you touch `browser.logs.onLog()` / `.onConsole()` /
+> `.onError()` / `.on()` / `.waitForConsole()` / `.waitForError()` — messages
+> emitted before that first touch are not captured, so a bare
+> `browser.logs.getMessages()` right after `navigateTo()` can return `[]`.
+> Either arm a listener before the action that logs, or launch with
+> `Browser.launch({ captureLogs: true })` to start capture immediately.
+
 ### getMessages()
 
 Get all console messages.

package/docs/browser-api.md

@@ -28,7 +28,8 @@ const browser = await Browser.launch({
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `browserName` | `'chrome' \| 'chromium' \| 'firefox'` | `'chrome'` | Browser to launch |
-| `enableBiDi` | `boolean` | `true` | Use WebDriver BiDi. Set `false` only when running against a browser that does not support it. |
+| `enableBiDi` | `boolean` | `true` | Use WebDriver BiDi. Set `false` only when running against a browser that does not support it — every BiDi-only feature then throws a `requires BiDi` error if called. |
+| `captureLogs` | `boolean` | `false` | Start console/error log capture immediately at launch instead of lazily on first `browser.logs`/`onConsole`/`onError`/`waitForConsole` touch. See [BiDi Features — Console & Error Logs](./bidi-features.md#console--error-logs). |
 | `storageState` | `string` | — | Path to a session-state JSON file to load on startup |
 | `mobileEmulation` | `MobileEmulation \| DeviceName` | — | Mobile device emulation settings (Chrome/Chromium only) |
 | `downloadsDir` | `string` | temp dir | Directory where downloaded files are saved |

package/docs/browser-context.md

@@ -333,13 +333,12 @@ Requests from other contexts are not seen.
 
 - `pattern`: a URL substring, a `RegExp`, or a glob (`*` matches any
   run of non-`/` characters; `**` matches any run of characters).
-- `handler({ request, fulfill, continue: cont, abort })`: called for
-  every matched request. Must call exactly one of:
-  - `fulfill({ status?, headers?, contentType?, body? })` — reply
-    immediately without hitting the network.
-  - `continue({ url?, method?, headers?, postData? })` — let the
-    request go through, optionally rewritten.
-  - `abort(reason?)` — fail the request.
+- `handler(request)`: called for every matched request, receiving an
+  `InterceptedRequest` (`url`, `method`, `headers`, `postData`, …).
+  Return a `MockResponse` (`{ status?, statusText?, headers?, body? }`)
+  to fulfill the request immediately without hitting the network, or
+  return/resolve `void` to let it continue to the network unmodified.
+  The handler may be async.
 
 ```typescript
 // Real-world: serve a fixture to one tenant, let the real API answer
@@ -347,13 +346,11 @@ Requests from other contexts are not seen.
 const admin = await browser.newContext();
 const guest = await browser.newContext();
 
-await admin.route('**/api/users', async ({ fulfill }) => {
-  await fulfill({
-    status: 200,
-    contentType: 'application/json',
-    body: JSON.stringify([{ id: 1, role: 'admin', name: 'Alice' }]),
-  });
-});
+await admin.route('**/api/users', (request) => ({
+  status: 200,
+  headers: { 'content-type': 'application/json' },
+  body: [{ id: 1, role: 'admin', name: 'Alice' }],
+}));
 
 const aPage = await admin.newPage({ url: '/users' });
 const gPage = await guest.newPage({ url: '/users' });

package/docs/dialogs.md

@@ -11,6 +11,13 @@ or the automation handles them.
 > failures so unexpected dialogs surface as broken tests rather than
 > passing tests against a stuck browser.
 
+> **`waitForDialog()` and `onDialog()` require BiDi.** Both are built on
+> BiDi's dialog-open event; under Classic WebDriver (`enableBiDi: false`)
+> `onDialog()` silently registers a no-op and `waitForDialog()` will simply
+> time out rather than error, since Classic has no push notification for
+> "a dialog opened." Use the imperative `acceptDialog()` / `dismissDialog()`
+> / `getDialogMessage()` API instead if you're running Classic-only.
+
 You handle a dialog one of three ways, depending on the shape of the
 test:
 
@@ -89,9 +96,13 @@ await browser.dismissDialog();       // click Cancel / close
 const text = await browser.getDialogMessage();
 ```
 
-These map directly onto W3C Classic alert endpoints
-(`/alert/accept`, `/alert/dismiss`, `/alert/text`) and throw if no
-dialog is currently open.
+`acceptDialog` / `dismissDialog` use BiDi's `handleUserPrompt` when the
+browser was launched with BiDi (the default), falling back to the W3C
+Classic alert endpoints (`/alert/accept`, `/alert/dismiss`) only when
+`enableBiDi: false`. `getDialogMessage` always uses the Classic
+`/alert/text` endpoint — BiDi only surfaces the dialog message via the
+`userPromptOpened` event, not a query, so there's nothing to query outside
+`onDialog`/`waitForDialog`. All four throw if no dialog is currently open.
 
 ## `Dialog` interface
 

package/docs/driver-configuration.md

@@ -7,13 +7,25 @@ Craftdriver resolves the WebDriver binary through a chain — first match wins:
 | 1 | `driverPath` option in `Browser.launch()` |
 | 2 | `CRAFTDRIVER_CHROMEDRIVER_PATH` / `CRAFTDRIVER_GECKODRIVER_PATH` env var |
 | 3 | `CRAFTDRIVER_DRIVER_PATH` env var (generic fallback for either browser) |
-| 4 | `chromedriver` / `geckodriver` in `node_modules/.bin` |
-| 5 | `chromedriver` / `geckodriver` on `PATH` |
-| 6 | **Auto-download from Chrome for Testing / GitHub** ← the zero-config default |
+| 4 | Legacy/Selenium-compatible env vars: `CHROMEDRIVER_PATH`, `SE_CHROMEDRIVER` (chromedriver) or `GECKODRIVER_PATH`, `GECKODRIVER_FILEPATH`, `SE_GECKODRIVER` (geckodriver) |
+| 5 | **Cached auto-resolution** — the path a previous auto-resolve settled on, reused within the `CRAFTDRIVER_DRIVER_TTL` window |
+| 6 | `chromedriver` / `geckodriver` in `node_modules/.bin` |
+| 7 | `chromedriver` / `geckodriver` on `PATH` |
+| 8 | **Auto-download from Chrome for Testing / GitHub** ← the zero-config default |
 
-Downloaded drivers are cached in `~/.cache/craftdriver` and reused as long as
-your browser version doesn't change. Only the driver binary is downloaded,
-never the browser itself.
+Downloaded drivers are cached in `~/.cache/craftdriver`, and so is the
+*resolution itself* — which driver path to use. Within the
+`CRAFTDRIVER_DRIVER_TTL` window (default 24 h), craftdriver reuses the
+resolved path directly and skips the system-browser probes it would
+otherwise run on **every** launch: launching the browser binary just to read
+its version string, and a `PATH` lookup. Both are blocking calls, so caching
+the resolution measurably speeds up launch — most noticeably when several
+browsers start in parallel (see [Performance](#performance)). After the TTL
+expires, or if Chrome reports that the cached chromedriver is for the wrong
+major version after a browser upgrade, the driver is re-resolved and
+re-downloaded if needed. Only the driver binary is ever downloaded, never the
+browser itself. Explicit configuration (steps 1–4) always takes precedence over
+the cache.
 
 ## Environment variables
 
@@ -24,7 +36,7 @@ never the browser itself.
 | `CRAFTDRIVER_DRIVER_PATH` | Generic fallback path (either browser) | — |
 | `CRAFTDRIVER_CACHE_DIR` | Directory for cached driver downloads | `~/.cache/craftdriver` |
 | `CRAFTDRIVER_OFFLINE` | Set to `1` to disable all network calls | — |
-| `CRAFTDRIVER_DRIVER_TTL` | Geckodriver freshness check interval (seconds) | `86400` (24 h) |
+| `CRAFTDRIVER_DRIVER_TTL` | Driver-resolution cache lifetime, in seconds (both browsers). `0` disables the cache | `86400` (24 h) |
 
 ## Examples
 
@@ -35,7 +47,7 @@ CRAFTDRIVER_CHROMEDRIVER_PATH=/usr/bin/chromedriver npm test
 # Pin a specific geckodriver
 CRAFTDRIVER_GECKODRIVER_PATH=/usr/local/bin/geckodriver npm test
 
-# Never make a network call (requires a local driver to exist in steps 1–5)
+# Never make a network call (requires a local driver to exist in steps 1–7)
 CRAFTDRIVER_OFFLINE=1 npm test
 
 # Change the cache location
@@ -45,6 +57,112 @@ CRAFTDRIVER_CACHE_DIR=/tmp/my-driver-cache npm test
 CRAFTDRIVER_DRIVER_TTL=3600 npm test
 ```
 
+## Performance
+
+Most of the time `Browser.launch()` spends is the browser process starting up
+(that's the same for WebDriver Classic and BiDi and there's little a client
+library can do about it). The part craftdriver *does* control is resolving and
+starting the driver, and it's tuned to stay out of the way:
+
+- **Driver resolution is cached** (see above). Without a cache, resolving a
+  chromedriver means launching your Chrome binary just to read its version
+  string — a blocking call of a few hundred milliseconds on *every* launch.
+  The TTL cache skips that after the first launch.
+- **Point at a driver explicitly to skip resolution entirely.** If you set
+  `CRAFTDRIVER_CHROMEDRIVER_PATH` / `CRAFTDRIVER_GECKODRIVER_PATH` (or pass
+  `chromeService: new ChromeService({ binaryPath })`), craftdriver uses it
+  directly — no version detection, no `PATH` lookup, no cache read. This is
+  the fastest and most deterministic option and is recommended for CI:
+
+  ```bash
+  CRAFTDRIVER_CHROMEDRIVER_PATH=/opt/chromedriver/chromedriver npm test
+  ```
+
+- **Parallel runs benefit the most.** The resolution work that the cache (or an
+  explicit path) removes was synchronous and blocked the event loop, so it
+  serialized when several browsers were launched at once. Removing it lets
+  concurrent `Browser.launch()` calls overlap their startup (measured ~17–20%
+  faster wall time for a batch of concurrent launches).
+
+### Concurrency and oversubscription
+
+Once resolution is out of the way, the rest of launch time is the browser
+process starting — and that is **CPU-bound**. Starting many browsers at once
+on a machine with fewer CPU cores oversubscribes the CPU, and each browser's
+startup slows down roughly in proportion. On an 8-core machine, for example, a
+single launch is ~2s but 20 simultaneous launches take ~25s *each* (they still
+finish sooner in aggregate than launching serially, just with diminishing
+returns). This is not a craftdriver limitation — it's the browser competing for
+CPU — and no client-side change removes it.
+
+Practical guidance for parallel test suites (e.g. Vitest / Jest / Playwright
+Test): **cap worker concurrency at roughly the number of CPU cores.** More
+workers than cores mostly adds launch latency, and a launch that is merely slow
+under heavy load can trip a short per-test/hook timeout and look like a hang.
+With Vitest, set `maxWorkers` (or `poolOptions`) accordingly; a generous
+`hookTimeout` for the `beforeAll` that launches the browser also helps on
+loaded CI runners.
+
+Indicative numbers from the `tests/perf/launch-critical-path.perf.ts`
+benchmark (macOS, Chrome, headless — absolute values are machine-dependent,
+but the direction holds):
+
+| Scenario | Before | After |
+|---|---|---|
+| `Browser.launch()` (BiDi) | ~2760ms | ~2240ms |
+| `Browser.launch()` (Classic) | ~2400ms | ~1860ms |
+| 4 browsers launched concurrently | ~6450ms | ~5130ms |
+
+Run it yourself with `npm run bench -- launch-critical-path`.
+
+### Browser startup flags (advanced, opt-in)
+
+craftdriver launches the browser with **no performance flags of its own** — it
+stays unopinionated so it never silently changes browser behavior underneath
+you. If you want to experiment, you can pass extra browser command-line flags
+via the `args` launch option (appended to `goog:chromeOptions.args` for
+Chrome/Chromium, `moz:firefoxOptions.args` for Firefox):
+
+```typescript
+const browser = await Browser.launch({
+  browserName: 'chrome',
+  args: [
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-background-networking',
+    '--disable-component-update',
+    '--disable-default-apps',
+    '--disable-extensions',
+    '--disable-sync',
+    '--metrics-recording-only',
+    '--disable-background-timer-throttling',
+    '--disable-backgrounding-occluded-windows',
+    '--disable-renderer-backgrounding',
+    '--mute-audio',
+    '--no-service-autorun',
+    '--password-store=basic',
+    '--use-mock-keychain', // macOS: skip keychain access
+    '--disable-features=Translate,BackForwardCache,AcceptCHFrame,MediaRouter,OptimizationHints',
+  ],
+});
+```
+
+> `args` are **browser** flags. They are distinct from the **driver**
+> (chromedriver/geckodriver) args you'd pass via `chromeService` /
+> `firefoxService` below.
+
+**Set expectations honestly:** on a normal local machine this set moved
+`Browser.launch()` wall time by **~0.4% (≈8ms — noise)** in our measurements.
+Cold browser startup is dominated by unavoidable process/engine init; these
+flags mostly suppress *background* work (auto-updates, telemetry, background
+networking, sync) that happens after startup rather than on the launch critical
+path. So their real value is **determinism and avoiding intermittent stalls in
+CI / constrained environments** (no update popups, no background network
+calls), not raw local launch speed. If you adopt them, **measure on your own
+environment** — the payoff is environment-dependent, and some flags can change
+behavior (e.g. `--no-sandbox`, or `--disable-features=...` entries a page or
+fixture relies on).
+
 ## Pinning via code
 
 For tighter control (custom port, extra driver flags), pass a `ChromeService`

package/docs/emulation.md

@@ -25,12 +25,16 @@ await browser.emulate({
 
 | Option | What the page sees | Transport | Cross-browser |
 |---|---|---|---|
-| `colorScheme` | `prefers-color-scheme` media query | BiDi + CDP `Emulation.setEmulatedMedia` | Chromium only |
-| `reducedMotion` | `prefers-reduced-motion` media query | BiDi + CDP `Emulation.setEmulatedMedia` | Chromium only |
-| `forcedColors` | `forced-colors` media query | BiDi + CDP `Emulation.setEmulatedMedia` | Chromium only |
+| `colorScheme` | `prefers-color-scheme` media query | CDP `Emulation.setEmulatedMedia` (over the BiDi+CDP bridge) | Chromium only |
+| `reducedMotion` | `prefers-reduced-motion` media query | CDP `Emulation.setEmulatedMedia` (over the BiDi+CDP bridge) | Chromium only |
+| `forcedColors` | `forced-colors` media query | CDP `Emulation.setEmulatedMedia` (over the BiDi+CDP bridge) | Chromium only |
 | `locale` | `navigator.language`, `Intl.*` formatting | BiDi `emulation.setLocaleOverride` | yes |
 | `timezoneId` | `Intl.DateTimeFormat`, `Date` offsets | BiDi `emulation.setTimezoneOverride` | yes |
-| `offline` | `navigator.onLine`, network stack | BiDi + CDP `Network.emulateNetworkConditions` | Chromium only |
+| `offline` | `navigator.onLine`, network stack | CDP `Network.emulateNetworkConditions` (over the BiDi+CDP bridge) | Chromium only |
+
+All options still require an active BiDi session (`enableBiDi: true`, the
+default) — the four CDP-backed options ride over a CDP bridge that BiDi
+opens, they don't work with BiDi disabled.
 
 - Pass `null` for any field to clear that override.
 - Calling `emulate({})` is a no-op.

package/docs/error-codes.md

@@ -1,6 +1,6 @@
 # Error codes
 
-Every error thrown from the public craftdriver API is a
+Nearly every error thrown from the public craftdriver API is a
 [`CraftdriverError`](../src/lib/errors.ts), carrying:
 
 - `code` — a stable, machine-readable identifier from the table below.
@@ -12,6 +12,11 @@ Every error thrown from the public craftdriver API is a
 `CraftdriverError extends Error`, so `instanceof Error` keeps working
 and stack traces are preserved.
 
+> A few edge cases still throw a plain `Error` instead — e.g. calling
+> `startTrace()` again while a trace is already running, or without
+> `outDir`. Guard against these with normal usage (don't call `startTrace()`
+> twice without `stopTrace()`) rather than a `code` check.
+
 ```ts
 import { CraftdriverError, ErrorCode } from 'craftdriver';
 
@@ -38,11 +43,11 @@ try {
 | `TIMEOUT` | Generic `WebDriverWait.until(...)` timeout with no more specific code. | Same as above — check the condition. |
 | `EXPECT_MISMATCH` | An `expect(locator).to…()` assertion failed after auto-waiting. | Inspect `error.detail` for the selector and observed value. |
 | `A11Y_VIOLATIONS` | `browser.a11y.check()` (or scoped variants) found axe-core violations. | Iterate over `error.violations` — each has an `id`, `impact`, and `helpUrl`. |
-| `EVAL_THREW` | The function passed to `evaluate()` threw inside the page. | The page-side exception text is in `error.detail.exception`. |
+| `EVAL_THREW` | The function passed to `evaluate()` threw inside the page. Also fires for `browser.clock` methods (`tick()`, `setSystemTime()`, `runFor()`) called before `install()` — they run as in-page scripts under the hood. | The page-side exception text is in `error.detail.exception`. |
 | `EVAL_BAD_ARG` | `evaluate()` / `addInitScript()` received a non-JSON-serializable argument (function, Symbol, DOM node…). | Pass plain JSON values. |
 | `INVALID_ARGUMENT` | Caller passed an invalid value (bad enum, wrong shape, unparseable duration…). | Read the message; it lists the accepted forms. |
 | `UNSUPPORTED` | Feature exists but is unavailable on this browser/transport (e.g. Chromium-only over Firefox, or a BiDi-only feature with BiDi disabled). | Enable BiDi (`enableBiDi: true`) or switch browser. |
-| `STATE_INVALID` | Method called in the wrong state (e.g. `stopTrace()` without `startTrace()`, `clock.tick()` before `install()`). | Call the prerequisite first. |
+| `STATE_INVALID` | Method called in the wrong state (e.g. `stopTrace()` without `startTrace()`). | Call the prerequisite first. |
 | `DRIVER_ERROR` | Driver-level / transport-level failure surfaced to the caller. | Inspect `error.cause`. |
 
 ## Stability