craftdriver 1.2.0 → 1.4.0

package/dist/lib/browser.js

@@ -1,7 +1,13 @@
 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 { 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 +24,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 +69,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 +168,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 +179,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 +200,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 +275,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,102 +312,91 @@ 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.
+        const browserBinary = target.kind === 'electron'
+            ? electronBinary
+            : 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 {
@@ -322,14 +404,50 @@ export class Browser {
             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
@@ -434,13 +552,13 @@ export class Browser {
         return this._clock;
     }
     /**
-     * Accessibility audits via axe-core (optional peer dependency).
+     * Accessibility audits via axe-core.
      *
      * ```ts
      * await browser.a11y.check({ disableRules: ['color-contrast'] });
      * ```
      *
-     * Requires `axe-core` to be installed: `npm install --save-dev axe-core`.
+     * axe-core ships as a direct dependency of craftdriver.
      */
     get a11y() {
         if (!this._a11y) {
@@ -448,6 +566,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
      */
@@ -460,61 +598,77 @@ export class Browser {
     async loadState(path) {
         return this.storage.loadState(path);
     }
+    async _runTracedAction(name, args, selector, run) {
+        const actionIndex = this._tracer?.recordAction(name, args, selector);
+        try {
+            const result = await run();
+            this._tracer?.recordActionEnd(actionIndex);
+            return result;
+        }
+        catch (error) {
+            this._tracer?.recordActionEnd(actionIndex, error);
+            throw error;
+        }
+    }
     async navigateTo(url, opts) {
-        this._tracer?.recordAction('navigateTo', [url, opts], url);
-        const waitUntil = opts?.waitUntil ?? 'load';
-        // Classic-first for ordinary `waitUntil: 'load'` navigations: Classic
-        // already blocks until `document.readyState === 'complete'`, so the common
-        // case avoids a BiDi round trip. Preload-backed sessions stay on BiDi
-        // because the next operation is often a BiDi script evaluation into the new
-        // document; mixing Classic navigate + immediate BiDi evaluate can race with
-        // the browser clearing old execution contexts on loaded-but-settling pages.
-        const needsBiDi = waitUntil !== 'load' || this.hasDefaultNavigationInitScripts();
-        const context = needsBiDi ? this.bidiSession?.getContext() : undefined;
-        if (context && this.bidiSession?.isConnected()) {
-            const conn = this.bidiSession.getConnection();
-            const bidiWait = bidiWaitFor(waitUntil);
-            await conn.send('browsingContext.navigate', { context, url, wait: bidiWait });
+        return this._runTracedAction('navigateTo', [url, opts], url, async () => {
+            const waitUntil = opts?.waitUntil ?? 'load';
+            // Classic-first for ordinary `waitUntil: 'load'` navigations: Classic
+            // already blocks until `document.readyState === 'complete'`, so the common
+            // case avoids a BiDi round trip. Preload-backed sessions stay on BiDi
+            // because the next operation is often a BiDi script evaluation into the new
+            // document; mixing Classic navigate + immediate BiDi evaluate can race with
+            // the browser clearing old execution contexts on loaded-but-settling pages.
+            const needsBiDi = waitUntil !== 'load' || this.hasDefaultNavigationInitScripts();
+            const context = needsBiDi ? this.bidiSession?.getContext() : undefined;
+            if (context && this.bidiSession?.isConnected()) {
+                const conn = this.bidiSession.getConnection();
+                const bidiWait = bidiWaitFor(waitUntil);
+                await conn.send('browsingContext.navigate', { context, url, wait: bidiWait });
+                if (waitUntil === 'networkidle') {
+                    await this.bidiSession.network.waitForNetworkIdle({
+                        timeout: this.defaults.navigationTimeout,
+                    });
+                }
+                return;
+            }
+            // Classic path — default 'load', or BiDi unavailable/no context yet.
+            await this.driver.navigateTo(url);
             if (waitUntil === 'networkidle') {
-                await this.bidiSession.network.waitForNetworkIdle({
-                    timeout: this.defaults.navigationTimeout,
-                });
+                // Best-effort: Classic can't track network events; give it a short settle time
+                await new Promise(r => setTimeout(r, NETWORK_IDLE_SETTLE_MS));
             }
-            return;
-        }
-        // Classic path — default 'load', or BiDi unavailable/no context yet.
-        await this.driver.navigateTo(url);
-        if (waitUntil === 'networkidle') {
-            // Best-effort: Classic can't track network events; give it a short settle time
-            await new Promise(r => setTimeout(r, NETWORK_IDLE_SETTLE_MS));
-        }
+        });
     }
     /**
      * Navigate the active page back one step in its session history.
      * Proxies to {@link Page.goBack} on {@link activePage}.
      */
     async goBack() {
-        this._tracer?.recordAction('goBack');
-        const page = await this.activePage();
-        await page.goBack();
+        return this._runTracedAction('goBack', undefined, undefined, async () => {
+            const page = await this.activePage();
+            await page.goBack();
+        });
     }
     /**
      * Navigate the active page forward one step in its session history.
      * Proxies to {@link Page.goForward} on {@link activePage}.
      */
     async goForward() {
-        this._tracer?.recordAction('goForward');
-        const page = await this.activePage();
-        await page.goForward();
+        return this._runTracedAction('goForward', undefined, undefined, async () => {
+            const page = await this.activePage();
+            await page.goForward();
+        });
     }
     /**
      * Reload the active page. Proxies to {@link Page.reload} on
      * {@link activePage}.
      */
     async reload() {
-        this._tracer?.recordAction('reload');
-        const page = await this.activePage();
-        await page.reload();
+        return this._runTracedAction('reload', undefined, undefined, async () => {
+            const page = await this.activePage();
+            await page.reload();
+        });
     }
     /**
      * Return the full HTML serialization of the active page.
@@ -529,9 +683,10 @@ export class Browser {
      * Proxies to {@link Page.setContent}.
      */
     async setContent(html, opts) {
-        this._tracer?.recordAction('setContent', [opts]);
-        const page = await this.activePage();
-        await page.setContent(html, opts);
+        return this._runTracedAction('setContent', [opts], undefined, async () => {
+            const page = await this.activePage();
+            await page.setContent(html, opts);
+        });
     }
     /**
      * Resize the viewport at runtime.
@@ -643,8 +798,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].');
             }
@@ -819,7 +976,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;
         }
@@ -864,7 +1021,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 } });
     }
@@ -884,6 +1041,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(() => { });
@@ -938,20 +1099,22 @@ export class Browser {
                 'Tracing relies on BiDi events; Classic WebDriver does not expose them.', { detail: { feature: 'startTrace' } });
         }
         if (!this._tracer) {
-            this._tracer = new Tracer(this, this.bidiSession.getConnection());
+            this._tracer = new Tracer(this, this.bidiSession.getConnection(), this._browserName);
         }
         await this._tracer.start(opts);
     }
     /**
      * Stop the active trace: drain in-flight screenshots, write the closing
-     * `meta` line, and close the file. If your test threw and never reached
-     * here, the file is still valid NDJSON — just without the closing line.
+     * `meta` line, and close the file. Pass `{ path: './trace.zip' }` to also
+     * export a Vibium/Playwright-compatible archive. If your test threw and
+     * never reached here, the raw file is still valid NDJSON — just without
+     * the closing line.
      */
-    async stopTrace() {
+    async stopTrace(opts) {
         if (!this._tracer || !this._tracer.isRunning) {
             throw new CraftdriverError(ErrorCode.STATE_INVALID, 'stopTrace(): no trace is running. Call startTrace() first.', { detail: { feature: 'stopTrace' } });
         }
-        await this._tracer.stop();
+        await this._tracer.stop(opts);
     }
     /**
      * Execute JavaScript in the page and return the result.
@@ -996,7 +1159,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;
@@ -1035,9 +1198,7 @@ export class Browser {
                 '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,
         });
@@ -1060,7 +1221,9 @@ export class Browser {
         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 });
+        return this.network.waitForRequest(pattern, {
+            timeout: opts?.timeout ?? this.defaults.navigationTimeout,
+        });
     }
     /**
      * Wait for the first completed response matching a URL glob or predicate.
@@ -1079,7 +1242,9 @@ export class Browser {
         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 });
+        return this.network.waitForResponse(pattern, {
+            timeout: opts?.timeout ?? this.defaults.navigationTimeout,
+        });
     }
     on(event, listener) {
         if (!this.bidiSession?.isConnected()) {
@@ -1113,7 +1278,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);
@@ -1125,7 +1290,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}`);
     }
@@ -1154,7 +1319,9 @@ export class Browser {
         }
         // Classic: 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).
@@ -1162,26 +1329,28 @@ export class Browser {
      * Uses BiDi when available, Classic WebDriver otherwise.
      */
     async acceptDialog(text) {
-        this._tracer?.recordAction('acceptDialog', text !== undefined ? [text] : undefined);
-        if (this.bidiSession?.isConnected()) {
-            await this.bidiSession.handleUserPrompt(true, text);
-            return;
-        }
-        if (text !== undefined)
-            await this.driver.sendAlertText(text);
-        await this.driver.acceptAlert();
+        return this._runTracedAction('acceptDialog', text !== undefined ? [text] : undefined, undefined, async () => {
+            if (this.bidiSession?.isConnected()) {
+                await this.bidiSession.handleUserPrompt(true, text);
+                return;
+            }
+            if (text !== undefined)
+                await this.driver.sendAlertText(text);
+            await this.driver.acceptAlert();
+        });
     }
     /**
      * Dismiss the currently open dialog (Cancel / close).
      * Uses BiDi when available, Classic WebDriver otherwise.
      */
     async dismissDialog() {
-        this._tracer?.recordAction('dismissDialog');
-        if (this.bidiSession?.isConnected()) {
-            await this.bidiSession.handleUserPrompt(false);
-            return;
-        }
-        await this.driver.dismissAlert();
+        return this._runTracedAction('dismissDialog', undefined, undefined, async () => {
+            if (this.bidiSession?.isConnected()) {
+                await this.bidiSession.handleUserPrompt(false);
+                return;
+            }
+            await this.driver.dismissAlert();
+        });
     }
     /**
      * Get the message text of the currently open dialog.
@@ -1210,7 +1379,10 @@ export class Browser {
         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)
+                ? setTimeout(() => {
+                    off();
+                    reject(new Error(`waitForDialog timed out after ${timeout}ms`));
+                }, timeout)
                 : undefined;
             const off = this.onDialog((dialog) => {
                 if (tid !== undefined)
@@ -1228,8 +1400,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 ───────────────────────────────────────────────────────────────
@@ -1255,7 +1431,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');
@@ -1283,7 +1461,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;
@@ -1307,7 +1487,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
@@ -1344,16 +1526,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();
@@ -1386,15 +1563,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
@@ -1451,7 +1673,9 @@ 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) {
@@ -1540,7 +1764,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)
@@ -1575,7 +1801,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();
         }
@@ -1632,30 +1860,52 @@ 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) {
-        if (this._tracer?.isRunning)
-            this._tracer.recordAction('click', undefined, selectorToString(selector));
-        const by = typeof selector === 'string' ? By.css(selector) : selector;
-        const timeout = opts?.timeout ?? this.defaults.timeout;
-        await clickWithFastPath(() => this.driver.findElement(by), (remaining) => this.driver.wait(until.elementIsVisible(by), { timeout: remaining }), timeout);
+        return this._runTracedAction('click', undefined, selectorToString(selector), async () => {
+            const by = typeof selector === 'string' ? By.css(selector) : selector;
+            const timeout = opts?.timeout ?? this.defaults.timeout;
+            await clickWithFastPath(() => this.driver.findElement(by), (remaining) => this.driver.wait(until.elementIsVisible(by), { timeout: remaining }), timeout);
+        });
     }
     async fill(selector, text, opts) {
-        if (this._tracer?.isRunning)
-            this._tracer.recordAction('fill', [text], selectorToString(selector));
-        const by = typeof selector === 'string' ? By.css(selector) : selector;
-        const timeout = opts?.timeout ?? this.defaults.timeout;
-        await fillWithFastPath(() => this.driver.findElement(by), (remaining) => this.driver.wait(until.elementIsVisible(by), { timeout: remaining }), text, timeout);
+        return this._runTracedAction('fill', [text], selectorToString(selector), async () => {
+            const by = typeof selector === 'string' ? By.css(selector) : selector;
+            const timeout = opts?.timeout ?? this.defaults.timeout;
+            await fillWithFastPath(() => this.driver.findElement(by), (remaining) => this.driver.wait(until.elementIsVisible(by), { timeout: remaining }), text, timeout);
+        });
     }
     async clear(selector, opts) {
-        if (this._tracer?.isRunning)
-            this._tracer.recordAction('clear', undefined, selectorToString(selector));
-        const by = typeof selector === 'string' ? By.css(selector) : selector;
-        const timeout = opts?.timeout ?? this.defaults.timeout;
-        await clearWithFastPath(() => this.driver.findElement(by), (remaining) => this.driver.wait(until.elementIsVisible(by), { timeout: remaining }), timeout);
+        return this._runTracedAction('clear', undefined, selectorToString(selector), async () => {
+            const by = typeof selector === 'string' ? By.css(selector) : selector;
+            const timeout = opts?.timeout ?? this.defaults.timeout;
+            await clearWithFastPath(() => this.driver.findElement(by), (remaining) => this.driver.wait(until.elementIsVisible(by), { timeout: remaining }), timeout);
+        });
     }
     async getValue(selector, opts) {
         const by = typeof selector === 'string' ? By.css(selector) : selector;
@@ -1786,19 +2036,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.
@@ -1812,10 +2070,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() {