@orkestrel/browser 0.0.14 → 0.0.16

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

@@ -1,22 +1,31 @@
-import { BrowserContextInterface } from '@orkestrel/browser';
-import { BrowserContextOptions } from '@orkestrel/browser';
+import type { BrowserContextInterface } from '@orkestrel/browser';
+import type { BrowserContextOptions } from '@orkestrel/browser';
 import { BrowserError } from '@orkestrel/browser';
-import { BrowserPageInterface } from '@orkestrel/browser';
-import { BrowserPageOptions } from '@orkestrel/browser';
-import { BrowserViewport } from '@orkestrel/browser';
-import { CDPTarget } from '@orkestrel/browser';
-import { CDPTransportEventMap } from '@orkestrel/browser';
-import { CDPTransportEventMap as CDPTransportEventMap_2 } from '@orkestrel/browser';
-import { CDPTransportInterface } from '@orkestrel/browser';
-import { CDPTransportInterface as CDPTransportInterface_2 } from '@orkestrel/browser';
-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 type { BrowserPageInterface } from '@orkestrel/browser';
+import type { BrowserPageOptions } from '@orkestrel/browser';
+import type { BrowserViewport } from '@orkestrel/browser';
+import type { BrowserWriterInterface } from '@orkestrel/browser';
+import type { CDPTarget } from '@orkestrel/browser';
+import type { CDPTransportEventMap } from '@orkestrel/browser';
+import type { CDPTransportInterface } from '@orkestrel/browser';
+import type { ChildProcess } from 'node:child_process';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { 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 +35,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 +48,135 @@ 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, and every
+ * other target category Chromium reports — `'/json/list'`.
+ */
 export declare const BROWSER_CDP_LIST_PATH = "/json/list";
 
-/** Protocol prefix for CDP discovery requests. */
+/** Names the protocol prefix for CDP discovery requests, `'http'`. */
 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, `'/json/version'`, which
+ * is where endpoint discovery reads.
+ */
 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, `9222`.
+ */
 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, `'127.0.0.1'`,
+ * which 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: `PLAYWRIGHT_EXECUTABLE_PATH`, then `CHROME_PATH`.
+ */
 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`, leaving `win32` empty because its roots come from
+ * `BROWSER_WINDOWS_SUFFIXES`.
+ */
 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, `'--headless=new'`.
+ */
 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 at `3_000`
+ * milliseconds.
+ */
 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 at `200` milliseconds,
+ * which is short because the probe only needs to detect an already-listening CDP endpoint
+ * rather than 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,
+ * `'process-exit'`.
+ */
 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, `'orkestrel-browser-'`.
+ */
 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`, starting with `/opt/pw-browsers`.
+ */
 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, `'PLAYWRIGHT_BROWSERS_PATH'`.
+ */
 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 or binary Playwright maintains inside a browser store
+ * base, `'chromium'`.
+ */
 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, `'transport-loss'`.
+ */
 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 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.
+ */
 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 `PROGRAMFILES`, `PROGRAMFILES(X86)`, or
+ * `LOCALAPPDATA` 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 +197,46 @@ 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, under the code
+ * `BROWSER_CONNECTION_ERROR`.
  */
 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 wrapper was destroyed, under the
+ * code `BROWSER_DESTROYED_ERROR`.
  */
 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 +246,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 +264,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
@@ -234,9 +294,9 @@ export declare type BrowserEventMap = {
  *   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
+ *   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`
+ * - `close` — graceful remote shutdown: best-effort sends CDP `Browser.close`
  *   (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
@@ -246,6 +306,8 @@ export declare type BrowserEventMap = {
  * **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 {
@@ -254,16 +316,15 @@ 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 serving this session's CDP endpoint, if any, while it is
+     * Reports the process serving this session's CDP endpoint, if any, while it is
      * believed alive.
      *
      * @remarks
@@ -276,28 +337,68 @@ export declare interface BrowserInterface {
      * until `destroy()` or an observed process exit clears it.
      */
     readonly pid: number | undefined;
+    /**
+     * Probes CDP passively, changing no connection state and neither launching nor attaching,
+     * and emits a `discover` event with the result.
+     */
     discover(): Promise<BrowserDiscoveryResult>;
+    /**
+     * Establishes a connection through the endpoint, then discovery, then a launch.
+     * Idempotent.
+     */
     connect(): Promise<void>;
-    /** Assume responsibility for terminating the currently connected browser. */
+    /** Assumes responsibility for terminating the connected browser. */
     adopt(): void;
+    /**
+     * Detaches the client-side transport while the remote browser keeps running. A merely
+     * attached CDP session forgets the endpoint and its ownership becomes `undefined`. A
+     * launched or explicitly adopted session retains ownership and its endpoint, so the same
+     * instance can reconnect and stays responsible for eventual termination. Transport loss
+     * while an owned browser remains alive is resumable the same way.
+     */
     disconnect(): Promise<void>;
+    /** Returns one context by index, or the first. */
     context(index?: number): BrowserContextInterface | undefined;
+    /** Returns every context. */
     contexts(): readonly BrowserContextInterface[];
+    /**
+     * Creates and registers an isolated CDP context with validated proxy, download, origin,
+     * and emulation options.
+     */
     isolate(options?: BrowserContextOptions): Promise<BrowserContextInterface>;
+    /** Opens a page in the default context. */
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
+    /**
+     * Releases local resources. A launched browser has the process serving its CDP endpoint
+     * terminated and its exit awaited — on POSIX that terminate reaches the launch's whole
+     * process group and awaits its drain, and on Windows it terminates one process by
+     * identifier, the spawned process or the one a launcher handed the endpoint to — which
+     * leaves the profile unlocked before cleanup. An adopted attachment is sent CDP
+     * `Browser.close`. A merely attached browser is detached locally and nothing more, because
+     * other clients may share its targets. Idempotent.
+     */
     destroy(): Promise<void>;
+    /**
+     * Shuts the remote browser down: sends CDP `Browser.close` best-effort whether attached or
+     * owned, and for an owned browser also awaits the exit of the process serving the CDP
+     * endpoint plus its POSIX process-group drain, escalating to a kill only where needed.
+     * Then closes every tracked context and page, sending remote `Target.closeTarget` and
+     * `disposeBrowserContext` whatever the ownership, before releasing the CDP client. This is
+     * the way to shut down a browser the instance does not own and still wants terminated.
+     */
     close(): Promise<void>;
 }
 
 /**
- * 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`.
  */
 export declare class BrowserNotConnectedError extends BrowserError {
     constructor(context?: Readonly<Record<string, unknown>>);
 }
 
 /**
- * Options for creating a Browser.
+ * Describes the options for creating a `Browser` instance.
  *
  * @remarks
  * - `on` — initial event listeners wired at construction
@@ -334,7 +435,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
@@ -346,30 +447,44 @@ 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 `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'
- *
- * const browser = createBrowser()
- * await browser.connect()
+ * import { createBrowser } from '@orkestrel/browser/server'
+ *
+ * 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()
  * ```
  */
 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
@@ -377,56 +492,84 @@ 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 `BrowserWriterInterface` that persists bytes through
+ * `node:fs/promises`.
  *
- * @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;
 
 /**
- * Create a filesystem-backed screenshot writer.
+ * Creates a Node `WebSocket`-backed `CDPTransportInterface` for the given CDP debugger URL.
  *
- * @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;
 
 /**
- * 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)
+ * ```
  */
-export declare function fetchCDPTargets(port: number, timeout: number, host?: string): Promise<readonly CDPTarget[]>;
-
-/** 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[];
+export declare function fetchCDPTargets(port: number, timeout: number, host?: string): Promise<Result<readonly CDPTarget[], BrowserError>>;
 
-/** 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}
@@ -435,7 +578,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
@@ -449,7 +592,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.
  *
@@ -459,31 +602,31 @@ 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 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
  */
 export declare function isBrowserConnectionError(value: unknown): value is BrowserConnectionError;
 
 /**
- * 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
  */
 export declare function isBrowserDestroyedError(value: unknown): value is BrowserDestroyedError;
 
 /**
- * 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
  */
 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
@@ -503,11 +646,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
@@ -515,11 +658,8 @@ 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[];
-
-/** Probe PATH (`which`/`where`) for the first resolvable command name. */
-export declare function probePathNames(names: readonly string[], platform: string): string | undefined;
+/** Probes PATH (`which`/`where`) for every resolvable command name, in the given order. */
+export declare function probePathNames(names: readonly string[], platform: string): readonly string[];
 
 /**
  * Returns the first non-empty line of a command's output, without its
@@ -541,7 +681,7 @@ export declare function probePathNames(names: readonly string[], platform: strin
 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
@@ -553,7 +693,7 @@ export declare function readFirstLine(output: string): string | undefined;
 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
@@ -565,7 +705,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
@@ -594,11 +734,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
@@ -606,25 +747,34 @@ 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;
     constructor(options: WebSocketCDPTransportOptions);
-    get emitter(): EmitterInterface<CDPTransportEventMap_2>;
+    get emitter(): EmitterInterface<CDPTransportEventMap>;
     start(): Promise<void>;
     send(data: string): Promise<void>;
     close(): Promise<void>;
 }
 
 /**
- * Options for creating a WebSocketCDPTransport.
+ * Describes the options for creating a `WebSocketCDPTransport` instance.
  *
  * @remarks
  * - `on` — initial event listeners wired at construction
@@ -639,7 +789,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 { }