@itmetsam/samurai-framework 0.10.0 → 0.12.1

package/dist/browser/browser-finder.js

@@ -1,28 +1,25 @@
-import assert from "node:assert";
 import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import logger from "../logger/index.js";
 const supportedBrowsers = ["firefox"];
+const isFindable = (name) => supportedBrowsers.includes(name);
 const macBrowserPaths = {
-    chrome: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
     firefox: "/Applications/Firefox.app/Contents/MacOS/Firefox",
 };
 /** @deprecated Launches use the builds SAMURAI downloads (`samurai browsers install`); removed in a later major */
 export function findBrowser(browserName) {
     logger.verbose("Checking install location for %s", browserName);
-    if (!supportedBrowsers.includes(browserName)) {
+    if (!isFindable(browserName)) {
         throw new Error("This browser is not supported. Supported browsers include: " +
             supportedBrowsers.join(", "));
     }
-    let browserLocation = "";
-    const notFoundMsg = `Cannot find browser ${browserName} on this machine! Is it installed?`;
+    let browserLocation;
     try {
         browserLocation = tryFindBrowser(browserName);
     }
     catch (err) {
-        throw new Error(notFoundMsg);
+        throw Object.assign(new Error(`Cannot find browser ${browserName} on this machine! Is it installed?`), { cause: err });
     }
-    assert(browserLocation, notFoundMsg);
     logger.verbose("Browser found at: %s", browserLocation);
     return browserLocation;
 }
@@ -42,7 +39,7 @@ function tryFindBrowser(browserName) {
 function findBrowserWindows(browserName) {
     // Function to prevent search the entire file system
     // We'll only try the most common paths
-    const possibleDirs = ["Program\ Files", "Program\ Files (x86)"];
+    const possibleDirs = ["Program Files", "Program Files (x86)"];
     const where = (dirPath) => {
         const command = `where /r ${dirPath} ${browserName}.exe`;
         try {
@@ -82,7 +79,6 @@ function findBrowserMac(browserName) {
     return checkPathExists(macBrowserPaths[browserName]);
 }
 const linuxBinaryNames = {
-    chrome: "google-chrome",
     firefox: "firefox",
 };
 function findBrowserLinux(browserName) {

package/dist/browser/browser.d.ts

@@ -1,41 +1,15 @@
 import type { SupportedBrowser } from "../types/browser.js";
-import { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
 import Page from "./page.js";
-import { SESSION_CAPABILITIES } from "./session-capabilities.js";
 import { type BrowserProcess } from "./chrome-launch.js";
 import { BrowserContext } from "./browser-context.js";
 import type { UserPromptHandler } from "../types/bidi-modules/session.js";
 import { type EmulationOptions } from "./emulation.js";
 import { ChromeDownloadFolders } from "./download-folders.js";
+import { type BrowserLaunchOptions } from "./launch-flags.js";
 import type { BiDiCommands } from "../types/bidi.js";
 import type { CookieFilter, PartialCookie, PartitionDescriptor } from "../types/bidi-modules/storage.js";
-export { SESSION_CAPABILITIES };
-/** session.new got no reply in time */
-export declare class BrowserStartTimeoutError extends Error {
-    constructor(label: string, timeout: number);
-}
-/** Sends session.new with its own, longer timeout; `label` names the browser in the timeout error */
-export declare function startSession(connector: Pick<BiDiConnector, "send">, label: string, commandTimeout: number | undefined): Promise<void>;
-export declare const browserLaunchFlag: (browserName: SupportedBrowser, launchOptions: Partial<BrowserLaunchOptions>) => string[];
-/**
- * Stops what a failed launch started. A browser left running holds the profile (the next launch
- * fails with "already open") and keeps the test process alive.
- */
-export declare function abandonLaunch(browserProc: {
-    kill(): boolean;
-}, biDiConnector: {
-    kill(): void;
-} | undefined): void;
-/** Env added to a browser's process */
-export declare const browserLaunchEnv: (browserName: SupportedBrowser, appDataPath?: string) => Record<string, string>;
-export interface BrowserLaunchOptions {
-    /** Which port to use for the WebDeveloper tools */
-    port: number;
-    /** The browser profile folder: user.js goes in it for Firefox, Chrome's user data for Chrome */
-    profileDir: string;
-    /** Start the browser in headless mode or in UI mode */
-    headless: boolean;
-}
+export type { BrowserLaunchOptions } from "./launch-flags.js";
 /** Options of `browser.newContext()` */
 export interface ContextOptions extends EmulationOptions {
     acceptInsecureCerts?: boolean;
@@ -95,5 +69,3 @@ export declare class Browser {
         partitionKey: import("../types/bidi-modules/storage.js").PartitionKey;
     }>;
 }
-/** Writes the browser's user.js unless it already holds the current prefs; an outdated one is replaced */
-export declare function ensureBrowserProfile(browserName: SupportedBrowser, profilePath?: string | undefined): void;

package/dist/browser/browser.js

@@ -1,119 +1,19 @@
-import { spawn } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { projectBrowser } from "../browsers/resolve.js";
 import path from "node:path";
-import { BiDiConnector, DEFAULT_COMMAND_TIMEOUT, } from "../transport/bidi-connection.js";
-import { BiDiError } from "../transport/bidi-error.js";
+import { projectBrowser } from "../browsers/resolve.js";
 import Page from "./page.js";
-import { SESSION_CAPABILITIES } from "./session-capabilities.js";
 import { launchChrome } from "./chrome-launch.js";
 import { BrowserContext } from "./browser-context.js";
 import { validateEmulation } from "./emulation.js";
 import { prepareDownloadsDir, removeIfEmpty } from "./downloads-dir.js";
 import { ChromeDownloadFolders } from "./download-folders.js";
+import { launchFirefox } from "./launch-firefox.js";
+import { defaultLaunchOptions, ensureBrowserProfile, } from "./launch-flags.js";
+import { abandonLaunch } from "./session.js";
 import logger from "../logger/index.js";
-import { browsersDir, projectDir, readConfig } from "../config/config.js";
-export { SESSION_CAPABILITIES };
-/** session.new waits at least this long (ms): the first start after an install can take a while (macOS checks the new app) */
-const SESSION_START_TIMEOUT = 120_000;
-/** session.new got no reply in time */
-export class BrowserStartTimeoutError extends Error {
-    constructor(label, timeout) {
-        super(`${label} did not finish starting within ${Math.round(timeout / 1000)}s. The first start after an install can be slow; run again.`);
-        this.name = "BrowserStartTimeoutError";
-    }
-}
-/** Sends session.new with its own, longer timeout; `label` names the browser in the timeout error */
-export async function startSession(connector, label, commandTimeout) {
-    const timeout = Math.max(commandTimeout ?? DEFAULT_COMMAND_TIMEOUT, SESSION_START_TIMEOUT);
-    try {
-        await connector.send("session.new", { capabilities: SESSION_CAPABILITIES }, { timeout });
-    }
-    catch (err) {
-        if (err instanceof BiDiError && err.code === "timeout")
-            throw new BrowserStartTimeoutError(label, timeout);
-        throw err;
-    }
-}
+import { projectDir, readConfig } from "../config/config.js";
 /** Time (ms) to wait for Firefox to answer browser.close before killing the process */
 const BROWSER_CLOSE_GRACE = 2000;
-const browserProfilePath = (browserName) => path.join(browsersDir(), "profiles", browserName, "user.js");
-const baseBrowserLaunchFlags = {
-    // Chrome is started by its chromedriver: see chrome-launch.ts
-    chrome: [],
-    firefox: ["--no-sandbox", "--no-remote"],
-};
-/** Read when a browser launches, since the profile folder depends on the active project */
-const defaultLaunchOptions = (browserName) => ({
-    port: 9222,
-    profileDir: path.dirname(browserProfilePath(browserName)),
-    headless: true,
-});
-export const browserLaunchFlag = (browserName, launchOptions) => {
-    const defLaunchOpts = defaultLaunchOptions(browserName);
-    const port = launchOptions.port || defLaunchOpts.port;
-    const profileDir = launchOptions.profileDir || defLaunchOpts.profileDir;
-    const headless = launchOptions.headless ?? defLaunchOpts.headless;
-    const baseLaunchFlags = [...baseBrowserLaunchFlags[browserName]];
-    if (headless) {
-        baseLaunchFlags.push("--headless");
-    }
-    baseLaunchFlags.push(`--remote-debugging-port=${port}`);
-    switch (browserName) {
-        case "chrome":
-            break;
-        case "firefox":
-            baseLaunchFlags.push("--profile", profileDir);
-            // The home page (about:home) is privileged: BiDi refuses commands such as setViewport on it
-            baseLaunchFlags.push("about:blank");
-            break;
-    }
-    logger.verbose("Launch flags for browser %s: ", browserName, {
-        baseLaunchFlags,
-    });
-    return baseLaunchFlags;
-};
-/**
- * Stops what a failed launch started. A browser left running holds the profile (the next launch
- * fails with "already open") and keeps the test process alive.
- */
-export function abandonLaunch(browserProc, biDiConnector) {
-    biDiConnector?.kill();
-    browserProc.kill();
-}
-// On macOS a spawned browser is attributed to the terminal, which is denied access to
-// ~/Library/Application Support/Firefox (profiles.ini). Point Firefox at a local app data dir instead.
-const browserAppDataPath = (browserName) => path.join(browsersDir(), "app-data", browserName);
-/** Env added to a browser's process */
-export const browserLaunchEnv = (browserName, appDataPath = browserAppDataPath(browserName)) => {
-    mkdirSync(appDataPath, { recursive: true });
-    logger.debug("Using app data dir for %s: %s", browserName, appDataPath);
-    switch (browserName) {
-        case "chrome":
-            return {};
-        case "firefox":
-            // The project profile may have been opened by a newer Firefox (the system one, before 0.6);
-            // without this Firefox refuses to start on it
-            return { MOZ_APP_DATA: appDataPath, MOZ_ALLOW_DOWNGRADE: "1" };
-    }
-};
-const browserProfiles = {
-    // Chrome needs no prefs file; its profile folder is created at launch
-    chrome: "",
-    firefox: `
-    user_pref("devtools.debugger.remote-enabled", true);
-    user_pref("devtools.debugger.prompt-connection", false);
-    user_pref("devtools.chrome.enabled", true);
-    // The home page (about:home) is privileged: BiDi refuses commands such as setViewport on it
-    user_pref("browser.startup.page", 0);
-    user_pref("browser.startup.homepage", "about:blank");
-    user_pref("browser.newtabpage.enabled", false);
-  `,
-};
-// Firefox logs "WebDriver BiDi listening on ws://<host>:<port>" without the endpoint path
-const FIREFOX_WS_PATH = "/session";
-const FIREFOX_WS_REGEX = /ws:\/\/(\d){1,3}.(\d){1,3}.(\d){1,3}.(\d){1,3}:(\d){4}/g;
 export class Browser {
     constructor({ browserProc, biDiConnector, downloadsDir, downloadFolders, }) {
         this.userContexts = new Map();
@@ -143,86 +43,41 @@ export class Browser {
         signal?.throwIfAborted();
         logger.verbose("Trying to launch browser %s", browserName);
         const resolved = await projectBrowser(browserName);
-        const { executablePath: browserLocation, label } = resolved;
-        logger.debug("Found browser install location at: %s", browserLocation);
-        ensureBrowserProfile(browserName);
-        if (browserName === "chrome") {
-            const commandTimeout = await readCommandTimeout();
-            const { proc, connector } = await launchChrome({
-                executablePath: browserLocation,
+        logger.debug("Found browser install location at: %s", resolved.executablePath);
+        ensureBrowserProfile(browserName, launchOptions.profileDir &&
+            path.join(launchOptions.profileDir, "user.js"));
+        const commandTimeout = await readCommandTimeout();
+        // Both launchers hand back an open BiDi session: Firefox after session.new, Chrome with the one
+        // its chromedriver created
+        const { proc, connector } = browserName === "chrome"
+            ? await launchChrome({
+                executablePath: resolved.executablePath,
                 driverPath: resolved.driverPath,
-                profileDir: launchOptions.profileDir ?? defaultLaunchOptions("chrome").profileDir,
+                profileDir: launchOptions.profileDir ??
+                    defaultLaunchOptions("chrome").profileDir,
                 headless: launchOptions.headless ?? defaultLaunchOptions("chrome").headless,
                 commandTimeout,
                 signal,
+            })
+            : await launchFirefox({
+                executablePath: resolved.executablePath,
+                label: resolved.label,
+                launchOptions,
+                commandTimeout,
+                signal,
             });
-            try {
-                // The chromedriver session is the BiDi session: there is no session.new to send
-                return await Browser.attach(proc, connector, browserName);
-            }
-            catch (err) {
-                abandonLaunch(proc, connector);
-                throw err;
-            }
+        try {
+            return await Browser.attach(proc, connector, browserName);
+        }
+        catch (err) {
+            abandonLaunch(proc, connector);
+            throw err;
         }
-        logger.verbose("Trying to spawn %s process", browserName);
-        const browserProc = spawn(browserLocation, browserLaunchFlag(browserName, launchOptions), { env: { ...process.env, ...browserLaunchEnv(browserName) } });
-        return new Promise((resolve, reject) => {
-            const onUnexpectedClose = (code) => {
-                reject(new Error(`Browser process exited unexpectedly with code ${code}`));
-            };
-            browserProc.on("close", onUnexpectedClose);
-            const onAbort = () => {
-                logger.verbose("Launch of %s aborted, killing process", browserName);
-                browserProc.kill();
-                reject(signal?.reason);
-            };
-            signal?.addEventListener("abort", onAbort, { once: true });
-            browserProc.stdout.on("data", (data) => {
-                logger.debug(`${browserName} stdout: ${data}`);
-                if (String(data).match(/!!!\scould\snot\sstart\sserver\son\sport\s(\d){4}/g)) {
-                    browserProc.kill();
-                    reject(`PORT ${launchOptions.port} is already in use!`);
-                }
-            });
-            browserProc.stderr.on("data", async (data) => {
-                logger.debug(`${browserName} stderr: ${data}`);
-                const urlMatch = String(data).match(FIREFOX_WS_REGEX);
-                logger.debug("Browser announced its endpoint", { urlMatch });
-                if (!Array.isArray(urlMatch) || urlMatch.length === 0) {
-                    return;
-                }
-                // Killing the process mid-handshake rejects pending BiDi calls; surface that via reject
-                // instead of an unhandled rejection from this async listener
-                let biDiConnector;
-                try {
-                    let url = urlMatch[0] + FIREFOX_WS_PATH;
-                    logger.verbose("Websocket URL match: %s", url);
-                    const commandTimeout = await readCommandTimeout();
-                    biDiConnector = await BiDiConnector.connect(url, { commandTimeout });
-                    logger.verbose("Starting new session");
-                    const status = await biDiConnector.send("session.status", {});
-                    logger.verbose("Session status", status);
-                    await startSession(biDiConnector, label, commandTimeout);
-                    logger.verbose("Session started successfully");
-                    const launched = await Browser.attach(browserProc, biDiConnector, browserName);
-                    browserProc.off("close", onUnexpectedClose);
-                    signal?.removeEventListener("abort", onAbort);
-                    resolve(launched);
-                }
-                catch (err) {
-                    browserProc.off("close", onUnexpectedClose);
-                    signal?.removeEventListener("abort", onAbort);
-                    abandonLaunch(browserProc, biDiConnector);
-                    reject(err);
-                }
-            });
-        });
     }
     /** Sets up a browser whose BiDi session is open: downloads folder, the first page and what it tracks */
     static async attach(browserProc, biDiConnector, browserName) {
         biDiConnector.browserName = browserName;
-        const downloadsDir = await prepareDownloadsDir(biDiConnector, path.resolve(projectDir(), (await readOptionalConfig("downloadsDir")) ?? "result/downloads"));
+        const downloadsDir = await prepareDownloadsDir(biDiConnector, path.resolve(projectDir(), (await readDownloadsDir()) ?? "result/downloads"));
         // Chrome replaces a file that has the name of a download; this keeps every download
         const downloadFolders = browserName === "chrome" && downloadsDir
             ? new ChromeDownloadFolders(biDiConnector, downloadsDir)
@@ -247,13 +102,7 @@ export class Browser {
         else {
             page = await browser.newPage({ type: "tab" });
         }
-        await page.applyDefaultViewport();
-        // Requests made before tracking starts are invisible to it, and a dialog nobody watches would hang the page
-        await page.startNetworkTracking();
-        await page.startDialogHandling();
-        await page.startLogging();
-        await page.startDownloadTracking();
-        await page.startFileChooserTracking();
+        await page.startTracking();
         return { browser, page };
     }
     /** Closes the browser via BiDi browser.close, then makes sure the process has exited */
@@ -296,12 +145,7 @@ export class Browser {
         logger.debug("Created browsing context", { createBrowserContext });
         const page = new Page(this.biDiConnector, createBrowserContext.context);
         this.contextFor(userContext).register(page);
-        await page.applyDefaultViewport();
-        await page.startNetworkTracking();
-        await page.startDialogHandling();
-        await page.startLogging();
-        await page.startDownloadTracking();
-        await page.startFileChooserTracking();
+        await page.startTracking();
         return page;
     }
     /**
@@ -363,13 +207,13 @@ export class Browser {
         });
     }
 }
-/** A config value, or undefined when it is not set or the config cannot be read */
-async function readOptionalConfig(key) {
+/** The configured downloads folder; a missing or unreadable config falls back to the default */
+async function readDownloadsDir() {
     try {
-        return await readConfig(key);
+        return await readConfig("downloadsDir");
     }
     catch (err) {
-        logger.debug("Could not read %s from config, using the default", key, {
+        logger.debug("Could not read downloadsDir from config, using the default", {
             err,
         });
         return undefined;
@@ -385,30 +229,3 @@ async function readCommandTimeout() {
         return undefined;
     }
 }
-/** Writes the browser's user.js unless it already holds the current prefs; an outdated one is replaced */
-export function ensureBrowserProfile(browserName, profilePath = browserProfilePath(browserName)) {
-    logger.verbose("Checking browser profile for: %s", browserName);
-    if (!profilePath) {
-        logger.verbose("No browser profile path declared, skipping...");
-        return;
-    }
-    if (existsSync(profilePath)) {
-        if (readFileSync(profilePath, "utf8") === browserProfiles[browserName]) {
-            logger.verbose("Browser profile is up to date at: %s", profilePath);
-            return;
-        }
-        logger.verbose("Browser profile at %s is outdated, rewriting it", profilePath);
-    }
-    else {
-        logger.verbose("No browser profile created yet for %s", browserName);
-    }
-    createBrowserProfile(browserName, profilePath);
-}
-function createBrowserProfile(browserName, profilePath) {
-    logger.verbose("Creating browser profile for %s at %s", browserName, profilePath);
-    mkdirSync(path.dirname(profilePath), { recursive: true });
-    writeFileSync(profilePath, browserProfiles[browserName], {
-        encoding: "utf8",
-    });
-    logger.verbose("Browser profile created");
-}

package/dist/browser/chrome-launch.d.ts

@@ -8,7 +8,7 @@ export interface BrowserProcess {
     once(event: "exit", listener: (...args: any[]) => void): unknown;
     kill(signal?: NodeJS.Signals): boolean;
 }
-export interface ChromeLaunch {
+interface ChromeLaunch {
     executablePath: string;
     driverPath: string;
     profileDir: string;
@@ -67,3 +67,4 @@ export declare class ChromeProcess extends EventEmitter implements BrowserProces
     ended(): void;
     kill(signal?: NodeJS.Signals): boolean;
 }
+export {};

package/dist/browser/dialog-handling.d.ts

@@ -0,0 +1,32 @@
+import type EventEmitter from "node:events";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
+import type { ContextTree } from "./context-tree.js";
+/** The context tree of a page: created on first use, readable once it exists */
+export interface TreeSource {
+    ensure(): Promise<ContextTree>;
+    peek(): ContextTree | undefined;
+}
+/**
+ * Watches the JavaScript dialogs of one page (frames included) and hands each to the `dialog` listeners of
+ * `emitter`; a dialog nobody answers gets the default answer, so nothing hangs.
+ */
+export declare class DialogHandling {
+    private connector;
+    private contextId;
+    private tree;
+    private emitter;
+    private lazySubscription;
+    private openDialogs;
+    constructor(connector: BiDiConnector, contextId: BrowsingContext, tree: TreeSource, emitter: EventEmitter);
+    /** Starts watching for dialogs; the browser does this when it opens a page, `page.on("dialog")` when needed */
+    start(): Promise<void>;
+    /** Stops listening, forgets the open dialogs and gives the subscription back */
+    dispose(): Promise<void>;
+    private stopListening;
+    private ownsContext;
+    private onPromptOpened;
+    private onPromptClosed;
+    /** Lets the listeners answer; a dialog still open afterwards gets the default answer, so nothing hangs */
+    private dispatchDialog;
+}

package/dist/browser/dialog-handling.js

@@ -0,0 +1,85 @@
+import logger from "../logger/index.js";
+import { Dialog } from "./dialog.js";
+import { Lazy } from "./lazy.js";
+/**
+ * Watches the JavaScript dialogs of one page (frames included) and hands each to the `dialog` listeners of
+ * `emitter`; a dialog nobody answers gets the default answer, so nothing hangs.
+ */
+export class DialogHandling {
+    constructor(connector, contextId, tree, emitter) {
+        this.connector = connector;
+        this.contextId = contextId;
+        this.tree = tree;
+        this.emitter = emitter;
+        this.lazySubscription = new Lazy();
+        this.openDialogs = new Map();
+        this.onPromptOpened = (params) => {
+            if (!this.ownsContext(params.context))
+                return;
+            this.dispatchDialog(new Dialog(this.connector, this.contextId, params), params).catch((err) => logger.error("Handling a dialog failed", { err }));
+        };
+        this.onPromptClosed = (params) => {
+            if (!this.ownsContext(params.context))
+                return;
+            const dialog = this.openDialogs.get(params.context);
+            this.openDialogs.delete(params.context);
+            dialog?.markClosed({
+                accepted: params.accepted,
+                ...(params.userText !== undefined && { userText: params.userText }),
+            });
+        };
+    }
+    /** Starts watching for dialogs; the browser does this when it opens a page, `page.on("dialog")` when needed */
+    async start() {
+        await this.lazySubscription.get(async () => {
+            await this.tree.ensure();
+            this.connector.onEvent("browsingContext.userPromptOpened", this.onPromptOpened);
+            this.connector.onEvent("browsingContext.userPromptClosed", this.onPromptClosed);
+            try {
+                return await this.connector.subscribe([
+                    "browsingContext.userPromptOpened",
+                    "browsingContext.userPromptClosed",
+                ]);
+            }
+            catch (err) {
+                this.stopListening();
+                throw err;
+            }
+        });
+    }
+    /** Stops listening, forgets the open dialogs and gives the subscription back */
+    async dispose() {
+        const subscription = this.lazySubscription.take();
+        this.stopListening();
+        this.openDialogs.clear();
+        await (await subscription)?.unsubscribe();
+    }
+    stopListening() {
+        this.connector.offEvent("browsingContext.userPromptOpened", this.onPromptOpened);
+        this.connector.offEvent("browsingContext.userPromptClosed", this.onPromptClosed);
+    }
+    ownsContext(context) {
+        return (this.tree.peek()?.isWithin(context, this.contextId) ??
+            context === this.contextId);
+    }
+    /** Lets the listeners answer; a dialog still open afterwards gets the default answer, so nothing hangs */
+    async dispatchDialog(dialog, params) {
+        this.openDialogs.set(params.context, dialog);
+        // rawListeners: the wrappers that make a `once` listener remove itself when called
+        const listeners = this.emitter.rawListeners("dialog");
+        await Promise.all(listeners.map(async (listener) => {
+            try {
+                await listener(dialog);
+            }
+            catch (err) {
+                logger.error("A dialog listener threw", { err });
+            }
+        }));
+        if (dialog.handled)
+            return;
+        // Staying on a page is not what a test that navigates wants: leave it, dismiss everything else
+        const accept = params.type === "beforeunload";
+        logger.warn('Dialog "%s" was %s automatically; add page.on("dialog") to handle it', params.message, accept ? "accepted" : "dismissed");
+        await (accept ? dialog.accept() : dialog.dismiss());
+    }
+}

package/dist/browser/document-watcher.d.ts

@@ -0,0 +1,44 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { Subscription } from "../transport/subscriptions.js";
+import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
+/** What a wait for the document can reach */
+export type DocumentState = "load" | "domcontentloaded";
+/**
+ * Follows the document of one page: which navigations reached DOMContentLoaded and load, and waits for a state of
+ * the document that is showing (or of the navigation that is on its way).
+ */
+export declare class DocumentWatcher {
+    private connector;
+    private contextId;
+    /** How far navigations that did not wait for the load got, by navigation id (the latest few) */
+    private navigationProgress;
+    private lazyEvents;
+    constructor(connector: BiDiConnector, contextId: BrowsingContext);
+    /** The progress of `navigation`, created (and the oldest forgotten) when it is not known yet */
+    progressOf(navigation: string): {
+        domContentLoaded: boolean;
+        load: boolean;
+    };
+    private onDocumentEvent;
+    private onDomContentLoaded;
+    private onLoad;
+    /** Starts recording which navigations reached DOMContentLoaded and load; kept until dispose */
+    watch(): Promise<Subscription>;
+    /** Stops listening and gives the subscription back */
+    dispose(): Promise<void>;
+    private canBeAborted;
+    /** Subscribes to what a wait listens for; a browser that lacks the navigationAborted event (Firefox) is asked only once */
+    private subscribe;
+    /**
+     * The first of: the state is reached, the navigation `last` fails, the navigation `last` is aborted. Registered
+     * before the state is read, so an event in between is not lost.
+     */
+    private eventsOf;
+    /** Whether the document is at `target` already: a navigation we saw fall short beats the document that is showing */
+    private readyStateReached;
+    /**
+     * Resolves when the document reached `target`; rejects with a NavigationError when the navigation `last` (the
+     * latest one navigateTo started) fails or is aborted, and with a WaitTimeoutError after `timeout` ms.
+     */
+    waitForState(target: DocumentState, timeout: number, last: string | undefined): Promise<void>;
+}