@orkestrel/browser 0.0.13 → 0.0.15

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

@@ -4,6 +4,8 @@ import { BrowserError } from '@orkestrel/browser';
 import { BrowserPageInterface } from '@orkestrel/browser';
 import { BrowserPageOptions } from '@orkestrel/browser';
 import { BrowserViewport } from '@orkestrel/browser';
+import { BrowserWriterInterface } from '@orkestrel/browser';
+import { BrowserWriterInterface as BrowserWriterInterface_2 } from '@orkestrel/browser';
 import { CDPTarget } from '@orkestrel/browser';
 import { CDPTransportEventMap } from '@orkestrel/browser';
 import { CDPTransportEventMap as CDPTransportEventMap_2 } from '@orkestrel/browser';
@@ -13,10 +15,20 @@ import { ChildProcess } from 'node:child_process';
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
-import { ScreenshotWriterInterface } from '@orkestrel/browser';
+import { Result } from '@orkestrel/contract';
 
 /**
  * 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()
+ * ```
  */
 export declare class Browser implements BrowserInterface {
     #private;
@@ -26,7 +38,6 @@ export declare class Browser implements BrowserInterface {
     get status(): BrowserStatus;
     get connection(): BrowserConnection | undefined;
     get owned(): boolean | undefined;
-    get connected(): boolean;
     get pid(): number | undefined;
     discover(): Promise<BrowserDiscoveryResult>;
     connect(): Promise<void>;
@@ -40,83 +51,83 @@ export declare class Browser implements BrowserInterface {
     close(): Promise<void>;
 }
 
-/** 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, etc). */
 export declare const BROWSER_CDP_LIST_PATH = "/json/list";
 
-/** Protocol prefix for CDP discovery requests. */
+/** Names the protocol prefix for CDP discovery requests. */
 export declare const 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 (endpoint discovery). */
 export declare const BROWSER_CDP_VERSION_PATH = "/json/version";
 
-/** 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. */
 export declare const 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 (avoids `localhost` resolving to `::1` when Chromium binds `127.0.0.1`). */
 export declare const BROWSER_DEFAULT_HOST = "127.0.0.1";
 
 /**
- * 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`.
  */
 export declare const BROWSER_ENGINE_HINTS: Readonly<Record<BrowserEngine, readonly string[]>>;
 
-/** 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. */
 export declare const BROWSER_ENV_PATH_KEYS: readonly string[];
 
-/** 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. */
 export declare const BROWSER_EXECUTABLE_NAMES: readonly string[];
 
-/** 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`. */
 export declare const BROWSER_EXECUTABLE_PATHS: Readonly<Record<string, readonly string[]>>;
 
-/** Flag enabling headless mode on a launched browser process. */
+/** Names the flag that enables headless mode on a launched browser process. */
 export declare const BROWSER_HEADLESS_ARG = "--headless=new";
 
-/** Bound for each launched-process exit window during TERM-to-KILL teardown. */
+/** Bounds each launched-process exit window during TERM-to-KILL teardown. */
 export declare const BROWSER_KILL_GRACE_MS = 3000;
 
-/** 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. */
 export declare const BROWSER_LAUNCH_ARGS: readonly string[];
 
-/** 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 — short, because it only needs to detect an already-listening CDP endpoint, not perform full discovery. */
 export declare const BROWSER_PORT_PROBE_TIMEOUT_MS = 200;
 
-/** Machine-readable error-context cause for an owned browser process exiting. */
+/** Names the machine-readable error-context cause for an owned browser process exiting. */
 export declare const BROWSER_PROCESS_EXIT_CAUSE = "process-exit";
 
-/** 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. */
 export declare const BROWSER_PROFILE_PREFIX = "orkestrel-browser-";
 
-/** 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). */
 export declare const BROWSER_STORE_CACHE_DIRS: Readonly<Record<string, string>>;
 
-/** 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`. */
 export declare const BROWSER_STORE_DEFAULT_DIRS: readonly string[];
 
-/** Environment variable naming an additional Playwright browser store base directory. */
+/** Names the environment variable that carries an additional Playwright browser store base directory. */
 export declare const BROWSER_STORE_ENV_KEY = "PLAYWRIGHT_BROWSERS_PATH";
 
-/** 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`. */
 export declare const BROWSER_STORE_GLOBS: Readonly<Record<string, string>>;
 
-/** Name of the top-level Chromium symlink/binary Playwright maintains inside a browser store base. */
+/** Names the top-level Chromium symlink/binary Playwright maintains inside a browser store base. */
 export declare const BROWSER_STORE_LINK_NAME = "chromium";
 
-/** 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. */
 export declare const BROWSER_TRANSPORT_LOSS_CAUSE = "transport-loss";
 
-/** 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, briefly, 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. */
 export declare const BROWSER_TRANSPORT_LOSS_DEFER_MS = 50;
 
-/** Fallback Windows install roots used when the corresponding environment variable is absent. */
+/** Lists the fallback Windows install roots used when the corresponding environment variable is absent. */
 export declare const BROWSER_WINDOWS_ROOT_FALLBACKS: Readonly<Record<string, string>>;
 
-/** 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`). */
 export declare const BROWSER_WINDOWS_SUFFIXES: readonly string[];
 
 /**
- * CDP (Chrome DevTools Protocol) connection configuration.
+ * Configures the CDP (Chrome DevTools Protocol) connection.
  *
  * @remarks
  * - `port` — port number to probe for an existing CDP endpoint (default `9222`)
@@ -137,47 +148,44 @@ export declare interface BrowserCDPOptions {
     readonly discover?: boolean;
 }
 
-/** How the browser connection was established. */
+/** Names how the browser connection was established. */
 export declare type BrowserConnection = 'cdp' | 'launch' | 'persistent';
 
 /**
- * A CDP connection, discovery, or launch attempt failed.
+ * Reports that a CDP connection, discovery, or launch attempt failed.
  */
 export declare class BrowserConnectionError extends BrowserError {
     constructor(message: string, context?: Readonly<Record<string, unknown>>);
 }
 
 /**
- * An operation was attempted after the Browser was destroyed.
+ * Reports that an operation was attempted after the Browser was destroyed.
  */
 export declare class BrowserDestroyedError extends BrowserError {
     constructor(context?: Readonly<Record<string, unknown>>);
 }
 
 /**
- * Result of passive browser discovery.
+ * Describes the result of passive browser discovery.
  *
  * @remarks
  * Returned by `discover()` to report whether an existing browser is
- * reachable via CDP without actually connecting to it.
+ * reachable through CDP without actually connecting to it. A defined
+ * `endpoint` is the whole answer — no separate flag repeats it.
  *
- * - `found` — true when a browser responded on the CDP endpoint
- * - `endpoint` — the CDP WebSocket URL when found
+ * - `endpoint` — the CDP WebSocket URL, or undefined when nothing answered
  * - `browser` — browser product name reported by the endpoint
- * - `connection` — the connection mode that would be used
  */
 export declare interface BrowserDiscoveryResult {
-    readonly found: boolean;
     readonly endpoint: string | undefined;
     readonly browser: string | undefined;
-    readonly connection: BrowserConnection | undefined;
 }
 
-/** Supported browser engine (raw CDP targets Chromium-family browsers only). */
+/** Names a supported browser engine (raw CDP targets Chromium-family browsers only). */
 export declare type BrowserEngine = 'chromium' | 'chrome' | 'edge';
 
 /**
- * Event map for a {@link BrowserInterface}.
+ * Maps the events a {@link BrowserInterface} emits.
  *
  * @remarks
  * - `idle` — no active connection (initial state, or after disconnect)
@@ -187,7 +195,8 @@ export declare type BrowserEngine = 'chromium' | 'chrome' | 'edge';
  *   an external disconnect (process exit or transport loss); always preceded
  *   by a coded `error` describing the cause
  * - `launch` — a new browser process was launched, carrying the engine
- * - `page` — a new page was created via the `create()` shortcut
+ * - `page` — a new page was created through the `create()` shortcut
+ * - `context` — an isolated browser context was created, carrying the context
  * - `error` — a connection or launch fault
  * - `destroy` — the browser and all resources were torn down
  */
@@ -204,13 +213,13 @@ export declare type BrowserEventMap = {
 };
 
 /**
- * Browser wrapper with discovery, connection management, and lifecycle control.
+ * Wraps a browser with discovery, connection management, and lifecycle control.
  *
  * @remarks
  * Encapsulates the full raw-CDP browser lifecycle behind a clean interface:
  *
  * **Connection strategy** (executed by `connect()`):
- * 1. If `cdp.endpoint` is set, connect directly via CDP
+ * 1. If `cdp.endpoint` is set, connect directly through CDP
  * 2. Probe `localhost:{cdp.port}` for an existing browser (passive discovery)
  * 3. If found, connect over CDP (preserves the existing browser session)
  * 4. Otherwise, launch a new browser process with raw-CDP flags
@@ -231,19 +240,23 @@ 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
  * - `contexts()` → all contexts
+ * - `isolate` — create and register an isolated CDP context with validated
+ *   proxy, download, origin, and emulation options
  * - `create(options?)` → shortcut to open a page in the default context
  */
 export declare interface BrowserInterface {
@@ -252,26 +265,30 @@ export declare interface BrowserInterface {
     readonly status: BrowserStatus;
     readonly connection: BrowserConnection | undefined;
     /**
-     * Whether this instance is responsible for terminating the represented browser.
+     * Reports whether this instance is responsible for terminating the represented browser.
      *
      * @remarks
      * `true` for launched and explicitly adopted sessions, `false` for an
      * active attachment, and `undefined` when no session is represented.
      */
     readonly owned: boolean | undefined;
-    readonly connected: boolean;
     /**
-     * The process this instance launched, if any, while it is believed alive.
+     * Reports 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>;
     connect(): Promise<void>;
-    /** Assume responsibility for terminating the currently connected browser. */
+    /** Assumes responsibility for terminating the currently connected browser. */
     adopt(): void;
     disconnect(): Promise<void>;
     context(index?: number): BrowserContextInterface | undefined;
@@ -283,14 +300,14 @@ export declare interface BrowserInterface {
 }
 
 /**
- * An operation requiring an active connection was attempted while disconnected.
+ * Reports that an operation requiring an active connection was attempted while disconnected.
  */
 export declare class BrowserNotConnectedError extends BrowserError {
     constructor(context?: Readonly<Record<string, unknown>>);
 }
 
 /**
- * Options for creating a Browser.
+ * Describes the options for creating a Browser.
  *
  * @remarks
  * - `on` — initial event listeners wired at construction
@@ -327,7 +344,7 @@ export declare interface BrowserOptions {
 }
 
 /**
- * Resolved browser profile directory used for a Chromium-family launch.
+ * Describes the resolved browser profile directory used for a Chromium-family launch.
  *
  * @remarks
  * `temporary` is true only for an isolated profile created by
@@ -339,21 +356,30 @@ export declare interface BrowserProfileResult {
     readonly temporary: boolean;
 }
 
-/** Lifecycle status of a browser wrapper. */
+/** Names the lifecycle status of a browser wrapper. */
 export declare type BrowserStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
 
-/** 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). */
 export declare function browserToEngine(browser?: string): BrowserEngine;
 
+/** Builds the default well-known install-path candidates for a platform, deriving Windows roots from env vars. */
+export declare function buildInstallPaths(platform: string, env: Readonly<Record<string, string | undefined>>): readonly string[];
+
+/** Builds the default Playwright browser store base directories to search for a managed Chromium. */
+export declare function buildStoreBases(env: Readonly<Record<string, string | undefined>>, platform: string): readonly string[];
+
+/** Derives Windows install roots from env vars, falling back to well-known literals when absent. */
+export declare function buildWindowsRoots(env: Readonly<Record<string, string | undefined>>): readonly string[];
+
 /**
- * Create a raw-CDP Browser façade.
+ * Creates a raw-CDP Browser façade.
  *
  * @param options - Connection, launch, and viewport configuration
  * @returns A {@link BrowserInterface}
  *
  * @example
  * ```ts
- * import { createBrowser } from '@src/server'
+ * import { createBrowser } from '@orkestrel/browser/server'
  *
  * const browser = createBrowser()
  * await browser.connect()
@@ -362,7 +388,7 @@ export declare function browserToEngine(browser?: string): BrowserEngine;
 export declare function createBrowser(options?: BrowserOptions): BrowserInterface;
 
 /**
- * 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
@@ -370,56 +396,82 @@ export declare function createBrowser(options?: BrowserOptions): BrowserInterfac
 export declare function createBrowserProfile(path?: string): Promise<BrowserProfileResult>;
 
 /**
- * Create a Node `WebSocket`-backed CDP transport.
+ * Creates a filesystem-backed browser writer.
  *
- * @param options - The CDP WebSocket debugger URL (and optional timeout)
- * @returns A {@link CDPTransportInterface}
+ * @returns A {@link BrowserWriterInterface} that persists bytes through `node:fs/promises`
  */
-export declare function createCDPTransport(options: WebSocketCDPTransportOptions): CDPTransportInterface_2;
+export declare function createBrowserWriter(): BrowserWriterInterface_2;
 
 /**
- * Create a filesystem-backed screenshot writer.
+ * Creates a Node `WebSocket`-backed CDP transport.
  *
- * @returns A {@link ScreenshotWriterInterface} that persists bytes via `node:fs/promises`
+ * @param options - The CDP WebSocket debugger URL (and optional timeout)
+ * @returns A {@link CDPTransportInterface}
  */
-export declare function createScreenshotWriter(): ScreenshotWriterInterface;
-
-/** Build the default well-known install-path candidates for a platform, deriving Windows roots from env vars. */
-export declare function defaultInstallPaths(platform: string, env: Readonly<Record<string, string | undefined>>): readonly string[];
-
-/** Build the default Playwright browser store base directories to search for a managed Chromium. */
-export declare function defaultStoreBases(env: Readonly<Record<string, string | undefined>>, platform: string): readonly string[];
+export declare function createCDPTransport(options: WebSocketCDPTransportOptions): CDPTransportInterface_2;
 
 /**
- * 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.
+ *
+ * @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)
+ * ```
  */
-export declare function fetchCDPTargets(port: number, timeout: number, host?: string): Promise<readonly CDPTarget[]>;
+export declare function fetchCDPTargets(port: number, timeout: number, host?: string): Promise<Result<readonly CDPTarget[], BrowserError>>;
 
-/** Check the env-override keys (`PLAYWRIGHT_EXECUTABLE_PATH`, `CHROME_PATH`) in order, returning every one that exists. */
-export declare function findAllEnvOverrides(env: Readonly<Record<string, string | undefined>>): readonly string[];
-
-/** Return every candidate path that exists on disk, in the given order. */
-export declare function findAllInstallPaths(paths: readonly string[]): readonly string[];
-
-/** Search one store base for the top-level `chromium` link and every `chromium-*` install, highest revision first. */
-export declare function findAllInStore(base: string, platform: string): readonly string[];
+/**
+ * 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]))
+ * ```
+ */
+export declare class FileBrowserWriter implements BrowserWriterInterface {
+    /**
+     * 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
+     */
+    write(path: string, data: Uint8Array): Promise<void>;
+}
 
-/** Check the env-override keys (`PLAYWRIGHT_EXECUTABLE_PATH`, `CHROME_PATH`) in order for an existing file. */
-export declare function findEnvOverride(env: Readonly<Record<string, string | undefined>>): string | undefined;
+/** Checks the env-override keys (`PLAYWRIGHT_EXECUTABLE_PATH`, `CHROME_PATH`) in order and returns every one that exists. */
+export declare function findEnvOverrides(env: Readonly<Record<string, string | undefined>>): readonly string[];
 
-/** Return the first candidate path that exists on disk. */
-export declare function findInstallPath(paths: readonly string[]): string | undefined;
+/** Returns every candidate path that exists on disk, in the given order. */
+export declare function findInstallPaths(paths: readonly string[]): readonly string[];
 
-/** Search one store base for the top-level `chromium` link, else the highest-revision `chromium-*` install. */
-export declare function findInStore(base: string, platform: string): string | undefined;
+/** Searches one store base for the top-level `chromium` link and every `chromium-*` install, highest revision first. */
+export declare function findStorePaths(base: string, platform: string): readonly string[];
 
 /**
- * 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}
@@ -428,7 +480,7 @@ export declare function findInStore(base: string, platform: string): string | un
 export declare function findSystemBrowser(options?: SystemBrowserOptions): SystemBrowser | undefined;
 
 /**
- * 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
@@ -442,7 +494,7 @@ export declare function findSystemBrowser(options?: SystemBrowserOptions): Syste
  *    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.
  *
@@ -452,35 +504,40 @@ export declare function findSystemBrowser(options?: SystemBrowserOptions): Syste
 export declare function findSystemBrowsers(options?: SystemBrowserOptions): readonly SystemBrowser[];
 
 /**
- * Narrow an unknown value to BrowserConnectionError.
+ * Narrows an unknown value to BrowserConnectionError.
  *
  * @param value - Value to check
- * @returns True when value is a BrowserConnectionError instance
+ * @returns True if value is a BrowserConnectionError instance; false otherwise
  */
 export declare function isBrowserConnectionError(value: unknown): value is BrowserConnectionError;
 
 /**
- * Narrow an unknown value to BrowserDestroyedError.
+ * Narrows an unknown value to BrowserDestroyedError.
  *
  * @param value - Value to check
- * @returns True when value is a BrowserDestroyedError instance
+ * @returns True if value is a BrowserDestroyedError instance; false otherwise
  */
 export declare function isBrowserDestroyedError(value: unknown): value is BrowserDestroyedError;
 
 /**
- * Narrow an unknown value to BrowserNotConnectedError.
+ * Narrows an unknown value to BrowserNotConnectedError.
  *
  * @param value - Value to check
- * @returns True when value is a BrowserNotConnectedError instance
+ * @returns True if value is a BrowserNotConnectedError instance; false otherwise
  */
 export declare function isBrowserNotConnectedError(value: unknown): value is BrowserNotConnectedError;
 
 /**
- * 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
  * 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
@@ -491,11 +548,11 @@ export declare function isBrowserNotConnectedError(value: unknown): value is Bro
  */
 export declare function launchBrowserProcess(executable: string, port: number, headless: boolean, profile?: string, extra?: readonly string[]): ChildProcess;
 
-/** Normalize an executable path for cross-source deduplication (case-insensitive on Windows). */
+/** Normalizes an executable path for cross-source deduplication (case-insensitive on Windows). */
 export declare function normalizeExecutablePath(path: string, platform: string): string;
 
 /**
- * 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
@@ -503,14 +560,30 @@ export declare function normalizeExecutablePath(path: string, platform: string):
  */
 export declare function parseBrowserEngine(executable: string): BrowserEngine | undefined;
 
-/** Probe PATH (`which`/`where`) for every resolvable command name, in the given order. */
-export declare function probeAllPathNames(names: readonly string[], platform: string): readonly string[];
+/** Probes PATH (`which`/`where`) for every resolvable command name, in the given order. */
+export declare function probePathNames(names: readonly string[], platform: string): readonly string[];
 
-/** 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.
+ * Removes a library-owned isolated browser profile.
  *
  * @remarks
  * The path must remain a direct child of the operating-system temp directory
@@ -522,7 +595,7 @@ export declare function probePathNames(names: readonly string[], platform: strin
 export declare function removeBrowserProfile(profile: BrowserProfileResult): Promise<void>;
 
 /**
- * One discovered browser executable on this machine.
+ * Represents one discovered browser executable on this machine.
  *
  * @remarks
  * Returned by `findSystemBrowsers`/`findSystemBrowser` — pairs the resolved
@@ -534,7 +607,7 @@ export declare type SystemBrowser = {
 };
 
 /**
- * Options overriding `findSystemBrowsers`'/`findSystemBrowser`'s candidate sources.
+ * Describes the options overriding `findSystemBrowsers`'/`findSystemBrowser`'s candidate sources.
  *
  * @remarks
  * Each field replaces the default candidate list for its category — a field
@@ -563,11 +636,12 @@ export declare interface SystemBrowserOptions {
 }
 
 /**
- * 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
@@ -575,13 +649,22 @@ export declare interface SystemBrowserOptions {
 export declare function waitForCDPReady(port: number, timeout: number, host?: string, signal?: AbortSignal): Promise<string>;
 
 /**
- * `@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()
+ * ```
  */
 export declare class WebSocketCDPTransport implements CDPTransportInterface {
     #private;
@@ -593,7 +676,7 @@ export declare class WebSocketCDPTransport implements CDPTransportInterface {
 }
 
 /**
- * Options for creating a WebSocketCDPTransport.
+ * Describes the options for creating a WebSocketCDPTransport.
  *
  * @remarks
  * - `on` — initial event listeners wired at construction
@@ -608,7 +691,4 @@ export declare interface WebSocketCDPTransportOptions {
     readonly timeout?: number;
 }
 
-/** Derive Windows install roots from env vars, falling back to well-known literals when absent. */
-export declare function windowsRoots(env: Readonly<Record<string, string | undefined>>): readonly string[];
-
 export { }