@orkestrel/browser 0.0.3 → 0.0.6

package/dist/src/server/index.cjs

@@ -1,14 +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 _orkestrel_contract = require("@orkestrel/contract");
+let node_timers_promises = require("node:timers/promises");
 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_fs_promises = require("node:fs/promises");
+let node_events = require("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;
@@ -20,23 +24,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`. */
@@ -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
@@ -260,10 +263,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 (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];
@@ -347,7 +388,7 @@ function findAllInStore(base, platform) {
 	const glob = BROWSER_STORE_GLOBS[platform];
 	if (glob === void 0) return found;
 	const matches = (0, node_fs.globSync)(`${base.replaceAll("\\", "/")}/${glob}`).filter((match) => (0, node_fs.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;
 }
@@ -379,23 +420,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 ((0, _orkestrel_contract.isRecord)(info) && (0, _orkestrel_contract.isString)(info["webSocketDebuggerUrl"])) return info["webSocketDebuggerUrl"];
 			}
-		} catch {} finally {
-			clearTimeout(timer);
+		} catch (error) {
+			if (signal?.aborted === true) throw error;
 		}
-		await new Promise((resolve) => setTimeout(resolve, _src_core.BROWSER_WAIT_POLL_INTERVAL_MS));
+		const delay = Math.min(_src_core.BROWSER_WAIT_POLL_INTERVAL_MS, Math.max(0, deadline - Date.now()));
+		if (delay > 0) await (0, node_timers_promises.setTimeout)(delay, void 0, { signal });
 	}
 	throw new Error(`CDP endpoint on port ${port} did not become ready within ${timeout}ms`);
 }
@@ -407,7 +449,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);
@@ -415,16 +457,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 (!(0, _orkestrel_contract.isArray)(list)) return [];
 		const targets = [];
 		for (const entry of list) {
 			if (!(0, _orkestrel_contract.isRecord)(entry)) continue;
-			if (!(0, _orkestrel_contract.isString)(entry["id"]) || !(0, _orkestrel_contract.isString)(entry["type"])) continue;
+			if (!(0, _orkestrel_contract.isString)(entry["id"]) || !(0, _orkestrel_contract.isString)(entry["type"]) || !(0, _orkestrel_contract.isString)(entry["title"]) || !(0, _orkestrel_contract.isString)(entry["url"])) continue;
 			targets.push({
 				id: entry["id"],
 				type: entry["type"],
-				title: (0, _orkestrel_contract.isString)(entry["title"]) ? entry["title"] : "",
-				url: (0, _orkestrel_contract.isString)(entry["url"]) ? entry["url"] : ""
+				title: entry["title"],
+				url: entry["url"]
 			});
 		}
 		return targets;
@@ -437,33 +479,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 _orkestrel_emitter.Emitter();
+		this.#emitter = new _orkestrel_emitter.Emitter({
+			on: options.on,
+			error: options.error
+		});
 		this.#url = options.url;
 		this.#timeout = options.timeout ?? _src_core.BROWSER_DEFAULT_TIMEOUT_MS;
 	}
@@ -471,62 +512,22 @@ var WebSocketCDPTransport = class {
 		return this.#emitter;
 	}
 	async start() {
-		const url = new URL(this.#url);
-		const key = (0, node_crypto.randomBytes)(16).toString("base64");
-		const ws = await new Promise((resolve, reject) => {
-			const settle = (fn) => {
-				this.#connecting = void 0;
-				fn();
-			};
-			const timer = setTimeout(() => {
-				request.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 = (0, node_http.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": _orkestrel_websocket.WEBSOCKET_VERSION
-				}
-			});
-			request.on("upgrade", (response, socket, head) => {
-				clearTimeout(timer);
-				const accept = response.headers["sec-websocket-accept"];
-				if (!(0, _orkestrel_contract.isString)(accept) || accept !== (0, _orkestrel_websocket.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((0, _orkestrel_websocket.createNodeWebSocket)({
-					socket,
-					head
-				})));
-			});
-			request.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.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.destroy(),
-				timer,
-				reject: (error) => settle(() => reject(error))
-			};
-			request.end();
-		});
-		this.#socket = ws;
-		this.#bind(ws);
+		if (this.#closing !== void 0) await this.#closing;
+		if (this.#socket?.readyState === _orkestrel_websocket.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;
@@ -534,32 +535,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 = (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();
+		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": _orkestrel_websocket.WEBSOCKET_VERSION
+			}
+		};
+		const request = url.protocol === "wss:" ? (0, node_https.request)(options) : (0, node_http.request)(options);
+		this.#request = request;
+		this.#resolve = deferred.resolve;
+		this.#reject = deferred.reject;
+		this.#timer = setTimeout(() => this.#expire(request), this.#timeout);
+		request.on("upgrade", (response, socket, head) => {
+			this.#upgrade(request, key, response, socket, head);
+		});
+		request.on("response", (response) => this.#decline(request, response));
+		request.on("error", (error) => this.#fail(request, error));
+		request.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 === _orkestrel_websocket.WEBSOCKET_READY_CLOSED) return;
+		const closed = Promise.withResolvers();
+		this.#closeResolve = closed.resolve;
+		socket.emitter.on("close", this.#onSocketClose);
+		try {
 			socket.close();
-		});
+			if (socket.readyState !== _orkestrel_websocket.WEBSOCKET_READY_CLOSED) await closed.promise;
+		} catch {
+			socket.destroy();
+			if (socket.readyState !== _orkestrel_websocket.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 (!(0, _orkestrel_contract.isString)(accept) || accept !== (0, _orkestrel_websocket.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, (0, _orkestrel_websocket.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
@@ -603,23 +716,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 _orkestrel_emitter.Emitter({ on: options?.on });
+		this.#emitter = new _orkestrel_emitter.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;
@@ -638,63 +765,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;
@@ -704,239 +830,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();
+		(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();
-		if (this.#status !== "connected" || this.#client === void 0) throw new BrowserNotConnectedError();
-		let ctx = this.#contexts[0];
-		if (ctx === void 0) {
-			ctx = new _src_core.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 _src_core.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((0, _orkestrel_contract.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 = (0, node_events.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;
+		}
+		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 !== void 0 && process.pid !== void 0) try {
+		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 ?? _src_core.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 (!(0, _orkestrel_contract.isRecord)(info)) return this.#notFoundResult();
+			if (!(0, _orkestrel_contract.isRecord)(info)) return this.#notFound();
 			const endpoint = (0, _orkestrel_contract.isString)(info["webSocketDebuggerUrl"]) ? info["webSocketDebuggerUrl"] : void 0;
-			const browserName = (0, _orkestrel_contract.isString)(info["Browser"]) ? info["Browser"] : void 0;
+			const browser = (0, _orkestrel_contract.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,
@@ -944,31 +1081,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()
@@ -977,18 +1104,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;
 		}
 	}
@@ -1006,18 +1142,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 _src_core.CDPClient({
@@ -1025,20 +1167,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;
 		}
 	}
@@ -1047,72 +1196,209 @@ 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 = (0, node_events.once)(process, "exit", { signal }).then((values) => {
+			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 (isBrowserConnectionError(error)) throw error;
+			if (this.#signal().aborted) throw new BrowserConnectionError("Connection aborted", context);
+			throw new BrowserConnectionError((0, _orkestrel_contract.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 _src_core.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 (!(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;
+			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 _src_core.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 _src_core.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 (0, node_events.once)(process, "exit");
+	}
+	async #waitForProcessWithin(process, timeout) {
+		if (process.exitCode !== null || process.signalCode !== null) return true;
+		const signal = AbortSignal.timeout(timeout);
+		try {
+			await (0, node_events.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
@@ -1128,13 +1414,15 @@ exports.BROWSER_EXECUTABLE_PATHS = BROWSER_EXECUTABLE_PATHS;
 exports.BROWSER_HEADLESS_ARG = BROWSER_HEADLESS_ARG;
 exports.BROWSER_KILL_GRACE_MS = BROWSER_KILL_GRACE_MS;
 exports.BROWSER_LAUNCH_ARGS = BROWSER_LAUNCH_ARGS;
-exports.BROWSER_NOT_FOUND_RESULT = BROWSER_NOT_FOUND_RESULT;
 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;
 exports.BROWSER_STORE_GLOBS = BROWSER_STORE_GLOBS;
 exports.BROWSER_STORE_LINK_NAME = BROWSER_STORE_LINK_NAME;
+exports.BROWSER_TRANSPORT_LOSS_CAUSE = BROWSER_TRANSPORT_LOSS_CAUSE;
 exports.BROWSER_TRANSPORT_LOSS_DEFER_MS = BROWSER_TRANSPORT_LOSS_DEFER_MS;
 exports.BROWSER_WINDOWS_ROOT_FALLBACKS = BROWSER_WINDOWS_ROOT_FALLBACKS;
 exports.BROWSER_WINDOWS_SUFFIXES = BROWSER_WINDOWS_SUFFIXES;
@@ -1145,11 +1433,12 @@ exports.BrowserNotConnectedError = BrowserNotConnectedError;
 exports.WebSocketCDPTransport = WebSocketCDPTransport;
 exports.browserToEngine = browserToEngine;
 exports.createBrowser = createBrowser;
+exports.createBrowserProfile = createBrowserProfile;
 exports.createCDPTransport = createCDPTransport;
 exports.createScreenshotWriter = createScreenshotWriter;
 exports.defaultInstallPaths = defaultInstallPaths;
 exports.defaultStoreBases = defaultStoreBases;
-exports.fetchCdpTargets = fetchCdpTargets;
+exports.fetchCDPTargets = fetchCDPTargets;
 exports.findAllEnvOverrides = findAllEnvOverrides;
 exports.findAllInStore = findAllInStore;
 exports.findAllInstallPaths = findAllInstallPaths;
@@ -1166,7 +1455,8 @@ exports.normalizeExecutablePath = normalizeExecutablePath;
 exports.parseBrowserEngine = parseBrowserEngine;
 exports.probeAllPathNames = probeAllPathNames;
 exports.probePathNames = probePathNames;
-exports.waitForCdpReady = waitForCdpReady;
+exports.removeBrowserProfile = removeBrowserProfile;
+exports.waitForCDPReady = waitForCDPReady;
 exports.windowsRoots = windowsRoots;
 
 //# sourceMappingURL=index.cjs.map