@descryy/runtime-browser 0.5.2 → 0.5.4

package/dist/browser-session.js

@@ -12,10 +12,105 @@
  */
 import { chromium } from "playwright-core";
 import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { existsSync, rmSync } from "node:fs";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { writeOwnerOnlyFile } from "./owner-only-file.js";
+export const DEFAULT_MAX_AUXILIARY_PAGES = 4;
+export class AuxiliaryPageLimitError extends Error {
+    limit;
+    constructor(limit) {
+        super(`This session already has ${limit} auxiliary ${limit === 1 ? "page" : "pages"} open and allows at most ${limit} auxiliary ` +
+            `${limit === 1 ? "page" : "pages"} at once -- close one (page.close()) before opening another, or launch the session with a ` +
+            "larger maxAuxiliaryPages.");
+        this.name = "AuxiliaryPageLimitError";
+        this.limit = limit;
+    }
+}
+function auxiliaryPageLimitOf(options) {
+    const limit = options.maxAuxiliaryPages;
+    if (limit === undefined)
+        return DEFAULT_MAX_AUXILIARY_PAGES;
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new Error(`maxAuxiliaryPages must be a positive whole number, got ${String(limit)}`);
+    }
+    return limit;
+}
+export const MAX_DIALOG_EVENTS = 200;
+export const MAX_DIALOG_MESSAGE_CHARS = 2_000;
+export function dialogDecision(kind, policy) {
+    if (kind === "alert" || kind === "beforeunload")
+        return "accept";
+    if (kind === "confirm")
+        return policy?.confirm ?? "dismiss";
+    if (kind === "prompt")
+        return policy?.prompt ?? "dismiss";
+    return "dismiss";
+}
+function dialogKindOf(type) {
+    return type === "alert" || type === "confirm" || type === "prompt" || type === "beforeunload" ? type : "alert";
+}
+function dialogPageUrl(dialog) {
+    try {
+        return dialog.page()?.url() ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+export async function answerDialog(dialog, policy, events) {
+    const decision = dialogDecision(dialog.type(), policy);
+    let response;
+    try {
+        if (decision === "accept") {
+            await (dialog.type() === "prompt" ? dialog.accept(policy?.promptText ?? "") : dialog.accept());
+        }
+        else {
+            await dialog.dismiss();
+        }
+        response = decision === "accept" ? "accepted" : "dismissed";
+    }
+    catch {
+        response = "unanswered";
+    }
+    const message = dialog.message();
+    if (events.length >= MAX_DIALOG_EVENTS)
+        events.shift();
+    events.push({
+        kind: dialogKindOf(dialog.type()),
+        message: message.length > MAX_DIALOG_MESSAGE_CHARS ? `${message.slice(0, MAX_DIALOG_MESSAGE_CHARS)}…` : message,
+        url: dialogPageUrl(dialog),
+        response,
+        at: new Date().toISOString(),
+    });
+}
+export const MAX_VIDEO_BYTES = 64 * 1024 * 1024;
+export class VideoTooLargeError extends Error {
+    sizeBytes;
+    maxBytes;
+    constructor(sizeBytes, maxBytes) {
+        super(`the recorded video is ${String(sizeBytes)} bytes, over the ${String(maxBytes)}-byte limit, so it was discarded rather than loaded into memory`);
+        this.name = "VideoTooLargeError";
+        this.sizeBytes = sizeBytes;
+        this.maxBytes = maxBytes;
+    }
+}
+/**
+ * An origin as the browser compares it: lower-case scheme and host, default
+ * port dropped, an IDN host in punycode, no path. `null` for anything with an
+ * opaque origin (`data:`, `file:`, `about:`) or that does not parse -- such a
+ * URL is never a consented origin and never equals one.
+ */
+export function normalizeOrigin(url) {
+    try {
+        const origin = new URL(url).origin;
+        return origin === "null" ? null : origin;
+    }
+    catch {
+        return null;
+    }
+}
 export const CHROMIUM_INSTALL_REMEDY = "npx playwright install chromium";
 /**
  * Resolved at launch time, not import time -- a module-level check would
@@ -55,6 +150,9 @@ export class BrowserUnavailableError extends Error {
  * only rethrow.
  */
 export async function launchBrowserSessionOrRefuse(options = {}) {
+    // Before anything is launched, so a bad origin list leaves no browser behind.
+    consentedOriginsOf(options);
+    auxiliaryPageLimitOf(options);
     const chromiumBinary = resolveChromiumExecutable();
     if (!chromiumBinary.available) {
         const { available: _available, ...unavailable } = chromiumBinary;
@@ -70,11 +168,92 @@ export async function launchBrowserSession(options = {}) {
     }
     return launch.session;
 }
+const SANDBOX_LAUNCH_FAILURE = /sandbox|namespace|suid|zygote/i;
+async function launchPreferringSandbox(launch, base) {
+    try {
+        return { browser: await launch({ ...base, chromiumSandbox: true }), sandbox: { enabled: true, fallbackReason: null } };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        if (!SANDBOX_LAUNCH_FAILURE.test(detail))
+            throw error;
+        const firstLine = detail.split("\n").find((line) => SANDBOX_LAUNCH_FAILURE.test(line))?.trim() ?? detail.split("\n")[0] ?? detail;
+        return {
+            browser: await launch({ ...base, chromiumSandbox: false }),
+            sandbox: { enabled: false, fallbackReason: `Chromium could not start with its sandbox (${firstLine}), so it was launched without one: a renderer exploit would run with this process's privileges.` },
+        };
+    }
+}
 async function launchWithExecutable(options, executablePath) {
-    const browser = await chromium.launch({ headless: options.headless ?? true, executablePath });
-    return createSessionFromBrowser(browser, options, async () => {
-        await browser.close();
+    const { browser, sandbox } = await launchPreferringSandbox((launchOptions) => chromium.launch(launchOptions), {
+        headless: options.headless ?? true,
+        executablePath,
+    });
+    try {
+        return await createSessionFromBrowser(browser, options, async () => {
+            await browser.close();
+        }, sandbox);
+    }
+    catch (error) {
+        await browser.close().catch(() => undefined);
+        throw error;
+    }
+}
+const guardOriginOf = normalizeOrigin;
+/** The consented origins, normalised, or null when the session is not confined. Throws on an entry that is not an origin: confining to nothing would block every page silently. */
+function consentedOriginsOf(options) {
+    if (options.confineToOrigins === undefined)
+        return null;
+    if (options.confineToOrigins.length === 0)
+        throw new Error("confineToOrigins is empty: a confined session needs at least one origin");
+    const origins = new Set();
+    for (const raw of options.confineToOrigins) {
+        const origin = normalizeOrigin(raw);
+        if (origin === null)
+            throw new Error(`confineToOrigins: "${raw}" is not a valid origin (it has no host, or its origin is opaque)`);
+        origins.add(origin);
+    }
+    return origins;
+}
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+function isInertUrl(url) {
+    return url === "about:blank" || url.startsWith("chrome-error://");
+}
+/** A page load of a top-level frame (the session's page or a popup). A service-worker request has no frame, and `frame()` throws for it. */
+function isTopLevelPageLoad(request) {
+    if (!request.isNavigationRequest())
+        return false;
+    try {
+        return request.frame().parentFrame() === null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks every redirect a page load of the session's own page answers with, before the browser
+ * follows it. Playwright continues redirect hops inside the browser without calling a route
+ * handler again, so this sits one level down: Chromium's Fetch domain, at the response stage, for
+ * documents. That stage reports each redirect response, the first hop and every later one, while
+ * the browser is still holding it. A hop `allow` refuses is failed as aborted, so its target is
+ * never requested and the page stays where it was. Everything else is continued unchanged, so the
+ * browser still loads every document itself.
+ */
+async function guardRedirects(page, allow) {
+    const cdp = await page.context().newCDPSession(page);
+    const tree = (await cdp.send("Page.getFrameTree"));
+    const mainFrameId = tree.frameTree.frame.id;
+    cdp.on("Fetch.requestPaused", (event) => {
+        const status = event.responseStatusCode;
+        const location = event.responseHeaders?.find((header) => header.name.toLowerCase() === "location")?.value;
+        const refused = event.frameId === mainFrameId && status !== undefined && REDIRECT_STATUSES.has(status) && location !== undefined && !allow(location, event.request.url);
+        // Always answered: a paused request that is never continued or failed hangs the page.
+        const answer = refused
+            ? cdp.send("Fetch.failRequest", { requestId: event.requestId, errorReason: "Aborted" })
+            : cdp.send("Fetch.continueRequest", { requestId: event.requestId });
+        answer.catch(() => undefined);
     });
+    await cdp.send("Fetch.enable", { patterns: [{ urlPattern: "*", resourceType: "Document", requestStage: "Response" }] });
 }
 /**
  * The context/page half of a session's launch, factored out of
@@ -89,14 +268,55 @@ async function launchWithExecutable(options, executablePath) {
  * context's slot back to the manager and leaves the browser running for the next
  * caller.
  */
-async function createSessionFromBrowser(browser, options, afterContextClosed) {
+const uncollectedVideoDirs = new Set();
+let videoDirExitHookInstalled = false;
+function removeAtExit(dir) {
+    uncollectedVideoDirs.add(dir);
+    if (videoDirExitHookInstalled)
+        return;
+    videoDirExitHookInstalled = true;
+    process.once("exit", () => {
+        for (const pending of uncollectedVideoDirs) {
+            try {
+                rmSync(pending, { recursive: true, force: true });
+            }
+            catch {
+                continue;
+            }
+        }
+    });
+}
+async function createSessionFromBrowser(browser, options, afterContextClosed, sandbox) {
+    const created = { context: null, videoDir: null };
+    try {
+        return await assembleSession(browser, options, afterContextClosed, created, sandbox);
+    }
+    catch (error) {
+        if (created.context !== null)
+            await created.context.close().catch(() => undefined);
+        if (created.videoDir !== null) {
+            await rm(created.videoDir, { recursive: true, force: true }).catch(() => undefined);
+            uncollectedVideoDirs.delete(created.videoDir);
+        }
+        throw error;
+    }
+}
+async function assembleSession(browser, options, afterContextClosed, created, sandbox) {
     const sessionId = randomUUID();
     // session-scoped temp dir, never caller-supplied (see BrowserConfiguration.recordVideo).
     // created before newContext(): Playwright's recordVideo.dir must exist and be known at context-creation time.
     const videoDir = options.recordVideo === true ? await mkdtemp(join(tmpdir(), `descry-video-${sessionId}-`)) : null;
+    created.videoDir = videoDir;
+    if (videoDir !== null)
+        removeAtExit(videoDir);
     const auth = options.auth;
+    const consented = consentedOriginsOf(options);
     const context = await browser.newContext({
+        acceptDownloads: false,
         ...(videoDir === null ? {} : { recordVideo: { dir: videoDir } }),
+        // A service worker's requests bypass `context.route`, so in a confined session one could
+        // navigate or fetch where the guard below never looks.
+        ...(consented === null ? {} : { serviceWorkers: "block" }),
         // Built rather than passed through: what a caller names is a cookie and a
         // key/value map for one origin, and Playwright's own storage-state shape
         // wants a domain per cookie and an array per origin. Deriving the domain
@@ -104,27 +324,138 @@ async function createSessionFromBrowser(browser, options, afterContextClosed) {
         // a property of the code rather than of a caller getting it right.
         ...(auth === undefined ? {} : { storageState: seedStateFor(auth) }),
     });
+    created.context = context;
+    const dialogEvents = [];
+    context.on("dialog", (dialog) => {
+        void answerDialog(dialog, options.dialogs, dialogEvents);
+    });
     const page = await context.newPage();
-    // Only installed when there is a header to send. Route interception is not
-    // free -- it puts a handler in front of every request the context makes --
-    // and a session with no header must behave exactly as it did before this
-    // option existed. `context.setExtraHTTPHeaders` would have been one line,
-    // and would have sent the credential to every host the page touches.
-    if (auth?.extraHttpHeaders !== undefined && Object.keys(auth.extraHttpHeaders).length > 0) {
-        const headers = auth.extraHttpHeaders;
-        const consented = auth.origin;
+    const isConsented = (origin) => origin !== null && consented !== null && consented.has(origin);
+    const blockedByGuard = new WeakSet();
+    // A redirect is stopped below Playwright, which knows the hop by URL only. The page load that
+    // then fails is matched to it here -- registered before any collector's listener, so the
+    // request is marked by the time a collector asks.
+    const blockedRedirectSources = new Set();
+    const markBlockedRedirects = (target) => {
+        target.on("requestfailed", (request) => {
+            if (!request.isNavigationRequest() || !blockedRedirectSources.delete(request.url()))
+                return;
+            blockedByGuard.add(request);
+        });
+    };
+    markBlockedRedirects(page);
+    const offOriginEvents = [];
+    const recordOffOrigin = (kind, url) => {
+        offOriginEvents.push({ kind, url, at: new Date().toISOString() });
+    };
+    // Only installed when there is a header to send or an origin to hold. Route
+    // interception is not free -- it puts a handler in front of every request
+    // the context makes -- and a session with neither must behave exactly as it
+    // did before these options existed. `context.setExtraHTTPHeaders` would have
+    // been one line, and would have sent the credential to every host the page
+    // touches.
+    const headers = auth?.extraHttpHeaders !== undefined && Object.keys(auth.extraHttpHeaders).length > 0 ? auth.extraHttpHeaders : undefined;
+    if (headers !== undefined || consented !== null) {
         await context.route("**/*", async (route) => {
-            let sameOrigin = false;
+            const request = route.request();
+            const requestOrigin = guardOriginOf(request.url());
+            const topLevel = consented !== null && isTopLevelPageLoad(request);
+            if (topLevel && !isConsented(requestOrigin)) {
+                blockedByGuard.add(request);
+                recordOffOrigin("blocked", request.url());
+                // "aborted" (net::ERR_ABORTED), not "blockedbyclient": Chromium
+                // commits an error page for most top-level failures, which would
+                // replace the app's page; an aborted navigation leaves it in place.
+                await route.abort("aborted");
+                return;
+            }
+            // A request off the consented origin continues untouched -- not
+            // blocked. The header seam exists to stop a credential travelling.
+            const sameOrigin = auth !== undefined && requestOrigin === normalizeOrigin(auth.origin);
+            const credentialNames = headers === undefined ? [] : Object.keys(lowerCased(headers));
+            const carriedAcrossRedirect = headers !== undefined && !sameOrigin && request.redirectedFrom() !== null && credentialNames.some((name) => name in request.headers());
+            const sentHeaders = headers !== undefined && sameOrigin
+                ? { ...request.headers(), ...lowerCased(headers) }
+                : carriedAcrossRedirect
+                    ? Object.fromEntries(Object.entries(request.headers()).filter(([name]) => !credentialNames.includes(name.toLowerCase())))
+                    : undefined;
+            // Continued, never fetched and fulfilled here: a document the browser did not load itself
+            // has no address space, so Chromium's local-network checks then block every loopback
+            // subresource and frame it asks for -- a local app would lose its own API on another port.
+            await route.continue(sentHeaders === undefined ? {} : { headers: sentHeaders });
+        });
+    }
+    const confineNavigation = async (target) => {
+        await guardRedirects(target, (location, from) => {
+            let destination;
             try {
-                sameOrigin = new URL(route.request().url()).origin === consented;
+                destination = new URL(location, from).href;
             }
             catch {
-                sameOrigin = false;
+                destination = null;
             }
-            // A request off the consented origin continues untouched -- not
-            // blocked. This seam exists to stop a credential travelling, not to
-            // become a second, undisclosed network policy.
-            await route.continue(sameOrigin ? { headers: { ...route.request().headers(), ...lowerCased(headers) } } : {});
+            if (destination !== null && isConsented(guardOriginOf(destination)))
+                return true;
+            blockedRedirectSources.add(from);
+            recordOffOrigin("redirect-blocked", destination ?? location);
+            return false;
+        });
+        // Defence in depth, not the mechanism: every route the page can take off the
+        // list is stopped before it is sent above. If this ever fires, one was missed.
+        target.on("framenavigated", (frame) => {
+            if (frame !== target.mainFrame())
+                return;
+            const url = frame.url();
+            if (isInertUrl(url) || isConsented(guardOriginOf(url)))
+                return;
+            recordOffOrigin("landed", url);
+            void target.goto("about:blank").catch(() => undefined);
+        });
+    };
+    const auxiliaryLimit = auxiliaryPageLimitOf(options);
+    const liveAuxiliaryPages = new Set();
+    const issuedAuxiliaryPages = new WeakSet();
+    let auxiliaryQueue = Promise.resolve();
+    let auxiliaryRequestsPending = 0;
+    let closing = null;
+    const isClosing = () => closing !== null;
+    if (consented !== null) {
+        await confineNavigation(page);
+        // This session drives its own page and the auxiliary pages it opened itself. Any other
+        // page -- a popup, same origin or not -- is one nothing is driving, so it is closed and
+        // recorded rather than left running where no one is watching. While an auxiliary page
+        // is being created the verdict waits for it, so the page is recognised by identity
+        // before the guard decides; nothing about a page (an absent opener included) can make
+        // a popup pass for one.
+        context.on("page", (opened) => {
+            if (opened === page)
+                return;
+            const decide = () => {
+                if (issuedAuxiliaryPages.has(opened))
+                    return;
+                recordOffOrigin("popup-closed", opened.url());
+                void opened.close().catch(() => undefined);
+            };
+            if (auxiliaryRequestsPending === 0)
+                decide();
+            else
+                void auxiliaryQueue.then(decide);
+        });
+    }
+    const unobservedPopups = [];
+    if (consented === null) {
+        context.on("page", (opened) => {
+            if (opened === page || issuedAuxiliaryPages.has(opened))
+                return;
+            const record = () => {
+                if (issuedAuxiliaryPages.has(opened))
+                    return;
+                unobservedPopups.push({ kind: "popup-unobserved", url: opened.url(), at: new Date().toISOString() });
+            };
+            if (auxiliaryRequestsPending === 0)
+                record();
+            else
+                void auxiliaryQueue.then(record);
         });
     }
     const startedAt = new Date().toISOString();
@@ -132,14 +463,69 @@ async function createSessionFromBrowser(browser, options, afterContextClosed) {
     page.on("crash", () => {
         crashed = true;
     });
+    const createAuxiliaryPage = async () => {
+        if (isClosing()) {
+            throw new Error("openAuxiliaryPage() called after close() -- the session is closed, so there is no browser context to open a page in.");
+        }
+        if (liveAuxiliaryPages.size >= auxiliaryLimit)
+            throw new AuxiliaryPageLimitError(auxiliaryLimit);
+        let auxiliary;
+        try {
+            auxiliary = await context.newPage();
+        }
+        catch (error) {
+            if (isClosing()) {
+                throw new Error("openAuxiliaryPage() was interrupted by close() -- the session is closed, so the page was not opened.", { cause: error });
+            }
+            throw new Error(`openAuxiliaryPage() could not open a page: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        issuedAuxiliaryPages.add(auxiliary);
+        liveAuxiliaryPages.add(auxiliary);
+        auxiliary.on("close", () => {
+            liveAuxiliaryPages.delete(auxiliary);
+        });
+        try {
+            markBlockedRedirects(auxiliary);
+            if (consented !== null)
+                await confineNavigation(auxiliary);
+        }
+        catch (error) {
+            await auxiliary.close().catch(() => undefined);
+            throw new Error(`openAuxiliaryPage() could not apply the session's origin restrictions to the new page, so it was closed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        return auxiliary;
+    };
     return {
         sessionId,
         page,
         startedAt,
         isUsable: () => !crashed && !page.isClosed(),
-        async close() {
-            await context.close();
-            await afterContextClosed();
+        wasBlockedByOriginGuard: (request) => blockedByGuard.has(request),
+        drainOffOriginEvents: () => offOriginEvents.splice(0, offOriginEvents.length),
+        drainDialogEvents: () => dialogEvents.splice(0, dialogEvents.length),
+        drainUnobservedPopups: () => unobservedPopups.splice(0, unobservedPopups.length),
+        sandbox,
+        consentedOrigins: () => (consented === null ? null : [...consented]),
+        openAuxiliaryPage() {
+            auxiliaryRequestsPending += 1;
+            const opened = auxiliaryQueue.then(createAuxiliaryPage);
+            auxiliaryQueue = opened
+                .then(() => undefined, () => undefined)
+                .then(() => {
+                auxiliaryRequestsPending -= 1;
+            });
+            return opened;
+        },
+        close() {
+            closing ??= (async () => {
+                try {
+                    await context.close();
+                }
+                finally {
+                    await afterContextClosed();
+                }
+            })();
+            return closing;
         },
         async saveStorageState(path) {
             if (page.isClosed()) {
@@ -147,14 +533,22 @@ async function createSessionFromBrowser(browser, options, afterContextClosed) {
                     "read, so this would write an empty file that looks like a session with nothing in it. Call it " +
                     "while the session is still open.");
             }
-            await context.storageState({ path });
+            const state = await context.storageState();
+            await writeOwnerOnlyFile(path, JSON.stringify(state));
         },
         async injectStorageState(seed) {
             if (page.isClosed()) {
                 throw new Error("injectStorageState() called after close() -- there is no live browser context to inject into. Call " +
                     "it while the session is still open.");
             }
-            const host = hostnameOf(seed.origin);
+            const seedOrigin = normalizeOrigin(seed.origin);
+            if (seedOrigin === null) {
+                throw new Error(`injectStorageState: "${seed.origin}" is not a valid origin (it has no host, or its origin is opaque), so no cookie domain can be derived from it.`);
+            }
+            if (consented !== null && !consented.has(seedOrigin)) {
+                throw new Error(`injectStorageState: ${seedOrigin} is not among this session's consented origins (${[...consented].join(", ")}); a credential is only injected for an origin the session was consented to.`);
+            }
+            const host = hostnameOf(seedOrigin);
             const cookies = (seed.cookies ?? []).map((cookie) => ({
                 name: cookie.name,
                 value: cookie.value,
@@ -174,7 +568,7 @@ async function createSessionFromBrowser(browser, options, afterContextClosed) {
             let localStorageSkipped = null;
             if (storedEntries.length > 0) {
                 const currentOrigin = originOf(page.url());
-                if (currentOrigin === seed.origin) {
+                if (currentOrigin === seedOrigin) {
                     await page.evaluate((entries) => {
                         // `localStorage` isn't declared under this project's Node-only
                         // `lib` (ES2023, no `dom` -- see tsconfig.base.json's own
@@ -193,7 +587,7 @@ async function createSessionFromBrowser(browser, options, afterContextClosed) {
                 else {
                     localStorageSkipped =
                         `the page is currently on ${currentOrigin ?? "an origin that could not be read from its URL"}, not ` +
-                            `${seed.origin} -- localStorage can only be written for the origin a page is actually showing, so ` +
+                            `${seedOrigin} -- localStorage can only be written for the origin a page is actually showing, so ` +
                             `${storedEntries.length} ${storedEntries.length === 1 ? "entry was" : "entries were"} not injected. ` +
                             "Navigate to that origin first, then call injectStorageState again.";
                 }
@@ -214,9 +608,16 @@ async function createSessionFromBrowser(browser, options, afterContextClosed) {
             if (video === null)
                 return null;
             const videoFilePath = await video.path();
+            const { size } = await stat(videoFilePath);
+            if (size > MAX_VIDEO_BYTES) {
+                await rm(videoDir, { recursive: true, force: true }).catch(() => { });
+                uncollectedVideoDirs.delete(videoDir);
+                throw new VideoTooLargeError(size, MAX_VIDEO_BYTES);
+            }
             const bytes = await readFile(videoFilePath);
             // best-effort: bytes are already captured, so a cleanup failure here must not fail the call.
             await rm(videoDir, { recursive: true, force: true }).catch(() => { });
+            uncollectedVideoDirs.delete(videoDir);
             return bytes;
         },
     };
@@ -311,93 +712,132 @@ function lowerCased(headers) {
 export const SHARED_BROWSER_IDLE_TIMEOUT_MS = 5 * 60 * 1000; // starting value, not a measurement -- see RT-264. Chosen to match
 /** See the module doc above this constant — NOT SHIPPABLE until the isolation test
  *  (`browser-session-reuse.test.ts`) has actually been run and is green. */
-export function createSharedBrowserManager(idleTimeoutMs = SHARED_BROWSER_IDLE_TIMEOUT_MS) {
-    let browser = null;
-    let launchInFlight = null;
-    let liveCount = 0;
-    let idleTimer = null;
-    function cancelIdleTimer() {
-        if (idleTimer !== null) {
-            clearTimeout(idleTimer);
-            idleTimer = null;
+export function createSharedBrowserManager(idleTimeoutMs = SHARED_BROWSER_IDLE_TIMEOUT_MS, seams = {}) {
+    const launch = seams.launch ?? ((options) => chromium.launch(options));
+    const resolveExecutable = seams.resolveExecutable ?? resolveChromiumExecutable;
+    const newSlot = (headless) => ({
+        headless,
+        browser: null,
+        sandbox: { enabled: true, fallbackReason: null },
+        launchInFlight: null,
+        liveCount: 0,
+        pending: 0,
+        idleTimer: null,
+        lostUnexpectedly: false,
+    });
+    const slots = { headless: newSlot(true), headed: newSlot(false) };
+    const slotFor = (headless) => (headless ? slots.headless : slots.headed);
+    function cancelIdleTimer(slot) {
+        if (slot.idleTimer !== null) {
+            clearTimeout(slot.idleTimer);
+            slot.idleTimer = null;
         }
     }
-    function armIdleTimerIfIdle() {
-        cancelIdleTimer();
-        idleTimer = setTimeout(() => {
-            // Re-checked at fire time, not assumed from when the timer was armed -- an
-            // acquireSession() in between already cancelled this timer via
-            // cancelIdleTimer(), so reaching here with liveCount still 0 means the
-            // browser really has sat idle for the whole window.
-            if (liveCount === 0 && browser !== null) {
-                const toClose = browser;
-                browser = null;
+    function armIdleTimerIfIdle(slot) {
+        cancelIdleTimer(slot);
+        if (slot.liveCount > 0 || slot.pending > 0 || slot.browser === null)
+            return;
+        slot.idleTimer = setTimeout(() => {
+            slot.idleTimer = null;
+            if (slot.liveCount === 0 && slot.pending === 0 && slot.browser !== null) {
+                const toClose = slot.browser;
+                slot.browser = null;
                 void toClose.close().catch(() => { });
             }
         }, idleTimeoutMs);
     }
-    async function ensureBrowser() {
-        if (browser !== null)
-            return { ok: true, browser, relaunched: false };
-        if (launchInFlight === null) {
-            launchInFlight = (async () => {
-                const chromiumBinary = resolveChromiumExecutable();
+    async function ensureBrowser(slot) {
+        if (slot.browser !== null && slot.browser.isConnected())
+            return { ok: true, browser: slot.browser, relaunched: false, launched: false };
+        if (slot.browser !== null) {
+            slot.browser = null;
+            slot.lostUnexpectedly = true;
+        }
+        let inFlight = slot.launchInFlight;
+        if (inFlight === null) {
+            inFlight = (async () => {
+                const chromiumBinary = resolveExecutable();
                 if (!chromiumBinary.available) {
                     const { available: _available, ...unavailable } = chromiumBinary;
                     return { ok: false, ...unavailable };
                 }
-                const launched = await chromium.launch({ headless: true, executablePath: chromiumBinary.executablePath });
-                // The shared browser process itself dying (not one page/context) -- noticed
-                // here so the NEXT acquireSession() relaunches rather than resolving a dead
-                // handle. Nulling `browser` (guarded by identity, in case a relaunch has
-                // already replaced it by the time this fires) is the only action taken; a
-                // live session already holding a context on it is left to fail on its own
-                // next call.
+                const { browser: launched, sandbox } = await launchPreferringSandbox(launch, { headless: slot.headless, executablePath: chromiumBinary.executablePath });
+                slot.sandbox = sandbox;
                 launched.on("disconnected", () => {
-                    if (browser === launched)
-                        browser = null;
+                    if (slot.browser === launched) {
+                        slot.browser = null;
+                        slot.lostUnexpectedly = true;
+                    }
                 });
-                return { ok: true, browser: launched };
+                const relaunched = slot.lostUnexpectedly;
+                slot.lostUnexpectedly = false;
+                slot.browser = launched;
+                return { ok: true, browser: launched, relaunched };
             })();
+            slot.launchInFlight = inFlight;
+        }
+        try {
+            const result = await inFlight;
+            return result.ok ? { ...result, launched: true } : result;
+        }
+        finally {
+            if (slot.launchInFlight === inFlight)
+                slot.launchInFlight = null;
         }
-        const result = await launchInFlight;
-        launchInFlight = null;
-        if (!result.ok)
-            return result;
-        const relaunched = browser === null;
-        browser = result.browser;
-        return { ok: true, browser: result.browser, relaunched };
     }
     return {
         async acquireSession(options = {}) {
-            cancelIdleTimer();
-            const ensured = await ensureBrowser();
-            if (!ensured.ok) {
-                return {
-                    launched: false,
-                    refusal: ensured.refusal,
-                    message: ensured.message,
-                    remedy: ensured.remedy,
-                    expectedExecutablePath: ensured.expectedExecutablePath,
+            consentedOriginsOf(options);
+            const slot = slotFor(options.headless ?? true);
+            cancelIdleTimer(slot);
+            slot.pending += 1;
+            try {
+                const ensured = await ensureBrowser(slot);
+                if (!ensured.ok) {
+                    return {
+                        launched: false,
+                        refusal: ensured.refusal,
+                        message: ensured.message,
+                        remedy: ensured.remedy,
+                        expectedExecutablePath: ensured.expectedExecutablePath,
+                    };
+                }
+                slot.liveCount += 1;
+                let released = false;
+                const release = async () => {
+                    if (released)
+                        return;
+                    released = true;
+                    slot.liveCount = Math.max(0, slot.liveCount - 1);
+                    armIdleTimerIfIdle(slot);
                 };
+                let session;
+                try {
+                    session = await createSessionFromBrowser(ensured.browser, options, release, slot.sandbox);
+                }
+                catch (error) {
+                    await release();
+                    throw error;
+                }
+                return { launched: true, session, relaunchedBrowser: ensured.relaunched, launchedBrowser: ensured.launched === true };
+            }
+            finally {
+                slot.pending = Math.max(0, slot.pending - 1);
+                armIdleTimerIfIdle(slot);
             }
-            liveCount += 1;
-            const session = await createSessionFromBrowser(ensured.browser, options, async () => {
-                liveCount = Math.max(0, liveCount - 1);
-                if (liveCount === 0)
-                    armIdleTimerIfIdle();
-            });
-            return { launched: true, session, relaunchedBrowser: ensured.relaunched };
         },
-        liveSessionCount: () => liveCount,
+        liveSessionCount: () => slots.headless.liveCount + slots.headed.liveCount,
         async dispose() {
-            cancelIdleTimer();
-            liveCount = 0;
-            if (browser !== null) {
-                const toClose = browser;
-                browser = null;
-                await toClose.close().catch(() => { });
-            }
+            await Promise.all([slots.headless, slots.headed].map(async (slot) => {
+                cancelIdleTimer(slot);
+                slot.liveCount = 0;
+                slot.lostUnexpectedly = false;
+                if (slot.browser !== null) {
+                    const toClose = slot.browser;
+                    slot.browser = null;
+                    await toClose.close().catch(() => { });
+                }
+            }));
         },
     };
 }