@orkestrel/browser 0.0.15 → 0.0.17

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { attempt, instanceOf, isArray, isBoolean, isFiniteNumber, isFunction, isInstance, isInteger, isRecord, isString, parseArray, parseEnum, parseJSON } from "@orkestrel/contract";
+import { attempt, instanceOf, isArray, isBoolean, isFiniteNumber, isFunction, isInstance, isInteger, isRecord, isString, parseArray, parseEnum, parseJSON, parseJSONAs } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
 import { createHTML, renderText } from "@orkestrel/html";
 //#region src/core/constants.ts
@@ -71,14 +71,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
@@ -94,8 +97,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
@@ -105,18 +108,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";
@@ -157,13 +171,13 @@ var BROWSER_MOUSE_BUTTON_MASKS = Object.freeze({
 */
 var BROWSER_HAR_CREATOR = Object.freeze({
 	name: "@orkestrel/browser",
-	version: "0.0.15"
+	version: "0.0.17"
 });
 /** 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
@@ -172,23 +186,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)}
@@ -281,11 +298,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;
@@ -298,7 +315,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) {
@@ -307,12 +325,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) {
@@ -321,9 +339,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) {
@@ -332,7 +350,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) {
@@ -341,8 +360,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) {
@@ -351,7 +371,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
@@ -360,7 +380,7 @@ function isBrowserError(value) {
 	return 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
@@ -369,7 +389,7 @@ function isBrowserSelectorError(value) {
 	return 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
@@ -378,7 +398,7 @@ function isCDPError(value) {
 	return 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
@@ -387,7 +407,7 @@ function isCDPConnectionError(value) {
 	return 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
@@ -396,7 +416,7 @@ function isCDPTimeoutError(value) {
 	return 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
@@ -574,8 +594,8 @@ function parseBrowserWebSocketFrame(value) {
 */
 function parseBrowserBindingCall(value) {
 	if (!isRecord(value) || !isString(value["name"]) || !isString(value["payload"]) || !isInteger(value["executionContextId"])) return;
-	const payload = parseJSON(value["payload"]);
-	if (!isRecord(payload) || !isString(payload["id"]) || !isString(payload["name"]) || !isArray(payload["args"]) || payload["name"] !== value["name"]) return;
+	const payload = parseJSONAs(value["payload"], isRecord);
+	if (payload === void 0 || !isString(payload["id"]) || !isString(payload["name"]) || !isArray(payload["args"]) || payload["name"] !== value["name"]) return;
 	return {
 		id: payload["id"],
 		name: payload["name"],
@@ -701,8 +721,8 @@ function parseBrowserDownloadProgress(value) {
 */
 function parseCodegenActionPayload(payload) {
 	if (!isString(payload)) return void 0;
-	const parsed = parseJSON(payload);
-	if (!isRecord(parsed)) return void 0;
+	const parsed = parseJSONAs(payload, isRecord);
+	if (parsed === void 0) return void 0;
 	const action = parseEnum(parsed["action"], [
 		"click",
 		"fill",
@@ -728,8 +748,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
@@ -756,8 +776,7 @@ function parseCodegenNavigateAction(params) {
 * @returns The number array, or undefined
 */
 function parseNumberArray(value) {
-	if (!isArray(value) || !value.every(isFiniteNumber)) return;
-	return value;
+	return parseArray(value, isFiniteNumber);
 }
 /**
 * Coerces one CDP snapshot string-table index to its string, or `undefined`
@@ -772,8 +791,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
@@ -870,7 +888,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
@@ -1055,7 +1074,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
@@ -1073,7 +1093,7 @@ function validateBrowserPoint(point) {
 	if (!isFiniteNumber(point.x) || !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
@@ -1239,7 +1259,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
@@ -1275,7 +1296,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
@@ -1300,7 +1321,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
@@ -1313,7 +1334,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
@@ -1341,7 +1362,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
@@ -1365,7 +1386,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
@@ -1386,7 +1407,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
@@ -1402,7 +1423,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
@@ -1435,7 +1456,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
@@ -1487,7 +1508,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
@@ -1497,7 +1518,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
@@ -1541,7 +1562,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
@@ -1556,7 +1577,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
@@ -1607,7 +1628,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
@@ -1628,7 +1649,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
@@ -1640,7 +1662,8 @@ function readBrowserRemoteValue(value) {
 	if (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
@@ -1676,13 +1699,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
@@ -1700,7 +1722,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
@@ -1729,7 +1752,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
@@ -1765,7 +1789,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
@@ -1803,7 +1828,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) {
@@ -1943,7 +1968,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
@@ -1963,7 +1989,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
@@ -1973,7 +2000,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
@@ -1992,7 +2020,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
@@ -2010,7 +2038,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
@@ -2020,8 +2050,8 @@ function readBrowserAttributes(value, strings) {
 function readBrowserSnapshot(value, styles = [], limit = BROWSER_SNAPSHOT_NODE_LIMIT) {
 	if (!isInteger(limit) || limit < 0) throw new BrowserError("Browser snapshot limit must be a non-negative integer", void 0, { limit });
 	if (!isRecord(value) || !isArray(value["strings"]) || !isArray(value["documents"])) throw new BrowserError("Malformed DOMSnapshot.captureSnapshot result");
-	if (!value["strings"].every(isString)) throw new BrowserError("Malformed DOMSnapshot string table");
-	const strings = value["strings"];
+	const strings = parseArray(value["strings"], isString);
+	if (strings === void 0) throw new BrowserError("Malformed DOMSnapshot string table");
 	let count = 0;
 	for (const document of value["documents"]) {
 		if (!isRecord(document) || !isRecord(document["nodes"])) continue;
@@ -2139,7 +2169,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
@@ -2411,9 +2441,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
@@ -2438,7 +2468,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
@@ -4070,7 +4100,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
@@ -4704,8 +4734,9 @@ var BrowserLocator = class BrowserLocator {
 	}
 	async texts() {
 		const value = await this.#frame.evaluate(`(${compileLocatorListExpression(this.#query)}).map((element) => element.innerText)`);
-		if (!isArray(value) || !value.every(isString)) throw new BrowserError("Browser locator text list is malformed");
-		return value;
+		const texts = parseArray(value, isString);
+		if (texts === void 0) throw new BrowserError("Browser locator text list is malformed");
+		return texts;
 	}
 	async html() {
 		return await this.#string("outerHTML", "Browser locator HTML");
@@ -7371,7 +7402,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}
@@ -7388,7 +7419,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}