craftdriver 1.3.0 → 1.5.0

package/dist/lib/browser.js

@@ -1,7 +1,14 @@
 import { Builder } from './builder.js';
 import { ChromeService } from './chrome.js';
+import { ElectronService, writeElectronDebug } from './electron.js';
+import { diagnoseElectronLaunchFailure } from './electronDiagnostics.js';
+import { ElectronRemote } from './electronRemote.js';
+import { findFreePort } from './service.js';
 import { FirefoxService } from './firefox.js';
+import { SafariService } from './safari.js';
 import { resolveBrowserBinaryPath } from './driverManager.js';
+import { buildLaunchCapabilities } from './capabilities.js';
+import { resolveLaunchTarget } from './launchTarget.js';
 import { By } from './by.js';
 import { until } from './wait.js';
 import { DEFAULT_ELEMENT_TIMEOUT_MS, DEFAULT_NAVIGATION_TIMEOUT_MS, STATE_POLL_INTERVAL_MS, NETWORK_IDLE_SETTLE_MS, PORT_RELEASE_DELAY_MS, BIDI_CONNECT_MAX_ATTEMPTS, BIDI_CONNECT_BACKOFF_STEP_MS, EVAL_REALM_RETRY_ATTEMPTS, EVAL_REALM_RETRY_DELAY_MS, } from './timing.js';
@@ -18,7 +25,7 @@ import { Mouse } from './mouse.js';
 import { ActionsBuilder } from './actions.js';
 import { BiDiSession, SessionStateManager, } from './bidi/index.js';
 import { Frame } from './frame.js';
-import { Page } from './page.js';
+import { Page, isNoSuchWindowError } from './page.js';
 import { bidiWaitFor } from './loadState.js';
 import { BrowserContext } from './browserContext.js';
 import { Tracer } from './tracing.js';
@@ -63,6 +70,75 @@ export const devices = {
         userAgent: 'Mozilla/5.0 (iPad; CPU OS 15_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.0 Mobile/15E148 Safari/604.1',
     },
 };
+/**
+ * Resolve a `goog:chromeOptions.mobileEmulation` payload from the public
+ * `MobileEmulation | DeviceName` option — a built-in device name maps to
+ * Chrome's `deviceName`, otherwise a custom `deviceMetrics`/`userAgent` config
+ * is built. Kept next to `devices`; `buildLaunchCapabilities` takes the result.
+ */
+function resolveMobileEmulationConfig(mobileEmulation) {
+    const emulation = typeof mobileEmulation === 'string' ? devices[mobileEmulation] : mobileEmulation;
+    if ('deviceName' in emulation && emulation.deviceName) {
+        // Use Chrome's built-in device name
+        return { deviceName: emulation.deviceName };
+    }
+    // Build custom mobile emulation config
+    const mobileConfig = {};
+    if (emulation.deviceMetrics) {
+        mobileConfig.deviceMetrics = {
+            width: emulation.deviceMetrics.width,
+            height: emulation.deviceMetrics.height,
+            pixelRatio: emulation.deviceMetrics.pixelRatio,
+            mobile: emulation.deviceMetrics.mobile ?? true,
+            touch: emulation.deviceMetrics.touch ?? true,
+        };
+    }
+    if (emulation.userAgent) {
+        mobileConfig.userAgent = emulation.userAgent;
+    }
+    return mobileConfig;
+}
+async function resolveElectronAppBinaryPath(appBinaryPath) {
+    const resolved = path.resolve(appBinaryPath);
+    let stat;
+    try {
+        stat = await fs.stat(resolved);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT') {
+            throw new Error(`electron.appBinaryPath "${appBinaryPath}" does not exist.`);
+        }
+        if (code === 'EACCES') {
+            throw new Error(`electron.appBinaryPath "${appBinaryPath}" is not accessible.`);
+        }
+        throw error;
+    }
+    if (!stat.isFile()) {
+        throw new Error(`electron.appBinaryPath "${appBinaryPath}" is not a file.`);
+    }
+    if (process.platform !== 'win32') {
+        try {
+            await fs.access(resolved, fsSync.constants.X_OK);
+        }
+        catch {
+            throw new Error(`electron.appBinaryPath "${appBinaryPath}" is not executable.`);
+        }
+    }
+    return resolved;
+}
+/**
+ * Pure predicate behind {@link Browser.waitForPage}'s matcher form: do a page's
+ * `url`/`title` satisfy the matcher? Only the fields named in `matcher` are checked,
+ * and every named field must match (string = substring, RegExp = test). Exported for
+ * unit testing.
+ */
+export function matchPageFields(fields, matcher) {
+    const hit = (value, pattern) => pattern === undefined ||
+        (value !== undefined &&
+            (typeof pattern === 'string' ? value.includes(pattern) : pattern.test(value)));
+    return hit(fields.url, matcher.url) && hit(fields.title, matcher.title);
+}
 // ---------------------------------------------------------------------------
 // BiDi value helpers — used only by Browser.evaluate()
 // ---------------------------------------------------------------------------
@@ -93,7 +169,10 @@ function serializeLocalValue(v) {
     if (typeof v === 'object') {
         return {
             type: 'object',
-            value: Object.entries(v).map(([k, val]) => [k, serializeLocalValue(val)]),
+            value: Object.entries(v).map(([k, val]) => [
+                k,
+                serializeLocalValue(val),
+            ]),
         };
     }
     throw new CraftdriverError(ErrorCode.EVAL_BAD_ARG, `evaluate() argument of type "${typeof v}" is not JSON-serializable. ` +
@@ -101,11 +180,16 @@ function serializeLocalValue(v) {
 }
 function unwrapRemoteValue(v) {
     switch (v.type) {
-        case 'undefined': return undefined;
-        case 'null': return null;
-        case 'string': return v.value;
-        case 'boolean': return v.value;
-        case 'bigint': return BigInt(v.value);
+        case 'undefined':
+            return undefined;
+        case 'null':
+            return null;
+        case 'string':
+            return v.value;
+        case 'boolean':
+            return v.value;
+        case 'bigint':
+            return BigInt(v.value);
         case 'number': {
             if (v.value === 'NaN')
                 return NaN;
@@ -117,13 +201,15 @@ function unwrapRemoteValue(v) {
                 return -0;
             return v.value;
         }
-        case 'array': return (v.value ?? []).map(unwrapRemoteValue);
+        case 'array':
+            return (v.value ?? []).map(unwrapRemoteValue);
         case 'object':
             return Object.fromEntries((v.value ?? []).map(([k, val]) => [
                 typeof k === 'string' ? k : String(unwrapRemoteValue(k)),
                 unwrapRemoteValue(val),
             ]));
-        case 'date': return new Date(v.value);
+        case 'date':
+            return new Date(v.value);
         case 'function':
             throw new CraftdriverError(ErrorCode.EVAL_BAD_ARG, 'evaluate() returned a function, which is not JSON-serializable. ' +
                 'Return a primitive, array, or plain object instead.', { detail: { returnedType: 'function' } });
@@ -190,11 +276,19 @@ export class Browser {
     _browserInitScriptIds = new Set();
     _downloadsDir;
     _driverService;
+    /** Main-process inspector endpoint, set when launched with `electron.mainProcess`. */
+    _electronInspect;
+    /** The launched Electron app's executable path (for deep-link routing on Windows). */
+    _electronAppBinaryPath;
+    _electron;
     _browserName = 'chrome';
     /** Active emulation overrides, re-applied to new top-level contexts. */
     _emulation = {};
     /** Mutable browser-level defaults. Use setDefaultTimeout() / setDefaultNavigationTimeout() to change. */
-    defaults = { timeout: DEFAULT_ELEMENT_TIMEOUT_MS, navigationTimeout: DEFAULT_NAVIGATION_TIMEOUT_MS };
+    defaults = {
+        timeout: DEFAULT_ELEMENT_TIMEOUT_MS,
+        navigationTimeout: DEFAULT_NAVIGATION_TIMEOUT_MS,
+    };
     constructor(driver) {
         this.driver = driver;
         this.keyboard = new Keyboard(this.driver);
@@ -219,117 +313,158 @@ export class Browser {
     hasBrowserInitScripts = () => this._browserInitScriptIds.size > 0;
     hasDefaultNavigationInitScripts = () => this._defaultContext?._hasInitScriptsForNavigation() ?? this.hasBrowserInitScripts();
     static async launch(options = {}) {
-        const name = options.browserName ?? 'chrome';
-        const isFirefox = name === 'firefox';
+        // Normalize first: callers may be JavaScript or JSON-driven, so reject
+        // malformed/mixed targets before touching disk or starting a driver.
+        const target = resolveLaunchTarget(options);
+        const isElectron = target.kind === 'electron';
+        const name = target.browserName;
         const isChromeFamily = name === 'chrome' || name === 'chromium';
-        if (options.mobileEmulation && !isChromeFamily) {
+        if (target.kind === 'browser' && options.mobileEmulation && !isChromeFamily) {
             throw new Error(`mobileEmulation is only supported on Chrome/Chromium (got "${name}"). ` +
                 `Firefox does not expose a device-emulation API equivalent to goog:chromeOptions.mobileEmulation.`);
         }
-        // Handle headless mode via env var
+        const bidiRequested = target.bidiRequested;
+        // Handle headless mode via env var (never applied to Electron — see capabilities.ts).
         const headlessEnv = process.env.HEADLESS;
         const isHeadless = headlessEnv === 'true' || headlessEnv === '1';
+        // Resolve Electron before creating session directories. A malformed or
+        // missing executable must never degrade into a regular Chrome launch.
+        const electronBinary = target.kind === 'electron'
+            ? await resolveElectronAppBinaryPath(target.appBinaryPath)
+            : undefined;
+        if (options.electronService !== undefined &&
+            !(options.electronService instanceof ElectronService)) {
+            throw new Error('electronService must be an ElectronService instance.');
+        }
+        if (target.kind === 'electron') {
+            writeElectronDebug({
+                appPath: electronBinary,
+                protocol: bidiRequested ? 'bidi' : 'classic',
+                platform: `${os.platform()}-${os.arch()}`,
+            });
+        }
         // Set up downloads directory
-        const downloadsDir = options.downloadsDir ?? path.join(os.tmpdir(), 'craftdriver-downloads', `session-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        const downloadsDir = options.downloadsDir ??
+            path.join(os.tmpdir(), 'craftdriver-downloads', `session-${Date.now()}-${Math.random().toString(36).slice(2)}`);
         await fs.mkdir(downloadsDir, { recursive: true });
-        // Custom browser binary (Chrome/Chromium/Firefox). When unresolved,
-        // nothing is forwarded and the driver uses its own built-in browser
-        // discovery — but see resolveBrowserBinaryPath's doc: some of the env
-        // vars in this chain aren't craftdriver-opt-in, they're ambient
-        // conventions other tools may already have set.
-        const browserPath = resolveBrowserBinaryPath(isChromeFamily ? 'chrome' : 'firefox', options.browserPath);
-        let caps = {};
-        if (isChromeFamily) {
-            const chromeOptions = {
-                args: [...(isHeadless ? ['--headless=new'] : []), ...(options.args ?? [])],
-                prefs: {
-                    'download.default_directory': downloadsDir,
-                    'download.prompt_for_download': false,
-                    'safebrowsing.enabled': true,
-                },
-            };
-            if (browserPath)
-                chromeOptions.binary = browserPath;
-            // Add mobile emulation if specified
-            if (options.mobileEmulation) {
-                const emulation = typeof options.mobileEmulation === 'string'
-                    ? devices[options.mobileEmulation]
-                    : options.mobileEmulation;
-                if ('deviceName' in emulation && emulation.deviceName) {
-                    // Use Chrome's built-in device name
-                    chromeOptions.mobileEmulation = { deviceName: emulation.deviceName };
-                }
-                else {
-                    // Build custom mobile emulation config
-                    const mobileConfig = {};
-                    if (emulation.deviceMetrics) {
-                        mobileConfig.deviceMetrics = {
-                            width: emulation.deviceMetrics.width,
-                            height: emulation.deviceMetrics.height,
-                            pixelRatio: emulation.deviceMetrics.pixelRatio,
-                            mobile: emulation.deviceMetrics.mobile ?? true,
-                            touch: emulation.deviceMetrics.touch ?? true,
-                        };
-                    }
-                    if (emulation.userAgent) {
-                        mobileConfig.userAgent = emulation.userAgent;
-                    }
-                    chromeOptions.mobileEmulation = mobileConfig;
-                }
-            }
-            caps['goog:chromeOptions'] = chromeOptions;
-        }
-        else if (isFirefox) {
-            const firefoxArgs = [];
-            if (isHeadless)
-                firefoxArgs.push('-headless');
-            if (options.args?.length)
-                firefoxArgs.push(...options.args);
-            caps['moz:firefoxOptions'] = {
-                args: firefoxArgs,
-                prefs: {
-                    'browser.download.folderList': 2,
-                    'browser.download.dir': downloadsDir,
-                    'browser.download.useDownloadDir': true,
-                    'browser.helperApps.neverAsk.saveToDisk': 'application/octet-stream,application/pdf,text/plain,text/csv,application/zip',
-                    'pdfjs.disabled': true,
-                },
-                ...(browserPath ? { binary: browserPath } : {}),
-            };
-        }
-        if (options.enableBiDi !== false) {
-            // Request BiDi WebSocket URL
-            caps.webSocketUrl = true;
-            // Set all prompt types to 'ignore' so BiDi events fire and we can handle them
-            caps.unhandledPromptBehavior = {
-                alert: 'ignore',
-                confirm: 'ignore',
-                prompt: 'ignore',
-                beforeUnload: 'ignore',
-            };
-        }
+        // The binary that becomes goog:chromeOptions.binary / moz:firefoxOptions.binary.
+        // For Electron it's the app executable (explicit, required). For browsers
+        // it's the optional custom-binary resolution chain — but see
+        // resolveBrowserBinaryPath's doc: some of the env vars in that chain aren't
+        // craftdriver-opt-in, they're ambient conventions other tools may have set.
+        // Safari has no custom-binary concept: browserPath/args are rejected
+        // upstream in resolveLaunchTarget(), so target.browserPath is
+        // always undefined here. Skip resolveBrowserBinaryPath() for Safari
+        // entirely rather than calling it with 'firefox' as a stand-in — it would
+        // still probe FIREFOX_BIN/SE_FIREFOX_PATH-style env vars that have
+        // nothing to do with Safari, which is misleading even though it happens
+        // to return undefined/harmless today.
+        const browserBinary = target.kind === 'electron'
+            ? electronBinary
+            : name === 'safari'
+                ? undefined
+                : resolveBrowserBinaryPath(isChromeFamily ? 'chrome' : 'firefox', target.browserPath);
+        // Main-process access (opt-in): launch the Electron app with a Node inspector
+        // on a free local port. chromedriver forwards this arg to the app, enabling
+        // its main-process inspector; browser.electron connects below for log capture
+        // and retries on first executeMain() if that eager connection was too early.
+        let electronInspect;
+        let launchArgs = target.args;
+        if (target.kind === 'electron' && target.mainProcess) {
+            const host = '127.0.0.1';
+            const port = await findFreePort();
+            electronInspect = { host, port };
+            launchArgs = [...(target.args ?? []), `--inspect=${host}:${port}`];
+        }
+        const caps = buildLaunchCapabilities({
+            browserName: name,
+            isElectron,
+            isHeadless,
+            bidiRequested,
+            browserBinary,
+            downloadsDir,
+            args: launchArgs,
+            mobileEmulation: target.kind === 'browser' && isChromeFamily && options.mobileEmulation
+                ? resolveMobileEmulationConfig(options.mobileEmulation)
+                : undefined,
+        });
         const builder = new Builder().forBrowser(name);
         let driverService;
-        if (isChromeFamily) {
+        if (target.kind === 'electron') {
+            driverService =
+                options.electronService ??
+                    new ElectronService({
+                        chromedriverPath: target.chromedriverPath,
+                        version: target.version,
+                        // Lets the driver resolver read the Electron version from a packaged app's
+                        // bundle when no explicit version/driver is given (production apps).
+                        appBinaryPath: electronBinary,
+                    });
+            builder.setChromeService(driverService);
+        }
+        else if (isChromeFamily) {
             // Only thread browserPath into a default ChromeService — a
             // caller-supplied one is expected to already pin what it needs (same
             // reasoning as explicit config always winning over auto-detection).
-            driverService = options.chromeService ?? new ChromeService({ browserPath });
+            driverService = options.chromeService ?? new ChromeService({ browserPath: browserBinary });
             builder.setChromeService(driverService);
         }
+        else if (name === 'safari') {
+            // No browserPath threading (Safari has none — see the browserBinary
+            // resolution above) and no headless/args to pass through; SafariService
+            // resolves its own driver binary (never auto-downloaded).
+            driverService = options.safariService ?? new SafariService();
+            builder.setSafariService(driverService);
+        }
         else {
             driverService = options.firefoxService ?? new FirefoxService();
             builder.setFirefoxService(driverService);
         }
         builder.withCapabilities(caps);
-        const driver = await builder.build();
+        let driver;
+        if (target.kind === 'electron') {
+            try {
+                driver = await builder.build();
+            }
+            catch (err) {
+                // Turn an opaque "Chrome instance exited" into a diagnosed, actionable
+                // error (macOS signing/Gatekeeper, Linux sandbox) with the chromedriver
+                // output tail attached. Non-app-exit failures pass through unchanged.
+                throw diagnoseElectronLaunchFailure(err, {
+                    appBinaryPath: electronBinary,
+                    args: target.args,
+                    driverOutputTail: driverService.getOutputTail?.(),
+                });
+            }
+        }
+        else {
+            driver = await builder.build();
+        }
         const browser = new Browser(driver);
         browser._downloadsDir = downloadsDir;
         browser._driverService = driverService;
         browser._browserName = name;
+        browser._electronInspect = electronInspect;
+        browser._electronAppBinaryPath = electronBinary;
+        // With main-process access enabled, open the inspector bridge now so
+        // main-process console/error capture (browser.electron.mainLogs) starts at
+        // launch, mirroring always-on renderer log capture. Best-effort: a disabled
+        // EnableNodeCliInspectArguments fuse or an unreachable inspector must never
+        // fail renderer automation — executeMain still surfaces the actionable error
+        // on first use.
+        if (electronInspect) {
+            const remote = new ElectronRemote(electronInspect, { appBinaryPath: electronBinary });
+            browser._electron = remote;
+            await remote.connect().catch((err) => {
+                writeElectronDebug({
+                    event: 'main-bridge-eager-connect-failed',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
         // Initialize BiDi session if WebSocket URL available
         const wsUrl = driver.__wsUrl;
-        if (wsUrl && options.enableBiDi !== false) {
+        if (wsUrl && bidiRequested) {
             await browser.initBiDi(wsUrl);
         }
         // Load session state if provided
@@ -380,6 +515,26 @@ export class Browser {
     isBiDiEnabled() {
         return this.bidiSession?.isConnected() ?? false;
     }
+    /**
+     * Guard for the BiDi-only surface below. On Safari (which never
+     * negotiates BiDi) this throws `CraftdriverError`/`UNSUPPORTED` with a
+     * stable `{ browserName, feature }` detail so callers can branch on `code`
+     * instead of parsing prose. On every other browser the behavior is
+     * unchanged: the exact plain-`Error` message passed by the call site.
+     *
+     * Deliberately scoped to Safari's guards only — the pre-existing
+     * plain-`Error` guards elsewhere are a separate follow-up, not silently
+     * folded into this helper.
+     */
+    requireBiDi(feature, chromeMessage) {
+        if (this.bidiSession?.isConnected())
+            return;
+        if (this._browserName === 'safari') {
+            throw new CraftdriverError(ErrorCode.UNSUPPORTED, `${feature} is not supported on Safari (no WebDriver BiDi). ` +
+                'Apple does not document a WebDriver BiDi endpoint for Safari.', { detail: { browserName: 'safari', feature } });
+        }
+        throw new Error(chromeMessage);
+    }
     // === BiDi Feature Accessors ===
     /**
      * Network interception API (BiDi)
@@ -387,10 +542,8 @@ export class Browser {
      */
     get network() {
         if (!this._network) {
-            if (!this.bidiSession?.isConnected()) {
-                throw new Error('Network interception requires BiDi. ' +
-                    'BiDi negotiation may have failed at launch — check browser logs for WebSocket errors.');
-            }
+            this.requireBiDi('network', 'Network interception requires BiDi. ' +
+                'BiDi negotiation may have failed at launch — check browser logs for WebSocket errors.');
             this._network = this.bidiSession.network;
         }
         return this._network;
@@ -400,10 +553,8 @@ export class Browser {
      */
     get logs() {
         if (!this._logs) {
-            if (!this.bidiSession?.isConnected()) {
-                throw new Error('Log monitoring requires BiDi. ' +
-                    'BiDi negotiation may have failed at launch — check browser logs for WebSocket errors.');
-            }
+            this.requireBiDi('logs', 'Log monitoring requires BiDi. ' +
+                'BiDi negotiation may have failed at launch — check browser logs for WebSocket errors.');
             this._logs = this.bidiSession.logs;
         }
         return this._logs;
@@ -448,6 +599,26 @@ export class Browser {
         }
         return this._a11y;
     }
+    /**
+     * Electron **main-process** access. `browser.electron.executeMain(fn, ...args)`
+     * runs `fn(electron, ...args)` in the app's main process (full `electron`
+     * module), complementing the renderer automation on `Browser` itself.
+     *
+     * Requires launching with `electron: { mainProcess: true }`; otherwise
+     * `executeMain` throws `ELECTRON_MAIN_UNAVAILABLE`.
+     *
+     * ```ts
+     * const version = await browser.electron.executeMain((electron) => electron.app.getVersion());
+     * ```
+     */
+    get electron() {
+        if (!this._electron) {
+            this._electron = new ElectronRemote(this._electronInspect, {
+                appBinaryPath: this._electronAppBinaryPath,
+            });
+        }
+        return this._electron;
+    }
     /**
      * Save current session state (cookies + localStorage) to file
      */
@@ -600,11 +771,9 @@ export class Browser {
      * await browser.grantPermissions(['clipboard-read'], { origin: 'https://example.com' });
      */
     async grantPermissions(permissions, opts) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('grantPermissions() requires BiDi (enableBiDi: true). ' +
-                'Permission overrides use the W3C BiDi `permissions.setPermission` command, ' +
-                'which has no Classic-WebDriver equivalent.');
-        }
+        this.requireBiDi('grantPermissions()', 'grantPermissions() requires BiDi (enableBiDi: true). ' +
+            'Permission overrides use the W3C BiDi `permissions.setPermission` command, ' +
+            'which has no Classic-WebDriver equivalent.');
         if (!Array.isArray(permissions) || permissions.length === 0) {
             throw new Error('grantPermissions: pass a non-empty array of permission names.');
         }
@@ -643,11 +812,9 @@ export class Browser {
      * await browser.setGeolocation(null); // clear
      */
     async setGeolocation(coords) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('setGeolocation() requires BiDi (enableBiDi: true). ' +
-                'Geolocation overrides use the W3C BiDi `emulation.setGeolocationOverride` ' +
-                'command, which has no Classic-WebDriver equivalent.');
-        }
+        this.requireBiDi('setGeolocation()', 'setGeolocation() requires BiDi (enableBiDi: true). ' +
+            'Geolocation overrides use the W3C BiDi `emulation.setGeolocationOverride` ' +
+            'command, which has no Classic-WebDriver equivalent.');
         const conn = this.bidiSession.getConnection();
         // Apply across all top-level contexts in the default user context.
         const tree = await conn.send('browsingContext.getTree', { maxDepth: 0 });
@@ -660,8 +827,10 @@ export class Browser {
         else {
             if (typeof coords.latitude !== 'number' ||
                 typeof coords.longitude !== 'number' ||
-                coords.latitude < -90 || coords.latitude > 90 ||
-                coords.longitude < -180 || coords.longitude > 180) {
+                coords.latitude < -90 ||
+                coords.latitude > 90 ||
+                coords.longitude < -180 ||
+                coords.longitude > 180) {
                 throw new Error(`setGeolocation: invalid coordinates ${JSON.stringify(coords)}. ` +
                     'latitude must be in [-90, 90] and longitude in [-180, 180].');
             }
@@ -711,12 +880,10 @@ export class Browser {
     async emulate(options) {
         if (!options || Object.keys(options).length === 0)
             return;
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('emulate() requires BiDi (enableBiDi: true). ' +
-                'Emulation overrides use the W3C BiDi `emulation.*` commands ' +
-                '(and the BiDi+CDP bridge for media features and offline), ' +
-                'which have no Classic-WebDriver equivalent.');
-        }
+        this.requireBiDi('emulate()', 'emulate() requires BiDi (enableBiDi: true). ' +
+            'Emulation overrides use the W3C BiDi `emulation.*` commands ' +
+            '(and the BiDi+CDP bridge for media features and offline), ' +
+            'which have no Classic-WebDriver equivalent.');
         // Validate Chromium-only fields up front so we fail before mutating state.
         const chromiumOnly = ['colorScheme', 'reducedMotion', 'forcedColors', 'offline'];
         const isFirefox = this._browserName === 'firefox';
@@ -836,7 +1003,7 @@ export class Browser {
             }
             // Classic fallback: best-effort 500ms settle
             else {
-                await new Promise(r => setTimeout(r, NETWORK_IDLE_SETTLE_MS));
+                await new Promise((r) => setTimeout(r, NETWORK_IDLE_SETTLE_MS));
             }
             return;
         }
@@ -881,7 +1048,7 @@ export class Browser {
             const readyState = await this.driver.executeScript('return document.readyState', []);
             if (readyState === 'complete' || (target === 'interactive' && readyState === 'interactive'))
                 return;
-            await new Promise(r => setTimeout(r, STATE_POLL_INTERVAL_MS));
+            await new Promise((r) => setTimeout(r, STATE_POLL_INTERVAL_MS));
         }
         throw new CraftdriverError(ErrorCode.TIMEOUT_WAITING_LOAD, `waitForLoadState('${state}') timed out after ${timeout}ms`, { detail: { state, timeout } });
     }
@@ -901,6 +1068,10 @@ export class Browser {
         // Whether this session had a live BiDi WebSocket. Only the Firefox+BiDi
         // combination needs the port-release pause below; capture it before close().
         const bidiWasActive = !!this.bidiSession;
+        // Close the Electron main-process inspector bridge, if one was opened.
+        if (this._electron) {
+            await this._electron.close().catch(() => { });
+        }
         // Close BiDi connection first
         if (this.bidiSession) {
             await this.bidiSession.close().catch(() => { });
@@ -952,7 +1123,7 @@ export class Browser {
     async startTrace(opts) {
         if (!this.bidiSession?.isConnected()) {
             throw new CraftdriverError(ErrorCode.UNSUPPORTED, 'startTrace() requires BiDi (enableBiDi: true). ' +
-                'Tracing relies on BiDi events; Classic WebDriver does not expose them.', { detail: { feature: 'startTrace' } });
+                'Tracing relies on BiDi events; Classic WebDriver does not expose them.', { detail: { browserName: this._browserName, feature: 'startTrace' } });
         }
         if (!this._tracer) {
             this._tracer = new Tracer(this, this.bidiSession.getConnection(), this._browserName);
@@ -1015,7 +1186,7 @@ export class Browser {
                 catch (err) {
                     if (attempt < EVAL_REALM_RETRY_ATTEMPTS &&
                         String(err?.message).includes('execution contexts cleared')) {
-                        await new Promise(r => setTimeout(r, EVAL_REALM_RETRY_DELAY_MS));
+                        await new Promise((r) => setTimeout(r, EVAL_REALM_RETRY_DELAY_MS));
                         continue;
                     }
                     throw err;
@@ -1049,14 +1220,10 @@ export class Browser {
      * ```
      */
     async addInitScript(fnOrSrc) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('addInitScript() requires BiDi. ' +
-                'BiDi is enabled by default — check that your browser supports it.');
-        }
+        this.requireBiDi('addInitScript()', 'addInitScript() requires BiDi. ' +
+            'BiDi is enabled by default — check that your browser supports it.');
         const conn = this.bidiSession.getConnection();
-        const fnSrc = typeof fnOrSrc === 'function'
-            ? fnOrSrc.toString()
-            : `() => { ${fnOrSrc} }`;
+        const fnSrc = typeof fnOrSrc === 'function' ? fnOrSrc.toString() : `() => { ${fnOrSrc} }`;
         const result = await conn.send('script.addPreloadScript', {
             functionDeclaration: fnSrc,
         });
@@ -1076,10 +1243,10 @@ export class Browser {
      * Register **before** the action that triggers the request.
      */
     waitForRequest(pattern, opts) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('waitForRequest() requires BiDi. BiDi is enabled by default — check your browser supports it.');
-        }
-        return this.network.waitForRequest(pattern, { timeout: opts?.timeout ?? this.defaults.navigationTimeout });
+        this.requireBiDi('waitForRequest()', 'waitForRequest() requires BiDi. BiDi is enabled by default — check your browser supports it.');
+        return this.network.waitForRequest(pattern, {
+            timeout: opts?.timeout ?? this.defaults.navigationTimeout,
+        });
     }
     /**
      * Wait for the first completed response matching a URL glob or predicate.
@@ -1095,16 +1262,14 @@ export class Browser {
      * ```
      */
     waitForResponse(pattern, opts) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('waitForResponse() requires BiDi. BiDi is enabled by default \u2014 check your browser supports it.');
-        }
-        return this.network.waitForResponse(pattern, { timeout: opts?.timeout ?? this.defaults.navigationTimeout });
+        this.requireBiDi('waitForResponse()', 'waitForResponse() requires BiDi. BiDi is enabled by default \u2014 check your browser supports it.');
+        return this.network.waitForResponse(pattern, {
+            timeout: opts?.timeout ?? this.defaults.navigationTimeout,
+        });
     }
     on(event, listener) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error(`browser.on('${event}') requires BiDi (enableBiDi: true). ` +
-                'Network event listeners use the W3C BiDi `network` module, which has no Classic-WebDriver equivalent.');
-        }
+        this.requireBiDi(`browser.on('${event}')`, `browser.on('${event}') requires BiDi (enableBiDi: true). ` +
+            'Network event listeners use the W3C BiDi `network` module, which has no Classic-WebDriver equivalent.');
         if (event === 'request') {
             return this.network.on('request', listener);
         }
@@ -1120,6 +1285,17 @@ export class Browser {
      * await dl.saveAs('/tmp/report.csv');
      */
     async waitForDownload(action, opts) {
+        if (this._browserName === 'safari') {
+            // safaridriver exposes no download-directory configuration craftdriver
+            // can manage, so a browser download never lands in _downloadsDir — it
+            // goes to the user's ~/Downloads. Without this guard, waitForDownload()
+            // would watch an empty temp dir and fail with an opaque timeout instead
+            // of a clear "unsupported" error. Craftdriver-managed downloads are out
+            // of scope for Safari.
+            throw new CraftdriverError(ErrorCode.UNSUPPORTED, 'waitForDownload() is not supported on Safari: safaridriver exposes no ' +
+                'download-directory configuration craftdriver can manage, so downloads ' +
+                'cannot be routed to or observed in a controlled directory.', { detail: { browserName: 'safari', feature: 'waitForDownload()' } });
+        }
         const dir = this._downloadsDir;
         if (!dir) {
             throw new Error('waitForDownload() requires a downloads directory. Browser was not launched correctly.');
@@ -1132,7 +1308,7 @@ export class Browser {
         const deadline = Date.now() + timeout;
         while (Date.now() < deadline) {
             const after = fsSync.readdirSync(dir);
-            const newFiles = after.filter(f => !before.has(f) && !f.endsWith('.crdownload'));
+            const newFiles = after.filter((f) => !before.has(f) && !f.endsWith('.crdownload'));
             if (newFiles.length > 0) {
                 const filename = newFiles[0];
                 const filePath = path.join(dir, filename);
@@ -1144,7 +1320,7 @@ export class Browser {
                     },
                 };
             }
-            await new Promise(r => setTimeout(r, STATE_POLL_INTERVAL_MS));
+            await new Promise((r) => setTimeout(r, STATE_POLL_INTERVAL_MS));
         }
         throw new Error(`waitForDownload() timed out after ${timeout}ms — no file appeared in ${dir}`);
     }
@@ -1171,9 +1347,27 @@ export class Browser {
                 await handler(dialog);
             });
         }
-        // Classic: no push events — callers must use the imperative API below
+        if (this._browserName === 'safari') {
+            // Safari is Classic-only and has no WebDriver BiDi push events, so there
+            // is no event-driven way to detect a dialog opening. A polling fallback
+            // (repeatedly calling getAlertText()/driver "no such alert" errors to
+            // detect a dialog) was considered, but would need to be *proven*
+            // reliable on real Safari before shipping. Rather than silently no-op (today's
+            // Classic behavior for other browsers) or let waitForDialog() hang
+            // until its own generic timeout — which would look like a missed
+            // dialog rather than "this API isn't supported here" — fail
+            // immediately with a clear, actionable error. Revisit if a polling
+            // form is later measured reliable on real Safari.
+            throw new CraftdriverError(ErrorCode.UNSUPPORTED, 'onDialog() / waitForDialog() are not supported on Safari: Safari has no ' +
+                'WebDriver BiDi, so there is no push-event mechanism for dialogs. ' +
+                'Use the imperative dialog API instead — acceptDialog(), dismissDialog(), ' +
+                'getDialogMessage() — which work in Classic mode.', { detail: { browserName: 'safari', feature: 'onDialog()' } });
+        }
+        // Classic (non-Safari): no push events — callers must use the imperative API below
         // Return a no-op unsubscribe
-        return () => { };
+        return () => {
+            /* no-op */
+        };
     }
     /**
      * Accept the currently open dialog (OK / confirm).
@@ -1230,15 +1424,31 @@ export class Browser {
     waitForDialog(opts) {
         const timeout = opts?.timeout ?? this.defaults.timeout;
         return new Promise((resolve, reject) => {
-            const tid = timeout > 0
-                ? setTimeout(() => { off(); reject(new Error(`waitForDialog timed out after ${timeout}ms`)); }, timeout)
-                : undefined;
-            const off = this.onDialog((dialog) => {
-                if (tid !== undefined)
-                    clearTimeout(tid);
-                off();
-                resolve(dialog);
-            });
+            let tid;
+            let off;
+            // onDialog() throws synchronously on Safari (no BiDi push events for
+            // dialogs — see onDialog()'s comment). Register the handler before
+            // scheduling the timeout so that throw rejects this promise
+            // immediately instead of leaving a dangling timer whose callback would
+            // later reference `off` before it was ever assigned.
+            try {
+                off = this.onDialog((dialog) => {
+                    if (tid !== undefined)
+                        clearTimeout(tid);
+                    off();
+                    resolve(dialog);
+                });
+            }
+            catch (err) {
+                reject(err);
+                return;
+            }
+            if (timeout > 0) {
+                tid = setTimeout(() => {
+                    off();
+                    reject(new Error(`waitForDialog timed out after ${timeout}ms`));
+                }, timeout);
+            }
         });
     }
     _buildDialog(params) {
@@ -1249,8 +1459,12 @@ export class Browser {
             type: () => _type,
             message: () => _message,
             defaultValue: () => _defaultValue,
-            accept: async (text) => { await this.acceptDialog(text); },
-            dismiss: async () => { await this.dismissDialog(); },
+            accept: async (text) => {
+                await this.acceptDialog(text);
+            },
+            dismiss: async () => {
+                await this.dismissDialog();
+            },
         };
     }
     // ─── Frames ───────────────────────────────────────────────────────────────
@@ -1276,7 +1490,9 @@ export class Browser {
             const topContextId = this.bidiSession.getContext();
             if (topContextId) {
                 try {
-                    const tree = await conn.send('browsingContext.getTree', { root: topContextId });
+                    const tree = await conn.send('browsingContext.getTree', {
+                        root: topContextId,
+                    });
                     // The BiDi context for the iframe has the top-level context as ancestor.
                     // We find the first child context (iframes appear as children).
                     const iframeSrc = await el.getAttribute('src');
@@ -1304,7 +1520,9 @@ export class Browser {
         let tree;
         if (conn && topContextId) {
             try {
-                tree = await conn.send('browsingContext.getTree', { root: topContextId });
+                tree = await conn.send('browsingContext.getTree', {
+                    root: topContextId,
+                });
             }
             catch {
                 tree = undefined;
@@ -1328,7 +1546,9 @@ export class Browser {
     async pages() {
         if (this.bidiSession?.isConnected()) {
             const conn = this.bidiSession.getConnection();
-            const tree = await conn.send('browsingContext.getTree', { maxDepth: 0 });
+            const tree = await conn.send('browsingContext.getTree', {
+                maxDepth: 0,
+            });
             return (tree.contexts ?? []).map((ctx) => new Page(this.driver, ctx.context, this.getDefaultTimeout, conn, this._wrapContext(ctx.userContext ?? 'default')));
         }
         // Classic fallback: use window handles
@@ -1351,10 +1571,8 @@ export class Browser {
      * await page.waitForLoadState();
      */
     async openPage(opts) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('openPage() requires BiDi (enableBiDi: true). ' +
-                'WebDriver Classic cannot create top-level browsing contexts.');
-        }
+        this.requireBiDi('openPage()', 'openPage() requires BiDi (enableBiDi: true). ' +
+            'WebDriver Classic cannot create top-level browsing contexts.');
         const conn = this.bidiSession.getConnection();
         const created = await conn.send('browsingContext.create', {
             type: opts?.type ?? 'tab',
@@ -1365,16 +1583,11 @@ export class Browser {
         }
         return page;
     }
-    /**
-     * Run `action` and wait for a new top-level browsing context (tab / popup)
-     * to open. Returns a `Page` bound to the new context.
-     *
-     * @example
-     * const popup = await browser.waitForPage(() => browser.click('#open-popup'));
-     * await popup.waitForLoadState();
-     * const title = await popup.title();
-     */
-    async waitForPage(action, opts) {
+    async waitForPage(actionOrMatcher, opts) {
+        if (typeof actionOrMatcher !== 'function') {
+            return this._waitForMatchingPage(actionOrMatcher, opts);
+        }
+        const action = actionOrMatcher;
         const timeout = opts?.timeout ?? this.defaults.navigationTimeout;
         if (this.bidiSession?.isConnected()) {
             const conn = this.bidiSession.getConnection();
@@ -1407,15 +1620,60 @@ export class Browser {
         const deadline = Date.now() + timeout;
         while (Date.now() < deadline) {
             const after = await this.driver.getWindowHandles();
-            const newHandles = after.filter(h => !before.has(h));
+            const newHandles = after.filter((h) => !before.has(h));
             if (newHandles.length > 0) {
                 const handle = newHandles[0];
                 return new Page(this.driver, handle, this.getDefaultTimeout);
             }
-            await new Promise(r => setTimeout(r, STATE_POLL_INTERVAL_MS));
+            await new Promise((r) => setTimeout(r, STATE_POLL_INTERVAL_MS));
         }
         throw new Error(`waitForPage() timed out after ${timeout}ms — no new tab or popup appeared`);
     }
+    /** Poll open top-level pages until one matches `matcher`; see {@link waitForPage}. */
+    async _waitForMatchingPage(matcher, opts) {
+        if (matcher.url === undefined && matcher.title === undefined) {
+            throw new Error('waitForPage(matcher): provide at least one of { url, title }.');
+        }
+        const timeout = opts?.timeout ?? this.defaults.navigationTimeout;
+        const deadline = Date.now() + timeout;
+        const seen = new Set();
+        for (;;) {
+            for (const page of await this.pages()) {
+                try {
+                    if (await this._pageMatches(page, matcher, seen)) {
+                        // Classic: make the matched window current so browser.find(...) targets
+                        // it too (BiDi drives through the returned Page's own context).
+                        if (!this.bidiSession?.isConnected()) {
+                            await this.driver.switchToWindow(page.id()).catch(() => { });
+                        }
+                        return page;
+                    }
+                }
+                catch (err) {
+                    // A window that closed mid-check (e.g. the splash) — skip it, keep looking.
+                    if (!isNoSuchWindowError(err))
+                        throw err;
+                }
+            }
+            if (Date.now() >= deadline) {
+                const label = [
+                    matcher.title !== undefined ? `title ${String(matcher.title)}` : undefined,
+                    matcher.url !== undefined ? `url ${String(matcher.url)}` : undefined,
+                ]
+                    .filter(Boolean)
+                    .join(' and ');
+                throw new Error(`waitForPage(matcher) timed out after ${timeout}ms — no window matched ${label}. ` +
+                    `Saw: ${[...seen].join(' | ') || '(no readable windows)'}.`);
+            }
+            await new Promise((r) => setTimeout(r, STATE_POLL_INTERVAL_MS));
+        }
+    }
+    async _pageMatches(page, matcher, seen) {
+        const url = matcher.url !== undefined ? await page.url() : undefined;
+        const title = matcher.title !== undefined ? await page.title() : undefined;
+        seen.add([title !== undefined ? `"${title}"` : '', url ?? ''].filter(Boolean).join(' '));
+        return matchPageFields({ url, title }, matcher);
+    }
     // ─── User contexts (isolated profiles, BiDi-only) ────────────────────────
     /**
      * Create a new isolated user context (an "incognito profile"). Each
@@ -1472,14 +1730,14 @@ export class Browser {
         this._contextsById.set(id, ctx);
         // Evict on close so long-running suites that create many contexts don't
         // accumulate dead wrappers.
-        ctx.on('close', () => { this._contextsById.delete(id); });
+        ctx.on('close', () => {
+            this._contextsById.delete(id);
+        });
         return ctx;
     }
     async newContext(opts) {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('newContext() requires BiDi (enableBiDi: true). ' +
-                'WebDriver Classic has no concept of user contexts.');
-        }
+        this.requireBiDi('newContext()', 'newContext() requires BiDi (enableBiDi: true). ' +
+            'WebDriver Classic has no concept of user contexts.');
         const conn = this.bidiSession.getConnection();
         const created = await conn.send('browser.createUserContext', {});
         const ctx = this._wrapContext(created.userContext, {
@@ -1489,7 +1747,7 @@ export class Browser {
         if (opts?.storageState !== undefined) {
             await ctx.loadStorageState(opts.storageState);
         }
-        // Apply Milestone-C emulation options. Each setter is `userContexts`-scoped,
+        // Apply identity & device emulation options. Each setter is `userContexts`-scoped,
         // so future pages in this context inherit automatically.
         if (opts?.locale !== undefined)
             await ctx.setLocale(opts.locale);
@@ -1505,11 +1763,9 @@ export class Browser {
      * Maps to BiDi `browser.getUserContexts`. **BiDi-only.**
      */
     async contexts() {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('contexts() requires BiDi (enableBiDi: true). ' +
-                'WebDriver Classic has no concept of user contexts. ' +
-                'Use browser.pages() to list tabs instead.');
-        }
+        this.requireBiDi('contexts()', 'contexts() requires BiDi (enableBiDi: true). ' +
+            'WebDriver Classic has no concept of user contexts. ' +
+            'Use browser.pages() to list tabs instead.');
         const conn = this.bidiSession.getConnection();
         const result = await conn.send('browser.getUserContexts', {});
         return (result.userContexts ?? []).map((uc) => this._wrapContext(uc.userContext));
@@ -1520,10 +1776,8 @@ export class Browser {
      * to this context. **BiDi-only.**
      */
     get defaultContext() {
-        if (!this.bidiSession?.isConnected()) {
-            throw new Error('defaultContext requires BiDi (enableBiDi: true). ' +
-                'WebDriver Classic has no concept of user contexts.');
-        }
+        this.requireBiDi('defaultContext', 'defaultContext requires BiDi (enableBiDi: true). ' +
+            'WebDriver Classic has no concept of user contexts.');
         if (this._defaultContext)
             return this._defaultContext;
         this._defaultContext = this._wrapContext('default');
@@ -1561,7 +1815,9 @@ export class Browser {
             // would break that contract if a future refactor made the branch reachable.
             await conn
                 .subscribe(['browsingContext.contextCreated', 'browsingContext.contextDestroyed'])
-                .catch(() => { });
+                .catch(() => {
+                /* already subscribed or unsupported; fallback sync will cover us */
+            });
         }
         const onCreated = (params) => {
             if (params.parent)
@@ -1596,7 +1852,9 @@ export class Browser {
     }
     async _refreshTopLevelContextCache(conn) {
         const version = this._topLevelContextCacheVersion;
-        const tree = await conn.send('browsingContext.getTree', { maxDepth: 0 });
+        const tree = await conn.send('browsingContext.getTree', {
+            maxDepth: 0,
+        });
         if (this._topLevelContextCacheVersion === version) {
             this._topLevelContextUserContexts.clear();
         }
@@ -1653,8 +1911,30 @@ export class Browser {
             }
             return new Page(this.driver, fallback, this.getDefaultTimeout, conn, this.defaultContext);
         }
-        // Classic mode: no user-context concept; just wrap the current window.
-        const handle = await this.driver.getCurrentWindowHandle();
+        // Classic mode: wrap the current window. If it was closed (e.g. a splash that
+        // replaced itself), re-point to the sole remaining top-level window when there's
+        // exactly one — unambiguous — and otherwise ask the caller to select explicitly,
+        // rather than guessing among several or throwing an opaque "no such window".
+        let handle;
+        try {
+            handle = await this.driver.getCurrentWindowHandle();
+        }
+        catch (err) {
+            if (!isNoSuchWindowError(err))
+                throw err;
+        }
+        const handles = await this.driver.getWindowHandles();
+        if (handle === undefined || !handles.includes(handle)) {
+            if (handles.length === 0) {
+                throw new Error('activePage(): all windows are closed.');
+            }
+            if (handles.length > 1) {
+                throw new Error('activePage(): the current window was closed and several windows are open. ' +
+                    'Select one with browser.waitForPage({ title } | { url }) or browser.pages().');
+            }
+            handle = handles[0];
+            await this.driver.switchToWindow(handle).catch(() => { });
+        }
         return new Page(this.driver, handle, this.getDefaultTimeout);
     }
     async click(selector, opts) {
@@ -1695,12 +1975,31 @@ export class Browser {
     }
     gesture = {
         swipe: async ({ from, to, durationMs = 300, }) => {
+            this.rejectTouchActionsOnSafari('gesture.swipe()');
             await this.driver.performTouchSwipe(from, to, durationMs);
         },
         pinch: async ({ center, scale = 0.5, distance = 100, durationMs = 250, }) => {
+            this.rejectTouchActionsOnSafari('gesture.pinch()');
             await this.driver.performTouchPinch(center, scale, distance, durationMs);
         },
     };
+    /**
+     * `gesture.swipe()`/`gesture.pinch()` send W3C actions with a `pointer`
+     * input source whose `parameters.pointerType` is `'touch'`. Desktop Safari
+     * has no touchscreen and Apple's Safari 12+ WebDriver command table gives
+     * no indication `safaridriver` synthesizes touch-type pointer input —
+     * unlike `pointerType: 'mouse'`, which is exercised by every other pointer
+     * helper and is squarely in scope. Rather than let the action silently
+     * no-op (or behave unpredictably) on real Safari, fail loudly before
+     * sending it.
+     */
+    rejectTouchActionsOnSafari(feature) {
+        if (this._browserName !== 'safari')
+            return;
+        throw new CraftdriverError(ErrorCode.UNSUPPORTED, `${feature} sends a touch-type pointer action, which desktop Safari does not support. ` +
+            'Safari has no touchscreen and no documented touch-pointer WebDriver behavior; ' +
+            'this is desktop browser automation, not iPhone/iPad Safari coverage.', { detail: { browserName: 'safari', feature } });
+    }
     /**
      * Capture a screenshot of the active page (viewport by default), the
      * full scrollable document (`fullPage: true`), or an element matching
@@ -1733,11 +2032,9 @@ export class Browser {
             buf = Buffer.from(b64, 'base64');
         }
         else if (opts?.fullPage) {
-            if (!this.bidiSession?.isConnected()) {
-                throw new Error('screenshot({ fullPage: true }) requires BiDi (enableBiDi: true). ' +
-                    'Full-page screenshots use the W3C BiDi `browsingContext.captureScreenshot` ' +
-                    'command with `origin: "document"`, which has no Classic-WebDriver equivalent.');
-            }
+            this.requireBiDi('screenshot({ fullPage: true })', 'screenshot({ fullPage: true }) requires BiDi (enableBiDi: true). ' +
+                'Full-page screenshots use the W3C BiDi `browsingContext.captureScreenshot` ' +
+                'command with `origin: "document"`, which has no Classic-WebDriver equivalent.');
             const conn = this.bidiSession.getConnection();
             const page = await this.activePage();
             const result = await conn.send('browsingContext.captureScreenshot', {
@@ -1807,19 +2104,27 @@ export class Browser {
     static Key = Key;
     async waitForVisible(selector, opts) {
         const by = typeof selector === 'string' ? By.css(selector) : selector;
-        await this.driver.wait(until.elementIsVisible(by), { timeout: opts?.timeout ?? this.defaults.timeout });
+        await this.driver.wait(until.elementIsVisible(by), {
+            timeout: opts?.timeout ?? this.defaults.timeout,
+        });
     }
     async waitForHidden(selector, opts) {
         const by = typeof selector === 'string' ? By.css(selector) : selector;
-        await this.driver.wait(until.elementIsNotVisible(by), { timeout: opts?.timeout ?? this.defaults.timeout });
+        await this.driver.wait(until.elementIsNotVisible(by), {
+            timeout: opts?.timeout ?? this.defaults.timeout,
+        });
     }
     async waitForAttached(selector, opts) {
         const by = typeof selector === 'string' ? By.css(selector) : selector;
-        await this.driver.wait(until.elementExists(by), { timeout: opts?.timeout ?? this.defaults.timeout });
+        await this.driver.wait(until.elementExists(by), {
+            timeout: opts?.timeout ?? this.defaults.timeout,
+        });
     }
     async waitForDetached(selector, opts) {
         const by = typeof selector === 'string' ? By.css(selector) : selector;
-        await this.driver.wait(until.elementNotExists(by), { timeout: opts?.timeout ?? this.defaults.timeout });
+        await this.driver.wait(until.elementNotExists(by), {
+            timeout: opts?.timeout ?? this.defaults.timeout,
+        });
     }
     /**
      * Wait for an element to reach the given state.
@@ -1833,10 +2138,14 @@ export class Browser {
      */
     async waitFor(selector, opts) {
         switch (opts.state) {
-            case 'visible': return this.waitForVisible(selector, opts);
-            case 'hidden': return this.waitForHidden(selector, opts);
-            case 'attached': return this.waitForAttached(selector, opts);
-            case 'detached': return this.waitForDetached(selector, opts);
+            case 'visible':
+                return this.waitForVisible(selector, opts);
+            case 'hidden':
+                return this.waitForHidden(selector, opts);
+            case 'attached':
+                return this.waitForAttached(selector, opts);
+            case 'detached':
+                return this.waitForDetached(selector, opts);
         }
     }
     actions() {