@orkestrel/browser 0.0.14 → 0.0.16

package/dist/src/server/index.js

@@ -1,4 +1,4 @@
-import { BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_WAIT_POLL_INTERVAL_MS, BrowserContext, BrowserError, CDPClient, validateBrowserContextOptions } from "../core/index.js";
+import { BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_WAIT_POLL_INTERVAL_MS, BrowserContext, BrowserError, BrowserTransition, CDPClient, validateBrowserContextOptions } from "../core/index.js";
 import { attempt, isArray, isError, isInstance, isInteger, isRecord, isString } from "@orkestrel/contract";
 import { existsSync, globSync } from "node:fs";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
@@ -13,35 +13,75 @@ import { Emitter } from "@orkestrel/emitter";
 import { WEBSOCKET_READY_CLOSED, WEBSOCKET_READY_OPEN, WEBSOCKET_VERSION, computeWebSocketAccept, createNodeWebSocket } from "@orkestrel/websocket";
 import { addAbortListener, once } from "node:events";
 //#region src/server/constants.ts
-/** Default CDP port probed for an existing browser and used for launches. */
+/**
+* Sets the default CDP port probed for an existing browser and used for launches, `9222`.
+*/
 var BROWSER_DEFAULT_CDP_PORT = 9222;
-/** Default host probed for an existing browser and used for launches (avoids `localhost` resolving to `::1` when Chromium binds `127.0.0.1`). */
+/**
+* Sets the default host probed for an existing browser and used for launches, `'127.0.0.1'`,
+* which avoids `localhost` resolving to `::1` when Chromium binds `127.0.0.1`.
+*/
 var BROWSER_DEFAULT_HOST = "127.0.0.1";
-/** Protocol prefix for CDP discovery requests. */
+/** Names the protocol prefix for CDP discovery requests, `'http'`. */
 var BROWSER_CDP_PROTOCOL = "http";
-/** Path appended to the CDP host to fetch version metadata (endpoint discovery). */
+/**
+* Names the path appended to the CDP host to fetch version metadata, `'/json/version'`, which
+* is where endpoint discovery reads.
+*/
 var BROWSER_CDP_VERSION_PATH = "/json/version";
-/** Path appended to the CDP host to list open targets (pages, workers, etc). */
+/**
+* Names the path appended to the CDP host to list open targets — pages, workers, and every
+* other target category Chromium reports — `'/json/list'`.
+*/
 var BROWSER_CDP_LIST_PATH = "/json/list";
-/** Flags always passed to a launched browser process, alongside the caller's own. */
+/** Lists the 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. */
+/**
+* Names the flag that enables headless mode on a launched browser process, `'--headless=new'`.
+*/
 var BROWSER_HEADLESS_ARG = "--headless=new";
-/** Prefix for isolated browser profiles created beneath the operating-system temp directory. */
+/**
+* Names the prefix for isolated browser profiles created beneath the operating-system temp
+* directory, `'orkestrel-browser-'`.
+*/
 var BROWSER_PROFILE_PREFIX = "orkestrel-browser-";
-/** Bound for each launched-process exit window during TERM-to-KILL teardown. */
+/**
+* Bounds each launched-process exit window during TERM-to-KILL teardown at `3_000`
+* milliseconds.
+*/
 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. */
+/**
+* Bounds the `discover: false` port-occupancy probe before launching at `200` milliseconds,
+* which is short because the probe only needs to detect an already-listening CDP endpoint
+* rather than 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. */
+/**
+* Defers once for `50` milliseconds 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. */
+/**
+* Names the machine-readable error-context cause for an owned browser process exiting,
+* `'process-exit'`.
+*/
 var BROWSER_PROCESS_EXIT_CAUSE = "process-exit";
-/** Machine-readable error-context cause for a CDP transport disconnecting while its browser remains alive. */
+/**
+* Names the machine-readable error-context cause for a CDP transport disconnecting while its
+* browser remains alive, `'transport-loss'`.
+*/
 var BROWSER_TRANSPORT_LOSS_CAUSE = "transport-loss";
-/** Environment variables checked (in order) for an explicit browser executable path override. */
+/**
+* Lists the environment variables checked, in order, for an explicit browser executable path
+* override: `PLAYWRIGHT_EXECUTABLE_PATH`, then `CHROME_PATH`.
+*/
 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`. */
+/**
+* Lists the well-known Chrome/Chromium/Edge executable paths with no platform-specific root,
+* keyed by `process.platform`, leaving `win32` empty because its roots come from
+* `BROWSER_WINDOWS_SUFFIXES`.
+*/
 var BROWSER_EXECUTABLE_PATHS = Object.freeze({
 	linux: Object.freeze([
 		"/usr/bin/google-chrome",
@@ -61,18 +101,21 @@ var BROWSER_EXECUTABLE_PATHS = Object.freeze({
 	]),
 	win32: Object.freeze([])
 });
-/** Windows install-root-relative suffixes for Chrome/Edge/Chromium, joined against each candidate root (`PROGRAMFILES`, `PROGRAMFILES(X86)`, `LOCALAPPDATA`). */
+/** Lists the Windows install-root-relative suffixes for Chrome/Edge/Chromium, joined against each candidate root (`PROGRAMFILES`, `PROGRAMFILES(X86)`, `LOCALAPPDATA`). */
 var BROWSER_WINDOWS_SUFFIXES = Object.freeze([
 	"Google\\Chrome\\Application\\chrome.exe",
 	"Microsoft\\Edge\\Application\\msedge.exe",
 	"Chromium\\Application\\chrome.exe"
 ]);
-/** Fallback Windows install roots used when the corresponding environment variable is absent. */
+/**
+* Lists the fallback Windows install roots used when `PROGRAMFILES`, `PROGRAMFILES(X86)`, or
+* `LOCALAPPDATA` is absent.
+*/
 var BROWSER_WINDOWS_ROOT_FALLBACKS = Object.freeze({
 	PROGRAMFILES: "C:\\Program Files",
 	"PROGRAMFILES(X86)": "C:\\Program Files (x86)"
 });
-/** Command names probed on PATH when no well-known executable path exists. */
+/** Lists the command names probed on PATH when no well-known executable path exists. */
 var BROWSER_EXECUTABLE_NAMES = Object.freeze([
 	"google-chrome",
 	"google-chrome-stable",
@@ -82,19 +125,28 @@ var BROWSER_EXECUTABLE_NAMES = Object.freeze([
 	"chromium-browser",
 	"chrome"
 ]);
-/** Environment variable naming an additional Playwright browser store base directory. */
+/**
+* Names the environment variable that carries an additional Playwright browser store base
+* directory, `'PLAYWRIGHT_BROWSERS_PATH'`.
+*/
 var BROWSER_STORE_ENV_KEY = "PLAYWRIGHT_BROWSERS_PATH";
-/** Well-known Playwright browser store base directories checked in addition to `PLAYWRIGHT_BROWSERS_PATH`. */
+/**
+* Lists the well-known Playwright browser store base directories checked in addition to
+* `PLAYWRIGHT_BROWSERS_PATH`, starting with `/opt/pw-browsers`.
+*/
 var BROWSER_STORE_DEFAULT_DIRS = Object.freeze(["/opt/pw-browsers"]);
-/** Per-OS default Playwright browser cache directory, relative to the home directory (win32 uses `LOCALAPPDATA` directly). */
+/** Names the per-OS default Playwright browser cache directory, relative to the home directory (win32 uses `LOCALAPPDATA` directly). */
 var BROWSER_STORE_CACHE_DIRS = Object.freeze({
 	linux: ".cache/ms-playwright",
 	darwin: "Library/Caches/ms-playwright"
 });
-/** Name of the top-level Chromium symlink/binary Playwright maintains inside a browser store base. */
+/**
+* Names the top-level Chromium symlink or binary Playwright maintains inside a browser store
+* base, `'chromium'`.
+*/
 var BROWSER_STORE_LINK_NAME = "chromium";
 /**
-* Case-insensitive substrings identifying an executable path/name's browser
+* Lists the case-insensitive substrings identifying an executable path/name's browser
 * engine, checked by `parseBrowserEngine` in the order `edge` → `chromium` → `chrome`.
 */
 var BROWSER_ENGINE_HINTS = Object.freeze({
@@ -118,7 +170,7 @@ var BROWSER_ENGINE_HINTS = Object.freeze({
 		"chrome"
 	])
 });
-/** Glob pattern (relative to a store base) matching a versioned Chromium binary, keyed by `process.platform`. */
+/** Names the glob pattern (relative to a store base) matching a versioned Chromium binary, keyed by `process.platform`. */
 var BROWSER_STORE_GLOBS = Object.freeze({
 	linux: "chromium-*/chrome-linux*/chrome",
 	darwin: "chromium-*/chrome-mac*/Chromium.app/Contents/MacOS/Chromium",
@@ -127,7 +179,8 @@ var BROWSER_STORE_GLOBS = Object.freeze({
 //#endregion
 //#region src/server/errors.ts
 /**
-* A CDP connection, discovery, or launch attempt failed.
+* Reports that a CDP connection, discovery, or launch attempt failed, under the code
+* `BROWSER_CONNECTION_ERROR`.
 */
 var BrowserConnectionError = class extends BrowserError {
 	constructor(message, context) {
@@ -136,7 +189,8 @@ var BrowserConnectionError = class extends BrowserError {
 	}
 };
 /**
-* An operation requiring an active connection was attempted while disconnected.
+* Reports that an operation requiring an active connection was attempted while disconnected,
+* under the code `BROWSER_NOT_CONNECTED_ERROR`.
 */
 var BrowserNotConnectedError = class extends BrowserError {
 	constructor(context) {
@@ -145,7 +199,8 @@ var BrowserNotConnectedError = class extends BrowserError {
 	}
 };
 /**
-* An operation was attempted after the Browser was destroyed.
+* Reports that an operation was attempted after the browser wrapper was destroyed, under the
+* code `BROWSER_DESTROYED_ERROR`.
 */
 var BrowserDestroyedError = class extends BrowserError {
 	constructor(context) {
@@ -154,28 +209,28 @@ var BrowserDestroyedError = class extends BrowserError {
 	}
 };
 /**
-* Narrow an unknown value to BrowserConnectionError.
+* Narrows an unknown value to a `BrowserConnectionError`.
 *
 * @param value - Value to check
-* @returns True when value is a BrowserConnectionError instance
+* @returns True if value is a BrowserConnectionError instance; false otherwise
 */
 function isBrowserConnectionError(value) {
 	return isInstance(value, BrowserConnectionError);
 }
 /**
-* Narrow an unknown value to BrowserNotConnectedError.
+* Narrows an unknown value to a `BrowserNotConnectedError`.
 *
 * @param value - Value to check
-* @returns True when value is a BrowserNotConnectedError instance
+* @returns True if value is a BrowserNotConnectedError instance; false otherwise
 */
 function isBrowserNotConnectedError(value) {
 	return isInstance(value, BrowserNotConnectedError);
 }
 /**
-* Narrow an unknown value to BrowserDestroyedError.
+* Narrows an unknown value to a `BrowserDestroyedError`.
 *
 * @param value - Value to check
-* @returns True when value is a BrowserDestroyedError instance
+* @returns True if value is a BrowserDestroyedError instance; false otherwise
 */
 function isBrowserDestroyedError(value) {
 	return isInstance(value, BrowserDestroyedError);
@@ -183,7 +238,7 @@ function isBrowserDestroyedError(value) {
 //#endregion
 //#region src/server/helpers.ts
 /**
-* Enumerate every Chrome/Chromium/Edge executable discoverable on this
+* Enumerates every Chrome/Chromium/Edge executable discoverable on this
 * machine, deduplicated by normalized absolute path.
 *
 * @remarks
@@ -197,7 +252,7 @@ function isBrowserDestroyedError(value) {
 *    and the per-OS Playwright cache directory) — the top-level `chromium`
 *    link/binary, then the highest-revision `chromium-*` install found
 *
-* Each candidate is classified into a {@link BrowserEngine} via
+* Each candidate is classified into a {@link BrowserEngine} through
 * `parseBrowserEngine` (unclassifiable candidates default to `'chromium'`),
 * and `options.engine` (when given) narrows the result to that engine.
 *
@@ -208,13 +263,13 @@ function findSystemBrowsers(options) {
 	const platform = process.platform;
 	const env = options?.env ?? process.env;
 	const candidates = [];
-	candidates.push(...findAllEnvOverrides(env));
-	const paths = options?.paths ?? defaultInstallPaths(platform, env);
-	candidates.push(...findAllInstallPaths(paths));
+	candidates.push(...findEnvOverrides(env));
+	const paths = options?.paths ?? buildInstallPaths(platform, env);
+	candidates.push(...findInstallPaths(paths));
 	const names = options?.names ?? BROWSER_EXECUTABLE_NAMES;
-	candidates.push(...probeAllPathNames(names, platform));
-	const stores = options?.stores ?? defaultStoreBases(env, platform);
-	for (const store of stores) candidates.push(...findAllInStore(store, platform));
+	candidates.push(...probePathNames(names, platform));
+	const stores = options?.stores ?? buildStoreBases(env, platform);
+	for (const store of stores) candidates.push(...findStorePaths(store, platform));
 	const seen = /* @__PURE__ */ new Set();
 	const browsers = [];
 	for (const executable of candidates) {
@@ -231,7 +286,7 @@ function findSystemBrowsers(options) {
 	return browsers;
 }
 /**
-* Locate a Chrome/Chromium/Edge executable on this machine — the first entry
+* Locates a Chrome/Chromium/Edge executable on this machine — the first entry
 * of {@link findSystemBrowsers}.
 *
 * @param options - Overrides for the candidate sources; see {@link SystemBrowserOptions}
@@ -241,7 +296,7 @@ function findSystemBrowser(options) {
 	return findSystemBrowsers(options)[0];
 }
 /**
-* Classify an executable path/name into a {@link BrowserEngine} by
+* Classifies an executable path/name into a {@link BrowserEngine} by
 * case-insensitive hint, checked in the order edge → chromium → chrome.
 *
 * @param executable - Executable path or command name to classify
@@ -255,19 +310,19 @@ function parseBrowserEngine(executable) {
 		"chrome"
 	]) if (BROWSER_ENGINE_HINTS[engine].some((hint) => lower.includes(hint))) return engine;
 }
-/** Normalize an executable path for cross-source deduplication (case-insensitive on Windows). */
+/** Normalizes an executable path for cross-source deduplication (case-insensitive on Windows). */
 function normalizeExecutablePath(path, platform) {
 	const normalized = platform === "win32" ? win32.normalize(path) : posix.normalize(path);
 	return platform === "win32" ? normalized.toLowerCase() : normalized;
 }
-/** Classify a `/json/version` `Browser` string into a {@link BrowserEngine} (`Edg/` → edge, `Chrome/` → chrome, else chromium). */
+/** Classifies a `/json/version` `Browser` string into a {@link BrowserEngine} (`Edg/` → edge, `Chrome/` → chrome, else chromium). */
 function browserToEngine(browser) {
 	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.
+* Resolves a persistent caller profile or creates an isolated temporary one.
 *
 * @param path - Optional caller-owned persistent user-data directory
 * @returns The resolved profile and whether the library owns its lifecycle
@@ -283,7 +338,7 @@ async function createBrowserProfile(path) {
 	};
 }
 /**
-* Remove a library-owned isolated browser profile.
+* Removes a library-owned isolated browser profile.
 *
 * @remarks
 * The path must remain a direct child of the operating-system temp directory
@@ -296,7 +351,7 @@ 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");
+	if (dirname(path) !== temporary || !basename(path).startsWith("orkestrel-browser-")) throw new BrowserError("Refusing to remove an unsafe browser profile path", void 0, { path });
 	await rm(path, {
 		recursive: true,
 		force: true,
@@ -304,12 +359,8 @@ async function removeBrowserProfile(profile) {
 		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];
-}
-/** Check the env-override keys (`PLAYWRIGHT_EXECUTABLE_PATH`, `CHROME_PATH`) in order, returning every one that exists. */
-function findAllEnvOverrides(env) {
+/** Checks the env-override keys (`PLAYWRIGHT_EXECUTABLE_PATH`, `CHROME_PATH`) in order and returns every one that exists. */
+function findEnvOverrides(env) {
 	const found = [];
 	for (const key of BROWSER_ENV_PATH_KEYS) {
 		const value = env[key];
@@ -317,36 +368,28 @@ function findAllEnvOverrides(env) {
 	}
 	return found;
 }
-/** Build the default well-known install-path candidates for a platform, deriving Windows roots from env vars. */
-function defaultInstallPaths(platform, env) {
+/** Builds the default well-known install-path candidates for a platform, deriving Windows roots from env vars. */
+function buildInstallPaths(platform, env) {
 	if (platform !== "win32") return BROWSER_EXECUTABLE_PATHS[platform] ?? [];
-	const roots = windowsRoots(env);
+	const roots = buildWindowsRoots(env);
 	const paths = [];
 	for (const root of roots) for (const suffix of BROWSER_WINDOWS_SUFFIXES) paths.push(win32.join(root, suffix));
 	return paths;
 }
-/** Derive Windows install roots from env vars, falling back to well-known literals when absent. */
-function windowsRoots(env) {
+/** Derives Windows install roots from env vars, falling back to well-known literals when absent. */
+function buildWindowsRoots(env) {
 	return [
 		env["PROGRAMFILES"] ?? BROWSER_WINDOWS_ROOT_FALLBACKS["PROGRAMFILES"],
 		env["PROGRAMFILES(X86)"] ?? BROWSER_WINDOWS_ROOT_FALLBACKS["PROGRAMFILES(X86)"],
 		env["LOCALAPPDATA"]
 	].filter((root) => root !== void 0);
 }
-/** Return the first candidate path that exists on disk. */
-function findInstallPath(paths) {
-	return findAllInstallPaths(paths)[0];
-}
-/** Return every candidate path that exists on disk, in the given order. */
-function findAllInstallPaths(paths) {
+/** Returns every candidate path that exists on disk, in the given order. */
+function findInstallPaths(paths) {
 	return paths.filter((path) => existsSync(path));
 }
-/** Probe PATH (`which`/`where`) for the first resolvable command name. */
+/** Probes PATH (`which`/`where`) for every resolvable command name, in the given order. */
 function probePathNames(names, platform) {
-	return probeAllPathNames(names, platform)[0];
-}
-/** Probe PATH (`which`/`where`) for every resolvable command name, in the given order. */
-function probeAllPathNames(names, platform) {
 	const finder = platform === "win32" ? "where" : "which";
 	const found = [];
 	for (const name of names) {
@@ -381,8 +424,8 @@ function readFirstLine(output) {
 		if (text.length > 0) return text;
 	}
 }
-/** Build the default Playwright browser store base directories to search for a managed Chromium. */
-function defaultStoreBases(env, platform) {
+/** Builds the default Playwright browser store base directories to search for a managed Chromium. */
+function buildStoreBases(env, platform) {
 	const bases = [];
 	const envBase = env[BROWSER_STORE_ENV_KEY];
 	if (envBase !== void 0 && envBase.length > 0) bases.push(envBase);
@@ -397,12 +440,8 @@ function defaultStoreBases(env, platform) {
 	}
 	return bases;
 }
-/** Search one store base for the top-level `chromium` link, else the highest-revision `chromium-*` install. */
-function findInStore(base, platform) {
-	return findAllInStore(base, platform)[0];
-}
-/** Search one store base for the top-level `chromium` link and every `chromium-*` install, highest revision first. */
-function findAllInStore(base, platform) {
+/** Searches one store base for the top-level `chromium` link and every `chromium-*` install, highest revision first. */
+function findStorePaths(base, platform) {
 	const joiner = platform === "win32" ? win32.join : posix.join;
 	const found = [];
 	const linkPath = joiner(base, BROWSER_STORE_LINK_NAME);
@@ -416,7 +455,7 @@ function findAllInStore(base, platform) {
 	return found;
 }
 /**
-* Launch a browser process with raw-CDP debugging flags.
+* Launches a browser process with raw-CDP debugging flags.
 *
 * @remarks
 * POSIX launches own an isolated process group so lifecycle teardown can
@@ -446,11 +485,12 @@ function launchBrowserProcess(executable, port, headless, profile, extra) {
 	});
 }
 /**
-* Poll a browser's CDP version endpoint until it responds or the timeout elapses.
+* Polls a browser's CDP version endpoint until it responds or the timeout elapses.
 *
 * @param port - Port the browser exposes its CDP endpoint on
 * @param timeout - Maximum time to wait in milliseconds
 * @param host - Host the browser exposes its CDP endpoint on (default `127.0.0.1`)
+* @param signal - Optional external abort; an abort while waiting rethrows rather than resolving
 * @returns The browser's WebSocket debugger URL
 *
 * @throws When the endpoint does not become ready before the timeout
@@ -474,15 +514,34 @@ async function waitForCDPReady(port, timeout, host = BROWSER_DEFAULT_HOST, signa
 		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`);
+	throw new BrowserConnectionError(`CDP endpoint on port ${port} did not become ready within ${timeout}ms`, {
+		port,
+		timeout
+	});
 }
 /**
-* Fetch the current CDP target list from a browser's `/json/list` endpoint.
+* Fetches the current CDP target list from a browser's `/json/list` endpoint, as a `Result`
+* carrying either the targets or a coded `BrowserConnectionError`.
+*
+* @remarks
+* The endpoint is a network boundary, so an unreachable host, a non-2xx
+* response, and a body that is not a JSON array each come back as a failed
+* `Result` carrying a coded `BrowserConnectionError`. An entry missing a
+* required string field is skipped rather than failing the whole list.
 *
 * @param port - Port the browser exposes its CDP endpoint on
 * @param timeout - Request timeout in milliseconds
 * @param host - Host the browser exposes its CDP endpoint on (default `127.0.0.1`)
-* @returns Normalized CDP targets
+* @returns The normalized CDP targets, or the fault that stopped the request
+*
+* @example
+* ```ts
+* import { fetchCDPTargets } from '@orkestrel/browser/server'
+*
+* const result = await fetchCDPTargets(9222, 2000)
+* if (result.success) log(result.value.length)
+* else log(result.error.code)
+* ```
 */
 async function fetchCDPTargets(port, timeout, host = BROWSER_DEFAULT_HOST) {
 	const url = `${BROWSER_CDP_PROTOCOL}://${host}:${port}${BROWSER_CDP_LIST_PATH}`;
@@ -490,23 +549,41 @@ async function fetchCDPTargets(port, timeout, host = BROWSER_DEFAULT_HOST) {
 	const timer = setTimeout(() => controller.abort(), timeout);
 	try {
 		const response = await fetch(url, { signal: controller.signal });
-		if (!response.ok) return [];
+		if (!response.ok) return {
+			success: false,
+			error: new BrowserConnectionError("CDP target list request was refused", {
+				url,
+				status: response.status
+			})
+		};
 		const list = await response.json();
-		if (!isArray(list)) return [];
+		if (!isArray(list)) return {
+			success: false,
+			error: new BrowserConnectionError("CDP target list is not a JSON array", { url })
+		};
 		const targets = [];
 		for (const entry of list) {
 			if (!isRecord(entry)) continue;
 			if (!isString(entry["id"]) || !isString(entry["type"]) || !isString(entry["title"]) || !isString(entry["url"])) continue;
 			targets.push({
 				id: entry["id"],
-				type: entry["type"],
+				category: entry["type"],
 				title: entry["title"],
 				url: entry["url"]
 			});
 		}
-		return targets;
-	} catch {
-		return [];
+		return {
+			success: true,
+			value: targets
+		};
+	} catch (error) {
+		return {
+			success: false,
+			error: new BrowserConnectionError("CDP target list is unreachable", {
+				url,
+				error
+			})
+		};
 	} finally {
 		clearTimeout(timer);
 	}
@@ -514,27 +591,36 @@ async function fetchCDPTargets(port, timeout, host = BROWSER_DEFAULT_HOST) {
 //#endregion
 //#region src/server/transports/WebSocketCDPTransport.ts
 /**
-* `@orkestrel/websocket`-backed raw CDP text transport.
+* Provides a raw CDP text transport backed by `@orkestrel/websocket`.
 *
 * @remarks
 * 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.
+*
+* @example
+* ```ts
+* import { WebSocketCDPTransport } from '@orkestrel/browser/server'
+*
+* const transport = new WebSocketCDPTransport({ url: 'ws://127.0.0.1:9222/devtools/browser/abc' })
+* await transport.start()
+* await transport.close()
+* ```
 */
 var WebSocketCDPTransport = class {
 	#emitter;
 	#url;
 	#timeout;
 	#socket;
-	#starting;
-	#closing;
+	#starting = new BrowserTransition();
+	#closing = new BrowserTransition();
 	#request;
 	#resolve;
 	#reject;
 	#timer;
 	#closeResolve;
-	#onSocketClose = this.#handleSocketClose.bind(this);
+	#socketCloseHandler = this.#handleSocketClose.bind(this);
 	constructor(options) {
 		this.#emitter = new Emitter({
 			...options.on !== void 0 ? { on: options.on } : {},
@@ -547,43 +633,27 @@ var WebSocketCDPTransport = class {
 		return this.#emitter;
 	}
 	async start() {
-		if (this.#closing !== void 0) await this.#closing;
+		const closing = this.#closing.pending;
+		if (closing !== void 0) await closing;
 		if (this.#socket?.readyState === WEBSOCKET_READY_OPEN) return;
-		const active = this.#starting;
+		const active = this.#starting.pending;
 		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;
-		}
+		await this.#starting.execute(() => this.#start());
 	}
 	async send(data) {
 		const socket = this.#socket;
-		if (socket === void 0 || socket.readyState !== WEBSOCKET_READY_OPEN) throw new Error("WebSocket CDP transport is not open");
+		if (socket === void 0 || socket.readyState !== WEBSOCKET_READY_OPEN) throw new BrowserConnectionError("WebSocket CDP transport is not open", { url: this.#url });
 		socket.send(data);
 	}
 	async close() {
-		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;
-		}
+		await this.#closing.execute(() => this.#close());
 	}
-	async #open() {
+	async #start() {
 		const parsed = attempt(() => new URL(this.#url));
 		if (!parsed.success) throw new BrowserConnectionError(`WebSocket CDP URL is invalid: ${this.#url}`, {
 			url: this.#url,
@@ -619,19 +689,19 @@ var WebSocketCDPTransport = class {
 		this.#socket = socket;
 		this.#bind(socket);
 	}
-	async #stop() {
+	async #close() {
 		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);
+		await this.#starting.pending?.catch(() => void 0);
 		const socket = this.#socket;
 		this.#socket = void 0;
 		if (socket === void 0 || socket.readyState === WEBSOCKET_READY_CLOSED) return;
 		const closed = Promise.withResolvers();
 		this.#closeResolve = closed.resolve;
-		socket.emitter.on("close", this.#onSocketClose);
+		socket.emitter.on("close", this.#socketCloseHandler);
 		try {
 			socket.close();
 			if (socket.readyState !== WEBSOCKET_READY_CLOSED) await closed.promise;
@@ -639,7 +709,7 @@ var WebSocketCDPTransport = class {
 			socket.destroy();
 			if (socket.readyState !== WEBSOCKET_READY_CLOSED) await closed.promise;
 		} finally {
-			socket.emitter.off("close", this.#onSocketClose);
+			socket.emitter.off("close", this.#socketCloseHandler);
 			this.#closeResolve = void 0;
 		}
 	}
@@ -714,26 +784,61 @@ var WebSocketCDPTransport = class {
 	}
 };
 //#endregion
+//#region src/server/writers/FileBrowserWriter.ts
+/**
+* Persists captured browser bytes to the filesystem through `node:fs/promises`.
+*
+* @remarks
+* Creates every missing parent directory of the target path before writing, so
+* a caller may name a nested destination that does not exist yet.
+*
+* @example
+* ```ts
+* import { FileBrowserWriter } from '@orkestrel/browser/server'
+*
+* const writer = new FileBrowserWriter()
+* await writer.write('shots/hero.png', new Uint8Array([137, 80, 78, 71]))
+* ```
+*/
+var FileBrowserWriter = class {
+	/**
+	* Writes the captured bytes to a path, creating its parent directories.
+	*
+	* @param path - Destination file path
+	* @param data - Captured bytes to persist
+	* @returns A promise resolving once the bytes are on disk
+	*/
+	async write(path, data) {
+		await mkdir(dirname(path), { recursive: true });
+		await writeFile(path, data);
+	}
+};
+//#endregion
 //#region src/server/factories.ts
 /**
-* Create a raw-CDP Browser façade.
+* Creates a raw-CDP `BrowserInterface` façade with discovery, connection, and lifecycle
+* management.
 *
 * @param options - Connection, launch, and viewport configuration
 * @returns A {@link BrowserInterface}
 *
-* @example
+* @example Connect to a browser and drive a page
 * ```ts
-* import { createBrowser } from '@src/server'
+* import { createBrowser } from '@orkestrel/browser/server'
 *
-* const browser = createBrowser()
-* await browser.connect()
+* const browser = createBrowser({ headless: true })
+* await browser.connect() // CDP endpoint discovery → connect, else launch
+* const page = await browser.create({ url: 'https://example.com' })
+* await page.click('#accept')
+* const shot = await page.screenshot({ path: './out.png' })
+* await browser.destroy()
 * ```
 */
 function createBrowser(options) {
 	return new Browser(options);
 }
 /**
-* Create a Node `WebSocket`-backed CDP transport.
+* Creates a Node `WebSocket`-backed `CDPTransportInterface` for the given CDP debugger URL.
 *
 * @param options - The CDP WebSocket debugger URL (and optional timeout)
 * @returns A {@link CDPTransportInterface}
@@ -742,20 +847,28 @@ function createCDPTransport(options) {
 	return new WebSocketCDPTransport(options);
 }
 /**
-* Create a filesystem-backed screenshot writer.
+* Creates a filesystem-backed `BrowserWriterInterface` that persists bytes through
+* `node:fs/promises`.
 *
-* @returns A {@link ScreenshotWriterInterface} that persists bytes via `node:fs/promises`
+* @returns A {@link BrowserWriterInterface} that persists bytes through `node:fs/promises`
 */
-function createScreenshotWriter() {
-	return { async write(path, data) {
-		await mkdir(dirname(path), { recursive: true });
-		await writeFile(path, data);
-	} };
+function createBrowserWriter() {
+	return new FileBrowserWriter();
 }
 //#endregion
 //#region src/server/Browser.ts
 /**
 * Discovers, launches, connects to, and owns Chromium-family browser sessions.
+*
+* @example
+* ```ts
+* import { Browser } from '@orkestrel/browser/server'
+*
+* const browser = new Browser({ headless: true })
+* await browser.connect()
+* const page = await browser.create({ url: 'https://example.com' })
+* await browser.destroy()
+* ```
 */
 var Browser = class {
 	#emitter;
@@ -774,14 +887,14 @@ var Browser = class {
 	#profile;
 	#contexts = [];
 	#destroyed = false;
-	#connecting;
-	#disconnecting;
+	#connecting = new BrowserTransition();
+	#disconnecting = new BrowserTransition();
 	#exitCleanup;
 	#shutdown;
 	#transport;
-	#onTransportClose = this.#handleTransportLoss.bind(this);
-	#onTransportError = this.#handleTransportLoss.bind(this);
-	#onProcessExit = this.#handleProcessExit.bind(this);
+	#transportCloseHandler = this.#handleTransportLoss.bind(this);
+	#transportErrorHandler = this.#handleTransportLoss.bind(this);
+	#processExitHandler = this.#handleProcessExit.bind(this);
 	constructor(options) {
 		this.#emitter = new Emitter({
 			...options?.on !== void 0 ? { on: options.on } : {},
@@ -808,9 +921,6 @@ var Browser = class {
 	get owned() {
 		return this.#owned;
 	}
-	get connected() {
-		return this.#status === "connected";
-	}
 	get pid() {
 		return this.#servingPid ?? this.#process?.pid;
 	}
@@ -821,19 +931,13 @@ var Browser = class {
 	}
 	async connect() {
 		if (this.#destroyed) throw new BrowserDestroyedError();
-		const active = this.#connecting;
+		const active = this.#connecting.pending;
 		if (active !== void 0) {
 			await active;
 			return;
 		}
 		if (this.#status === "connected") return;
-		const attempt = this.#establish();
-		this.#connecting = attempt;
-		try {
-			await attempt;
-		} finally {
-			if (this.#connecting === attempt) this.#connecting = void 0;
-		}
+		await this.#connecting.execute(() => this.#establish());
 	}
 	adopt() {
 		if (this.#destroyed) throw new BrowserDestroyedError();
@@ -842,19 +946,13 @@ var Browser = class {
 	}
 	async disconnect() {
 		if (this.#destroyed) return;
-		const disconnecting = this.#disconnecting;
-		const connecting = this.#connecting;
+		const disconnecting = this.#disconnecting.pending;
+		const connecting = this.#connecting.pending;
 		if (disconnecting !== void 0) await disconnecting;
 		if (connecting !== void 0) await connecting.catch(() => void 0);
 		if (this.#destroyed) return;
 		if (this.#status !== "connected" || this.#client === void 0) return;
-		const attempt = this.#detach();
-		this.#disconnecting = attempt;
-		try {
-			await attempt;
-		} finally {
-			if (this.#disconnecting === attempt) this.#disconnecting = void 0;
-		}
+		await this.#disconnecting.execute(() => this.#detach());
 	}
 	context(index) {
 		const i = index ?? 0;
@@ -878,7 +976,7 @@ var Browser = class {
 		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);
+		const context = new BrowserContext(client, id, options?.emulation?.viewport ?? this.#options.viewport, createBrowserWriter(), options?.emulation, options?.downloads, options);
 		try {
 			if (options?.downloads !== void 0) await client.send("Browser.setDownloadBehavior", {
 				behavior: options.downloads.named === true ? "allowAndName" : "allow",
@@ -899,7 +997,7 @@ var Browser = class {
 		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());
+			context = new BrowserContext(client, void 0, this.#options.viewport, createBrowserWriter());
 			this.#registerContext(context);
 		}
 		const page = await context.create(options);
@@ -927,7 +1025,8 @@ var Browser = class {
 		return shutdown;
 	}
 	async #establish() {
-		if (this.#disconnecting !== void 0) await this.#disconnecting;
+		const disconnecting = this.#disconnecting.pending;
+		if (disconnecting !== void 0) await disconnecting;
 		await this.#settleExit();
 		if (this.#destroyed) throw new BrowserDestroyedError();
 		if (this.#status === "connected") return;
@@ -945,7 +1044,7 @@ var Browser = class {
 			}
 			if (this.#options.cdp?.discover ?? true) {
 				const discovery = await this.#raceAbort(this.#discoverCDP(this.#signal()));
-				if (discovery.found && discovery.endpoint !== void 0) {
+				if (discovery.endpoint !== void 0) {
 					this.#engine = browserToEngine(discovery.browser);
 					await this.#connectCDP(discovery.endpoint);
 					return;
@@ -1063,24 +1162,24 @@ var Browser = class {
 	#bindTransport(transport) {
 		this.#unbindTransport();
 		this.#transport = transport;
-		transport.emitter.on("close", this.#onTransportClose);
-		transport.emitter.on("error", this.#onTransportError);
+		transport.emitter.on("close", this.#transportCloseHandler);
+		transport.emitter.on("error", this.#transportErrorHandler);
 	}
 	#unbindTransport() {
 		const transport = this.#transport;
 		if (transport === void 0) return;
-		transport.emitter.off("close", this.#onTransportClose);
-		transport.emitter.off("error", this.#onTransportError);
+		transport.emitter.off("close", this.#transportCloseHandler);
+		transport.emitter.off("error", this.#transportErrorHandler);
 		this.#transport = void 0;
 	}
 	#bindProcess(process) {
 		this.#unbindProcess();
 		if (this.#servingPid !== void 0) return;
-		process.once("exit", this.#onProcessExit);
-		if (process.exitCode !== null || process.signalCode !== null) queueMicrotask(this.#onProcessExit);
+		process.once("exit", this.#processExitHandler);
+		if (process.exitCode !== null || process.signalCode !== null) queueMicrotask(this.#processExitHandler);
 	}
 	#unbindProcess() {
-		this.#process?.off("exit", this.#onProcessExit);
+		this.#process?.off("exit", this.#processExitHandler);
 	}
 	#timeout() {
 		return this.#options.timeout ?? BROWSER_DEFAULT_TIMEOUT_MS;
@@ -1093,13 +1192,9 @@ var Browser = class {
 			if (!response.ok) return this.#notFound();
 			const info = await response.json();
 			if (!isRecord(info)) return this.#notFound();
-			const endpoint = isString(info["webSocketDebuggerUrl"]) ? info["webSocketDebuggerUrl"] : void 0;
-			const browser = isString(info["Browser"]) ? info["Browser"] : void 0;
 			return {
-				found: endpoint !== void 0,
-				endpoint,
-				browser,
-				connection: endpoint !== void 0 ? "cdp" : void 0
+				endpoint: isString(info["webSocketDebuggerUrl"]) ? info["webSocketDebuggerUrl"] : void 0,
+				browser: isString(info["Browser"]) ? info["Browser"] : void 0
 			};
 		} catch (error) {
 			if (signal?.aborted === true) throw error;
@@ -1108,10 +1203,8 @@ var Browser = class {
 	}
 	#notFound() {
 		return {
-			found: false,
 			endpoint: void 0,
-			browser: void 0,
-			connection: void 0
+			browser: void 0
 		};
 	}
 	async #assertPortFree() {
@@ -1312,13 +1405,13 @@ var Browser = class {
 			if (!isRecord(target) || !isString(target["targetId"]) || target["type"] !== "page" || !isString(target["title"]) || !isString(target["url"])) continue;
 			pages.push({
 				id: target["targetId"],
-				type: target["type"],
+				category: 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());
+		const context = new BrowserContext(client, void 0, this.#options.viewport, createBrowserWriter());
 		await context.sync(pages);
 		this.#registerContext(context);
 	}
@@ -1382,8 +1475,8 @@ var Browser = class {
 		}
 	}
 	async #settle() {
-		await this.#connecting?.catch(() => void 0);
-		await this.#disconnecting?.catch(() => void 0);
+		await this.#connecting.pending?.catch(() => void 0);
+		await this.#disconnecting.pending?.catch(() => void 0);
 		await this.#settleExit();
 	}
 	async #settleExit() {
@@ -1549,6 +1642,6 @@ var Browser = class {
 	}
 };
 //#endregion
-export { BROWSER_CDP_LIST_PATH, BROWSER_CDP_PROTOCOL, BROWSER_CDP_VERSION_PATH, BROWSER_DEFAULT_CDP_PORT, BROWSER_DEFAULT_HOST, BROWSER_ENGINE_HINTS, BROWSER_ENV_PATH_KEYS, BROWSER_EXECUTABLE_NAMES, BROWSER_EXECUTABLE_PATHS, BROWSER_HEADLESS_ARG, BROWSER_KILL_GRACE_MS, BROWSER_LAUNCH_ARGS, BROWSER_PORT_PROBE_TIMEOUT_MS, BROWSER_PROCESS_EXIT_CAUSE, BROWSER_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, readFirstLine, removeBrowserProfile, 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, FileBrowserWriter, WebSocketCDPTransport, browserToEngine, buildInstallPaths, buildStoreBases, buildWindowsRoots, createBrowser, createBrowserProfile, createBrowserWriter, createCDPTransport, fetchCDPTargets, findEnvOverrides, findInstallPaths, findStorePaths, findSystemBrowser, findSystemBrowsers, isBrowserConnectionError, isBrowserDestroyedError, isBrowserNotConnectedError, launchBrowserProcess, normalizeExecutablePath, parseBrowserEngine, probePathNames, readFirstLine, removeBrowserProfile, waitForCDPReady };
 
 //# sourceMappingURL=index.js.map