@orkestrel/browser 0.0.12 → 0.0.14

package/dist/src/server/index.d.ts

@@ -231,15 +231,17 @@ export declare type BrowserEventMap = {
  *   process exiting on its own) drives the disconnected state, preceded by
  *   a coded `error` — `connect()` on the same instance can reattach afterward.
  * - `destroy` — release local resources. On a launched browser this closes
- *   pages/contexts, then kills and awaits the process plus its POSIX process
- *   group. On an adopted browser it sends `Browser.close`. On a merely
+ *   pages/contexts, then kills and awaits the process serving the CDP endpoint
+ *   plus its POSIX process group. On an adopted browser it sends
+ *   `Browser.close`. On a merely
  *   attached browser this is a LOCAL DETACH ONLY because other clients may
  *   share its targets. Idempotent.
  * - `close` — graceful REMOTE shutdown: best-effort sends CDP `Browser.close`
- *   (works whether attached or owned), and when owned also awaits the
- *   process's exit and POSIX group drain (escalating to a kill only if needed),
- *   then performs the same local cleanup as `destroy()`. Use this to shut
- *   down a browser this instance doesn't own but wants to terminate anyway.
+ *   (works whether attached or owned), and when owned also awaits the exit of
+ *   the process serving the CDP endpoint plus its POSIX process-group drain
+ *   (escalating to a kill only if needed), then performs the same local cleanup
+ *   as `destroy()`. Use this to shut down a browser this instance doesn't own
+ *   but wants to terminate anyway.
  *
  * **Page management:**
  * - `context(index?)` → one context or first
@@ -261,12 +263,17 @@ export declare interface BrowserInterface {
     readonly owned: boolean | undefined;
     readonly connected: boolean;
     /**
-     * The process this instance launched, if any, while it is believed alive.
+     * The process serving this session's CDP endpoint, if any, while it is
+     * believed alive.
      *
      * @remarks
-     * Remains readable after a persistent disconnect (the process keeps
-     * running, detached from the transport) until `destroy()` or an
-     * observed process exit clears it.
+     * A launch owns the process behind its endpoint rather than the process it
+     * spawned. The two are the same until the spawned process is a launcher
+     * that re-executes the browser and exits before the endpoint answers —
+     * Microsoft Edge on Windows — in which case this reports the process the
+     * launcher handed the endpoint to. Remains readable after a persistent
+     * disconnect (the process keeps running, detached from the transport)
+     * until `destroy()` or an observed process exit clears it.
      */
     readonly pid: number | undefined;
     discover(): Promise<BrowserDiscoveryResult>;
@@ -481,6 +488,11 @@ export declare function isBrowserNotConnectedError(value: unknown): value is Bro
  * @remarks
  * POSIX launches own an isolated process group so lifecycle teardown can
  * signal and await every Chromium subprocess without affecting the caller.
+ * Windows launches are not detached and own no group, so teardown there
+ * signals one process by identifier: the spawned process, or the process the
+ * launcher handed the endpoint to when that spawned process re-executed the
+ * browser and exited. Terminating a Chromium browser process takes its own
+ * subprocesses with it, so that single signal drains the tree.
  *
  * @param executable - Absolute path to the browser executable
  * @param port - Port the browser exposes its CDP endpoint on
@@ -509,6 +521,25 @@ export declare function probeAllPathNames(names: readonly string[], platform: st
 /** Probe PATH (`which`/`where`) for the first resolvable command name. */
 export declare function probePathNames(names: readonly string[], platform: string): string | undefined;
 
+/**
+ * Returns the first non-empty line of a command's output, without its
+ * surrounding whitespace.
+ *
+ * @remarks
+ * `where` reports every PATH match on its own CRLF-terminated line, so a
+ * carriage return left on the first line would travel into `existsSync` and
+ * `spawn` as part of the executable path.
+ *
+ * @param output - Raw decoded standard output of a command
+ * @returns The first line carrying text, or undefined when the output has none
+ *
+ * @example
+ * ```ts
+ * readFirstLine('C:\\bin\\chrome.exe\r\nC:\\other\\chrome.exe\r\n') // 'C:\\bin\\chrome.exe'
+ * ```
+ */
+export declare function readFirstLine(output: string): string | undefined;
+
 /**
  * Remove a library-owned isolated browser profile.
  *

package/dist/src/server/index.js

@@ -352,12 +352,35 @@ function probeAllPathNames(names, platform) {
 	for (const name of names) {
 		const result = spawnSync(finder, [name], { stdio: "pipe" });
 		if (result.status === 0) {
-			const output = result.stdout.toString("utf-8").trim().split("\n")[0];
-			if (output !== void 0 && output.length > 0) found.push(output);
+			const executable = readFirstLine(result.stdout.toString("utf-8"));
+			if (executable !== void 0) found.push(executable);
 		}
 	}
 	return found;
 }
+/**
+* Returns the first non-empty line of a command's output, without its
+* surrounding whitespace.
+*
+* @remarks
+* `where` reports every PATH match on its own CRLF-terminated line, so a
+* carriage return left on the first line would travel into `existsSync` and
+* `spawn` as part of the executable path.
+*
+* @param output - Raw decoded standard output of a command
+* @returns The first line carrying text, or undefined when the output has none
+*
+* @example
+* ```ts
+* readFirstLine('C:\\bin\\chrome.exe\r\nC:\\other\\chrome.exe\r\n') // 'C:\\bin\\chrome.exe'
+* ```
+*/
+function readFirstLine(output) {
+	for (const line of output.split(/\r?\n/)) {
+		const text = line.trim();
+		if (text.length > 0) return text;
+	}
+}
 /** Build the default Playwright browser store base directories to search for a managed Chromium. */
 function defaultStoreBases(env, platform) {
 	const bases = [];
@@ -398,6 +421,11 @@ function findAllInStore(base, platform) {
 * @remarks
 * POSIX launches own an isolated process group so lifecycle teardown can
 * signal and await every Chromium subprocess without affecting the caller.
+* Windows launches are not detached and own no group, so teardown there
+* signals one process by identifier: the spawned process, or the process the
+* launcher handed the endpoint to when that spawned process re-executed the
+* browser and exited. Terminating a Chromium browser process takes its own
+* subprocesses with it, so that single signal drains the tree.
 *
 * @param executable - Absolute path to the browser executable
 * @param port - Port the browser exposes its CDP endpoint on
@@ -742,6 +770,7 @@ var Browser = class {
 	#endpoint;
 	#client;
 	#process;
+	#servingPid;
 	#profile;
 	#contexts = [];
 	#destroyed = false;
@@ -783,7 +812,7 @@ var Browser = class {
 		return this.#status === "connected";
 	}
 	get pid() {
-		return this.#process?.pid;
+		return this.#servingPid ?? this.#process?.pid;
 	}
 	async discover() {
 		const result = await this.#discoverCDP();
@@ -979,6 +1008,7 @@ var Browser = class {
 		this.#unbindTransport();
 		this.#unbindProcess();
 		this.#process = void 0;
+		this.#servingPid = void 0;
 		const cleanup = this.#cleanupExitedProcess(process, contexts, client);
 		this.#exitCleanup = cleanup;
 		cleanup.catch((error) => this.#emitter.emit("error", error));
@@ -996,27 +1026,19 @@ var Browser = class {
 	}
 	#handleTransportLoss() {
 		if (this.#destroyed || this.#status !== "connected") return;
-		const process = this.#process;
-		if (process !== void 0 && (process.exitCode !== null || process.signalCode !== null)) {
-			this.#handleProcessExit();
+		if (this.#process === void 0) {
+			this.#confirmTransportLoss();
 			return;
 		}
-		if (process !== void 0) {
-			setTimeout(() => this.#confirmTransportLoss(), 50);
+		if (!this.#alive()) {
+			this.#handleProcessExit();
 			return;
 		}
-		this.#confirmTransportLoss();
+		setTimeout(() => this.#confirmTransportLoss(), 50);
 	}
 	#confirmTransportLoss() {
 		if (this.#destroyed || this.#status !== "connected") return;
-		const process = this.#process;
-		if (process !== void 0 && (process.exitCode !== null || process.signalCode !== null)) {
-			this.#handleProcessExit();
-			return;
-		}
-		if (process?.pid !== void 0) try {
-			process.kill(0);
-		} catch {
+		if (this.#process !== void 0 && !this.#alive()) {
 			this.#handleProcessExit();
 			return;
 		}
@@ -1053,6 +1075,7 @@ var Browser = class {
 	}
 	#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);
 	}
@@ -1177,6 +1200,7 @@ var Browser = class {
 				timeout: this.#timeout()
 			});
 			await this.#raceAbort(client.connect());
+			await this.#takeEndpointOwner(process, client);
 			const connection = this.#options.profile === void 0 ? "launch" : "persistent";
 			this.#client = client;
 			this.#endpoint = endpoint;
@@ -1195,12 +1219,49 @@ var Browser = class {
 			await this.#terminate(process);
 			await this.#releaseProfile();
 			this.#process = void 0;
+			this.#servingPid = void 0;
 			this.#client = void 0;
 			this.#endpoint = void 0;
 			this.#owned = void 0;
 			throw error;
 		}
 	}
+	/**
+	* Takes over the process serving the CDP endpoint when the spawned child is
+	* no longer it.
+	*
+	* @remarks
+	* A Windows launcher — Microsoft Edge — re-executes the browser with the
+	* same `--remote-debugging-port` and exits 0 before the endpoint answers, so
+	* the child this instance spawned parents the real tree without being part
+	* of it. Chromium names the process behind the endpoint as the `browser`
+	* entry of `SystemInfo.getProcessInfo`, which identifies it without a
+	* platform branch. An endpoint that names no such process cannot be owned,
+	* so the launch closes it and fails rather than leaking it.
+	*/
+	async #takeEndpointOwner(process, client) {
+		if (process.exitCode === null && process.signalCode === null) return;
+		let result;
+		try {
+			result = await client.send("SystemInfo.getProcessInfo");
+		} catch {
+			result = void 0;
+		}
+		let pid;
+		if (isRecord(result) && isArray(result["processInfo"])) for (const entry of result["processInfo"]) {
+			if (!isRecord(entry) || entry["type"] !== "browser" || !isInteger(entry["id"])) continue;
+			pid = entry["id"];
+			break;
+		}
+		if (pid === void 0) {
+			await this.#closeRemote(client);
+			throw new BrowserConnectionError("The browser launcher exited without naming the process serving its CDP endpoint", {
+				executable: this.#options.executable,
+				pid: process.pid
+			});
+		}
+		this.#servingPid = pid;
+	}
 	async #waitForLaunch(process, executable, args) {
 		const context = {
 			executable,
@@ -1212,6 +1273,7 @@ var Browser = class {
 		const exited = once(process, "exit", { signal }).then((values) => {
 			const code = isInteger(values[0]) ? values[0] : null;
 			const exitSignal = isString(values[1]) ? values[1] : null;
+			if (code === 0 && exitSignal === null) return ready;
 			throw new BrowserConnectionError(this.#formatLaunchExit(code, exitSignal), context);
 		});
 		try {
@@ -1274,6 +1336,7 @@ var Browser = class {
 			this.#contexts = [];
 			await this.#terminate(this.#process);
 			this.#process = void 0;
+			this.#servingPid = void 0;
 			terminated = true;
 		} finally {
 			const contexts = this.#contexts;
@@ -1303,6 +1366,7 @@ var Browser = class {
 				if (!await this.#waitForTerminationWithin(process, 3e3)) await this.#terminate(process);
 			}
 			this.#process = void 0;
+			this.#servingPid = void 0;
 			terminated = true;
 		} finally {
 			const contexts = this.#contexts;
@@ -1414,31 +1478,39 @@ var Browser = class {
 		const pid = process.pid;
 		return globalThis.process.platform !== "win32" && pid !== void 0 && pid > 0;
 	}
-	#inspectProcessGroup(process) {
-		if (!this.#hasProcessGroup(process)) return false;
+	#alive() {
+		const process = this.#process;
+		if (process === void 0) return false;
+		if (this.#servingPid !== void 0) return this.#signalProcess(process, 0) !== false;
+		return process.exitCode === null && process.signalCode === null;
+	}
+	#inspectRemainder(process) {
+		if (!this.#hasProcessGroup(process) && this.#servingPid === void 0) return false;
 		return this.#signalProcess(process, 0);
 	}
 	#signalProcess(process, signal) {
 		const pid = process.pid;
+		const serving = this.#servingPid;
 		try {
 			if (this.#hasProcessGroup(process) && pid !== void 0) return globalThis.process.kill(-pid, signal);
+			if (serving !== void 0) return globalThis.process.kill(serving, signal);
 			return process.kill(signal);
 		} catch (error) {
 			const code = isError(error) && "code" in error && isString(error.code) ? error.code : void 0;
 			if (code === "ESRCH") return false;
 			if (signal === 0) return code === "EPERM" ? true : void 0;
 			throw new BrowserConnectionError("Failed to signal the browser process", {
-				pid,
+				pid: serving ?? pid,
 				signal,
 				cause: error
 			});
 		}
 	}
-	async #waitForProcessGroupWithin(process, timeout) {
+	async #waitForRemainderWithin(process, timeout) {
 		const deadline = performance.now() + timeout;
 		let confirmed = false;
 		while (true) {
-			const alive = this.#inspectProcessGroup(process);
+			const alive = this.#inspectRemainder(process);
 			if (alive === false) return true;
 			if (alive === true) confirmed = true;
 			const remaining = deadline - performance.now();
@@ -1448,17 +1520,17 @@ var Browser = class {
 	}
 	async #waitForTerminationWithin(process, timeout, final = false) {
 		const exited = this.#waitForProcessWithin(process, timeout);
-		const drained = this.#waitForProcessGroupWithin(process, timeout);
+		const drained = this.#waitForRemainderWithin(process, timeout);
 		const results = await Promise.all([exited, drained]);
 		return results[0] && (results[1] === true || final && results[1] === void 0);
 	}
 	async #terminate(process) {
-		if (process === void 0 || (process.exitCode !== null || process.signalCode !== null) && this.#inspectProcessGroup(process) === false) return;
+		if (process === void 0 || (process.exitCode !== null || process.signalCode !== null) && this.#inspectRemainder(process) === false) return;
 		if (this.#signalProcess(process, "SIGTERM") === false) return;
 		if (await this.#waitForTerminationWithin(process, 3e3)) return;
 		if (this.#signalProcess(process, "SIGKILL") === false) return;
 		if (await this.#waitForTerminationWithin(process, 3e3, true)) return;
-		throw new BrowserConnectionError("Browser process did not exit after SIGKILL", { pid: process.pid });
+		throw new BrowserConnectionError("Browser process did not exit after SIGKILL", { pid: this.#servingPid ?? process.pid });
 	}
 	#finish() {
 		this.#unbindTransport();
@@ -1469,6 +1541,7 @@ var Browser = class {
 		this.#endpoint = void 0;
 		this.#client = void 0;
 		this.#process = void 0;
+		this.#servingPid = void 0;
 		this.#exitCleanup = void 0;
 		this.#contexts = [];
 		this.#emitter.emit("destroy");
@@ -1476,6 +1549,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, 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, 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 };
 
 //# sourceMappingURL=index.js.map