@itmetsam/samurai-framework 0.10.0 → 0.12.1

package/dist/browser/document-watcher.js

@@ -0,0 +1,160 @@
+import { callFunction } from "../script/call-function.js";
+import { BiDiError } from "../transport/bidi-error.js";
+import { Lazy } from "./lazy.js";
+import { NavigationError } from "./navigation-error.js";
+/** How many navigations keep their load progress */
+const NAVIGATIONS_REMEMBERED = 20;
+/** Events a connection's browser rejected as unknown, so nothing asks for them again */
+const unsupportedEventsByConnector = new WeakMap();
+function unsupportedEvents(connector) {
+    let events = unsupportedEventsByConnector.get(connector);
+    if (!events)
+        unsupportedEventsByConnector.set(connector, (events = new Set()));
+    return events;
+}
+/** A wait ends with the navigation it was waiting for failing or being aborted */
+function navigationFailure(url, what) {
+    throw new NavigationError(url, what, undefined, "waitForLoadState");
+}
+/**
+ * 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 class DocumentWatcher {
+    constructor(connector, contextId) {
+        this.connector = connector;
+        this.contextId = contextId;
+        /** How far navigations that did not wait for the load got, by navigation id (the latest few) */
+        this.navigationProgress = new Map();
+        this.lazyEvents = new Lazy();
+        this.onDocumentEvent = (kind) => (info) => {
+            if (info.context !== this.contextId || info.navigation === null)
+                return;
+            const progress = this.progressOf(info.navigation);
+            progress.domContentLoaded = true;
+            if (kind === "load")
+                progress.load = true;
+        };
+        this.onDomContentLoaded = this.onDocumentEvent("domContentLoaded");
+        this.onLoad = this.onDocumentEvent("load");
+    }
+    /** The progress of `navigation`, created (and the oldest forgotten) when it is not known yet */
+    progressOf(navigation) {
+        let progress = this.navigationProgress.get(navigation);
+        if (!progress) {
+            progress = { domContentLoaded: false, load: false };
+            this.navigationProgress.set(navigation, progress);
+            // Only the latest few navigations matter
+            if (this.navigationProgress.size > NAVIGATIONS_REMEMBERED) {
+                this.navigationProgress.delete(this.navigationProgress.keys().next().value);
+            }
+        }
+        return progress;
+    }
+    /** Starts recording which navigations reached DOMContentLoaded and load; kept until dispose */
+    watch() {
+        return this.lazyEvents.get(async () => {
+            this.connector.onEvent("browsingContext.domContentLoaded", this.onDomContentLoaded);
+            this.connector.onEvent("browsingContext.load", this.onLoad);
+            try {
+                return await this.connector.subscribe([
+                    "browsingContext.domContentLoaded",
+                    "browsingContext.load",
+                ]);
+            }
+            catch (err) {
+                this.connector.offEvent("browsingContext.domContentLoaded", this.onDomContentLoaded);
+                this.connector.offEvent("browsingContext.load", this.onLoad);
+                throw err;
+            }
+        });
+    }
+    /** Stops listening and gives the subscription back */
+    async dispose() {
+        const subscription = this.lazyEvents.take();
+        this.connector.offEvent("browsingContext.domContentLoaded", this.onDomContentLoaded);
+        this.connector.offEvent("browsingContext.load", this.onLoad);
+        await (await subscription)?.unsubscribe();
+    }
+    canBeAborted() {
+        return !unsupportedEvents(this.connector).has("browsingContext.navigationAborted");
+    }
+    /** Subscribes to what a wait listens for; a browser that lacks the navigationAborted event (Firefox) is asked only once */
+    async subscribe(reachedEvent) {
+        const required = [
+            reachedEvent,
+            "browsingContext.navigationFailed",
+        ];
+        if (!this.canBeAborted())
+            return this.connector.subscribe([...required]);
+        try {
+            return await this.connector.subscribe([
+                ...required,
+                "browsingContext.navigationAborted",
+            ]);
+        }
+        catch (err) {
+            if (!(err instanceof BiDiError) || err.code !== "invalid argument")
+                throw err;
+            unsupportedEvents(this.connector).add("browsingContext.navigationAborted");
+            return this.connector.subscribe([...required]);
+        }
+    }
+    /**
+     * 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.
+     */
+    eventsOf(reachedEvent, last, listen) {
+        const connector = this.connector;
+        return Promise.race([
+            connector.waitForEvent(reachedEvent, (p) => p.context === this.contextId, listen),
+            connector
+                .waitForEvent("browsingContext.navigationFailed", (p) => p.context === this.contextId &&
+                (last === undefined || p.navigation === last), listen)
+                .then((p) => navigationFailure(p.url, "navigation failed")),
+            ...(this.canBeAborted()
+                ? [
+                    connector
+                        .waitForEvent("browsingContext.navigationAborted", (p) => p.context === this.contextId &&
+                        last !== undefined &&
+                        p.navigation === last, listen)
+                        .then((p) => navigationFailure(p.url, "navigation aborted")),
+                ]
+                : []),
+        ]);
+    }
+    /** Whether the document is at `target` already: a navigation we saw fall short beats the document that is showing */
+    async readyStateReached(target, last) {
+        const known = last === undefined ? undefined : this.navigationProgress.get(last);
+        if (known && !(target === "load" ? known.load : known.domContentLoaded))
+            return false;
+        const readyState = await callFunction(this.connector, this.contextId, "() => document.readyState", [], { awaitPromise: false });
+        return target === "load"
+            ? readyState === "complete"
+            : readyState === "interactive" || readyState === "complete";
+    }
+    /**
+     * 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.
+     */
+    async waitForState(target, timeout, last) {
+        const reachedEvent = target === "load"
+            ? "browsingContext.load"
+            : "browsingContext.domContentLoaded";
+        const subscription = await this.subscribe(reachedEvent);
+        const abort = new AbortController();
+        try {
+            const events = this.eventsOf(reachedEvent, last, {
+                timeout,
+                signal: abort.signal,
+            });
+            events.catch(() => { }); // settled below, or aborted in finally
+            if (!(await this.readyStateReached(target, last)))
+                await events;
+        }
+        finally {
+            abort.abort();
+            await subscription.unsubscribe();
+        }
+    }
+}

package/dist/browser/download-folders.d.ts

@@ -21,7 +21,6 @@ export declare class ChromeDownloadFolders {
     private stagingRoot;
     /** Points the browser at a new, empty folder for the download after this one */
     private rotate;
-    private removeIfEmpty;
     private onBegin;
     private onEnd;
 }

package/dist/browser/download-folders.js

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, } from "node:fs";
+import { existsSync, mkdirSync, renameSync } from "node:fs";
 import path from "node:path";
 import logger from "../logger/index.js";
+import { removeIfEmpty } from "./downloads-dir.js";
 /** `report.csv` becomes `report(1).csv`, `report(2).csv`, … (the names Firefox gives) until a name is free in `dir` */
 export function uniqueName(dir, name) {
     if (!existsSync(path.join(dir, name)))
@@ -24,7 +25,7 @@ export class ChromeDownloadFolders {
         this.dir = dir;
         this.counter = 0;
         this.disposed = false;
-        this.onBegin = (_params) => {
+        this.onBegin = () => {
             if (this.disposed)
                 return;
             this.rotate().catch((err) => logger.error("Could not set a new download folder", { err }));
@@ -37,7 +38,7 @@ export class ChromeDownloadFolders {
                 const to = path.join(this.dir, uniqueName(this.dir, path.basename(from)));
                 renameSync(from, to);
                 params.filepath = to;
-                this.removeIfEmpty(path.dirname(from));
+                removeIfEmpty(path.dirname(from));
             }
             catch (err) {
                 logger.error("Could not move a finished download", { err });
@@ -68,8 +69,8 @@ export class ChromeDownloadFolders {
         this.connector.offEvent("browsingContext.downloadEnd", this.onEnd);
         await this.subscription?.unsubscribe().catch(() => undefined);
         if (this.staging)
-            this.removeIfEmpty(this.staging);
-        this.removeIfEmpty(this.stagingRoot());
+            removeIfEmpty(this.staging);
+        removeIfEmpty(this.stagingRoot());
     }
     stagingRoot() {
         return path.join(this.dir, ".staging");
@@ -83,15 +84,6 @@ export class ChromeDownloadFolders {
             downloadBehavior: { type: "allowed", destinationFolder: this.staging },
         });
         if (previous)
-            this.removeIfEmpty(previous);
-    }
-    removeIfEmpty(dir) {
-        try {
-            if (readdirSync(dir).length === 0)
-                rmSync(dir, { recursive: true });
-        }
-        catch {
-            // gone already, or not empty: leave it
-        }
+            removeIfEmpty(previous);
     }
 }

package/dist/browser/download.js

@@ -1,5 +1,5 @@
 import EventEmitter from "node:events";
-import logger from "../logger/index.js";
+import { emitSafely } from "./emit.js";
 import { WaitTimeoutError } from "../wait/wait-until.js";
 /** A download did not complete */
 export class DownloadError extends Error {
@@ -80,21 +80,16 @@ export class DownloadTracker {
                 return;
             const download = new Download(params.url, params.suggestedFilename, this.timeout);
             this.active.set(params.navigation, download);
-            for (const listener of this.events.rawListeners("download")) {
-                try {
-                    listener(download);
-                }
-                catch (err) {
-                    logger.error("A download listener threw", { err });
-                }
-            }
+            emitSafely(this.events, "download", [download]);
         };
         this.onEnd = (params) => {
             const download = this.active.get(params.navigation);
             if (!download)
                 return;
             this.active.delete(params.navigation);
-            download.finish(params.status === "complete" ? { status: "complete", path: params.filepath } : { status: "canceled" });
+            download.finish(params.status === "complete"
+                ? { status: "complete", path: params.filepath }
+                : { status: "canceled" });
         };
     }
     static async start(connector, tree, contextId, options) {

package/dist/browser/downloads-dir.js

@@ -1,7 +1,7 @@
 import { mkdirSync, rmdirSync } from "node:fs";
 import path from "node:path";
 import logger from "../logger/index.js";
-import { BiDiError } from "../transport/bidi-error.js";
+import { isUnsupported } from "../transport/unsupported.js";
 let counter = 0;
 /**
  * Makes downloads land in a folder of their own, so a test knows where to look and runs do not mix: a new folder
@@ -17,7 +17,7 @@ export async function prepareDownloadsDir(connector, baseDir) {
     }
     catch (err) {
         removeIfEmpty(dir);
-        if (err instanceof BiDiError && (err.code === "unknown command" || err.code === "unsupported operation")) {
+        if (isUnsupported(err)) {
             logger.warn("The browser cannot be told where to save downloads; they go to its own folder");
             return undefined;
         }

package/dist/browser/emit.d.ts

@@ -0,0 +1,7 @@
+import type EventEmitter from "node:events";
+/**
+ * Calls the listeners of `event` in order with `args`. A listener that throws is logged, not rethrown: it must not
+ * stop the other listeners or the code that raised the event. `rawListeners` so the wrappers that make a `once`
+ * listener remove itself are called.
+ */
+export declare function emitSafely(emitter: EventEmitter, event: string, args: unknown[], label?: string): void;

package/dist/browser/emit.js

@@ -0,0 +1,16 @@
+import logger from "../logger/index.js";
+/**
+ * Calls the listeners of `event` in order with `args`. A listener that throws is logged, not rethrown: it must not
+ * stop the other listeners or the code that raised the event. `rawListeners` so the wrappers that make a `once`
+ * listener remove itself are called.
+ */
+export function emitSafely(emitter, event, args, label = event) {
+    for (const listener of emitter.rawListeners(event)) {
+        try {
+            listener(...args);
+        }
+        catch (err) {
+            logger.error("A %s listener threw", label, { err });
+        }
+    }
+}

package/dist/browser/emulation.d.ts

@@ -1,4 +1,4 @@
-import { UnsupportedOperationError } from "../locator/selector-errors.js";
+import { UnsupportedOperationError } from "../transport/unsupported.js";
 import type { BiDiConnector } from "../transport/bidi-connection.js";
 declare const ORIENTATIONS: readonly ["portrait-primary", "portrait-secondary", "landscape-primary", "landscape-secondary"];
 type OrientationType = (typeof ORIENTATIONS)[number];

package/dist/browser/emulation.js

@@ -1,5 +1,4 @@
-import { UnsupportedOperationError } from "../locator/selector-errors.js";
-import { BiDiError } from "../transport/bidi-error.js";
+import { isUnsupported, UnsupportedOperationError, } from "../transport/unsupported.js";
 const ORIENTATIONS = [
     "portrait-primary",
     "portrait-secondary",
@@ -20,7 +19,7 @@ export class EmulationError extends Error {
 /** The browser does not implement an emulation command */
 export class EmulationUnsupportedError extends UnsupportedOperationError {
     constructor(option, applied) {
-        super(`emulate({ ${option} }) is not supported by the browser`);
+        super(`emulate(): ${option} is not supported by the browser`);
         this.name = "EmulationUnsupportedError";
         this.option = option;
         this.applied = applied;
@@ -34,14 +33,19 @@ function plan(options) {
     if (options.locale !== undefined) {
         if (options.locale !== null) {
             try {
-                if (options.locale === "" || Intl.getCanonicalLocales(options.locale).length !== 1)
+                if (options.locale === "" ||
+                    Intl.getCanonicalLocales(options.locale).length !== 1)
                     throw new RangeError();
             }
             catch {
                 throw new RangeError(`emulate(): invalid locale "${options.locale}"`);
             }
         }
-        steps.push({ option: "locale", method: "emulation.setLocaleOverride", params: { locale: options.locale } });
+        steps.push({
+            option: "locale",
+            method: "emulation.setLocaleOverride",
+            params: { locale: options.locale },
+        });
     }
     if (options.timezone !== undefined) {
         if (options.timezone !== null) {
@@ -52,23 +56,36 @@ function plan(options) {
                 throw new RangeError(`emulate(): unknown timezone "${options.timezone}"`);
             }
         }
-        steps.push({ option: "timezone", method: "emulation.setTimezoneOverride", params: { timezone: options.timezone } });
+        steps.push({
+            option: "timezone",
+            method: "emulation.setTimezoneOverride",
+            params: { timezone: options.timezone },
+        });
     }
     if (options.userAgent !== undefined) {
         if (options.userAgent === "")
             throw new RangeError("emulate(): userAgent must not be empty");
-        steps.push({ option: "userAgent", method: "emulation.setUserAgentOverride", params: { userAgent: options.userAgent } });
+        steps.push({
+            option: "userAgent",
+            method: "emulation.setUserAgentOverride",
+            params: { userAgent: options.userAgent },
+        });
     }
     if (options.geolocation !== undefined) {
         const place = options.geolocation;
         if (place !== null) {
-            if (!isNumber(place.latitude) || place.latitude < -90 || place.latitude > 90) {
+            if (!isNumber(place.latitude) ||
+                place.latitude < -90 ||
+                place.latitude > 90) {
                 throw new RangeError("emulate(): latitude must be between -90 and 90");
             }
-            if (!isNumber(place.longitude) || place.longitude < -180 || place.longitude > 180) {
+            if (!isNumber(place.longitude) ||
+                place.longitude < -180 ||
+                place.longitude > 180) {
                 throw new RangeError("emulate(): longitude must be between -180 and 180");
             }
-            if (place.accuracy !== undefined && (!isNumber(place.accuracy) || place.accuracy < 0)) {
+            if (place.accuracy !== undefined &&
+                (!isNumber(place.accuracy) || place.accuracy < 0)) {
                 throw new RangeError("emulate(): accuracy must be 0 or more");
             }
         }
@@ -82,33 +99,52 @@ function plan(options) {
         steps.push({
             option: "offline",
             method: "emulation.setNetworkConditions",
-            params: { networkConditions: options.offline ? { type: "offline" } : null },
+            params: {
+                networkConditions: options.offline ? { type: "offline" } : null,
+            },
         });
     }
     if (options.orientation !== undefined) {
         let screenOrientation = null;
         if (options.orientation !== null) {
-            const type = (options.orientation === "portrait" || options.orientation === "landscape"
+            const type = (options.orientation === "portrait" ||
+                options.orientation === "landscape"
                 ? `${options.orientation}-primary`
                 : options.orientation);
             if (!ORIENTATIONS.includes(type))
                 throw new RangeError(`emulate(): unknown orientation "${options.orientation}"`);
-            screenOrientation = { natural: type.startsWith("portrait") ? "portrait" : "landscape", type };
+            screenOrientation = {
+                natural: type.startsWith("portrait") ? "portrait" : "landscape",
+                type,
+            };
         }
-        steps.push({ option: "orientation", method: "emulation.setScreenOrientationOverride", params: { screenOrientation } });
+        steps.push({
+            option: "orientation",
+            method: "emulation.setScreenOrientationOverride",
+            params: { screenOrientation },
+        });
     }
     if (options.screen !== undefined) {
         const area = options.screen;
-        if (area !== null && !(isPositiveInteger(area.width) && isPositiveInteger(area.height))) {
+        if (area !== null &&
+            !(isPositiveInteger(area.width) && isPositiveInteger(area.height))) {
             throw new RangeError("emulate(): screen width and height must be positive integers");
         }
-        steps.push({ option: "screen", method: "emulation.setScreenSettingsOverride", params: { screenArea: area } });
+        steps.push({
+            option: "screen",
+            method: "emulation.setScreenSettingsOverride",
+            params: { screenArea: area },
+        });
     }
     if (options.touch !== undefined) {
         if (options.touch !== null && !isPositiveInteger(options.touch)) {
             throw new RangeError("emulate(): touch must be a positive integer");
         }
-        steps.push({ option: "touch", method: "emulation.setTouchOverride", params: { maxTouchPoints: options.touch } });
+        steps.push({
+            option: "touch",
+            method: "emulation.setTouchOverride",
+            params: { maxTouchPoints: options.touch },
+        });
     }
     if (options.javaScriptEnabled !== undefined) {
         steps.push({
@@ -134,7 +170,7 @@ export async function applyEmulation(connector, target, options) {
             await connector.send(step.method, { ...step.params, ...target });
         }
         catch (err) {
-            if (err instanceof BiDiError && (err.code === "unknown command" || err.code === "unsupported operation")) {
+            if (isUnsupported(err)) {
                 throw new EmulationUnsupportedError(step.option, applied);
             }
             throw new EmulationError(step.option, applied, err);

package/dist/browser/file-chooser.js

@@ -1,5 +1,5 @@
 import EventEmitter from "node:events";
-import logger from "../logger/index.js";
+import { emitSafely } from "./emit.js";
 import { resolveFileInputs } from "./generated-files.js";
 /**
  * A native file picker the page asked for (a click on an `<input type=file>` or its label). Nothing appears on screen:
@@ -22,10 +22,10 @@ export class FileChooser {
         const sharedId = this.info.element
             ?.sharedId;
         if (!sharedId)
-            throw new Error("file chooser has no element reference");
+            throw new Error("setFiles(): the file chooser has no element reference");
         const paths = await resolveFileInputs(files, "setFiles");
         if (paths.length > 1 && !this.info.multiple) {
-            throw new Error("file chooser does not accept multiple files");
+            throw new Error("setFiles(): the file chooser does not accept multiple files");
         }
         await this.connector.send("input.setFiles", {
             context: this.info.context,
@@ -46,14 +46,7 @@ export class FileChooserTracker {
             if (!this.tree.isWithin(params.context, this.contextId))
                 return;
             const chooser = new FileChooser(this.connector, params);
-            for (const listener of this.events.rawListeners("filechooser")) {
-                try {
-                    listener(chooser);
-                }
-                catch (err) {
-                    logger.error("A filechooser listener threw", { err });
-                }
-            }
+            emitSafely(this.events, "filechooser", [chooser]);
         };
     }
     static async start(connector, tree, contextId) {

package/dist/browser/history.d.ts

@@ -0,0 +1,6 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/**
+ * Goes one entry back (-1) or forward (1) in the context's history and resolves once the entry is shown. False when
+ * there is no such entry.
+ */
+export declare function traverseHistory(connector: BiDiConnector, context: string, delta: -1 | 1): Promise<boolean>;

package/dist/browser/history.js

@@ -0,0 +1,89 @@
+import logger from "../logger/index.js";
+import { callFunction } from "../script/call-function.js";
+import { BiDiError } from "../transport/bidi-error.js";
+/** Time (ms) a history traversal may go without a sign that the entry is shown before it is taken as done */
+const HISTORY_SETTLE_TIMEOUT = 1000;
+/**
+ * Goes one entry back (-1) or forward (1) in the context's history and resolves once the entry is shown. False when
+ * there is no such entry.
+ */
+export async function traverseHistory(connector, context, delta) {
+    if (delta === -1 && (await atFirstEntry(connector, context)))
+        return false;
+    const settled = await watchHistoryTraversal(connector, context);
+    try {
+        await connector.send("browsingContext.traverseHistory", {
+            context,
+            delta,
+        });
+        // Firefox answers once the entry is shown; Chrome answers before, and a script call in between can hit the
+        // document that is going away
+        await settled.done;
+        return true;
+    }
+    catch (err) {
+        if (err instanceof BiDiError && err.code === "no such history entry")
+            return false;
+        throw err;
+    }
+    finally {
+        await settled.stop();
+    }
+}
+/**
+ * Whether going back would only reach the blank page a tab starts with. Firefox does not keep that page in the
+ * history, Chrome does; the Navigation API (Chrome only) lets Chrome say the same as Firefox.
+ */
+async function atFirstEntry(connector, context) {
+    try {
+        return await callFunction(connector, context, `() => {
+          const nav = globalThis.navigation;
+          if (!nav) return false;
+          const entries = nav.entries();
+          const index = nav.currentEntry.index;
+          return index === 0 || (index === 1 && entries[0].url === "about:blank");
+        }`, [], { awaitPromise: false });
+    }
+    catch (err) {
+        logger.debug("Could not read the history position", { err });
+        return false;
+    }
+}
+/**
+ * Starts listening for the end of a history traversal (the new entry committed, or the history or fragment changed
+ * within the document). `done` resolves at the first such event, or after a second without one (a page restored from
+ * the back-forward cache may say nothing); it never rejects.
+ */
+async function watchHistoryTraversal(connector, context) {
+    const events = [
+        "browsingContext.navigationCommitted",
+        "browsingContext.historyUpdated",
+        "browsingContext.fragmentNavigated",
+    ];
+    let subscription;
+    try {
+        subscription = await connector.subscribe([...events]);
+    }
+    catch (err) {
+        logger.debug("Could not watch a history traversal", { err });
+        return { done: Promise.resolve(), stop: async () => { } };
+    }
+    let finish;
+    const done = new Promise((resolve) => (finish = resolve));
+    const timer = setTimeout(finish, HISTORY_SETTLE_TIMEOUT);
+    const listener = (info) => {
+        if (info.context === context)
+            finish();
+    };
+    for (const event of events)
+        connector.onEvent(event, listener);
+    return {
+        done,
+        stop: async () => {
+            clearTimeout(timer);
+            for (const event of events)
+                connector.offEvent(event, listener);
+            await subscription?.unsubscribe().catch(() => undefined);
+        },
+    };
+}

package/dist/browser/index.d.ts

@@ -1,4 +1,6 @@
 export { Browser, type BrowserLaunchOptions, type ContextOptions, } from "./browser.js";
 export { BrowserContext } from "./browser-context.js";
 export { default as Page } from "./page.js";
+export { DownloadTimeoutError } from "./download.js";
+export { EmulationUnsupportedError } from "./emulation.js";
 export { findBrowser } from "./browser-finder.js";

package/dist/browser/index.js

@@ -1,4 +1,6 @@
 export { Browser, } from "./browser.js";
 export { BrowserContext } from "./browser-context.js";
 export { default as Page } from "./page.js";
+export { DownloadTimeoutError } from "./download.js";
+export { EmulationUnsupportedError } from "./emulation.js";
 export { findBrowser } from "./browser-finder.js";

package/dist/browser/init-script.d.ts

@@ -0,0 +1,2 @@
+/** Wraps an init script as one function declaration; the argument is embedded as JSON because preload scripts take no arguments */
+export declare function initScriptSource(script: string | ((arg?: any) => void), arg: unknown): string;

package/dist/browser/init-script.js

@@ -0,0 +1,16 @@
+import { toFunctionDeclaration } from "../script/call-function.js";
+/** Wraps an init script as one function declaration; the argument is embedded as JSON because preload scripts take no arguments */
+export function initScriptSource(script, arg) {
+    if (typeof script === "string") {
+        if (arg !== undefined) {
+            throw new TypeError("addInitScript(): a string script does not take an argument; pass a function instead");
+        }
+        return `() => {\n${script}\n}`;
+    }
+    const declaration = toFunctionDeclaration(script);
+    const argument = arg === undefined ? "undefined" : JSON.stringify(arg);
+    if (argument === undefined) {
+        throw new TypeError("addInitScript(): the argument must be JSON-serializable");
+    }
+    return `() => (${declaration})(${argument})`;
+}

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

@@ -0,0 +1,20 @@
+import { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowserProcess } from "./chrome-launch.js";
+import { type BrowserLaunchOptions } from "./launch-flags.js";
+export interface FirefoxLaunch {
+    executablePath: string;
+    /** Names the browser in the start timeout error */
+    label: string;
+    launchOptions: Partial<BrowserLaunchOptions>;
+    commandTimeout: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Starts Firefox, waits for it to announce its BiDi endpoint, connects and opens the BiDi session.
+ * Rejects with an Error when the process exits first or the handshake fails, with the abort reason when aborted,
+ * and with a message string when the debugging port is taken. A failed launch stops what it started.
+ */
+export declare function launchFirefox(launch: FirefoxLaunch): Promise<{
+    proc: BrowserProcess;
+    connector: BiDiConnector;
+}>;