@orkestrel/browser 0.0.5 → 0.0.7

package/dist/src/server/index.cjs

@@ -1,17 +1,18 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _src_core = require("../core/index.cjs");
+let _orkestrel_contract = require("@orkestrel/contract");
 let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
+let node_os = require("node:os");
 let node_path = require("node:path");
 let node_child_process = require("node:child_process");
 let node_timers_promises = require("node:timers/promises");
-let _orkestrel_contract = require("@orkestrel/contract");
 let node_crypto = require("node:crypto");
 let node_http = require("node:http");
 let node_https = require("node:https");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 let _orkestrel_websocket = require("@orkestrel/websocket");
 let node_events = require("node:events");
-let node_fs_promises = require("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;
@@ -27,7 +28,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;
@@ -158,7 +161,7 @@ var BrowserDestroyedError = class extends _src_core.BrowserError {
 * @returns True when value is a BrowserConnectionError instance
 */
 function isBrowserConnectionError(value) {
-	return value instanceof BrowserConnectionError;
+	return (0, _orkestrel_contract.isInstance)(value, BrowserConnectionError);
 }
 /**
 * Narrow an unknown value to BrowserNotConnectedError.
@@ -167,7 +170,7 @@ function isBrowserConnectionError(value) {
 * @returns True when value is a BrowserNotConnectedError instance
 */
 function isBrowserNotConnectedError(value) {
-	return value instanceof BrowserNotConnectedError;
+	return (0, _orkestrel_contract.isInstance)(value, BrowserNotConnectedError);
 }
 /**
 * Narrow an unknown value to BrowserDestroyedError.
@@ -176,7 +179,7 @@ function isBrowserNotConnectedError(value) {
 * @returns True when value is a BrowserDestroyedError instance
 */
 function isBrowserDestroyedError(value) {
-	return value instanceof BrowserDestroyedError;
+	return (0, _orkestrel_contract.isInstance)(value, BrowserDestroyedError);
 }
 //#endregion
 //#region src/server/helpers.ts
@@ -264,6 +267,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 (0, node_fs_promises.mkdtemp)((0, node_path.join)((0, node_os.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 = (0, node_path.resolve)(profile.path);
+	const temporary = (0, node_path.resolve)((0, node_os.tmpdir)());
+	if ((0, node_path.dirname)(path) !== temporary || !(0, node_path.basename)(path).startsWith("orkestrel-browser-")) throw new Error("Refusing to remove an unsafe browser profile path");
+	await (0, node_fs_promises.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];
@@ -354,6 +395,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
@@ -367,7 +412,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 (0, node_child_process.spawn)(executable, args, { stdio: "ignore" });
+	return (0, node_child_process.spawn)(executable, args, {
+		stdio: "ignore",
+		detached: process.platform !== "win32"
+	});
 }
 /**
 * Poll a browser's CDP version endpoint until it responds or the timeout elapses.
@@ -416,7 +464,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 (!(0, _orkestrel_contract.isArray)(list)) return [];
 		const targets = [];
 		for (const entry of list) {
 			if (!(0, _orkestrel_contract.isRecord)(entry)) continue;
@@ -458,11 +506,11 @@ var WebSocketCDPTransport = class {
 	#reject;
 	#timer;
 	#closeResolve;
-	#onSocketClose = () => this.#closeResolve?.();
+	#onSocketClose = this.#handleSocketClose.bind(this);
 	constructor(options) {
 		this.#emitter = new _orkestrel_emitter.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 ?? _src_core.BROWSER_DEFAULT_TIMEOUT_MS;
@@ -480,12 +528,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) {
@@ -499,16 +547,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 = (0, _orkestrel_contract.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 = (0, node_crypto.randomBytes)(16).toString("base64");
 		const deferred = Promise.withResolvers();
@@ -628,6 +681,9 @@ var WebSocketCDPTransport = class {
 		});
 		socket.emitter.on("error", (error) => this.#emitter.emit("error", error));
 	}
+	#handleSocketClose() {
+		this.#closeResolve?.();
+	}
 };
 //#endregion
 //#region src/server/factories.ts
@@ -670,6 +726,9 @@ function createScreenshotWriter() {
 }
 //#endregion
 //#region src/server/Browser.ts
+/**
+* Discovers, launches, connects to, and owns Chromium-family browser sessions.
+*/
 var Browser = class {
 	#emitter;
 	#options;
@@ -683,19 +742,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 _orkestrel_emitter.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");
@@ -731,14 +792,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 {
@@ -754,15 +813,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;
@@ -780,6 +835,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();
+		(0, _src_core.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 (!(0, _orkestrel_contract.isRecord)(result) || !(0, _orkestrel_contract.isString)(result["browserContextId"])) throw new BrowserConnectionError("Failed to create isolated browser context");
+		const id = result["browserContextId"];
+		const context = new _src_core.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;
@@ -787,7 +871,7 @@ var Browser = class {
 		let context = this.#contexts[0];
 		if (context === void 0) {
 			context = new _src_core.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);
@@ -814,6 +898,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 {
@@ -840,8 +928,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((0, _orkestrel_contract.isError)(error) ? error.message : String(error), { executable: this.#options.executable });
 		}
 	}
 	async #detach() {
@@ -887,17 +975,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");
@@ -1057,15 +1147,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 {
@@ -1079,7 +1177,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;
@@ -1095,6 +1193,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;
@@ -1111,16 +1210,16 @@ var Browser = class {
 		const signal = AbortSignal.any([controller.signal, this.#signal()]);
 		const ready = waitForCDPReady(this.#cdpPort, this.#timeout(), this.#cdpHost, signal);
 		const exited = (0, node_events.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 = (0, _orkestrel_contract.isInteger)(values[0]) ? values[0] : null;
+			const exitSignal = (0, _orkestrel_contract.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((0, _orkestrel_contract.isError)(error) ? error.message : String(error), context);
 		} finally {
 			controller.abort();
 			ready.catch(() => void 0);
@@ -1145,7 +1244,7 @@ var Browser = class {
 		} catch {
 			return;
 		}
-		if (!(0, _orkestrel_contract.isRecord)(result) || !Array.isArray(result["targetInfos"])) return;
+		if (!(0, _orkestrel_contract.isRecord)(result) || !(0, _orkestrel_contract.isArray)(result["targetInfos"])) return;
 		const pages = [];
 		for (const target of result["targetInfos"]) {
 			if (!(0, _orkestrel_contract.isRecord)(target) || !(0, _orkestrel_contract.isString)(target["targetId"]) || target["type"] !== "page" || !(0, _orkestrel_contract.isString)(target["title"]) || !(0, _orkestrel_contract.isString)(target["url"])) continue;
@@ -1159,9 +1258,10 @@ var Browser = class {
 		if (pages.length === 0 || this.#contexts.length > 0) return;
 		const context = new _src_core.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();
@@ -1174,13 +1274,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();
@@ -1191,18 +1300,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;
@@ -1229,12 +1353,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 {
@@ -1247,9 +1379,24 @@ var Browser = class {
 			await client.close();
 		} catch {}
 	}
-	async #waitForProcess(process) {
-		if (process.exitCode !== null || process.signalCode !== null) return;
-		await (0, node_events.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;
@@ -1262,20 +1409,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 = (0, _orkestrel_contract.isError)(error) && "code" in error && (0, _orkestrel_contract.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(_src_core.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();
@@ -1286,6 +1468,7 @@ 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();
@@ -1306,6 +1489,7 @@ exports.BROWSER_KILL_GRACE_MS = BROWSER_KILL_GRACE_MS;
 exports.BROWSER_LAUNCH_ARGS = BROWSER_LAUNCH_ARGS;
 exports.BROWSER_PORT_PROBE_TIMEOUT_MS = BROWSER_PORT_PROBE_TIMEOUT_MS;
 exports.BROWSER_PROCESS_EXIT_CAUSE = BROWSER_PROCESS_EXIT_CAUSE;
+exports.BROWSER_PROFILE_PREFIX = BROWSER_PROFILE_PREFIX;
 exports.BROWSER_STORE_CACHE_DIRS = BROWSER_STORE_CACHE_DIRS;
 exports.BROWSER_STORE_DEFAULT_DIRS = BROWSER_STORE_DEFAULT_DIRS;
 exports.BROWSER_STORE_ENV_KEY = BROWSER_STORE_ENV_KEY;
@@ -1322,6 +1506,7 @@ exports.BrowserNotConnectedError = BrowserNotConnectedError;
 exports.WebSocketCDPTransport = WebSocketCDPTransport;
 exports.browserToEngine = browserToEngine;
 exports.createBrowser = createBrowser;
+exports.createBrowserProfile = createBrowserProfile;
 exports.createCDPTransport = createCDPTransport;
 exports.createScreenshotWriter = createScreenshotWriter;
 exports.defaultInstallPaths = defaultInstallPaths;
@@ -1343,6 +1528,7 @@ exports.normalizeExecutablePath = normalizeExecutablePath;
 exports.parseBrowserEngine = parseBrowserEngine;
 exports.probeAllPathNames = probeAllPathNames;
 exports.probePathNames = probePathNames;
+exports.removeBrowserProfile = removeBrowserProfile;
 exports.waitForCDPReady = waitForCDPReady;
 exports.windowsRoots = windowsRoots;