@orkestrel/browser 0.0.5 → 0.0.7

package/dist/src/server/index.js

@@ -1,16 +1,17 @@
-import { BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_WAIT_POLL_INTERVAL_MS, BrowserContext, BrowserError, CDPClient } from "../core/index.js";
+import { BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_WAIT_POLL_INTERVAL_MS, BrowserContext, BrowserError, CDPClient, validateBrowserContextOptions } from "../core/index.js";
+import { attempt, isArray, isError, isInstance, isInteger, isRecord, isString } from "@orkestrel/contract";
 import { existsSync, globSync } from "node:fs";
-import { dirname, posix, win32 } from "node:path";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, posix, resolve, win32 } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
-import { isRecord, isString } from "@orkestrel/contract";
 import { randomBytes } from "node:crypto";
 import { request } from "node:http";
 import { request as request$1 } from "node:https";
 import { Emitter } from "@orkestrel/emitter";
 import { WEBSOCKET_READY_CLOSED, WEBSOCKET_READY_OPEN, WEBSOCKET_VERSION, computeWebSocketAccept, createNodeWebSocket } from "@orkestrel/websocket";
 import { addAbortListener, once } from "node:events";
-import { mkdir, writeFile } from "node:fs/promises";
 //#region src/server/constants.ts
 /** Default CDP port probed for an existing browser and used for launches. */
 var BROWSER_DEFAULT_CDP_PORT = 9222;
@@ -26,7 +27,9 @@ var BROWSER_CDP_LIST_PATH = "/json/list";
 var BROWSER_LAUNCH_ARGS = Object.freeze(["--no-first-run", "--no-default-browser-check"]);
 /** Flag enabling headless mode on a launched browser process. */
 var BROWSER_HEADLESS_ARG = "--headless=new";
-/** Grace period after SIGTERM before a launched process is escalated to SIGKILL during teardown. */
+/** Prefix for isolated browser profiles created beneath the operating-system temp directory. */
+var BROWSER_PROFILE_PREFIX = "orkestrel-browser-";
+/** Bound for each launched-process exit window during TERM-to-KILL teardown. */
 var BROWSER_KILL_GRACE_MS = 3e3;
 /** Bound for the `discover: false` port-occupancy probe before launching — short, since it only needs to detect an already-listening CDP endpoint, not perform full discovery. */
 var BROWSER_PORT_PROBE_TIMEOUT_MS = 200;
@@ -157,7 +160,7 @@ var BrowserDestroyedError = class extends BrowserError {
 * @returns True when value is a BrowserConnectionError instance
 */
 function isBrowserConnectionError(value) {
-	return value instanceof BrowserConnectionError;
+	return isInstance(value, BrowserConnectionError);
 }
 /**
 * Narrow an unknown value to BrowserNotConnectedError.
@@ -166,7 +169,7 @@ function isBrowserConnectionError(value) {
 * @returns True when value is a BrowserNotConnectedError instance
 */
 function isBrowserNotConnectedError(value) {
-	return value instanceof BrowserNotConnectedError;
+	return isInstance(value, BrowserNotConnectedError);
 }
 /**
 * Narrow an unknown value to BrowserDestroyedError.
@@ -175,7 +178,7 @@ function isBrowserNotConnectedError(value) {
 * @returns True when value is a BrowserDestroyedError instance
 */
 function isBrowserDestroyedError(value) {
-	return value instanceof BrowserDestroyedError;
+	return isInstance(value, BrowserDestroyedError);
 }
 //#endregion
 //#region src/server/helpers.ts
@@ -263,6 +266,44 @@ function browserToEngine(browser) {
 	if (browser?.includes("Chrome/") === true) return "chrome";
 	return "chromium";
 }
+/**
+* Resolve a persistent caller profile or create an isolated temporary one.
+*
+* @param path - Optional caller-owned persistent user-data directory
+* @returns The resolved profile and whether the library owns its lifecycle
+*/
+async function createBrowserProfile(path) {
+	if (path !== void 0) return {
+		path,
+		temporary: false
+	};
+	return {
+		path: await mkdtemp(join(tmpdir(), BROWSER_PROFILE_PREFIX)),
+		temporary: true
+	};
+}
+/**
+* Remove a library-owned isolated browser profile.
+*
+* @remarks
+* The path must remain a direct child of the operating-system temp directory
+* with {@link BROWSER_PROFILE_PREFIX}; this defensive check prevents a
+* malformed profile value from widening recursive deletion.
+*
+* @param profile - Resolved profile lifecycle result
+*/
+async function removeBrowserProfile(profile) {
+	if (!profile.temporary) return;
+	const path = resolve(profile.path);
+	const temporary = resolve(tmpdir());
+	if (dirname(path) !== temporary || !basename(path).startsWith("orkestrel-browser-")) throw new Error("Refusing to remove an unsafe browser profile path");
+	await rm(path, {
+		recursive: true,
+		force: true,
+		maxRetries: 3,
+		retryDelay: 100
+	});
+}
 /** Check the env-override keys (`PLAYWRIGHT_EXECUTABLE_PATH`, `CHROME_PATH`) in order for an existing file. */
 function findEnvOverride(env) {
 	return findAllEnvOverrides(env)[0];
@@ -353,6 +394,10 @@ function findAllInStore(base, platform) {
 /**
 * Launch a browser process with raw-CDP debugging flags.
 *
+* @remarks
+* POSIX launches own an isolated process group so lifecycle teardown can
+* signal and await every Chromium subprocess without affecting the caller.
+*
 * @param executable - Absolute path to the browser executable
 * @param port - Port the browser exposes its CDP endpoint on
 * @param headless - Whether to launch in headless mode
@@ -366,7 +411,10 @@ function launchBrowserProcess(executable, port, headless, profile, extra) {
 	args.push(`--remote-debugging-port=${port}`, ...BROWSER_LAUNCH_ARGS);
 	if (headless) args.push(BROWSER_HEADLESS_ARG);
 	if (profile !== void 0) args.push(`--user-data-dir=${profile}`);
-	return spawn(executable, args, { stdio: "ignore" });
+	return spawn(executable, args, {
+		stdio: "ignore",
+		detached: process.platform !== "win32"
+	});
 }
 /**
 * Poll a browser's CDP version endpoint until it responds or the timeout elapses.
@@ -415,7 +463,7 @@ async function fetchCDPTargets(port, timeout, host = BROWSER_DEFAULT_HOST) {
 		const response = await fetch(url, { signal: controller.signal });
 		if (!response.ok) return [];
 		const list = await response.json();
-		if (!Array.isArray(list)) return [];
+		if (!isArray(list)) return [];
 		const targets = [];
 		for (const entry of list) {
 			if (!isRecord(entry)) continue;
@@ -457,11 +505,11 @@ var WebSocketCDPTransport = class {
 	#reject;
 	#timer;
 	#closeResolve;
-	#onSocketClose = () => this.#closeResolve?.();
+	#onSocketClose = this.#handleSocketClose.bind(this);
 	constructor(options) {
 		this.#emitter = new Emitter({
-			on: options.on,
-			error: options.error
+			...options.on !== void 0 ? { on: options.on } : {},
+			...options.error !== void 0 ? { error: options.error } : {}
 		});
 		this.#url = options.url;
 		this.#timeout = options.timeout ?? BROWSER_DEFAULT_TIMEOUT_MS;
@@ -479,12 +527,12 @@ var WebSocketCDPTransport = class {
 		}
 		this.#socket?.destroy();
 		this.#socket = void 0;
-		const attempt = this.#open();
-		this.#starting = attempt;
+		const transition = this.#open();
+		this.#starting = transition;
 		try {
-			await attempt;
+			await transition;
 		} finally {
-			if (this.#starting === attempt) this.#starting = void 0;
+			if (this.#starting === transition) this.#starting = void 0;
 		}
 	}
 	async send(data) {
@@ -498,16 +546,21 @@ var WebSocketCDPTransport = class {
 			await active;
 			return;
 		}
-		const attempt = this.#stop();
-		this.#closing = attempt;
+		const transition = this.#stop();
+		this.#closing = transition;
 		try {
-			await attempt;
+			await transition;
 		} finally {
-			if (this.#closing === attempt) this.#closing = void 0;
+			if (this.#closing === transition) this.#closing = void 0;
 		}
 	}
 	async #open() {
-		const url = new URL(this.#url);
+		const parsed = attempt(() => new URL(this.#url));
+		if (!parsed.success) throw new BrowserConnectionError(`WebSocket CDP URL is invalid: ${this.#url}`, {
+			url: this.#url,
+			error: parsed.error
+		});
+		const url = parsed.value;
 		if (url.protocol !== "ws:" && url.protocol !== "wss:") throw new BrowserConnectionError(`WebSocket CDP connection requires a ws: or wss: URL: ${this.#url}`, { url: this.#url });
 		const key = randomBytes(16).toString("base64");
 		const deferred = Promise.withResolvers();
@@ -627,6 +680,9 @@ var WebSocketCDPTransport = class {
 		});
 		socket.emitter.on("error", (error) => this.#emitter.emit("error", error));
 	}
+	#handleSocketClose() {
+		this.#closeResolve?.();
+	}
 };
 //#endregion
 //#region src/server/factories.ts
@@ -669,6 +725,9 @@ function createScreenshotWriter() {
 }
 //#endregion
 //#region src/server/Browser.ts
+/**
+* Discovers, launches, connects to, and owns Chromium-family browser sessions.
+*/
 var Browser = class {
 	#emitter;
 	#options;
@@ -682,19 +741,21 @@ var Browser = class {
 	#endpoint;
 	#client;
 	#process;
+	#profile;
 	#contexts = [];
 	#destroyed = false;
 	#connecting;
 	#disconnecting;
+	#exitCleanup;
 	#shutdown;
 	#transport;
-	#onTransportClose = () => this.#handleTransportLoss();
-	#onTransportError = () => this.#handleTransportLoss();
-	#onProcessExit = () => this.#handleProcessExit();
+	#onTransportClose = this.#handleTransportLoss.bind(this);
+	#onTransportError = this.#handleTransportLoss.bind(this);
+	#onProcessExit = this.#handleProcessExit.bind(this);
 	constructor(options) {
 		this.#emitter = new Emitter({
-			on: options?.on,
-			error: options?.error
+			...options?.on !== void 0 ? { on: options.on } : {},
+			...options?.error !== void 0 ? { error: options.error } : {}
 		});
 		this.#options = options ?? {};
 		this.#engine = this.#options.engine ?? (this.#options.executable !== void 0 ? parseBrowserEngine(this.#options.executable) ?? "chromium" : "chromium");
@@ -730,14 +791,12 @@ var Browser = class {
 	}
 	async connect() {
 		if (this.#destroyed) throw new BrowserDestroyedError();
-		if (this.#disconnecting !== void 0) await this.#disconnecting;
-		if (this.#destroyed) throw new BrowserDestroyedError();
-		if (this.#status === "connected") return;
 		const active = this.#connecting;
 		if (active !== void 0) {
 			await active;
 			return;
 		}
+		if (this.#status === "connected") return;
 		const attempt = this.#establish();
 		this.#connecting = attempt;
 		try {
@@ -753,15 +812,11 @@ var Browser = class {
 	}
 	async disconnect() {
 		if (this.#destroyed) return;
-		const active = this.#disconnecting;
-		if (active !== void 0) {
-			await active;
-			return;
-		}
-		if (this.#connecting !== void 0) {
-			await this.#connecting.catch(() => void 0);
-			if (this.#destroyed) return;
-		}
+		const disconnecting = this.#disconnecting;
+		const connecting = this.#connecting;
+		if (disconnecting !== void 0) await disconnecting;
+		if (connecting !== void 0) await connecting.catch(() => void 0);
+		if (this.#destroyed) return;
 		if (this.#status !== "connected" || this.#client === void 0) return;
 		const attempt = this.#detach();
 		this.#disconnecting = attempt;
@@ -779,6 +834,35 @@ var Browser = class {
 	contexts() {
 		return [...this.#contexts];
 	}
+	async isolate(options) {
+		if (this.#destroyed) throw new BrowserDestroyedError();
+		const client = this.#client;
+		if (this.#status !== "connected" || client === void 0) throw new BrowserNotConnectedError();
+		validateBrowserContextOptions(options);
+		const params = { disposeOnDetach: false };
+		if (options?.proxy !== void 0) {
+			params["proxyServer"] = options.proxy.server;
+			if (options.proxy.bypass !== void 0) params["proxyBypassList"] = options.proxy.bypass.join(",");
+		}
+		if (options?.origins !== void 0) params["originsWithUniversalNetworkAccess"] = [...options.origins];
+		const result = await client.send("Target.createBrowserContext", params);
+		if (!isRecord(result) || !isString(result["browserContextId"])) throw new BrowserConnectionError("Failed to create isolated browser context");
+		const id = result["browserContextId"];
+		const context = new BrowserContext(client, id, options?.emulation?.viewport ?? this.#options.viewport, createScreenshotWriter(), options?.emulation, options?.downloads);
+		try {
+			if (options?.downloads !== void 0) await client.send("Browser.setDownloadBehavior", {
+				behavior: options.downloads.named === true ? "allowAndName" : "allow",
+				browserContextId: id,
+				downloadPath: options.downloads.path,
+				eventsEnabled: true
+			});
+		} catch (error) {
+			await context.close().catch(() => void 0);
+			throw error;
+		}
+		this.#registerContext(context);
+		return context;
+	}
 	async create(options) {
 		if (this.#destroyed) throw new BrowserDestroyedError();
 		const client = this.#client;
@@ -786,7 +870,7 @@ var Browser = class {
 		let context = this.#contexts[0];
 		if (context === void 0) {
 			context = new BrowserContext(client, void 0, this.#options.viewport, createScreenshotWriter());
-			this.#contexts.push(context);
+			this.#registerContext(context);
 		}
 		const page = await context.create(options);
 		this.#emitter.emit("page", page);
@@ -813,6 +897,10 @@ var Browser = class {
 		return shutdown;
 	}
 	async #establish() {
+		if (this.#disconnecting !== void 0) await this.#disconnecting;
+		await this.#settleExit();
+		if (this.#destroyed) throw new BrowserDestroyedError();
+		if (this.#status === "connected") return;
 		this.#assertNotAborted();
 		this.#status = "connecting";
 		try {
@@ -839,8 +927,8 @@ var Browser = class {
 			if (this.#destroyed) throw new BrowserDestroyedError();
 			this.#status = "error";
 			this.#emitter.emit("error", error);
-			if (error instanceof BrowserConnectionError) throw error;
-			throw new BrowserConnectionError(error instanceof Error ? error.message : String(error), { executable: this.#options.executable });
+			if (isBrowserConnectionError(error)) throw error;
+			throw new BrowserConnectionError(isError(error) ? error.message : String(error), { executable: this.#options.executable });
 		}
 	}
 	async #detach() {
@@ -886,17 +974,19 @@ var Browser = class {
 		const connected = this.#status === "connected";
 		const client = this.#client;
 		const contexts = this.#contexts;
+		const process = this.#process;
 		this.#unbindTransport();
 		this.#unbindProcess();
 		this.#process = void 0;
+		const cleanup = this.#cleanupExitedProcess(process, contexts, client);
+		this.#exitCleanup = cleanup;
+		cleanup.catch((error) => this.#emitter.emit("error", error));
 		this.#client = void 0;
 		this.#contexts = [];
 		this.#connection = void 0;
 		this.#owned = void 0;
 		this.#endpoint = void 0;
 		if (connected) this.#status = "disconnected";
-		this.#destroyContextList(contexts);
-		this.#closeClient(client);
 		this.#emitter.emit("error", new BrowserConnectionError("The browser process exited unexpectedly", { cause: BROWSER_PROCESS_EXIT_CAUSE }));
 		if (connected) {
 			this.#emitter.emit("disconnect");
@@ -1056,15 +1146,23 @@ var Browser = class {
 		else {
 			const found = findSystemBrowser({
 				...this.#options.browsers,
-				engine: requestedEngine
+				...requestedEngine !== void 0 ? { engine: requestedEngine } : {}
 			});
 			executable = found?.executable;
 			resolvedEngine = found?.engine;
 		}
 		if (executable === void 0) throw new BrowserConnectionError("No Chromium browser found. Install Chrome, Edge, or Chromium.", requestedEngine === void 0 ? void 0 : { engine: requestedEngine });
 		this.#engine = resolvedEngine ?? "chromium";
-		const profile = this.#options.profile;
-		const process = launchBrowserProcess(executable, this.#cdpPort, this.#options.headless ?? true, profile, this.#options.args);
+		await this.#releaseProfile();
+		const profile = await createBrowserProfile(this.#options.profile);
+		this.#profile = profile;
+		let process;
+		try {
+			process = launchBrowserProcess(executable, this.#cdpPort, this.#options.headless ?? true, profile.path, this.#options.args);
+		} catch (error) {
+			await this.#releaseProfile();
+			throw error;
+		}
 		this.#process = process;
 		let client;
 		try {
@@ -1078,7 +1176,7 @@ var Browser = class {
 				timeout: this.#timeout()
 			});
 			await this.#raceAbort(client.connect());
-			const connection = profile === void 0 ? "launch" : "persistent";
+			const connection = this.#options.profile === void 0 ? "launch" : "persistent";
 			this.#client = client;
 			this.#endpoint = endpoint;
 			this.#connection = connection;
@@ -1094,6 +1192,7 @@ var Browser = class {
 			this.#unbindProcess();
 			await this.#closeClient(client);
 			await this.#terminate(process);
+			await this.#releaseProfile();
 			this.#process = void 0;
 			this.#client = void 0;
 			this.#endpoint = void 0;
@@ -1110,16 +1209,16 @@ var Browser = class {
 		const signal = AbortSignal.any([controller.signal, this.#signal()]);
 		const ready = waitForCDPReady(this.#cdpPort, this.#timeout(), this.#cdpHost, signal);
 		const exited = once(process, "exit", { signal }).then((values) => {
-			const code = typeof values[0] === "number" ? values[0] : null;
-			const exitSignal = typeof values[1] === "string" ? values[1] : null;
+			const code = isInteger(values[0]) ? values[0] : null;
+			const exitSignal = isString(values[1]) ? values[1] : null;
 			throw new BrowserConnectionError(this.#formatLaunchExit(code, exitSignal), context);
 		});
 		try {
 			return await Promise.race([ready, exited]);
 		} catch (error) {
-			if (error instanceof BrowserConnectionError) throw error;
+			if (isBrowserConnectionError(error)) throw error;
 			if (this.#signal().aborted) throw new BrowserConnectionError("Connection aborted", context);
-			throw new BrowserConnectionError(error instanceof Error ? error.message : String(error), context);
+			throw new BrowserConnectionError(isError(error) ? error.message : String(error), context);
 		} finally {
 			controller.abort();
 			ready.catch(() => void 0);
@@ -1144,7 +1243,7 @@ var Browser = class {
 		} catch {
 			return;
 		}
-		if (!isRecord(result) || !Array.isArray(result["targetInfos"])) return;
+		if (!isRecord(result) || !isArray(result["targetInfos"])) return;
 		const pages = [];
 		for (const target of result["targetInfos"]) {
 			if (!isRecord(target) || !isString(target["targetId"]) || target["type"] !== "page" || !isString(target["title"]) || !isString(target["url"])) continue;
@@ -1158,9 +1257,10 @@ var Browser = class {
 		if (pages.length === 0 || this.#contexts.length > 0) return;
 		const context = new BrowserContext(client, void 0, this.#options.viewport, createScreenshotWriter());
 		await context.sync(pages);
-		this.#contexts.push(context);
+		this.#registerContext(context);
 	}
 	async #destroyResources() {
+		let terminated = false;
 		try {
 			await this.#settle();
 			this.#unbindTransport();
@@ -1173,13 +1273,22 @@ var Browser = class {
 			this.#contexts = [];
 			await this.#terminate(this.#process);
 			this.#process = void 0;
-			await this.#closeClient(client);
-			this.#client = void 0;
+			terminated = true;
 		} finally {
-			this.#finish();
+			const contexts = this.#contexts;
+			this.#contexts = [];
+			const client = this.#client;
+			this.#client = void 0;
+			try {
+				await this.#cleanupLocal(contexts, client);
+				if (terminated) await this.#releaseProfile();
+			} finally {
+				this.#finish();
+			}
 		}
 	}
 	async #closeResources() {
+		let terminated = false;
 		try {
 			await this.#settle();
 			this.#unbindTransport();
@@ -1190,18 +1299,33 @@ var Browser = class {
 			await this.#closeRemote(client);
 			const process = this.#process;
 			if (process !== void 0) {
-				if (!await this.#waitForProcessWithin(process, 3e3)) await this.#terminate(process);
+				if (!await this.#waitForTerminationWithin(process, 3e3)) await this.#terminate(process);
 			}
 			this.#process = void 0;
-			await this.#closeClient(client);
-			this.#client = void 0;
+			terminated = true;
 		} finally {
-			this.#finish();
+			const contexts = this.#contexts;
+			this.#contexts = [];
+			const client = this.#client;
+			this.#client = void 0;
+			try {
+				await this.#cleanupLocal(contexts, client);
+				if (terminated) await this.#releaseProfile();
+			} finally {
+				this.#finish();
+			}
 		}
 	}
 	async #settle() {
 		await this.#connecting?.catch(() => void 0);
 		await this.#disconnecting?.catch(() => void 0);
+		await this.#settleExit();
+	}
+	async #settleExit() {
+		const cleanup = this.#exitCleanup;
+		if (cleanup === void 0) return;
+		await cleanup;
+		if (this.#exitCleanup === cleanup) this.#exitCleanup = void 0;
 	}
 	async #closeRemote(client) {
 		let remote = client;
@@ -1228,12 +1352,20 @@ var Browser = class {
 		if (temporary) await this.#closeClient(remote);
 	}
 	async #closeContexts() {
-		for (const context of this.#contexts) try {
+		for (const context of [...this.#contexts]) try {
 			await context.close();
 		} catch {}
 	}
 	async #destroyContexts() {
-		await this.#destroyContextList(this.#contexts);
+		await this.#destroyContextList([...this.#contexts]);
+	}
+	#registerContext(context) {
+		this.#contexts.push(context);
+		context.emitter.on("close", () => {
+			const index = this.#contexts.indexOf(context);
+			if (index >= 0) this.#contexts.splice(index, 1);
+		});
+		this.#emitter.emit("context", context);
 	}
 	async #destroyContextList(contexts) {
 		for (const context of contexts) try {
@@ -1246,9 +1378,24 @@ var Browser = class {
 			await client.close();
 		} catch {}
 	}
-	async #waitForProcess(process) {
-		if (process.exitCode !== null || process.signalCode !== null) return;
-		await once(process, "exit");
+	async #releaseProfile() {
+		const profile = this.#profile;
+		this.#profile = void 0;
+		if (profile !== void 0) await removeBrowserProfile(profile);
+	}
+	async #cleanupExitedProcess(process, contexts, client) {
+		let terminated = false;
+		try {
+			await this.#terminate(process);
+			terminated = true;
+		} finally {
+			await this.#cleanupLocal(contexts, client);
+		}
+		if (terminated) await this.#releaseProfile();
+	}
+	async #cleanupLocal(contexts, client) {
+		await this.#destroyContextList(contexts);
+		await this.#closeClient(client);
 	}
 	async #waitForProcessWithin(process, timeout) {
 		if (process.exitCode !== null || process.signalCode !== null) return true;
@@ -1261,20 +1408,55 @@ var Browser = class {
 			throw error;
 		}
 	}
-	async #terminate(process) {
-		if (process === void 0 || process.exitCode !== null || process.signalCode !== null) return;
+	#hasProcessGroup(process) {
+		const pid = process.pid;
+		return globalThis.process.platform !== "win32" && pid !== void 0 && pid > 0;
+	}
+	#inspectProcessGroup(process) {
+		if (!this.#hasProcessGroup(process)) return false;
+		return this.#signalProcess(process, 0);
+	}
+	#signalProcess(process, signal) {
+		const pid = process.pid;
 		try {
-			process.kill("SIGTERM");
-		} catch {
-			return;
+			if (this.#hasProcessGroup(process) && pid !== void 0) return globalThis.process.kill(-pid, signal);
+			return process.kill(signal);
+		} catch (error) {
+			const code = isError(error) && "code" in error && isString(error.code) ? error.code : void 0;
+			if (code === "ESRCH") return false;
+			if (signal === 0) return code === "EPERM" ? true : void 0;
+			throw new BrowserConnectionError("Failed to signal the browser process", {
+				pid,
+				signal,
+				cause: error
+			});
 		}
-		if (await this.#waitForProcessWithin(process, 3e3)) return;
-		try {
-			process.kill("SIGKILL");
-		} catch {
-			return;
+	}
+	async #waitForProcessGroupWithin(process, timeout) {
+		const deadline = performance.now() + timeout;
+		let confirmed = false;
+		while (true) {
+			const alive = this.#inspectProcessGroup(process);
+			if (alive === false) return true;
+			if (alive === true) confirmed = true;
+			const remaining = deadline - performance.now();
+			if (remaining <= 0) return confirmed ? false : void 0;
+			await new Promise((resolve) => setTimeout(resolve, Math.min(BROWSER_WAIT_POLL_INTERVAL_MS, remaining)));
 		}
-		await this.#waitForProcess(process);
+	}
+	async #waitForTerminationWithin(process, timeout, final = false) {
+		const exited = this.#waitForProcessWithin(process, timeout);
+		const drained = this.#waitForProcessGroupWithin(process, timeout);
+		const results = await Promise.all([exited, drained]);
+		return results[0] && (results[1] === true || final && results[1] === void 0);
+	}
+	async #terminate(process) {
+		if (process === void 0 || (process.exitCode !== null || process.signalCode !== null) && this.#inspectProcessGroup(process) === false) return;
+		if (this.#signalProcess(process, "SIGTERM") === false) return;
+		if (await this.#waitForTerminationWithin(process, 3e3)) return;
+		if (this.#signalProcess(process, "SIGKILL") === false) return;
+		if (await this.#waitForTerminationWithin(process, 3e3, true)) return;
+		throw new BrowserConnectionError("Browser process did not exit after SIGKILL", { pid: process.pid });
 	}
 	#finish() {
 		this.#unbindTransport();
@@ -1285,12 +1467,13 @@ var Browser = class {
 		this.#endpoint = void 0;
 		this.#client = void 0;
 		this.#process = void 0;
+		this.#exitCleanup = void 0;
 		this.#contexts = [];
 		this.#emitter.emit("destroy");
 		this.#emitter.destroy();
 	}
 };
 //#endregion
-export { BROWSER_CDP_LIST_PATH, BROWSER_CDP_PROTOCOL, BROWSER_CDP_VERSION_PATH, BROWSER_DEFAULT_CDP_PORT, BROWSER_DEFAULT_HOST, BROWSER_ENGINE_HINTS, BROWSER_ENV_PATH_KEYS, BROWSER_EXECUTABLE_NAMES, BROWSER_EXECUTABLE_PATHS, BROWSER_HEADLESS_ARG, BROWSER_KILL_GRACE_MS, BROWSER_LAUNCH_ARGS, BROWSER_PORT_PROBE_TIMEOUT_MS, BROWSER_PROCESS_EXIT_CAUSE, BROWSER_STORE_CACHE_DIRS, BROWSER_STORE_DEFAULT_DIRS, BROWSER_STORE_ENV_KEY, BROWSER_STORE_GLOBS, BROWSER_STORE_LINK_NAME, BROWSER_TRANSPORT_LOSS_CAUSE, BROWSER_TRANSPORT_LOSS_DEFER_MS, BROWSER_WINDOWS_ROOT_FALLBACKS, BROWSER_WINDOWS_SUFFIXES, Browser, BrowserConnectionError, BrowserDestroyedError, BrowserNotConnectedError, WebSocketCDPTransport, browserToEngine, createBrowser, createCDPTransport, createScreenshotWriter, defaultInstallPaths, defaultStoreBases, fetchCDPTargets, findAllEnvOverrides, findAllInStore, findAllInstallPaths, findEnvOverride, findInStore, findInstallPath, findSystemBrowser, findSystemBrowsers, isBrowserConnectionError, isBrowserDestroyedError, isBrowserNotConnectedError, launchBrowserProcess, normalizeExecutablePath, parseBrowserEngine, probeAllPathNames, probePathNames, waitForCDPReady, windowsRoots };
+export { BROWSER_CDP_LIST_PATH, BROWSER_CDP_PROTOCOL, BROWSER_CDP_VERSION_PATH, BROWSER_DEFAULT_CDP_PORT, BROWSER_DEFAULT_HOST, BROWSER_ENGINE_HINTS, BROWSER_ENV_PATH_KEYS, BROWSER_EXECUTABLE_NAMES, BROWSER_EXECUTABLE_PATHS, BROWSER_HEADLESS_ARG, BROWSER_KILL_GRACE_MS, BROWSER_LAUNCH_ARGS, BROWSER_PORT_PROBE_TIMEOUT_MS, BROWSER_PROCESS_EXIT_CAUSE, BROWSER_PROFILE_PREFIX, BROWSER_STORE_CACHE_DIRS, BROWSER_STORE_DEFAULT_DIRS, BROWSER_STORE_ENV_KEY, BROWSER_STORE_GLOBS, BROWSER_STORE_LINK_NAME, BROWSER_TRANSPORT_LOSS_CAUSE, BROWSER_TRANSPORT_LOSS_DEFER_MS, BROWSER_WINDOWS_ROOT_FALLBACKS, BROWSER_WINDOWS_SUFFIXES, Browser, BrowserConnectionError, BrowserDestroyedError, BrowserNotConnectedError, WebSocketCDPTransport, browserToEngine, createBrowser, createBrowserProfile, createCDPTransport, createScreenshotWriter, defaultInstallPaths, defaultStoreBases, fetchCDPTargets, findAllEnvOverrides, findAllInStore, findAllInstallPaths, findEnvOverride, findInStore, findInstallPath, findSystemBrowser, findSystemBrowsers, isBrowserConnectionError, isBrowserDestroyedError, isBrowserNotConnectedError, launchBrowserProcess, normalizeExecutablePath, parseBrowserEngine, probeAllPathNames, probePathNames, removeBrowserProfile, waitForCDPReady, windowsRoots };
 
 //# sourceMappingURL=index.js.map