@orkestrel/browser 0.0.15 → 0.0.17

package/dist/src/server/index.cjs

@@ -14,35 +14,75 @@ let _orkestrel_emitter = require("@orkestrel/emitter");
 let _orkestrel_websocket = require("@orkestrel/websocket");
 let node_events = require("node:events");
 //#region src/server/constants.ts
-/** 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`.
+*/
 var 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`.
+*/
 var BROWSER_DEFAULT_HOST = "127.0.0.1";
-/** Names the protocol prefix for CDP discovery requests. */
+/** Names the protocol prefix for CDP discovery requests, `'http'`. */
 var 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.
+*/
 var BROWSER_CDP_VERSION_PATH = "/json/version";
-/** 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'`.
+*/
 var BROWSER_CDP_LIST_PATH = "/json/list";
 /** Lists the flags always passed to a launched browser process, alongside the caller's own. */
 var BROWSER_LAUNCH_ARGS = Object.freeze(["--no-first-run", "--no-default-browser-check"]);
-/** 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'`.
+*/
 var BROWSER_HEADLESS_ARG = "--headless=new";
-/** 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-'`.
+*/
 var BROWSER_PROFILE_PREFIX = "orkestrel-browser-";
-/** 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.
+*/
 var BROWSER_KILL_GRACE_MS = 3e3;
-/** 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.
+*/
 var BROWSER_PORT_PROBE_TIMEOUT_MS = 200;
-/** 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.
+*/
 var BROWSER_TRANSPORT_LOSS_DEFER_MS = 50;
-/** 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'`.
+*/
 var BROWSER_PROCESS_EXIT_CAUSE = "process-exit";
-/** 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'`.
+*/
 var BROWSER_TRANSPORT_LOSS_CAUSE = "transport-loss";
-/** 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`.
+*/
 var BROWSER_ENV_PATH_KEYS = Object.freeze(["PLAYWRIGHT_EXECUTABLE_PATH", "CHROME_PATH"]);
-/** 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`.
+*/
 var BROWSER_EXECUTABLE_PATHS = Object.freeze({
 	linux: Object.freeze([
 		"/usr/bin/google-chrome",
@@ -68,7 +108,10 @@ var BROWSER_WINDOWS_SUFFIXES = Object.freeze([
 	"Microsoft\\Edge\\Application\\msedge.exe",
 	"Chromium\\Application\\chrome.exe"
 ]);
-/** 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.
+*/
 var BROWSER_WINDOWS_ROOT_FALLBACKS = Object.freeze({
 	PROGRAMFILES: "C:\\Program Files",
 	"PROGRAMFILES(X86)": "C:\\Program Files (x86)"
@@ -83,16 +126,25 @@ var BROWSER_EXECUTABLE_NAMES = Object.freeze([
 	"chromium-browser",
 	"chrome"
 ]);
-/** 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'`.
+*/
 var BROWSER_STORE_ENV_KEY = "PLAYWRIGHT_BROWSERS_PATH";
-/** 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`.
+*/
 var BROWSER_STORE_DEFAULT_DIRS = Object.freeze(["/opt/pw-browsers"]);
 /** Names the per-OS default Playwright browser cache directory, relative to the home directory (win32 uses `LOCALAPPDATA` directly). */
 var BROWSER_STORE_CACHE_DIRS = Object.freeze({
 	linux: ".cache/ms-playwright",
 	darwin: "Library/Caches/ms-playwright"
 });
-/** 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'`.
+*/
 var BROWSER_STORE_LINK_NAME = "chromium";
 /**
 * Lists the case-insensitive substrings identifying an executable path/name's browser
@@ -128,7 +180,8 @@ var BROWSER_STORE_GLOBS = Object.freeze({
 //#endregion
 //#region src/server/errors.ts
 /**
-* 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`.
 */
 var BrowserConnectionError = class extends _src_core.BrowserError {
 	constructor(message, context) {
@@ -137,7 +190,8 @@ var BrowserConnectionError = class extends _src_core.BrowserError {
 	}
 };
 /**
-* 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`.
 */
 var BrowserNotConnectedError = class extends _src_core.BrowserError {
 	constructor(context) {
@@ -146,7 +200,8 @@ var BrowserNotConnectedError = class extends _src_core.BrowserError {
 	}
 };
 /**
-* 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`.
 */
 var BrowserDestroyedError = class extends _src_core.BrowserError {
 	constructor(context) {
@@ -155,7 +210,7 @@ var BrowserDestroyedError = class extends _src_core.BrowserError {
 	}
 };
 /**
-* 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
@@ -164,7 +219,7 @@ function isBrowserConnectionError(value) {
 	return (0, _orkestrel_contract.isInstance)(value, BrowserConnectionError);
 }
 /**
-* 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
@@ -173,7 +228,7 @@ function isBrowserNotConnectedError(value) {
 	return (0, _orkestrel_contract.isInstance)(value, BrowserNotConnectedError);
 }
 /**
-* 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
@@ -466,7 +521,8 @@ async function waitForCDPReady(port, timeout, host = BROWSER_DEFAULT_HOST, signa
 	});
 }
 /**
-* 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
@@ -761,24 +817,29 @@ var FileBrowserWriter = class {
 //#endregion
 //#region src/server/factories.ts
 /**
-* 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()
 * ```
 */
 function createBrowser(options) {
 	return new Browser(options);
 }
 /**
-* 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}
@@ -787,7 +848,8 @@ function createCDPTransport(options) {
 	return new WebSocketCDPTransport(options);
 }
 /**
-* 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`
 */