@orkestrel/browser 0.0.15 → 0.0.16

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

@@ -1,21 +1,18 @@
-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 { 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';
-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 { Result } from '@orkestrel/contract';
+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.
@@ -51,19 +48,30 @@ export declare class Browser implements BrowserInterface {
     close(): Promise<void>;
 }
 
-/** Names the 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";
 
-/** Names the protocol prefix for CDP discovery requests. */
+/** Names the protocol prefix for CDP discovery requests, `'http'`. */
 export declare const BROWSER_CDP_PROTOCOL = "http";
 
-/** Names the 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";
 
-/** Sets the 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;
 
-/** 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`). */
+/**
+ * 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";
 
 /**
@@ -72,55 +80,96 @@ export declare const BROWSER_DEFAULT_HOST = "127.0.0.1";
  */
 export declare const BROWSER_ENGINE_HINTS: Readonly<Record<BrowserEngine, readonly string[]>>;
 
-/** Lists the 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[];
 
 /** Lists the command names probed on PATH when no well-known executable path exists. */
 export declare const BROWSER_EXECUTABLE_NAMES: readonly string[];
 
-/** Lists the 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[]>>;
 
-/** Names the flag that enables 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";
 
-/** Bounds 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;
 
 /** Lists the flags always passed to a launched browser process, alongside the caller's own. */
 export declare const BROWSER_LAUNCH_ARGS: readonly string[];
 
-/** 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. */
+/**
+ * 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;
 
-/** Names the 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";
 
-/** Names the 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-";
 
 /** 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>>;
 
-/** Lists the 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[];
 
-/** Names the environment variable that carries 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";
 
 /** 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>>;
 
-/** Names 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";
 
-/** Names the 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";
 
-/** 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. */
+/**
+ * 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;
 
-/** Lists the 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>>;
 
 /** Lists the Windows install-root-relative suffixes for Chrome/Edge/Chromium, joined against each candidate root (`PROGRAMFILES`, `PROGRAMFILES(X86)`, `LOCALAPPDATA`). */
@@ -152,14 +201,16 @@ export declare interface BrowserCDPOptions {
 export declare type BrowserConnection = 'cdp' | 'launch' | 'persistent';
 
 /**
- * Reports that 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>>);
 }
 
 /**
- * Reports that 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>>);
@@ -243,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
@@ -286,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>;
-    /** Assumes 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>;
 }
 
 /**
- * Reports that 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>>);
 }
 
 /**
- * Describes the options for creating a Browser.
+ * Describes the options for creating a `Browser` instance.
  *
  * @remarks
  * - `on` — initial event listeners wired at construction
@@ -372,17 +463,22 @@ export declare function buildStoreBases(env: Readonly<Record<string, string | un
 export declare function buildWindowsRoots(env: Readonly<Record<string, string | undefined>>): readonly string[];
 
 /**
- * Creates 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 '@orkestrel/browser/server'
  *
- * const browser = createBrowser()
- * await browser.connect()
+ * const browser = createBrowser({ headless: true })
+ * await browser.connect() // CDP endpoint discovery → connect, else launch
+ * const page = await browser.create({ url: 'https://example.com' })
+ * await page.click('#accept')
+ * const shot = await page.screenshot({ path: './out.png' })
+ * await browser.destroy()
  * ```
  */
 export declare function createBrowser(options?: BrowserOptions): BrowserInterface;
@@ -396,22 +492,24 @@ export declare function createBrowser(options?: BrowserOptions): BrowserInterfac
 export declare function createBrowserProfile(path?: string): Promise<BrowserProfileResult>;
 
 /**
- * Creates a filesystem-backed browser writer.
+ * Creates a filesystem-backed `BrowserWriterInterface` that persists bytes through
+ * `node:fs/promises`.
  *
  * @returns A {@link BrowserWriterInterface} that persists bytes through `node:fs/promises`
  */
-export declare function createBrowserWriter(): BrowserWriterInterface_2;
+export declare function createBrowserWriter(): BrowserWriterInterface;
 
 /**
- * Creates a Node `WebSocket`-backed CDP transport.
+ * Creates a Node `WebSocket`-backed `CDPTransportInterface` for the given CDP debugger URL.
  *
  * @param options - The CDP WebSocket debugger URL (and optional timeout)
  * @returns A {@link CDPTransportInterface}
  */
-export declare function createCDPTransport(options: WebSocketCDPTransportOptions): CDPTransportInterface_2;
+export declare function createCDPTransport(options: WebSocketCDPTransportOptions): CDPTransportInterface;
 
 /**
- * Fetches 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
@@ -504,7 +602,7 @@ export declare function findSystemBrowser(options?: SystemBrowserOptions): Syste
 export declare function findSystemBrowsers(options?: SystemBrowserOptions): readonly SystemBrowser[];
 
 /**
- * Narrows an unknown value to BrowserConnectionError.
+ * Narrows an unknown value to a `BrowserConnectionError`.
  *
  * @param value - Value to check
  * @returns True if value is a BrowserConnectionError instance; false otherwise
@@ -512,7 +610,7 @@ export declare function findSystemBrowsers(options?: SystemBrowserOptions): read
 export declare function isBrowserConnectionError(value: unknown): value is BrowserConnectionError;
 
 /**
- * Narrows an unknown value to BrowserDestroyedError.
+ * Narrows an unknown value to a `BrowserDestroyedError`.
  *
  * @param value - Value to check
  * @returns True if value is a BrowserDestroyedError instance; false otherwise
@@ -520,7 +618,7 @@ export declare function isBrowserConnectionError(value: unknown): value is Brows
 export declare function isBrowserDestroyedError(value: unknown): value is BrowserDestroyedError;
 
 /**
- * Narrows an unknown value to BrowserNotConnectedError.
+ * Narrows an unknown value to a `BrowserNotConnectedError`.
  *
  * @param value - Value to check
  * @returns True if value is a BrowserNotConnectedError instance; false otherwise
@@ -669,14 +767,14 @@ export declare function waitForCDPReady(port: number, timeout: number, host?: st
 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>;
 }
 
 /**
- * Describes the options for creating a WebSocketCDPTransport.
+ * Describes the options for creating a `WebSocketCDPTransport` instance.
  *
  * @remarks
  * - `on` — initial event listeners wired at construction