@orkestrel/browser 0.0.3 → 0.0.6

package/dist/src/server/index.js

@@ -1,13 +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 { isRecord, isString } from "@orkestrel/contract";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 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_OPEN, WEBSOCKET_VERSION, computeWebSocketAccept, createNodeWebSocket } from "@orkestrel/websocket";
-import { mkdir, writeFile } from "node:fs/promises";
+import { WEBSOCKET_READY_CLOSED, WEBSOCKET_READY_OPEN, WEBSOCKET_VERSION, computeWebSocketAccept, createNodeWebSocket } from "@orkestrel/websocket";
+import { addAbortListener, once } from "node:events";
 //#region src/server/constants.ts
 /** Default CDP port probed for an existing browser and used for launches. */
 var BROWSER_DEFAULT_CDP_PORT = 9222;
@@ -19,23 +23,22 @@ var BROWSER_CDP_PROTOCOL = "http";
 var BROWSER_CDP_VERSION_PATH = "/json/version";
 /** Path appended to the CDP host to list open targets (pages, workers, etc). */
 var BROWSER_CDP_LIST_PATH = "/json/list";
-/** Sentinel result returned by discovery when no browser is reachable. */
-var BROWSER_NOT_FOUND_RESULT = Object.freeze({
-	found: false,
-	endpoint: void 0,
-	browser: void 0,
-	connection: void 0
-});
 /** Flags always passed to a launched browser process, alongside the caller's own. */
 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";
+/** Prefix for isolated browser profiles created beneath the operating-system temp directory. */
+var BROWSER_PROFILE_PREFIX = "orkestrel-browser-";
 /** Grace period after SIGTERM before a launched process is escalated to SIGKILL during 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;
 /** Brief defer applied once when a transport loss is observed on an owned process, giving a near-simultaneous process-exit event (which libuv may reap slightly later than the socket close) first say over the diagnosis. */
 var BROWSER_TRANSPORT_LOSS_DEFER_MS = 50;
+/** Machine-readable error-context cause for an owned browser process exiting. */
+var BROWSER_PROCESS_EXIT_CAUSE = "process-exit";
+/** Machine-readable error-context cause for a CDP transport disconnecting while its browser remains alive. */
+var BROWSER_TRANSPORT_LOSS_CAUSE = "transport-loss";
 /** Environment variables checked (in order) for an explicit browser executable path override. */
 var BROWSER_ENV_PATH_KEYS = Object.freeze(["PLAYWRIGHT_EXECUTABLE_PATH", "CHROME_PATH"]);
 /** Well-known Chrome/Chromium/Edge executable paths with no platform-specific root, keyed by `process.platform`. */
@@ -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
@@ -259,10 +262,48 @@ function normalizeExecutablePath(path, platform) {
 }
 /** Classify a `/json/version` `Browser` string into a {@link BrowserEngine} (`Edg/` → edge, `Chrome/` → chrome, else chromium). */
 function browserToEngine(browser) {
-	if (browser.includes("Edg/")) return "edge";
-	if (browser.includes("Chrome/")) return "chrome";
+	if (browser?.includes("Edg/") === true) return "edge";
+	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];
@@ -346,7 +387,7 @@ function findAllInStore(base, platform) {
 	const glob = BROWSER_STORE_GLOBS[platform];
 	if (glob === void 0) return found;
 	const matches = globSync(`${base.replaceAll("\\", "/")}/${glob}`).filter((match) => existsSync(match));
-	matches.sort((a, b) => a < b ? 1 : a > b ? -1 : 0);
+	matches.sort((a, b) => b.localeCompare(a, void 0, { numeric: true }));
 	found.push(...matches);
 	return found;
 }
@@ -378,23 +419,24 @@ function launchBrowserProcess(executable, port, headless, profile, extra) {
 *
 * @throws When the endpoint does not become ready before the timeout
 */
-async function waitForCdpReady(port, timeout, host = BROWSER_DEFAULT_HOST) {
+async function waitForCDPReady(port, timeout, host = BROWSER_DEFAULT_HOST, signal) {
 	const url = `${BROWSER_CDP_PROTOCOL}://${host}:${port}${BROWSER_CDP_VERSION_PATH}`;
 	const deadline = Date.now() + timeout;
 	while (Date.now() < deadline) {
+		signal?.throwIfAborted();
 		const remaining = Math.max(0, deadline - Date.now());
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), remaining);
+		const requestSignal = signal === void 0 ? AbortSignal.timeout(remaining) : AbortSignal.any([signal, AbortSignal.timeout(remaining)]);
 		try {
-			const response = await fetch(url, { signal: controller.signal });
+			const response = await fetch(url, { signal: requestSignal });
 			if (response.ok) {
 				const info = await response.json();
 				if (isRecord(info) && isString(info["webSocketDebuggerUrl"])) return info["webSocketDebuggerUrl"];
 			}
-		} catch {} finally {
-			clearTimeout(timer);
+		} catch (error) {
+			if (signal?.aborted === true) throw error;
 		}
-		await new Promise((resolve) => setTimeout(resolve, BROWSER_WAIT_POLL_INTERVAL_MS));
+		const delay = Math.min(BROWSER_WAIT_POLL_INTERVAL_MS, Math.max(0, deadline - Date.now()));
+		if (delay > 0) await setTimeout$1(delay, void 0, { signal });
 	}
 	throw new Error(`CDP endpoint on port ${port} did not become ready within ${timeout}ms`);
 }
@@ -406,7 +448,7 @@ async function waitForCdpReady(port, timeout, host = BROWSER_DEFAULT_HOST) {
 * @param host - Host the browser exposes its CDP endpoint on (default `127.0.0.1`)
 * @returns Normalized CDP targets
 */
-async function fetchCdpTargets(port, timeout, host = BROWSER_DEFAULT_HOST) {
+async function fetchCDPTargets(port, timeout, host = BROWSER_DEFAULT_HOST) {
 	const url = `${BROWSER_CDP_PROTOCOL}://${host}:${port}${BROWSER_CDP_LIST_PATH}`;
 	const controller = new AbortController();
 	const timer = setTimeout(() => controller.abort(), timeout);
@@ -414,16 +456,16 @@ 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;
-			if (!isString(entry["id"]) || !isString(entry["type"])) continue;
+			if (!isString(entry["id"]) || !isString(entry["type"]) || !isString(entry["title"]) || !isString(entry["url"])) continue;
 			targets.push({
 				id: entry["id"],
 				type: entry["type"],
-				title: isString(entry["title"]) ? entry["title"] : "",
-				url: isString(entry["url"]) ? entry["url"] : ""
+				title: entry["title"],
+				url: entry["url"]
 			});
 		}
 		return targets;
@@ -436,33 +478,32 @@ async function fetchCdpTargets(port, timeout, host = BROWSER_DEFAULT_HOST) {
 //#endregion
 //#region src/server/transports/WebSocketCDPTransport.ts
 /**
-* `@orkestrel/websocket`-backed {@link CDPTransportInterface} — the dumb text
-* pipe a {@link import('@src/core').CDPClientInterface} sends and receives
-* JSON-RPC frames over.
+* `@orkestrel/websocket`-backed raw CDP text transport.
 *
 * @remarks
-* `start()` hand-rolls the RFC 6455 client handshake: it opens a `node:http`
-* `GET` carrying `Connection: Upgrade` / `Upgrade: websocket` / a random
-* `Sec-WebSocket-Key` / `Sec-WebSocket-Version`, awaits the client `'upgrade'`
-* event, and validates `Sec-WebSocket-Accept === computeWebSocketAccept(key)`
-* — a mismatch (or a connection/request error, or a timeout) rejects `start()`
-* with a coded {@link BrowserConnectionError} and cleans up the socket. On
-* success it wraps the raw upgraded socket in `createNodeWebSocket({ socket,
-* head })` (CLIENT mode — no `key` — so outgoing frames are masked per RFC
-* 6455 §5.3) and bridges its `message`/`close`/`error` events onto this
-* transport's emitter. `start()` opens a fresh socket each call (safe to call
-* again after `close()` — a new request/socket/NodeWebSocket triple is
-* created every time, which is what `CDPClient.reconnect()` depends on). CDP
-* frames are text-only, so `message` always carries a `string`.
+* Performs and validates the RFC 6455 HTTP upgrade, then delegates frame
+* handling to `@orkestrel/websocket`. Concurrent and repeated `start()` /
+* `close()` calls share their active transition, and a later `start()` opens a
+* fresh socket after the prior one closes.
 */
 var WebSocketCDPTransport = class {
 	#emitter;
 	#url;
 	#timeout;
 	#socket;
-	#connecting;
+	#starting;
+	#closing;
+	#request;
+	#resolve;
+	#reject;
+	#timer;
+	#closeResolve;
+	#onSocketClose = () => this.#closeResolve?.();
 	constructor(options) {
-		this.#emitter = new Emitter();
+		this.#emitter = new Emitter({
+			on: options.on,
+			error: options.error
+		});
 		this.#url = options.url;
 		this.#timeout = options.timeout ?? BROWSER_DEFAULT_TIMEOUT_MS;
 	}
@@ -470,62 +511,22 @@ var WebSocketCDPTransport = class {
 		return this.#emitter;
 	}
 	async start() {
-		const url = new URL(this.#url);
-		const key = randomBytes(16).toString("base64");
-		const ws = await new Promise((resolve, reject) => {
-			const settle = (fn) => {
-				this.#connecting = void 0;
-				fn();
-			};
-			const timer = setTimeout(() => {
-				request$1.destroy();
-				settle(() => reject(new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} timed out after ${this.#timeout}ms`, {
-					url: this.#url,
-					timeout: this.#timeout
-				})));
-			}, this.#timeout);
-			const request$1 = request({
-				hostname: url.hostname,
-				port: url.port.length > 0 ? Number(url.port) : 80,
-				path: `${url.pathname}${url.search}`,
-				headers: {
-					Connection: "Upgrade",
-					Upgrade: "websocket",
-					"Sec-WebSocket-Key": key,
-					"Sec-WebSocket-Version": WEBSOCKET_VERSION
-				}
-			});
-			request$1.on("upgrade", (response, socket, head) => {
-				clearTimeout(timer);
-				const accept = response.headers["sec-websocket-accept"];
-				if (!isString(accept) || accept !== computeWebSocketAccept(key)) {
-					socket.destroy();
-					settle(() => reject(new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: Sec-WebSocket-Accept mismatch`, { url: this.#url })));
-					return;
-				}
-				settle(() => resolve(createNodeWebSocket({
-					socket,
-					head
-				})));
-			});
-			request$1.on("response", (response) => {
-				clearTimeout(timer);
-				response.resume();
-				settle(() => reject(new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: upgrade declined with status ${response.statusCode ?? 0}`, { url: this.#url })));
-			});
-			request$1.on("error", (error) => {
-				clearTimeout(timer);
-				settle(() => reject(new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: ${error.message}`, { url: this.#url })));
-			});
-			this.#connecting = {
-				abort: () => request$1.destroy(),
-				timer,
-				reject: (error) => settle(() => reject(error))
-			};
-			request$1.end();
-		});
-		this.#socket = ws;
-		this.#bind(ws);
+		if (this.#closing !== void 0) await this.#closing;
+		if (this.#socket?.readyState === WEBSOCKET_READY_OPEN) return;
+		const active = this.#starting;
+		if (active !== void 0) {
+			await active;
+			return;
+		}
+		this.#socket?.destroy();
+		this.#socket = void 0;
+		const transition = this.#open();
+		this.#starting = transition;
+		try {
+			await transition;
+		} finally {
+			if (this.#starting === transition) this.#starting = void 0;
+		}
 	}
 	async send(data) {
 		const socket = this.#socket;
@@ -533,32 +534,144 @@ var WebSocketCDPTransport = class {
 		socket.send(data);
 	}
 	async close() {
-		const connecting = this.#connecting;
-		if (connecting !== void 0) {
-			clearTimeout(connecting.timer);
-			this.#connecting = void 0;
-			connecting.abort();
-			connecting.reject(new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} was closed before it finished connecting`, { url: this.#url }));
+		const active = this.#closing;
+		if (active !== void 0) {
+			await active;
 			return;
 		}
+		const transition = this.#stop();
+		this.#closing = transition;
+		try {
+			await transition;
+		} finally {
+			if (this.#closing === transition) this.#closing = void 0;
+		}
+	}
+	async #open() {
+		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();
+		const options = {
+			hostname: url.hostname,
+			port: url.port.length > 0 ? Number(url.port) : url.protocol === "wss:" ? 443 : 80,
+			path: `${url.pathname}${url.search}`,
+			headers: {
+				Connection: "Upgrade",
+				Upgrade: "websocket",
+				"Sec-WebSocket-Key": key,
+				"Sec-WebSocket-Version": WEBSOCKET_VERSION
+			}
+		};
+		const request$2 = url.protocol === "wss:" ? request$1(options) : request(options);
+		this.#request = request$2;
+		this.#resolve = deferred.resolve;
+		this.#reject = deferred.reject;
+		this.#timer = setTimeout(() => this.#expire(request$2), this.#timeout);
+		request$2.on("upgrade", (response, socket, head) => {
+			this.#upgrade(request$2, key, response, socket, head);
+		});
+		request$2.on("response", (response) => this.#decline(request$2, response));
+		request$2.on("error", (error) => this.#fail(request$2, error));
+		request$2.end();
+		const socket = await deferred.promise;
+		this.#socket = socket;
+		this.#bind(socket);
+	}
+	async #stop() {
+		const request = this.#request;
+		if (request !== void 0) {
+			this.#rejectRequest(request, new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} was closed before it finished connecting`, { url: this.#url }));
+			request.destroy();
+		}
+		await this.#starting?.catch(() => void 0);
 		const socket = this.#socket;
-		if (socket === void 0) return;
 		this.#socket = void 0;
-		await new Promise((resolve) => {
-			socket.emitter.on("close", () => resolve());
+		if (socket === void 0 || socket.readyState === WEBSOCKET_READY_CLOSED) return;
+		const closed = Promise.withResolvers();
+		this.#closeResolve = closed.resolve;
+		socket.emitter.on("close", this.#onSocketClose);
+		try {
 			socket.close();
-		});
+			if (socket.readyState !== WEBSOCKET_READY_CLOSED) await closed.promise;
+		} catch {
+			socket.destroy();
+			if (socket.readyState !== WEBSOCKET_READY_CLOSED) await closed.promise;
+		} finally {
+			socket.emitter.off("close", this.#onSocketClose);
+			this.#closeResolve = void 0;
+		}
 	}
-	#bind(ws) {
-		ws.emitter.on("message", (data) => {
-			this.#emitter.emit("message", data);
-		});
-		ws.emitter.on("close", () => {
+	#upgrade(request, key, response, socket, head) {
+		if (this.#request !== request) {
+			socket.destroy();
+			return;
+		}
+		const accept = response.headers["sec-websocket-accept"];
+		if (!isString(accept) || accept !== computeWebSocketAccept(key)) {
+			socket.destroy();
+			this.#rejectRequest(request, new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: Sec-WebSocket-Accept mismatch`, { url: this.#url }));
+			return;
+		}
+		try {
+			this.#resolveRequest(request, createNodeWebSocket({
+				socket,
+				head
+			}));
+		} catch (error) {
+			socket.destroy();
+			this.#rejectRequest(request, error);
+		}
+	}
+	#decline(request, response) {
+		response.resume();
+		const reason = response.statusCode === void 0 ? "upgrade was declined without a status code" : `upgrade declined with status ${response.statusCode}`;
+		this.#rejectRequest(request, new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: ${reason}`, { url: this.#url }));
+	}
+	#fail(request, error) {
+		this.#rejectRequest(request, new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: ${error.message}`, { url: this.#url }));
+	}
+	#expire(request) {
+		this.#rejectRequest(request, new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} timed out after ${this.#timeout}ms`, {
+			url: this.#url,
+			timeout: this.#timeout
+		}));
+		request.destroy();
+	}
+	#resolveRequest(request, socket) {
+		if (this.#request !== request) {
+			socket.destroy();
+			return;
+		}
+		const resolve = this.#resolve;
+		this.#clearRequest();
+		resolve?.(socket);
+	}
+	#rejectRequest(request, error) {
+		if (this.#request !== request) return;
+		const reject = this.#reject;
+		this.#clearRequest();
+		reject?.(error);
+	}
+	#clearRequest() {
+		if (this.#timer !== void 0) clearTimeout(this.#timer);
+		this.#timer = void 0;
+		this.#request = void 0;
+		this.#resolve = void 0;
+		this.#reject = void 0;
+	}
+	#bind(socket) {
+		socket.emitter.on("message", (data) => this.#emitter.emit("message", data));
+		socket.emitter.on("close", () => {
+			if (this.#socket === socket) this.#socket = void 0;
 			this.#emitter.emit("close");
 		});
-		ws.emitter.on("error", (error) => {
-			this.#emitter.emit("error", error);
-		});
+		socket.emitter.on("error", (error) => this.#emitter.emit("error", error));
 	}
 };
 //#endregion
@@ -602,23 +715,37 @@ function createScreenshotWriter() {
 }
 //#endregion
 //#region src/server/Browser.ts
+/**
+* Discovers, launches, connects to, and owns Chromium-family browser sessions.
+*/
 var Browser = class {
 	#emitter;
 	#options;
+	#abort = new AbortController();
+	#cdpPort;
+	#cdpHost;
 	#engine;
 	#status = "idle";
 	#connection;
+	#owned;
+	#endpoint;
 	#client;
 	#process;
-	#cdpPort;
-	#cdpHost;
+	#profile;
 	#contexts = [];
 	#destroyed = false;
-	#transportUnbind;
-	#processUnbind;
-	#lastPid;
+	#connecting;
+	#disconnecting;
+	#shutdown;
+	#transport;
+	#onTransportClose = () => this.#handleTransportLoss();
+	#onTransportError = () => this.#handleTransportLoss();
+	#onProcessExit = () => this.#handleProcessExit();
 	constructor(options) {
-		this.#emitter = new Emitter({ on: options?.on });
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
 		this.#options = options ?? {};
 		this.#engine = this.#options.engine ?? (this.#options.executable !== void 0 ? parseBrowserEngine(this.#options.executable) ?? "chromium" : "chromium");
 		this.#cdpPort = this.#options.cdp?.port ?? 9222;
@@ -637,63 +764,62 @@ var Browser = class {
 	get connection() {
 		return this.#connection;
 	}
+	get owned() {
+		return this.#owned;
+	}
 	get connected() {
 		return this.#status === "connected";
 	}
 	get pid() {
-		return this.#process?.pid ?? this.#lastPid;
+		return this.#process?.pid;
 	}
 	async discover() {
-		const result = await this.#discoverCdp();
+		const result = await this.#discoverCDP();
 		this.#emitter.emit("discover", result);
 		return result;
 	}
 	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;
-		this.#assertNotAborted();
-		this.#status = "connecting";
+		const active = this.#connecting;
+		if (active !== void 0) {
+			await active;
+			return;
+		}
+		const attempt = this.#establish();
+		this.#connecting = attempt;
 		try {
-			const cdpEndpoint = this.#options.cdp?.endpoint;
-			if (cdpEndpoint !== void 0) {
-				await this.#connectCdp(cdpEndpoint);
-				return;
-			}
-			if (this.#options.cdp?.discover ?? true) {
-				this.#assertNotAborted();
-				const discovery = await this.#raceAbort(this.#discoverCdp());
-				if (discovery.found && discovery.endpoint !== void 0) {
-					this.#engine = browserToEngine(discovery.browser ?? "");
-					await this.#connectCdp(discovery.endpoint);
-					return;
-				}
-			} else {
-				this.#assertNotAborted();
-				await this.#raceAbort(this.#assertPortFree());
-			}
-			this.#assertNotAborted();
-			await this.#launch();
-		} catch (thrown) {
-			this.#status = "error";
-			this.#emitter.emit("error", thrown);
-			if (thrown instanceof BrowserConnectionError) throw thrown;
-			throw new BrowserConnectionError(thrown instanceof Error ? thrown.message : String(thrown), { executable: this.#options.executable });
+			await attempt;
+		} finally {
+			if (this.#connecting === attempt) this.#connecting = void 0;
 		}
 	}
+	adopt() {
+		if (this.#destroyed) throw new BrowserDestroyedError();
+		if (this.#status !== "connected" || this.#client === void 0 || this.#endpoint === void 0) throw new BrowserNotConnectedError();
+		this.#owned = true;
+	}
 	async disconnect() {
-		if (this.#destroyed || this.#status !== "connected") return;
-		if (this.#connection === "launch") throw new BrowserConnectionError("Cannot disconnect() an ephemeral launch — no persistent profile to reattach to; ephemeral launches must use destroy() to release it", { connection: this.#connection });
-		this.#unbindTransport();
-		this.#unbindProcess();
-		const client = this.#client;
-		if (client !== void 0) try {
-			await client.close();
-		} catch {}
-		if (this.#process?.pid !== void 0) this.#lastPid = this.#process.pid;
-		this.#process = void 0;
-		this.#reset();
-		this.#emitter.emit("disconnect");
-		this.#emitter.emit("idle");
+		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;
+		}
+		if (this.#status !== "connected" || this.#client === void 0) return;
+		const attempt = this.#detach();
+		this.#disconnecting = attempt;
+		try {
+			await attempt;
+		} finally {
+			if (this.#disconnecting === attempt) this.#disconnecting = void 0;
+		}
 	}
 	context(index) {
 		const i = index ?? 0;
@@ -703,239 +829,250 @@ 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();
-		if (this.#status !== "connected" || this.#client === void 0) throw new BrowserNotConnectedError();
-		let ctx = this.#contexts[0];
-		if (ctx === void 0) {
-			ctx = new BrowserContext(this.#client, void 0, this.#options.viewport, createScreenshotWriter());
-			this.#contexts.push(ctx);
+		const client = this.#client;
+		if (this.#status !== "connected" || client === void 0) throw new BrowserNotConnectedError();
+		let context = this.#contexts[0];
+		if (context === void 0) {
+			context = new BrowserContext(client, void 0, this.#options.viewport, createScreenshotWriter());
+			this.#registerContext(context);
 		}
-		const page = await ctx.create(options);
+		const page = await context.create(options);
 		this.#emitter.emit("page", page);
 		return page;
 	}
-	async destroy() {
-		if (this.#destroyed) return;
+	destroy() {
+		const active = this.#shutdown;
+		if (active !== void 0) return active;
+		if (this.#destroyed) return Promise.resolve();
 		this.#destroyed = true;
-		try {
-			this.#unbindTransport();
-			this.#unbindProcess();
-			if (this.#process !== void 0) for (const ctx of this.#contexts) try {
-				await ctx.close();
-			} catch {}
-			this.#contexts = [];
-			await this.#terminate(this.#process);
-			this.#process = void 0;
-			if (this.#client !== void 0) {
-				try {
-					await this.#client.close();
-				} catch {}
-				this.#client = void 0;
-			}
-		} finally {
-			this.#status = "disconnected";
-			this.#connection = void 0;
-			this.#lastPid = void 0;
-			this.#emitter.emit("destroy");
-			this.#emitter.destroy();
-		}
+		this.#abort.abort();
+		const shutdown = this.#destroyResources();
+		this.#shutdown = shutdown;
+		return shutdown;
 	}
-	/**
-	* Gracefully shut down the remote browser, whether this instance owns its
-	* process or merely attached to it via CDP.
-	*
-	* @remarks
-	* Sends CDP `Browser.close` best-effort; on an owned browser also awaits
-	* the process's exit (bounded by the kill-escalation grace period,
-	* escalating to a kill only if it does not exit in time). Ends in the
-	* same local-cleanup state as `destroy()`.
-	*/
-	async close() {
-		if (this.#destroyed) return;
+	close() {
+		const active = this.#shutdown;
+		if (active !== void 0) return active;
+		if (this.#destroyed) return Promise.resolve();
 		this.#destroyed = true;
+		this.#abort.abort();
+		const shutdown = this.#closeResources();
+		this.#shutdown = shutdown;
+		return shutdown;
+	}
+	async #establish() {
+		this.#assertNotAborted();
+		this.#status = "connecting";
 		try {
-			this.#unbindTransport();
-			this.#unbindProcess();
-			const client = this.#client;
-			if (client !== void 0) try {
-				await client.send("Browser.close");
-			} catch {}
-			const process = this.#process;
-			if (process !== void 0) {
-				const exited = new Promise((resolve) => {
-					process.once("exit", () => resolve());
-				});
-				let timer;
-				const timedOut = await Promise.race([exited.then(() => false), new Promise((resolve) => {
-					timer = setTimeout(() => resolve(true), BROWSER_KILL_GRACE_MS);
-				})]);
-				if (timer !== void 0) clearTimeout(timer);
-				if (timedOut) await this.#terminate(process);
-				this.#process = void 0;
+			if (this.#owned === true && this.#endpoint !== void 0) {
+				await this.#connectCDP(this.#endpoint);
+				return;
 			}
-			for (const ctx of this.#contexts) try {
-				await ctx.close();
-			} catch {}
-			this.#contexts = [];
-			if (client !== void 0) {
-				try {
-					await client.close();
-				} catch {}
-				this.#client = void 0;
+			const endpoint = this.#options.cdp?.endpoint;
+			if (endpoint !== void 0) {
+				await this.#connectCDP(endpoint);
+				return;
 			}
-		} finally {
-			this.#status = "disconnected";
-			this.#connection = void 0;
-			this.#lastPid = void 0;
-			this.#emitter.emit("destroy");
-			this.#emitter.destroy();
+			if (this.#options.cdp?.discover ?? true) {
+				const discovery = await this.#raceAbort(this.#discoverCDP(this.#signal()));
+				if (discovery.found && discovery.endpoint !== void 0) {
+					this.#engine = browserToEngine(discovery.browser);
+					await this.#connectCDP(discovery.endpoint);
+					return;
+				}
+			} else await this.#raceAbort(this.#assertPortFree());
+			this.#assertNotAborted();
+			await this.#launch();
+		} catch (error) {
+			if (this.#destroyed) throw new BrowserDestroyedError();
+			this.#status = "error";
+			this.#emitter.emit("error", error);
+			if (isBrowserConnectionError(error)) throw error;
+			throw new BrowserConnectionError(isError(error) ? error.message : String(error), { executable: this.#options.executable });
 		}
 	}
+	async #detach() {
+		this.#status = "disconnected";
+		this.#connection = void 0;
+		this.#unbindTransport();
+		const client = this.#client;
+		this.#client = void 0;
+		await this.#destroyContexts();
+		this.#contexts = [];
+		if (this.#owned !== true) {
+			this.#owned = void 0;
+			this.#endpoint = void 0;
+		}
+		await this.#closeClient(client);
+		if (this.#destroyed) return;
+		this.#emitter.emit("disconnect");
+		this.#emitter.emit("idle");
+	}
 	#assertNotAborted() {
-		if (this.#options.signal?.aborted) throw new BrowserConnectionError("Connection aborted");
+		if (this.#signal().aborted) throw new BrowserConnectionError("Connection aborted");
+	}
+	#signal() {
+		const external = this.#options.signal;
+		return external === void 0 ? this.#abort.signal : AbortSignal.any([this.#abort.signal, external]);
 	}
-	/**
-	* Race a promise against the connection's external AbortSignal (if any),
-	* rejecting promptly with a coded BrowserConnectionError when it fires.
-	*/
 	async #raceAbort(promise) {
-		const signal = this.#options.signal;
-		if (signal === void 0) return promise;
+		const signal = this.#signal();
 		if (signal.aborted) throw new BrowserConnectionError("Connection aborted");
-		let abortWon = false;
-		return await new Promise((resolve, reject) => {
-			const onAbort = () => {
-				abortWon = true;
-				cleanup();
-				reject(new BrowserConnectionError("Connection aborted"));
-			};
-			const cleanup = () => signal.removeEventListener("abort", onAbort);
-			signal.addEventListener("abort", onAbort, { once: true });
-			promise.then((value) => {
-				cleanup();
-				resolve(value);
-			}, (error) => {
-				cleanup();
-				reject(error);
-			});
-		}).catch((error) => {
-			if (abortWon) promise.catch(() => void 0);
-			throw error;
+		const aborted = Promise.withResolvers();
+		const listener = addAbortListener(signal, () => {
+			aborted.reject(new BrowserConnectionError("Connection aborted"));
 		});
+		try {
+			return await Promise.race([promise, aborted.promise]);
+		} finally {
+			listener[Symbol.dispose]();
+			promise.catch(() => void 0);
+		}
 	}
-	#reset() {
-		this.#contexts = [];
-		this.#status = "disconnected";
-		this.#connection = void 0;
-		this.#client = void 0;
-	}
-	/**
-	* Handle the owned process exiting on its own (not via destroy()/close()).
-	* The process is already gone — no kill is attempted. Cleans up orphaned
-	* state so the next connect() call can start fresh, and emits a coded
-	* `error` (cause: process exit) before `disconnect`.
-	*/
 	#handleProcessExit() {
 		if (this.#destroyed) return;
-		if (this.#status !== "connected") return;
+		const connected = this.#status === "connected";
+		const client = this.#client;
+		const contexts = this.#contexts;
 		this.#unbindTransport();
 		this.#unbindProcess();
-		const client = this.#client;
 		this.#process = void 0;
-		this.#lastPid = void 0;
-		this.#reset();
-		if (client !== void 0) client.close().catch(() => void 0);
-		this.#emitter.emit("error", new BrowserConnectionError("The browser process exited unexpectedly", { cause: "process-exit" }));
-		this.#emitter.emit("disconnect");
-		this.#emitter.emit("idle");
+		this.#releaseProfile().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");
+			this.#emitter.emit("idle");
+		}
 	}
-	/**
-	* Handle a transport close/error while the owned process (if any) is
-	* still alive, or the connection is CDP-attached. Never kills the
-	* process — only the local client is reset, so the SAME instance can
-	* reconnect (e.g. rediscover on the port and reattach). Emits a coded
-	* `error` (cause: connection loss) before `disconnect`.
-	*/
-	#handleTransportLoss(deferred = false) {
-		if (this.#destroyed) return;
-		if (this.#status !== "connected") return;
+	#handleTransportLoss() {
+		if (this.#destroyed || this.#status !== "connected") return;
 		const process = this.#process;
 		if (process !== void 0 && (process.exitCode !== null || process.signalCode !== null)) {
 			this.#handleProcessExit();
 			return;
 		}
-		if (process !== void 0 && !deferred) {
-			setTimeout(() => this.#handleTransportLoss(true), 50);
+		if (process !== void 0) {
+			setTimeout(() => this.#confirmTransportLoss(), 50);
 			return;
 		}
-		if (process !== void 0 && process.pid !== void 0) try {
+		this.#confirmTransportLoss();
+	}
+	#confirmTransportLoss() {
+		if (this.#destroyed || this.#status !== "connected") return;
+		const process = this.#process;
+		if (process !== void 0 && (process.exitCode !== null || process.signalCode !== null)) {
+			this.#handleProcessExit();
+			return;
+		}
+		if (process?.pid !== void 0) try {
 			process.kill(0);
 		} catch {
 			this.#handleProcessExit();
 			return;
 		}
-		this.#unbindTransport();
 		const client = this.#client;
-		this.#reset();
-		if (client !== void 0) client.close().catch(() => void 0);
-		this.#emitter.emit("error", new BrowserConnectionError("The CDP transport connection was lost", { cause: "connection-loss" }));
+		const owned = this.#owned === true;
+		const contexts = this.#contexts;
+		this.#unbindTransport();
+		this.#client = void 0;
+		this.#contexts = [];
+		this.#connection = void 0;
+		this.#status = "disconnected";
+		if (!owned) {
+			this.#owned = void 0;
+			this.#endpoint = void 0;
+		}
+		this.#destroyContextList(contexts);
+		this.#closeClient(client);
+		this.#emitter.emit("error", new BrowserConnectionError("The CDP transport connection was lost", { cause: BROWSER_TRANSPORT_LOSS_CAUSE }));
 		this.#emitter.emit("disconnect");
 		this.#emitter.emit("idle");
 	}
-	/** Subscribe to the CDP transport's close/error events for deterministic transport-loss detection. */
 	#bindTransport(transport) {
-		const onClose = () => this.#handleTransportLoss();
-		const onError = () => this.#handleTransportLoss();
-		transport.emitter.on("close", onClose);
-		transport.emitter.on("error", onError);
-		this.#transportUnbind = () => {
-			transport.emitter.off("close", onClose);
-			transport.emitter.off("error", onError);
-		};
+		this.#unbindTransport();
+		this.#transport = transport;
+		transport.emitter.on("close", this.#onTransportClose);
+		transport.emitter.on("error", this.#onTransportError);
 	}
 	#unbindTransport() {
-		this.#transportUnbind?.();
-		this.#transportUnbind = void 0;
+		const transport = this.#transport;
+		if (transport === void 0) return;
+		transport.emitter.off("close", this.#onTransportClose);
+		transport.emitter.off("error", this.#onTransportError);
+		this.#transport = void 0;
 	}
-	/** Subscribe to a launched process's exit event for deterministic process-exit detection. */
 	#bindProcess(process) {
-		const onExit = () => this.#handleProcessExit();
-		process.once("exit", onExit);
-		this.#processUnbind = () => process.off("exit", onExit);
+		this.#unbindProcess();
+		process.once("exit", this.#onProcessExit);
+		if (process.exitCode !== null || process.signalCode !== null) queueMicrotask(this.#onProcessExit);
 	}
 	#unbindProcess() {
-		this.#processUnbind?.();
-		this.#processUnbind = void 0;
+		this.#process?.off("exit", this.#onProcessExit);
 	}
 	#timeout() {
 		return this.#options.timeout ?? BROWSER_DEFAULT_TIMEOUT_MS;
 	}
-	async #discoverCdp() {
-		const port = this.#cdpPort;
-		const url = `${BROWSER_CDP_PROTOCOL}://${this.#cdpHost}:${port}${BROWSER_CDP_VERSION_PATH}`;
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), this.#timeout());
+	async #discoverCDP(signal) {
+		const url = `${BROWSER_CDP_PROTOCOL}://${this.#cdpHost}:${this.#cdpPort}${BROWSER_CDP_VERSION_PATH}`;
+		const requestSignal = signal === void 0 ? AbortSignal.timeout(this.#timeout()) : AbortSignal.any([signal, AbortSignal.timeout(this.#timeout())]);
 		try {
-			const response = await fetch(url, { signal: controller.signal });
-			if (!response.ok) return this.#notFoundResult();
+			const response = await fetch(url, { signal: requestSignal });
+			if (!response.ok) return this.#notFound();
 			const info = await response.json();
-			if (!isRecord(info)) return this.#notFoundResult();
+			if (!isRecord(info)) return this.#notFound();
 			const endpoint = isString(info["webSocketDebuggerUrl"]) ? info["webSocketDebuggerUrl"] : void 0;
-			const browserName = isString(info["Browser"]) ? info["Browser"] : void 0;
+			const browser = isString(info["Browser"]) ? info["Browser"] : void 0;
 			return {
 				found: endpoint !== void 0,
 				endpoint,
-				browser: browserName,
+				browser,
 				connection: endpoint !== void 0 ? "cdp" : void 0
 			};
-		} catch {
-			return this.#notFoundResult();
-		} finally {
-			clearTimeout(timer);
+		} catch (error) {
+			if (signal?.aborted === true) throw error;
+			return this.#notFound();
 		}
 	}
-	#notFoundResult() {
+	#notFound() {
 		return {
 			found: false,
 			endpoint: void 0,
@@ -943,31 +1080,21 @@ var Browser = class {
 			connection: void 0
 		};
 	}
-	/**
-	* Reject when something is already listening on the configured CDP port —
-	* used ahead of a `discover: false` launch, so a caller demanding a fresh
-	* browser never silently attaches to a stranger already on that port.
-	*/
 	async #assertPortFree() {
 		if (await this.#probePort()) throw new BrowserConnectionError(`Port ${this.#cdpPort} on ${this.#cdpHost} is already occupied by another CDP endpoint`, {
 			port: this.#cdpPort,
 			host: this.#cdpHost
 		});
 	}
-	/** Very short probe of the CDP version endpoint — just enough to detect an occupied port, not full discovery. */
 	async #probePort() {
 		const url = `${BROWSER_CDP_PROTOCOL}://${this.#cdpHost}:${this.#cdpPort}${BROWSER_CDP_VERSION_PATH}`;
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), 200);
 		try {
-			return (await fetch(url, { signal: controller.signal })).ok;
+			return (await fetch(url, { signal: AbortSignal.timeout(200) })).ok;
 		} catch {
 			return false;
-		} finally {
-			clearTimeout(timer);
 		}
 	}
-	async #connectCdp(endpoint) {
+	async #connectCDP(endpoint) {
 		const transport = createCDPTransport({
 			url: endpoint,
 			timeout: this.#timeout()
@@ -976,18 +1103,27 @@ var Browser = class {
 			transport,
 			timeout: this.#timeout()
 		});
+		const retained = this.#owned === true && this.#endpoint === endpoint;
 		try {
 			await this.#raceAbort(client.connect());
 			this.#client = client;
-			this.#connection = "cdp";
+			this.#endpoint = endpoint;
+			this.#connection = retained ? this.#retainedConnection() : "cdp";
+			this.#owned = retained;
 			this.#status = "connected";
 			this.#bindTransport(transport);
 			await this.#syncContexts();
-			this.#emitter.emit("connect", "cdp");
+			this.#emitter.emit("connect", this.#connection);
 		} catch (error) {
-			try {
-				await client.close();
-			} catch {}
+			this.#unbindTransport();
+			if (this.#client === client) this.#client = void 0;
+			this.#contexts = [];
+			this.#connection = void 0;
+			if (!retained) {
+				this.#owned = void 0;
+				this.#endpoint = void 0;
+			}
+			await this.#closeClient(client);
 			throw error;
 		}
 	}
@@ -1005,18 +1141,24 @@ var Browser = class {
 			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 ? { engine: requestedEngine } : void 0);
+		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 headless = this.#options.headless ?? true;
-		const profile = this.#options.profile;
-		const extra = this.#options.args;
-		const process = launchBrowserProcess(executable, this.#cdpPort, headless, profile, extra);
+		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 transport;
 		let client;
 		try {
-			transport = createCDPTransport({
-				url: await this.#raceAbort(this.#waitForLaunch(process, executable, extra)),
+			const endpoint = await this.#waitForLaunch(process, executable, this.#options.args);
+			const transport = createCDPTransport({
+				url: endpoint,
 				timeout: this.#timeout()
 			});
 			client = new CDPClient({
@@ -1024,20 +1166,27 @@ var Browser = class {
 				timeout: this.#timeout()
 			});
 			await this.#raceAbort(client.connect());
+			const connection = this.#options.profile === void 0 ? "launch" : "persistent";
 			this.#client = client;
-			this.#connection = profile !== void 0 ? "persistent" : "launch";
+			this.#endpoint = endpoint;
+			this.#connection = connection;
+			this.#owned = true;
 			this.#status = "connected";
 			this.#bindTransport(transport);
 			this.#bindProcess(process);
 			await this.#syncContexts();
 			this.#emitter.emit("launch", this.#engine);
-			this.#emitter.emit("connect", this.#connection);
+			this.#emitter.emit("connect", connection);
 		} catch (error) {
-			if (client !== void 0) try {
-				await client.close();
-			} catch {}
+			this.#unbindTransport();
+			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;
+			this.#owned = void 0;
 			throw error;
 		}
 	}
@@ -1046,75 +1195,212 @@ var Browser = class {
 			executable,
 			args
 		};
-		return await new Promise((resolve, reject) => {
-			let settled = false;
-			const finish = (callback) => {
-				if (settled) return;
-				settled = true;
-				process.off("error", onError);
-				process.off("exit", onExit);
-				callback();
-			};
-			const onError = (error) => {
-				finish(() => reject(new BrowserConnectionError(error.message, context)));
-			};
-			const onExit = (code, signal) => {
-				finish(() => reject(new BrowserConnectionError(this.#formatLaunchExit(code, signal), context)));
-			};
-			process.once("error", onError);
-			process.once("exit", onExit);
-			waitForCdpReady(this.#cdpPort, this.#timeout(), this.#cdpHost).then((wsUrl) => {
-				finish(() => resolve(wsUrl));
-			}, (error) => {
-				const message = error instanceof Error ? error.message : String(error);
-				finish(() => reject(new BrowserConnectionError(message, context)));
-			});
+		const controller = new AbortController();
+		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 = 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 (isBrowserConnectionError(error)) throw error;
+			if (this.#signal().aborted) throw new BrowserConnectionError("Connection aborted", context);
+			throw new BrowserConnectionError(isError(error) ? error.message : String(error), context);
+		} finally {
+			controller.abort();
+			ready.catch(() => void 0);
+			exited.catch(() => void 0);
+		}
 	}
 	#formatLaunchExit(code, signal) {
 		if (signal !== null) return `Browser process exited before CDP became ready (signal: ${signal})`;
 		if (code !== null) return `Browser process exited before CDP became ready (code: ${code})`;
 		return "Browser process exited before CDP became ready";
 	}
+	#retainedConnection() {
+		if (this.#process === void 0) return "cdp";
+		return this.#options.profile === void 0 ? "launch" : "persistent";
+	}
 	async #syncContexts() {
-		if (this.#client === void 0) return;
-		const pageTargets = (await fetchCdpTargets(this.#cdpPort, this.#timeout(), this.#cdpHost)).filter((t) => t.type === "page");
-		if (pageTargets.length > 0 && this.#contexts.length === 0) {
-			const ctx = new BrowserContext(this.#client, void 0, this.#options.viewport, createScreenshotWriter());
-			await ctx.sync(pageTargets);
-			this.#contexts.push(ctx);
+		const client = this.#client;
+		if (client === void 0) return;
+		let result;
+		try {
+			result = await client.send("Target.getTargets");
+		} catch {
+			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;
+			pages.push({
+				id: target["targetId"],
+				type: target["type"],
+				title: target["title"],
+				url: target["url"]
+			});
+		}
+		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.#registerContext(context);
 	}
-	/**
-	* Terminate a browser process, escalating from SIGTERM to SIGKILL if it
-	* does not exit within the grace period. Tolerates a process that has
-	* already exited (ESRCH).
-	*/
-	async #terminate(process) {
-		if (process === void 0) return;
-		if (process.exitCode !== null || process.signalCode !== null) return;
-		const exited = new Promise((resolve) => {
-			process.once("exit", () => resolve());
+	async #destroyResources() {
+		try {
+			await this.#settle();
+			this.#unbindTransport();
+			this.#unbindProcess();
+			const client = this.#client;
+			if (this.#owned === true) {
+				await this.#closeContexts();
+				if (this.#process === void 0) await this.#closeRemote(client);
+			} else await this.#destroyContexts();
+			this.#contexts = [];
+			await this.#terminate(this.#process);
+			this.#process = void 0;
+			await this.#closeClient(client);
+			this.#client = void 0;
+		} finally {
+			try {
+				await this.#releaseProfile();
+			} finally {
+				this.#finish();
+			}
+		}
+	}
+	async #closeResources() {
+		try {
+			await this.#settle();
+			this.#unbindTransport();
+			this.#unbindProcess();
+			const client = this.#client;
+			await this.#closeContexts();
+			this.#contexts = [];
+			await this.#closeRemote(client);
+			const process = this.#process;
+			if (process !== void 0) {
+				if (!await this.#waitForProcessWithin(process, 3e3)) await this.#terminate(process);
+			}
+			this.#process = void 0;
+			await this.#closeClient(client);
+			this.#client = void 0;
+		} finally {
+			try {
+				await this.#releaseProfile();
+			} finally {
+				this.#finish();
+			}
+		}
+	}
+	async #settle() {
+		await this.#connecting?.catch(() => void 0);
+		await this.#disconnecting?.catch(() => void 0);
+	}
+	async #closeRemote(client) {
+		let remote = client;
+		let temporary = false;
+		if (remote === void 0 && this.#owned === true && this.#endpoint !== void 0) {
+			remote = new CDPClient({
+				transport: createCDPTransport({
+					url: this.#endpoint,
+					timeout: this.#timeout()
+				}),
+				timeout: this.#timeout()
+			});
+			try {
+				await remote.connect();
+				temporary = true;
+			} catch {
+				await this.#closeClient(remote);
+				return;
+			}
+		}
+		if (remote !== void 0) try {
+			await remote.send("Browser.close");
+		} catch {}
+		if (temporary) await this.#closeClient(remote);
+	}
+	async #closeContexts() {
+		for (const context of [...this.#contexts]) try {
+			await context.close();
+		} catch {}
+	}
+	async #destroyContexts() {
+		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 {
+			await context.destroy();
+		} catch {}
+	}
+	async #closeClient(client) {
+		if (client === void 0) return;
+		try {
+			await client.close();
+		} catch {}
+	}
+	async #releaseProfile() {
+		const profile = this.#profile;
+		this.#profile = void 0;
+		if (profile !== void 0) await removeBrowserProfile(profile);
+	}
+	async #waitForProcess(process) {
+		if (process.exitCode !== null || process.signalCode !== null) return;
+		await once(process, "exit");
+	}
+	async #waitForProcessWithin(process, timeout) {
+		if (process.exitCode !== null || process.signalCode !== null) return true;
+		const signal = AbortSignal.timeout(timeout);
+		try {
+			await once(process, "exit", { signal });
+			return true;
+		} catch (error) {
+			if (signal.aborted) return process.exitCode !== null || process.signalCode !== null;
+			throw error;
+		}
+	}
+	async #terminate(process) {
+		if (process === void 0 || process.exitCode !== null || process.signalCode !== null) return;
 		try {
 			process.kill("SIGTERM");
 		} catch {
 			return;
 		}
-		let timer;
-		const timedOut = await Promise.race([exited.then(() => false), new Promise((resolve) => {
-			timer = setTimeout(() => resolve(true), BROWSER_KILL_GRACE_MS);
-		})]);
-		if (timer !== void 0) clearTimeout(timer);
-		if (timedOut) {
-			try {
-				process.kill("SIGKILL");
-			} catch {}
-			await exited;
+		if (await this.#waitForProcessWithin(process, 3e3)) return;
+		try {
+			process.kill("SIGKILL");
+		} catch {
+			return;
 		}
+		await this.#waitForProcess(process);
+	}
+	#finish() {
+		this.#unbindTransport();
+		this.#unbindProcess();
+		this.#status = "disconnected";
+		this.#connection = void 0;
+		this.#owned = void 0;
+		this.#endpoint = void 0;
+		this.#client = void 0;
+		this.#process = 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_NOT_FOUND_RESULT, BROWSER_PORT_PROBE_TIMEOUT_MS, BROWSER_STORE_CACHE_DIRS, BROWSER_STORE_DEFAULT_DIRS, BROWSER_STORE_ENV_KEY, BROWSER_STORE_GLOBS, BROWSER_STORE_LINK_NAME, 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