@orkestrel/browser 0.0.1

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

@@ -0,0 +1,567 @@
+import { BrowserContextInterface } from '../core/index.ts';
+import { BrowserError } from '../core/index.ts';
+import { BrowserPageInterface } from '../core/index.ts';
+import { BrowserPageOptions } from '../core/index.ts';
+import { BrowserViewport } from '../core/index.ts';
+import { CDPTarget } from '../core/index.ts';
+import { CDPTransportEventMap } from '../../core/index.ts';
+import { CDPTransportInterface } from '../../core/index.ts';
+import { CDPTransportInterface as CDPTransportInterface_2 } from '../core/index.ts';
+import { ChildProcess } from 'node:child_process';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { ScreenshotWriterInterface } from '../core/index.ts';
+
+export declare class Browser implements BrowserInterface {
+    #private;
+    constructor(options?: BrowserOptions);
+    get emitter(): EmitterInterface<BrowserEventMap>;
+    get engine(): BrowserEngine;
+    get status(): BrowserStatus;
+    get connection(): BrowserConnection | undefined;
+    get connected(): boolean;
+    get pid(): number | undefined;
+    discover(): Promise<BrowserDiscoveryResult>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    context(index?: number): BrowserContextInterface | undefined;
+    contexts(): readonly BrowserContextInterface[];
+    create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
+    destroy(): Promise<void>;
+    /**
+     * Gracefully shut down the remote browser, whether this instance owns its
+     * process or merely attached to it via CDP.
+     *
+     * @remarks
+     * Sends CDP `Browser.close` best-effort; on an owned browser also awaits
+     * the process's exit (bounded by the kill-escalation grace period,
+     * escalating to a kill only if it does not exit in time). Ends in the
+     * same local-cleanup state as `destroy()`.
+     */
+    close(): Promise<void>;
+}
+
+/** 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. */
+export declare const BROWSER_CDP_PROTOCOL = "http";
+
+/** 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. */
+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`). */
+export declare const BROWSER_DEFAULT_HOST = "127.0.0.1";
+
+/**
+ * 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. */
+export declare const BROWSER_ENV_PATH_KEYS: readonly string[];
+
+/** 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`. */
+export declare const BROWSER_EXECUTABLE_PATHS: Readonly<Record<string, readonly string[]>>;
+
+/** Flag enabling headless mode on a launched browser process. */
+export declare const BROWSER_HEADLESS_ARG = "--headless=new";
+
+/** Grace period after SIGTERM before a launched process is escalated to SIGKILL during teardown. */
+export declare const BROWSER_KILL_GRACE_MS = 3000;
+
+/** Flags always passed to a launched browser process, alongside the caller's own. */
+export declare const BROWSER_LAUNCH_ARGS: readonly string[];
+
+/** Sentinel result returned by discovery when no browser is reachable. */
+export declare const BROWSER_NOT_FOUND_RESULT: BrowserDiscoveryResult;
+
+/** 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. */
+export declare const BROWSER_PORT_PROBE_TIMEOUT_MS = 200;
+
+/** 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`. */
+export declare const BROWSER_STORE_DEFAULT_DIRS: readonly string[];
+
+/** Environment variable naming 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`. */
+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. */
+export declare const BROWSER_STORE_LINK_NAME = "chromium";
+
+/** 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. */
+export declare const BROWSER_TRANSPORT_LOSS_DEFER_MS = 50;
+
+/** 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`). */
+export declare const BROWSER_WINDOWS_SUFFIXES: readonly string[];
+
+/**
+ * CDP (Chrome DevTools Protocol) connection configuration.
+ *
+ * @remarks
+ * - `port` — port number to probe for an existing CDP endpoint (default `9222`)
+ * - `host` — host to probe/launch on (default `127.0.0.1`; avoids `localhost`
+ *   resolving to `::1` when Chromium binds `127.0.0.1`)
+ * - `endpoint` — explicit CDP WebSocket URL; when provided, skips discovery
+ * - `discover` — whether `connect()` passively probes for an existing browser
+ *   before launching (default `true`); set `false` to skip discovery and go
+ *   straight to launch — a short probe of `port` still runs first and rejects
+ *   with a coded error naming the occupied port if something is already
+ *   listening there, so a demanded fresh launch never silently attaches to a
+ *   stranger browser
+ */
+export declare interface BrowserCdpOptions {
+    readonly port?: number;
+    readonly host?: string;
+    readonly endpoint?: string;
+    readonly discover?: boolean;
+}
+
+/** How the browser connection was established. */
+export declare type BrowserConnection = 'cdp' | 'launch' | 'persistent';
+
+/**
+ * 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.
+ */
+export declare class BrowserDestroyedError extends BrowserError {
+    constructor(context?: Readonly<Record<string, unknown>>);
+}
+
+/**
+ * Result of passive browser discovery.
+ *
+ * @remarks
+ * Returned by `discover()` to report whether an existing browser is
+ * reachable via CDP without actually connecting to it.
+ *
+ * - `found` — true when a browser responded on the CDP endpoint
+ * - `endpoint` — the CDP WebSocket URL when found
+ * - `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). */
+export declare type BrowserEngine = 'chromium' | 'chrome' | 'edge';
+
+/**
+ * Event map for a {@link BrowserInterface}.
+ *
+ * @remarks
+ * - `idle` — no active connection (initial state, or after disconnect)
+ * - `discover` — passive CDP probe completed
+ * - `connect` — a connection was established, carrying the mode used
+ * - `disconnect` — the connection was detached — either explicitly, or after
+ *   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
+ * - `error` — a connection or launch fault
+ * - `destroy` — the browser and all resources were torn down
+ */
+export declare type BrowserEventMap = {
+    readonly idle: readonly [];
+    readonly discover: readonly [result: BrowserDiscoveryResult];
+    readonly connect: readonly [connection: BrowserConnection];
+    readonly disconnect: readonly [];
+    readonly launch: readonly [engine: BrowserEngine];
+    readonly page: readonly [page: BrowserPageInterface];
+    readonly error: readonly [error: unknown];
+    readonly destroy: readonly [];
+};
+
+/**
+ * Browser wrapper 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
+ * 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
+ *
+ * This lets automation reuse an already-running browser before falling back
+ * to a fresh launch.
+ *
+ * **Lifecycle:**
+ * - `discover` — passive CDP probe, no side effects
+ * - `connect` — establish connection using the strategy above
+ * - `disconnect` — detach from the browser. For `'cdp'` and `'persistent'`
+ *   connections this closes the client WITHOUT killing the browser process —
+ *   a `'persistent'` (profile-backed) launch releases ownership of its process
+ *   (no kill, no exit listener) so the browser stays alive for later
+ *   reattachment via CDP discovery on the same port. Rejects with the coded
+ *   `BrowserConnectionError` for `'launch'` (ephemeral, no profile) sessions —
+ *   use `destroy()` instead. An external disconnect (transport loss while the
+ *   owned process is still alive, or the owned process exiting on its own)
+ *   drives this same released/disconnected state automatically, preceded by
+ *   a coded `error` — `connect()` on the same instance can reattach afterward.
+ * - `destroy` — release local resources. On an owned (`'launch'`/`'persistent'`)
+ *   browser this closes pages/contexts, then kills the process (SIGTERM,
+ *   escalating to SIGKILL). On a `'cdp'`-attached browser this is a LOCAL
+ *   DETACH ONLY — the client is closed and local context/page objects are
+ *   dropped WITHOUT sending any remote close to the browser, since other
+ *   clients may share those 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 (escalating to a kill only if it doesn't exit in time),
+ *   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
+ * - `create(options?)` → shortcut to open a page in the default context
+ */
+export declare interface BrowserInterface {
+    readonly emitter: EmitterInterface<BrowserEventMap>;
+    readonly engine: BrowserEngine;
+    readonly status: BrowserStatus;
+    readonly connection: BrowserConnection | undefined;
+    readonly connected: boolean;
+    /**
+     * The process this instance launched, if any, while it is believed alive.
+     *
+     * @remarks
+     * Remains readable after a persistent disconnect-release (the process
+     * keeps running, detached from this instance) until `destroy()` or an
+     * observed process exit clears it.
+     */
+    readonly pid: number | undefined;
+    discover(): Promise<BrowserDiscoveryResult>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    context(index?: number): BrowserContextInterface | undefined;
+    contexts(): readonly BrowserContextInterface[];
+    create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
+    destroy(): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * 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.
+ *
+ * @remarks
+ * - `on` — initial event listeners wired at construction
+ * - `headless` — launch in headless mode (default `true`; ignored for CDP connections)
+ * - `executable` — absolute path to a browser executable; when provided, skips
+ *   system browser discovery and launches this binary directly
+ * - `profile` — persistent browser profile (user-data) directory
+ * - `cdp` — CDP connection options (port and endpoint)
+ * - `timeout` — connection, discovery, and launch timeout in milliseconds (default `30_000`)
+ * - `viewport` — default viewport dimensions for new pages
+ * - `signal` — external AbortSignal for cancelling the connection attempt
+ * - `args` — additional command-line flags passed to the launched browser process
+ * - `engine` — preferred browser engine to launch; narrows system browser
+ *   discovery to this engine (ignored when `executable` is given); takes
+ *   precedence over `browsers.engine`
+ * - `browsers` — candidate-source overrides consulted when `connect()` needs
+ *   to launch (same shape `findSystemBrowsers` takes); ignored when
+ *   `executable` is given, which bypasses discovery entirely
+ */
+export declare interface BrowserOptions {
+    readonly on?: EmitterHooks<BrowserEventMap>;
+    readonly headless?: boolean;
+    readonly executable?: string;
+    readonly profile?: string;
+    readonly cdp?: BrowserCdpOptions;
+    readonly timeout?: number;
+    readonly viewport?: BrowserViewport;
+    readonly signal?: AbortSignal;
+    readonly args?: readonly string[];
+    readonly engine?: BrowserEngine;
+    readonly browsers?: SystemBrowserOptions;
+}
+
+/** 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). */
+export declare function browserToEngine(browser: string): BrowserEngine;
+
+/**
+ * Create a raw-CDP Browser façade.
+ *
+ * @param options - Connection, launch, and viewport configuration
+ * @returns A {@link BrowserInterface}
+ *
+ * @example
+ * ```ts
+ * import { createBrowser } from '@src/server'
+ *
+ * const browser = createBrowser()
+ * await browser.connect()
+ * ```
+ */
+export declare function createBrowser(options?: BrowserOptions): BrowserInterface;
+
+/**
+ * Create a Node `WebSocket`-backed CDP transport.
+ *
+ * @param options - The CDP WebSocket debugger URL (and optional timeout)
+ * @returns A {@link CDPTransportInterface}
+ */
+export declare function createCDPTransport(options: WebSocketCDPTransportOptions): CDPTransportInterface_2;
+
+/**
+ * Create a filesystem-backed screenshot writer.
+ *
+ * @returns A {@link ScreenshotWriterInterface} that persists bytes via `node:fs/promises`
+ */
+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[];
+
+/**
+ * Fetch the current CDP target list from a browser's `/json/list` endpoint.
+ *
+ * @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
+ */
+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[];
+
+/** 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[];
+
+/** 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;
+
+/** Return the first candidate path that exists on disk. */
+export declare function findInstallPath(paths: readonly string[]): string | undefined;
+
+/** 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;
+
+/**
+ * Locate a Chrome/Chromium/Edge executable on this machine — the first entry
+ * of {@link findSystemBrowsers}.
+ *
+ * @param options - Overrides for the candidate sources; see {@link SystemBrowserOptions}
+ * @returns The first discovered browser, or undefined
+ */
+export declare function findSystemBrowser(options?: SystemBrowserOptions): SystemBrowser | undefined;
+
+/**
+ * Enumerate every Chrome/Chromium/Edge executable discoverable on this
+ * machine, deduplicated by normalized absolute path.
+ *
+ * @remarks
+ * Resolution precedence (candidates appended in this order):
+ * 1. `PLAYWRIGHT_EXECUTABLE_PATH`, then `CHROME_PATH` — explicit environment
+ *    overrides that exist on disk
+ * 2. Well-known platform install locations (Chrome, Edge, Chromium); Windows
+ *    roots are derived from `PROGRAMFILES` / `PROGRAMFILES(X86)` / `LOCALAPPDATA`
+ * 3. PATH probe for known command names (`which` on POSIX, `where` on Windows)
+ * 4. Playwright-managed browser stores (`PLAYWRIGHT_BROWSERS_PATH`, `/opt/pw-browsers`,
+ *    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
+ * `parseBrowserEngine` (unclassifiable candidates default to `'chromium'`),
+ * and `options.engine` (when given) narrows the result to that engine.
+ *
+ * @param options - Overrides for the candidate sources; see {@link SystemBrowserOptions}
+ * @returns Every discovered browser, in resolution-precedence order
+ */
+export declare function findSystemBrowsers(options?: SystemBrowserOptions): readonly SystemBrowser[];
+
+/**
+ * Narrow an unknown value to BrowserConnectionError.
+ *
+ * @param value - Value to check
+ * @returns True when value is a BrowserConnectionError instance
+ */
+export declare function isBrowserConnectionError(value: unknown): value is BrowserConnectionError;
+
+/**
+ * Narrow an unknown value to BrowserDestroyedError.
+ *
+ * @param value - Value to check
+ * @returns True when value is a BrowserDestroyedError instance
+ */
+export declare function isBrowserDestroyedError(value: unknown): value is BrowserDestroyedError;
+
+/**
+ * Narrow an unknown value to BrowserNotConnectedError.
+ *
+ * @param value - Value to check
+ * @returns True when value is a BrowserNotConnectedError instance
+ */
+export declare function isBrowserNotConnectedError(value: unknown): value is BrowserNotConnectedError;
+
+/**
+ * Launch a browser process with raw-CDP debugging flags.
+ *
+ * @param executable - Absolute path to the browser executable
+ * @param port - Port the browser exposes its CDP endpoint on
+ * @param headless - Whether to launch in headless mode
+ * @param profile - Optional user-data-dir for a persistent profile
+ * @param extra - Additional command-line flags
+ * @returns The spawned ChildProcess
+ */
+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). */
+export declare function normalizeExecutablePath(path: string, platform: string): string;
+
+/**
+ * Classify 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
+ * @returns The classified engine, or undefined when no hint matches
+ */
+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;
+
+/**
+ * One discovered browser executable on this machine.
+ *
+ * @remarks
+ * Returned by `findSystemBrowsers`/`findSystemBrowser` — pairs the resolved
+ * absolute executable path with its classified engine.
+ */
+export declare type SystemBrowser = {
+    readonly executable: string;
+    readonly engine: BrowserEngine;
+};
+
+/**
+ * Options overriding `findSystemBrowsers`'/`findSystemBrowser`'s candidate sources.
+ *
+ * @remarks
+ * Each field replaces the default candidate list for its category — a field
+ * left `undefined` falls back to the platform default, an explicit `[]` (or
+ * empty `env`) disables that category entirely. Zero-arg `findSystemBrowsers()`
+ * uses full default resolution.
+ *
+ * - `env` — environment record consulted for both the override keys
+ *   (`PLAYWRIGHT_EXECUTABLE_PATH`, `CHROME_PATH`) and Windows install roots
+ *   (`PROGRAMFILES`, `PROGRAMFILES(X86)`, `LOCALAPPDATA`); defaults to `process.env`
+ * - `paths` — candidate install paths checked in order; defaults to the
+ *   platform's well-known Chrome/Edge/Chromium locations
+ * - `names` — command names probed on PATH (`which`/`where`); defaults to
+ *   `BROWSER_EXECUTABLE_NAMES`
+ * - `stores` — Playwright browser store base directories searched for a
+ *   managed Chromium; defaults to `PLAYWRIGHT_BROWSERS_PATH`, the well-known
+ *   store dirs, and the per-OS Playwright cache directory
+ * - `engine` — when set, narrows results to candidates classified as this engine
+ */
+export declare interface SystemBrowserOptions {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly paths?: readonly string[];
+    readonly names?: readonly string[];
+    readonly stores?: readonly string[];
+    readonly engine?: BrowserEngine;
+}
+
+/**
+ * Poll 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`)
+ * @returns The browser's WebSocket debugger URL
+ *
+ * @throws When the endpoint does not become ready before the timeout
+ */
+export declare function waitForCdpReady(port: number, timeout: number, host?: string): Promise<string>;
+
+/**
+ * `@orkestrel/websocket`-backed {@link CDPTransportInterface} — the dumb text
+ * pipe a {@link import('@src/core').CDPClientInterface} sends and receives
+ * JSON-RPC frames over.
+ *
+ * @remarks
+ * `start()` hand-rolls the RFC 6455 client handshake: it opens a `node:http`
+ * `GET` carrying `Connection: Upgrade` / `Upgrade: websocket` / a random
+ * `Sec-WebSocket-Key` / `Sec-WebSocket-Version`, awaits the client `'upgrade'`
+ * event, and validates `Sec-WebSocket-Accept === computeWebSocketAccept(key)`
+ * — a mismatch (or a connection/request error, or a timeout) rejects `start()`
+ * with a coded {@link BrowserConnectionError} and cleans up the socket. On
+ * success it wraps the raw upgraded socket in `createNodeWebSocket({ socket,
+ * head })` (CLIENT mode — no `key` — so outgoing frames are masked per RFC
+ * 6455 §5.3) and bridges its `message`/`close`/`error` events onto this
+ * transport's emitter. `start()` opens a fresh socket each call (safe to call
+ * again after `close()` — a new request/socket/NodeWebSocket triple is
+ * created every time, which is what `CDPClient.reconnect()` depends on). CDP
+ * frames are text-only, so `message` always carries a `string`.
+ */
+export declare class WebSocketCDPTransport implements CDPTransportInterface {
+    #private;
+    constructor(options: WebSocketCDPTransportOptions);
+    get emitter(): EmitterInterface<CDPTransportEventMap>;
+    start(): Promise<void>;
+    send(data: string): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * Options for creating a WebSocketCDPTransport.
+ *
+ * @remarks
+ * - `url` — the CDP WebSocket debugger URL to connect to
+ * - `timeout` — ms before the connection attempt fails (default from constants)
+ */
+export declare interface WebSocketCDPTransportOptions {
+    readonly url: string;
+    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 { }