@orkestrel/browser 0.0.15 → 0.0.16

package/README.md

@@ -1,16 +1,13 @@
 # @orkestrel/browser
 
-A typed [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
-browser automation library for the `@orkestrel` line. The environment-agnostic
-core (`src/core` — `CDPClient` speaking the CDP wire protocol over an injected
-`CDPTransportInterface`, plus `BrowserContext`, `BrowserPage`, and
-`BrowserFrame`, semantic locators, trusted input, network/HAR controls,
-diagnostics, structured DOM snapshots, content distillation that selects a
-document's article rather than its whole body text, and `BrowserCodegen`)
-never touches `node:*` or the DOM; the Node runtime (`src/server`)
-adapts it with a `WebSocketCDPTransport`, browser process launch/discovery
-(`node:child_process` + `fetch`), a filesystem browser writer, and the
-`Browser` façade that ties launch → context → page together. Part of the
+> A lightweight Chrome DevTools Protocol automation layer for Chromium-family
+> browsers: an environment-agnostic core that drives pages, frames, locators, and
+> DOM snapshots over an injected transport, and a Node runtime that finds,
+> launches, and connects to the browser itself.
+
+Connect to a running browser or launch one with the `createBrowser` function, open a page in its
+default context, and drive that page through locators, trusted input, network control, and DOM
+snapshots. Inject your own `CDPTransportInterface` where the runtime is not Node. Part of the
 `@orkestrel` line.
 
 ## Install
@@ -47,24 +44,23 @@ Drive the same protocol from any environment by injecting your own transport
 over the environment-agnostic core:
 
 ```ts
-import { CDPClient } from '@orkestrel/browser'
-import type { CDPTransportInterface } from '@orkestrel/browser'
+import { createCDPClient } from '@orkestrel/browser'
 
-const transport: CDPTransportInterface = /* your injected transport */
-const client = new CDPClient({ transport })
+const client = createCDPClient({ transport }) // transport: CDPTransportInterface
 await client.connect()
 const result = await client.send('Page.navigate', { url: 'https://example.com' })
+await client.close()
 ```
 
 ## Guide
 
-For the full surface — the CDP dispatch core, the `BrowserContext` /
-`BrowserPage` / `BrowserCodegen` entities, the server transports, and usage
+For the full surface — the CDP dispatch core, the `BrowserContext`,
+`BrowserPage`, and `BrowserCodegen` classes, the server transports, and usage
 patterns — see [`guides/browser.md`](guides/browser.md).
 
 ## Package
 
-Published with two entry points per the `exports` field in `package.json`:
+Published with the entry points the `exports` field in `package.json` names:
 the environment-agnostic core (`.`) — `CDPClient`, `BrowserContext`,
 `BrowserPage`, `BrowserFrame`, DOM snapshot traversal helpers,
 `BrowserCodegen`, `createCDPClient`, `CDPTransportInterface` —

package/dist/src/core/index.cjs

@@ -72,14 +72,17 @@ var BASE64_LOOKUP = Object.freeze({
 	"+": 62,
 	"/": 63
 });
-/** Sets the default timeout in milliseconds for browser connection, requests, and navigation. */
+/**
+* Sets the default timeout for browser connection, requests, and navigation, `30_000`
+* milliseconds.
+*/
 var BROWSER_DEFAULT_TIMEOUT_MS = 3e4;
 /**
-* Caps the serialized-character length for an `evaluate()`/`content()` result,
-* enforced IN-PAGE before the result is returned to CDP.
+* Caps the serialized-character length for an `evaluate()`/`content()` result at `2_500_000`,
+* enforced in-page before the result is returned to CDP.
 *
 * @remarks
-* This counts UTF-16 STRING LENGTH (`String#length`), not transport BYTES —
+* This counts UTF-16 string length (`String#length`), not transport bytes —
 * the actual CDP frame is UTF-8 encoded (up to 3 bytes/char for common
 * multibyte content) and carries additional JSON/CDP framing overhead on top
 * of the raw content. A `Runtime.evaluate` result above this size, once
@@ -95,8 +98,8 @@ var BROWSER_DEFAULT_TIMEOUT_MS = 3e4;
 */
 var BROWSER_RESULT_LIMIT = 25e5;
 /**
-* Names the distinctive prefix for the in-page result-limit sentinel error, immediately
-* followed by the serialized length.
+* Names the distinctive prefix for the in-page result-limit sentinel error,
+* `'[[ORKESTREL_BROWSER_RESULT_LIMIT]]'`, immediately followed by the serialized length.
 *
 * @remarks
 * Deliberately unlikely to appear in a page's own thrown error text (unlike
@@ -106,18 +109,29 @@ var BROWSER_RESULT_LIMIT = 25e5;
 */
 var BROWSER_RESULT_LIMIT_SENTINEL_PREFIX = "[[ORKESTREL_BROWSER_RESULT_LIMIT]]";
 /**
-* Matches the in-page result-limit sentinel error message, anchored
-* immediately after the `Error: ` (optionally `Uncaught Error: `) prefix that
-* Chromium prepends to a thrown error's description — so the guard's own
-* throw is recognized only at the message START, not wherever the substring
-* happens to occur.
+* Matches the in-page result-limit sentinel error message, anchored immediately after the
+* `Error:` (optionally `Uncaught Error:`) prefix Chromium prepends to a thrown error's
+* description, `/^(?:Uncaught )?Error: \[\[ORKESTREL_BROWSER_RESULT_LIMIT\]\](\d+)/`.
+*
+* @remarks
+* The anchor matches the guard's own throw only at the start of the message, rather than
+* wherever the substring happens to occur.
 */
 var BROWSER_RESULT_LIMIT_PATTERN = new RegExp(`^(?:Uncaught )?Error: \\[\\[ORKESTREL_BROWSER_RESULT_LIMIT\\]\\](\\d+)`);
-/** Sets the poll interval in milliseconds while waiting for a selector to appear. */
+/**
+* Sets the poll interval while waiting for a selector to appear, `100` milliseconds.
+*
+* @remarks
+* A wait adds the same interval as slack to its own CDP call timeout, so the in-page poll
+* expires before the call carrying it. Host-side CDP readiness probes wait it out between
+* attempts.
+*/
 var BROWSER_WAIT_POLL_INTERVAL_MS = 100;
-/** Sets the default maximum node count accepted from a decoded CDP DOM snapshot. */
+/**
+* Sets the default maximum node count accepted from a decoded CDP DOM snapshot, `100_000`.
+*/
 var BROWSER_SNAPSHOT_NODE_LIMIT = 1e5;
-/** Names the isolated world used for iframe evaluation. */
+/** Names the isolated world used for iframe evaluation, `'__orkestrelBrowserFrame'`. */
 var BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
 /** Names the attribute the semantic test-id selector uses. */
 var BROWSER_TEST_ID_ATTRIBUTE = "data-testid";
@@ -158,13 +172,13 @@ var BROWSER_MOUSE_BUTTON_MASKS = Object.freeze({
 */
 var BROWSER_HAR_CREATOR = Object.freeze({
 	name: "@orkestrel/browser",
-	version: "0.0.15"
+	version: "0.0.16"
 });
 /** Names the attribute that tags temporary screenshot styles and masks. */
 var BROWSER_SCREENSHOT_ATTRIBUTE = "data-orkestrel-screenshot";
 /**
-* Bounds (in milliseconds) the best-effort `Page.stopLoading` call issued
-* after a failed `navigate()`.
+* Bounds the best-effort `Page.stopLoading` call issued after a failed `navigate()` at `1_000`
+* milliseconds.
 *
 * @remarks
 * A wedged renderer can make the underlying CDP call hang for the full
@@ -173,23 +187,26 @@ var BROWSER_SCREENSHOT_ATTRIBUTE = "data-orkestrel-screenshot";
 * it. Best-effort only — never masks the original navigate error.
 */
 var BROWSER_STOP_LOADING_TIMEOUT_MS = 1e3;
-/** Sets the default viewport width in pixels. */
+/** Sets the default viewport width, `1280` pixels. */
 var BROWSER_DEFAULT_VIEWPORT_WIDTH = 1280;
-/** Sets the default viewport height in pixels. */
+/** Sets the default viewport height, `720` pixels. */
 var BROWSER_DEFAULT_VIEWPORT_HEIGHT = 720;
-/** Names the CDP runtime binding the codegen recorder script calls into. */
+/**
+* Names the CDP runtime binding the codegen recorder script calls into,
+* `'__orkestrelBrowserCodegen'`.
+*/
 var BROWSER_CODEGEN_BINDING_NAME = "__orkestrelBrowserCodegen";
 /**
 * Holds the in-page recorder script injected through `Page.addScriptToEvaluateOnNewDocument`
 * and `Runtime.evaluate`.
 *
 * @remarks
-* Attaches capturing-phase listeners for `click`, `input` (fill), and
-* `change` (select) on `document`, builds a stable CSS selector for the
-* target element, and forwards each action to the CDP binding
-* ({@link BROWSER_CODEGEN_BINDING_NAME}) as a JSON string payload. Guarded to
-* install exactly once per document (`window[name]` sentinel) so repeated
-* injection on every new document is idempotent.
+* Attaches capturing-phase listeners for `click`, `input` (fill), and `change` (select) on
+* `document`, builds a stable CSS selector for the target element, and forwards each action
+* to the CDP binding ({@link BROWSER_CODEGEN_BINDING_NAME}) as a JSON string payload. A
+* `contenteditable` fill is captured through `input` events, the same way an input or a
+* textarea is. Guarded to install exactly once per document (`window[name]` sentinel) so
+* repeated injection on every new document is idempotent.
 */
 var BROWSER_CODEGEN_SOURCE = `(() => {
 	const bindingName = ${JSON.stringify(BROWSER_CODEGEN_BINDING_NAME)}
@@ -282,11 +299,11 @@ var BROWSER_CODEGEN_SOURCE = `(() => {
 //#endregion
 //#region src/core/errors.ts
 /**
-* Represents the base error for all browser automation operations.
+* Represents the base error for all browser automation operations, carrying the code
+* `BROWSER_ERROR` and a `context` record.
 *
 * @remarks
-* Carries a machine-readable `code` and optional `context` so
-* callers can branch in a `catch` without parsing message strings.
+* A caller branches in a `catch` on the `code` rather than parsing message strings.
 */
 var BrowserError = class extends Error {
 	code;
@@ -299,7 +316,8 @@ var BrowserError = class extends Error {
 	}
 };
 /**
-* Reports that a selector-based lookup or wait timed out without the element appearing.
+* Reports that a selector-based lookup or wait timed out without the element appearing, under
+* the code `BROWSER_SELECTOR_ERROR`.
 */
 var BrowserSelectorError = class extends BrowserError {
 	constructor(message, context) {
@@ -308,12 +326,12 @@ var BrowserSelectorError = class extends BrowserError {
 	}
 };
 /**
-* Reports that a CDP request received an error response from the remote endpoint.
+* Reports that a CDP request received an error response from the remote endpoint, under the
+* code `BROWSER_CDP_ERROR`, with the `method`, the CDP `code`, the `message`, and any `data`
+* in its context.
 *
 * @remarks
-* Carries the originating `method` plus the CDP error's own `code`,
-* `message`, and `data` (when present) in `context`, so callers can branch
-* on the protocol-level error instead of parsing the message string.
+* Branch on the protocol-level error in `context` instead of parsing the message string.
 */
 var CDPError = class extends BrowserError {
 	constructor(message, context) {
@@ -322,9 +340,9 @@ var CDPError = class extends BrowserError {
 	}
 };
 /**
-* Reports that a CDP request could not be sent or completed because the client was not in
-* a connectable state (not connected, closed while connecting, or the
-* connection dropped mid-request).
+* Reports that a CDP request could not be sent or completed because the client was not in a
+* connectable state — not connected, closed while connecting, or the connection dropped
+* mid-request — under the code `BROWSER_CDP_CONNECTION_ERROR`.
 */
 var CDPConnectionError = class extends BrowserError {
 	constructor(message, context) {
@@ -333,7 +351,8 @@ var CDPConnectionError = class extends BrowserError {
 	}
 };
 /**
-* Reports that a pending CDP request was not answered within its timeout window.
+* Reports that a pending CDP request was not answered within its timeout window, under the
+* code `BROWSER_CDP_TIMEOUT_ERROR`.
 */
 var CDPTimeoutError = class extends BrowserError {
 	constructor(message, context) {
@@ -342,8 +361,9 @@ var CDPTimeoutError = class extends BrowserError {
 	}
 };
 /**
-* Reports that an `evaluate()`/`content()` result exceeded {@link BROWSER_RESULT_LIMIT}
-* and was rejected in-page before it could overflow the CDP transport frame.
+* Reports that an `evaluate()`/`content()` result exceeded {@link BROWSER_RESULT_LIMIT} and
+* was rejected in-page before it could overflow the CDP transport frame, under the code
+* `BROWSER_RESULT_LIMIT_ERROR`.
 */
 var BrowserResultLimitError = class extends BrowserError {
 	constructor(message, context) {
@@ -352,7 +372,7 @@ var BrowserResultLimitError = class extends BrowserError {
 	}
 };
 /**
-* Narrows an unknown value to BrowserError.
+* Narrows an unknown value to a `BrowserError`.
 *
 * @param value - Value to check
 * @returns True if value is a BrowserError instance; false otherwise
@@ -361,7 +381,7 @@ function isBrowserError(value) {
 	return (0, _orkestrel_contract.isInstance)(value, BrowserError);
 }
 /**
-* Narrows an unknown value to BrowserSelectorError.
+* Narrows an unknown value to a `BrowserSelectorError`.
 *
 * @param value - Value to check
 * @returns True if value is a BrowserSelectorError instance; false otherwise
@@ -370,7 +390,7 @@ function isBrowserSelectorError(value) {
 	return (0, _orkestrel_contract.isInstance)(value, BrowserSelectorError);
 }
 /**
-* Narrows an unknown value to CDPError.
+* Narrows an unknown value to a `CDPError`.
 *
 * @param value - Value to check
 * @returns True if value is a CDPError instance; false otherwise
@@ -379,7 +399,7 @@ function isCDPError(value) {
 	return (0, _orkestrel_contract.isInstance)(value, CDPError);
 }
 /**
-* Narrows an unknown value to CDPConnectionError.
+* Narrows an unknown value to a `CDPConnectionError`.
 *
 * @param value - Value to check
 * @returns True if value is a CDPConnectionError instance; false otherwise
@@ -388,7 +408,7 @@ function isCDPConnectionError(value) {
 	return (0, _orkestrel_contract.isInstance)(value, CDPConnectionError);
 }
 /**
-* Narrows an unknown value to CDPTimeoutError.
+* Narrows an unknown value to a `CDPTimeoutError`.
 *
 * @param value - Value to check
 * @returns True if value is a CDPTimeoutError instance; false otherwise
@@ -397,7 +417,7 @@ function isCDPTimeoutError(value) {
 	return (0, _orkestrel_contract.isInstance)(value, CDPTimeoutError);
 }
 /**
-* Narrows an unknown value to BrowserResultLimitError.
+* Narrows an unknown value to a `BrowserResultLimitError`.
 *
 * @param value - Value to check
 * @returns True if value is a BrowserResultLimitError instance; false otherwise
@@ -729,8 +749,8 @@ function parseCodegenActionPayload(payload) {
 	}
 }
 /**
-* Coerces a `Page.frameNavigated` CDP event to a `navigate` codegen action, or
-* `undefined` off-shape.
+* Coerces a `Page.frameNavigated` CDP event to a `navigate` codegen action, or `undefined`
+* off-shape and for every frame but the top-level one.
 *
 * @remarks
 * Only the top-level (main) frame's navigation is recorded — a frame
@@ -773,8 +793,7 @@ function parseSnapshotString(strings, index) {
 	return strings[index];
 }
 /**
-* Coerces a CDP snapshot rectangle to a `BrowserRect`, or `undefined`
-* off-shape.
+* Coerces a four-number CSS-pixel rectangle to a `BrowserRect`, or `undefined` off-shape.
 *
 * @param value - Candidate four-number array
 * @returns A rectangle, or undefined
@@ -871,7 +890,8 @@ function browserHeadersToProtocol(headers) {
 	}));
 }
 /**
-* Decodes a Chromium Headers object into string values.
+* Decodes a Chromium Headers object into string values, skipping every entry that is neither a
+* string nor a finite number.
 *
 * @param value - Unknown headers
 * @returns Frozen-compatible header record
@@ -1056,7 +1076,8 @@ function matchesBrowserURL(url, pattern) {
 	return new RegExp(`^${source}$`).test(url);
 }
 /**
-* Decodes the `Page.addScriptToEvaluateOnNewDocument` result.
+* Decodes the `Page.addScriptToEvaluateOnNewDocument` result, throwing a `BrowserError`
+* off-shape.
 *
 * @param value - Unknown protocol result
 * @returns Script identifier
@@ -1074,7 +1095,7 @@ function validateBrowserPoint(point) {
 	if (!(0, _orkestrel_contract.isFiniteNumber)(point.x) || !(0, _orkestrel_contract.isFiniteNumber)(point.y)) throw new BrowserError("Browser input coordinates must be finite", void 0, { point });
 }
 /**
-* Validates the bounded keys of one trusted-input operation.
+* Validates the bounded delay, count, steps, and position of one trusted-input operation.
 *
 * @remarks
 * The parameter is `BrowserOperationOptions`, so one validator answers for a
@@ -1240,7 +1261,8 @@ function validateBrowserRange(value, field, minimum, maximum, inclusive = true)
 	});
 }
 /**
-* Decodes Accessibility-domain nodes into a flat serializable tree.
+* Decodes Accessibility-domain nodes into a flat serializable tree, throwing a `BrowserError`
+* off-shape.
 *
 * @param value - Unknown full or partial AX-tree result
 * @returns Valid accessibility snapshot
@@ -1276,7 +1298,7 @@ function readBrowserAccessibility(value) {
 	};
 }
 /**
-* Decodes an Accessibility-domain AXValue.
+* Decodes an Accessibility-domain AXValue, or `undefined` when the record carries none.
 *
 * @param value - Unknown AX value
 * @returns Underlying value
@@ -1301,7 +1323,7 @@ function concatBytes(chunks) {
 	return result;
 }
 /**
-* Decodes one `IO.read` response.
+* Decodes one `IO.read` response, throwing a `BrowserError` off-shape.
 *
 * @param value - Unknown protocol result
 * @returns Valid stream chunk
@@ -1314,7 +1336,7 @@ function readBrowserStreamChunk(value) {
 	};
 }
 /**
-* Decodes JavaScript precise coverage.
+* Decodes JavaScript precise coverage, throwing a `BrowserError` off-shape.
 *
 * @param value - Unknown `Profiler.takePreciseCoverage` result
 * @returns Script coverage
@@ -1342,7 +1364,7 @@ function readBrowserScriptCoverage(value) {
 	});
 }
 /**
-* Decodes CSS rule usage.
+* Decodes CSS rule usage, throwing a `BrowserError` off-shape.
 *
 * @param value - Unknown `CSS.stopRuleUsageTracking` result
 * @returns Stylesheet coverage
@@ -1366,7 +1388,7 @@ function readBrowserStyleCoverage(value) {
 	}));
 }
 /**
-* Decodes coverage ranges.
+* Decodes and normalizes coverage ranges, throwing a `BrowserError` off-shape.
 *
 * @param value - Unknown ranges
 * @param script - Script index for diagnostics
@@ -1387,7 +1409,7 @@ function readBrowserCoverageRanges(value, script) {
 	});
 }
 /**
-* Decodes Performance-domain metrics.
+* Decodes Performance-domain metrics, throwing a `BrowserError` off-shape.
 *
 * @param value - Unknown metrics result
 * @returns Valid metrics
@@ -1403,7 +1425,7 @@ function readBrowserMetrics(value) {
 	});
 }
 /**
-* Decodes one CPU profile.
+* Decodes one CPU profile, throwing a `BrowserError` off-shape.
 *
 * @param value - Unknown `Profiler.stop` result
 * @returns Valid profile
@@ -1436,7 +1458,7 @@ function readBrowserProfile(value) {
 	};
 }
 /**
-* Decodes a CPU profile call frame.
+* Decodes a CPU profile call frame, throwing a `BrowserError` off-shape.
 *
 * @param value - Unknown call frame
 * @param node - Node index for diagnostics
@@ -1488,7 +1510,7 @@ function cookieToProtocol(cookie) {
 	return result;
 }
 /**
-* Decodes cookies returned by `Storage.getCookies`.
+* Decodes the cookies `Storage.getCookies` returns, throwing a `BrowserError` off-shape.
 *
 * @param value - Unknown protocol result
 * @returns Valid cookies
@@ -1498,7 +1520,7 @@ function readBrowserCookies(value) {
 	return value["cookies"].map((candidate, index) => readBrowserCookie(candidate, index));
 }
 /**
-* Decodes one Chromium cookie.
+* Decodes one Chromium cookie, throwing a `BrowserError` off-shape.
 *
 * @param value - Unknown cookie record
 * @param index - Source array position for diagnostics
@@ -1542,7 +1564,7 @@ function matchesBrowserCookieURL(cookie, value) {
 	return domainMatches && pathMatches && secureMatches;
 }
 /**
-* Decodes one in-page web-storage snapshot.
+* Decodes one in-page web-storage snapshot, throwing a `BrowserError` off-shape.
 *
 * @param value - Unknown evaluation result
 * @param origin - Origin represented by the result
@@ -1557,7 +1579,7 @@ function readBrowserStorageOrigin(value, origin) {
 	};
 }
 /**
-* Decodes a list of web-storage entries.
+* Decodes a list of web-storage entries, throwing a `BrowserError` off-shape.
 *
 * @param value - Unknown entry list
 * @param origin - Origin used for diagnostics
@@ -1608,7 +1630,7 @@ function mediaToFeatures(media) {
 	return features;
 }
 /**
-* Decodes a Chromium runtime stack trace.
+* Decodes a Chromium runtime stack trace, skipping every off-shape call frame.
 *
 * @param value - Unknown stack trace or call-frame list
 * @returns Valid stack frames
@@ -1629,7 +1651,8 @@ function readBrowserStack(value) {
 	return stack;
 }
 /**
-* Decodes a Runtime remote object's printable value.
+* Decodes a Runtime remote object's printable value, falling back to its unserializable form
+* and then its description, or `undefined` when it carries none.
 *
 * @param value - Unknown remote object
 * @returns By-value data or a description
@@ -1641,7 +1664,8 @@ function readBrowserRemoteValue(value) {
 	if ((0, _orkestrel_contract.isString)(value["description"])) return value["description"];
 }
 /**
-* Decodes one CDP `Runtime.evaluate` result.
+* Decodes one CDP `Runtime.evaluate` result, throwing a `BrowserError` on a failed evaluation
+* and a `BrowserResultLimitError` past the guarded result size.
 *
 * @param value - Unknown CDP result
 * @returns The returned by-value payload, or undefined
@@ -1677,13 +1701,12 @@ function requireBrowserString(value, field) {
 	throw new BrowserError(`${field} failed: no string value returned`);
 }
 /**
-* Normalizes a raw list of recorded codegen actions.
+* Normalizes recorded codegen actions, collapsing consecutive `fill` actions on the same
+* selector into the latest value.
 *
 * @remarks
-* Collapses consecutive `fill` actions on the same selector into the latest
-* value (a text input fires one `input` event per keystroke) so the
-* compiled script reflects the final typed value rather than every
-* intermediate keystroke.
+* A text input fires one `input` event per keystroke, so the compiled script reflects
+* the final typed value rather than every intermediate keystroke.
 *
 * @param actions - Raw recorded actions, in capture order
 * @returns Normalized actions, in the same order
@@ -1701,7 +1724,8 @@ function normalizeCodegenActions(actions) {
 	return result;
 }
 /**
-* Decodes a flattened CDP `Page.getFrameTree` result.
+* Decodes a flattened CDP `Page.getFrameTree` result into depth-first frame metadata, skipping
+* every off-shape frame.
 *
 * @param value - Unknown CDP result
 * @returns Frame metadata in depth-first, main-frame-first order
@@ -1730,7 +1754,8 @@ function readBrowserFrames(value) {
 	return frames;
 }
 /**
-* Decodes the first `DOM.getContentQuads` quad and its center.
+* Decodes the first `DOM.getContentQuads` quad and its center, throwing a `BrowserError`
+* off-shape.
 *
 * @param value - Unknown CDP result
 * @returns Decoded quad
@@ -1766,7 +1791,8 @@ function readBrowserQuad(value) {
 	};
 }
 /**
-* Extracts a keyboard chord such as `Control+Shift+P` into its parts.
+* Extracts a keyboard chord such as `Control+Shift+P` into its parts, throwing a
+* `BrowserError` on an empty chord or an unsupported modifier.
 *
 * @param value - Chord source
 * @returns Canonical modifiers and terminal key
@@ -1804,7 +1830,7 @@ function computeBrowserModifiers(modifiers) {
 /**
 * Computes the CDP Input pressed-button bitmask.
 *
-* @param buttons - Currently pressed public mouse buttons
+* @param buttons - Pressed public mouse buttons
 * @returns Combined CDP pressed-button mask
 */
 function computeBrowserButtons(buttons) {
@@ -1944,7 +1970,8 @@ function keyToBrowserInput(value) {
 	};
 }
 /**
-* Decodes CDP snapshot sparse string data.
+* Decodes CDP snapshot sparse string data into a node-index map, skipping every off-shape
+* entry.
 *
 * @param value - Sparse `{ index, value }` record
 * @param strings - Snapshot string table
@@ -1964,7 +1991,8 @@ function readRareStringData(value, strings) {
 	return decoded;
 }
 /**
-* Decodes CDP snapshot sparse boolean data.
+* Decodes CDP snapshot sparse boolean data into a set of node indexes, skipping every
+* off-shape entry.
 *
 * @param value - Sparse `{ index }` record
 * @returns Set of node indexes whose value is true
@@ -1974,7 +2002,8 @@ function readRareBooleanData(value) {
 	return new Set(parseNumberArray(value["index"]) ?? []);
 }
 /**
-* Decodes CDP snapshot sparse integer data.
+* Decodes CDP snapshot sparse integer data into a node-index map, skipping every off-shape
+* entry.
 *
 * @param value - Sparse `{ index, value }` record
 * @returns Node-index to integer map
@@ -1993,7 +2022,7 @@ function readRareIntegerData(value) {
 	return decoded;
 }
 /**
-* Decodes flattened CDP node attributes.
+* Decodes flattened CDP node attributes into a frozen record, skipping every off-shape pair.
 *
 * @param value - Candidate string-index array
 * @param strings - Snapshot string table
@@ -2011,7 +2040,9 @@ function readBrowserAttributes(value, strings) {
 	return Object.freeze(attributes);
 }
 /**
-* Decodes a CDP `DOMSnapshot.captureSnapshot` result.
+* Decodes a CDP `DOMSnapshot.captureSnapshot` result into a serializable
+* `BrowserSnapshotInput`, throwing a `BrowserError` off-shape and a `BrowserResultLimitError`
+* past the configured node limit.
 *
 * @param value - Unknown CDP result
 * @param styles - Requested computed-style names, in protocol order
@@ -2140,7 +2171,7 @@ function readBrowserSnapshot(value, styles = [], limit = BROWSER_SNAPSHOT_NODE_L
 	};
 }
 /**
-* Tests whether a browser-node matcher is a declarative query.
+* Tests whether a browser-node matcher is a declarative query rather than a predicate.
 *
 * @param value - Browser-node query or predicate
 * @returns True if the matcher is a declarative query; false otherwise
@@ -2412,9 +2443,9 @@ function compileStorageClearExpression() {
 })()`;
 }
 /**
-* Compiles a `Runtime.evaluate` expression so the IN-PAGE code stringifies
-* its own result and throws a recognizable error before an oversized result
-* would overflow the CDP transport frame.
+* Compiles a `Runtime.evaluate` expression so the in-page code stringifies its own result and
+* throws a recognizable sentinel error before an oversized result would overflow the CDP
+* transport frame.
 *
 * @remarks
 * A result whose `JSON.stringify` length exceeds `limit` throws
@@ -2439,7 +2470,7 @@ ${expression}
 ); const s = JSON.stringify(r); if (typeof s === 'string' && s.length > ${limit}) throw new Error(${JSON.stringify(BROWSER_RESULT_LIMIT_SENTINEL_PREFIX)} + s.length); return r })()`;
 }
 /**
-* Compiles recorded codegen actions into a replayable script.
+* Compiles recorded codegen actions into a replayable JavaScript or TypeScript script.
 *
 * @remarks
 * Emits one statement per action against a `page` object shaped like
@@ -4071,7 +4102,7 @@ var BrowserTracing = class {
 //#endregion
 //#region src/core/BrowserDiagnostics.ts
 /**
-* Groups the diagnostic subentities beneath one page.
+* Groups the tracing, coverage, performance, and profiler classes beneath one page.
 *
 * @example
 * ```ts
@@ -7372,7 +7403,7 @@ var BrowserContext = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Creates a CDP client bound to the given transport.
+* Creates a `CDPClientInterface` bound to the given `CDPTransportInterface`.
 *
 * @param options - The transport (and optional timeout) the client uses
 * @returns A {@link CDPClientInterface}
@@ -7389,7 +7420,7 @@ function createCDPClient(options) {
 	return new CDPClient(options);
 }
 /**
-* Creates a navigable browser snapshot from decoded serializable data.
+* Creates a navigable `BrowserSnapshotInterface` over decoded `BrowserSnapshotInput` data.
 *
 * @param input - Captured documents and computed-style names
 * @returns A {@link BrowserSnapshotInterface}