@orkestrel/browser 0.0.15 → 0.0.17

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

@@ -1,6 +1,6 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
 
 /** Holds the index-ordered base64 alphabet used to build {@link BASE64_LOOKUP}. */
 export declare const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -8,7 +8,10 @@ export declare const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq
 /** Maps each base64 character to its 6-bit value, derived from {@link BASE64_CHARS}. */
 export declare const BASE64_LOOKUP: Readonly<Record<string, number>>;
 
-/** Names the CDP runtime binding the codegen recorder script calls into. */
+/**
+ * Names the CDP runtime binding the codegen recorder script calls into,
+ * `'__orkestrelBrowserCodegen'`.
+ */
 export declare const BROWSER_CODEGEN_BINDING_NAME = "__orkestrelBrowserCodegen";
 
 /**
@@ -16,25 +19,28 @@ export declare const BROWSER_CODEGEN_BINDING_NAME = "__orkestrelBrowserCodegen";
  * 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.
  */
 export declare const BROWSER_CODEGEN_SOURCE: string;
 
-/** 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.
+ */
 export declare const BROWSER_DEFAULT_TIMEOUT_MS = 30000;
 
-/** Sets the default viewport height in pixels. */
+/** Sets the default viewport height, `720` pixels. */
 export declare const BROWSER_DEFAULT_VIEWPORT_HEIGHT = 720;
 
-/** Sets the default viewport width in pixels. */
+/** Sets the default viewport width, `1280` pixels. */
 export declare const BROWSER_DEFAULT_VIEWPORT_WIDTH = 1280;
 
-/** Names the isolated world used for iframe evaluation. */
+/** Names the isolated world used for iframe evaluation, `'__orkestrelBrowserFrame'`. */
 export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
 
 /**
@@ -47,7 +53,7 @@ export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
  */
 export declare const BROWSER_HAR_CREATOR: Readonly<{
     name: "@orkestrel/browser";
-    version: "0.0.15";
+    version: "0.0.17";
 }>;
 
 /** Maps a canonical modifier name to its CDP Input modifier bit value. */
@@ -57,11 +63,11 @@ export declare const BROWSER_KEY_MODIFIERS: Readonly<Record<string, number>>;
 export declare const BROWSER_MOUSE_BUTTON_MASKS: Readonly<Record<BrowserMouseButton, number>>;
 
 /**
- * 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
@@ -78,17 +84,19 @@ export declare const BROWSER_MOUSE_BUTTON_MASKS: Readonly<Record<BrowserMouseBut
 export declare const BROWSER_RESULT_LIMIT = 2500000;
 
 /**
- * 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.
  */
 export declare const BROWSER_RESULT_LIMIT_PATTERN: RegExp;
 
 /**
- * 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
@@ -101,15 +109,17 @@ export declare const BROWSER_RESULT_LIMIT_SENTINEL_PREFIX = "[[ORKESTREL_BROWSER
 /** Names the attribute that tags temporary screenshot styles and masks. */
 export declare const BROWSER_SCREENSHOT_ATTRIBUTE = "data-orkestrel-screenshot";
 
-/** 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`.
+ */
 export declare const BROWSER_SNAPSHOT_NODE_LIMIT = 100000;
 
 /** Sets the number of animation frames whose element bounds must agree before trusted input. */
 export declare const BROWSER_STABLE_FRAME_COUNT = 2;
 
 /**
- * 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
@@ -133,7 +143,14 @@ export declare const BROWSER_TEST_ID_ATTRIBUTE = "data-testid";
  */
 export declare const BROWSER_VISIBILITY_SOURCE = "style.display !== 'none' && style.visibility !== 'hidden' && style.visibility !== 'collapse' && rect.width > 0 && rect.height > 0";
 
-/** 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.
+ */
 export declare const BROWSER_WAIT_POLL_INTERVAL_MS = 100;
 
 /**
@@ -155,6 +172,7 @@ export declare class BrowserAccessibility implements BrowserAccessibilityInterfa
 
 /** Inspects the accessibility tree. */
 export declare interface BrowserAccessibilityInterface {
+    /** Reads the full accessibility tree, optionally pruned to the interesting nodes. */
     snapshot(options?: BrowserAccessibilityOptions): Promise<BrowserAccessibilitySnapshot>;
 }
 
@@ -185,7 +203,7 @@ export declare interface BrowserActionabilityOptions {
  *
  * @remarks
  * - `timeout` — maximum time to wait for the selector in milliseconds
- * - `strict` — require the selector to resolve to exactly one element
+ * - `strict` — require the selector to resolve to exactly one element (default `true`)
  * - `force` — skip the actionability checks
  * - `trial` — run the checks and stop before dispatching input
  */
@@ -267,10 +285,17 @@ export declare class BrowserClock implements BrowserClockInterface {
 /** Controls Chromium virtual time for deterministic page timers. */
 export declare interface BrowserClockInterface {
     readonly installed: boolean;
+    /** Takes over the page clock, optionally seeding it with an epoch time. */
     install(time?: number): Promise<void>;
+    /** Suspends virtual time so no page timer advances. */
     pause(): Promise<void>;
+    /** Continues virtual time after a pause. */
     resume(): Promise<void>;
+    /**
+     * Moves virtual time forward by the given milliseconds, firing the timers that fall due.
+     */
     advance(ms: number): Promise<void>;
+    /** Returns the page to the real clock, and does nothing when no clock was installed. */
     uninstall(): Promise<void>;
 }
 
@@ -350,11 +375,20 @@ export declare type BrowserCodegenEventMap = {
 export declare interface BrowserCodegenInterface {
     readonly emitter: EmitterInterface<BrowserCodegenEventMap>;
     readonly started: boolean;
+    /**
+     * Begins recording on the page's session. A call after teardown is a silent no-op, because
+     * a torn-down recorder cannot be restarted and a fresh one is obtained through the page.
+     */
     start(): Promise<void>;
+    /** Stops recording and returns the captured actions. */
     stop(): Promise<readonly BrowserCodegenAction[]>;
+    /** Returns the current normalized action list. */
     actions(): readonly BrowserCodegenAction[];
+    /** Compiles the captured actions into a script. */
     script(options?: BrowserCodegenScriptOptions): string;
+    /** Resets the captured action list. */
     clear(): void;
+    /** Tears down the recorder and detaches its CDP listeners. */
     destroy(): Promise<void>;
 }
 
@@ -362,7 +396,7 @@ export declare interface BrowserCodegenInterface {
 export declare type BrowserCodegenLanguage = 'javascript' | 'typescript';
 
 /**
- * Describes the options for creating a BrowserCodegen recorder.
+ * Describes the options for creating a `BrowserCodegen` recorder.
  *
  * @remarks
  * - `on` — initial event listeners wired at construction
@@ -464,11 +498,27 @@ export declare interface BrowserContextInterface {
     readonly permissions: BrowserPermissionManagerInterface;
     readonly storage: BrowserStorageManagerInterface;
     readonly emulation: BrowserEmulationManagerInterface;
+    /** Returns one page by index, or the first page. */
     page(index?: number): BrowserPageInterface | undefined;
+    /** Returns every page in creation order. */
     pages(): readonly BrowserPageInterface[];
+    /** Opens a page in this context. */
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
+    /**
+     * Synchronizes pages from the given CDP targets, which the server discovers and core never
+     * fetches. Performs a destructive diff rather than an additive merge: a page whose target
+     * id is missing from `targets` is closed and dropped, and a target that is not yet tracked
+     * is attached and added.
+     */
     sync(targets: readonly CDPTarget[]): Promise<void>;
+    /**
+     * Releases local pages and detaches their sessions without disposing the remote browser
+     * context.
+     */
     destroy(): Promise<void>;
+    /**
+     * Closes remote pages, disposes the remote browser context, and releases local resources.
+     */
     close(): Promise<void>;
 }
 
@@ -549,8 +599,11 @@ export declare class BrowserCookieManager implements BrowserCookieManagerInterfa
 
 /** Provides cookie operations scoped to one browser context. */
 export declare interface BrowserCookieManagerInterface {
+    /** Reads the context cookies, optionally narrowed to the given URLs. */
     cookies(urls?: readonly string[]): Promise<readonly BrowserCookie[]>;
+    /** Writes the given cookies into the context. */
     set(cookies: readonly BrowserCookieInput[]): Promise<void>;
+    /** Deletes the context cookies matching the filter, or every cookie when given none. */
     clear(filter?: BrowserCookieFilter): Promise<void>;
 }
 
@@ -584,8 +637,17 @@ export declare class BrowserCoverage implements BrowserCoverageInterface {
 /** Drives the coverage capture lifecycle. */
 export declare interface BrowserCoverageInterface {
     readonly active: boolean;
+    /**
+     * Arms the requested domains. Throws a `BrowserError` when collection is already active or
+     * when neither domain is requested.
+     */
     start(options?: BrowserCoverageOptions): Promise<void>;
+    /** Reads the collected usage and disarms every domain it armed. */
     stop(): Promise<BrowserCoverageResult>;
+    /**
+     * Stops an active collector, discarding any failure, and does nothing when no collection
+     * is running.
+     */
     destroy(): Promise<void>;
 }
 
@@ -616,7 +678,7 @@ export declare interface BrowserCredentials {
 }
 
 /**
- * Groups the diagnostic subentities beneath one page.
+ * Groups the tracing, coverage, performance, and profiler classes beneath one page.
  *
  * @example
  * ```ts
@@ -643,6 +705,7 @@ export declare interface BrowserDiagnosticsInterface {
     readonly coverage: BrowserCoverageInterface;
     readonly performance: BrowserPerformanceInterface;
     readonly profiler: BrowserProfilerInterface;
+    /** Tears down every diagnostics capability this page's group owns. */
     destroy(): Promise<void>;
 }
 
@@ -654,7 +717,11 @@ export declare interface BrowserDialogInterface {
     readonly category: BrowserDialogCategory;
     readonly message: string;
     readonly default: string;
+    /**
+     * Accepts the dialog, optionally supplying prompt text. Throws once the dialog is handled.
+     */
     accept(value?: string): Promise<void>;
+    /** Dismisses the dialog. Throws once the dialog is handled. */
     dismiss(): Promise<void>;
 }
 
@@ -694,6 +761,10 @@ export declare interface BrowserDownloadInterface {
     readonly received: number;
     readonly total: number;
     readonly path: string | undefined;
+    /**
+     * Sends CDP `Browser.cancelDownload` for this download, and is ignored unless the status
+     * is still pending.
+     */
     cancel(): Promise<void>;
     /** Records one step of the download's progress. The owning page drives it. */
     update(progress: BrowserDownloadProgress): void;
@@ -758,8 +829,13 @@ export declare class BrowserEmulationManager implements BrowserEmulationManagerI
 
 /** Configures context-scoped emulation. */
 export declare interface BrowserEmulationManagerInterface {
+    /**
+     * Clears the superseded overrides and applies the given ones to every page of the context.
+     */
     apply(options: BrowserEmulationOptions): Promise<void>;
+    /** Removes every override this manager applied. */
     clear(): Promise<void>;
+    /** Applies the retained overrides to a newly created page. */
     attach(page: BrowserPageInterface): Promise<void>;
 }
 
@@ -777,11 +853,11 @@ export declare interface BrowserEmulationOptions {
 }
 
 /**
- * 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.
  */
 export declare class BrowserError extends Error {
     readonly code: string;
@@ -792,7 +868,12 @@ export declare class BrowserError extends Error {
 /** Represents one intercepted file chooser. */
 export declare interface BrowserFileChooserInterface {
     readonly multiple: boolean;
+    /**
+     * Sets the chosen files. Throws when a single-file chooser is given several, and once the
+     * chooser is already handled.
+     */
     upload(files: readonly string[]): Promise<void>;
+    /** Clears the selection. Throws once the chooser is already handled. */
     cancel(): Promise<void>;
 }
 
@@ -881,20 +962,57 @@ export declare interface BrowserFrameInterface {
     readonly keyboard: BrowserKeyboardInterface;
     readonly mouse: BrowserMouseInterface;
     readonly touch: BrowserTouchInterface;
+    /** Resolves the frame document title. */
     title(): Promise<string>;
+    /** Extracts the URL, title, HTML, and visible text under the result-size guards. */
     content(): Promise<BrowserContentResult>;
+    /**
+     * Distills the frame HTML to reader-facing plain text, with boilerplate and hidden regions
+     * pruned.
+     */
     article(): Promise<string>;
+    /**
+     * Clicks a CSS-selector match, strict by default and requiring it visible and enabled.
+     */
     click(selector: string, options?: BrowserActionOptions): Promise<void>;
+    /**
+     * Fills an editable input or contenteditable element, strict by default, dispatching input
+     * and change events.
+     */
     fill(selector: string, value: string, options?: BrowserActionOptions): Promise<void>;
+    /** Selects options on an enabled `select` element, strict by default. */
     select(selector: string, values: readonly string[], options?: BrowserActionOptions): Promise<void>;
+    /** Evaluates an expression in the frame execution world under the result-size guard. */
     evaluate(expression: string, timeout?: number): Promise<unknown>;
+    /**
+     * Evaluates an expression by reference and returns a disposable remote object handle.
+     */
     handle(expression: string): Promise<BrowserHandleInterface>;
+    /** Waits for a selector to reach the attached, detached, visible, or hidden state. */
     wait(selector: string, options?: BrowserWaitOptions): Promise<void>;
+    /**
+     * Issues a raw CDP method in the frame's current target session, with a trailing
+     * `BrowserSendOptions` carrying a per-call `timeout` overriding the client-wide default.
+     */
     send(method: string, params?: Readonly<Record<string, unknown>>, options?: BrowserSendOptions): Promise<unknown>;
+    /** Subscribes to a CDP event in the frame's current target session. */
     subscribe(method: string, handler: CDPHandler): Promise<void>;
+    /** Removes a frame-session CDP event subscription. */
     unsubscribe(method: string, handler: CDPHandler): Promise<void>;
+    /**
+     * Persists bytes through a page writer; a child frame rejects because it owns no writer.
+     */
     save(path: string, bytes: Uint8Array): Promise<void>;
+    /**
+     * Throws a coded `BrowserError` when the frame can no longer accept protocol work: a frame
+     * throws once the CDP client disconnects, and a page also throws once it closes. Every
+     * other member here calls it first.
+     */
     assert(): void;
+    /**
+     * Records an externally observed URL as the frame's current `url`, which a page calls from
+     * its own `Page.frameNavigated` handler.
+     */
     update(url: string): void;
 }
 
@@ -917,10 +1035,18 @@ export declare interface BrowserGeolocation {
  */
 export declare interface BrowserHandleInterface {
     readonly id: string;
+    /** Reads the object back by value. */
     value(): Promise<unknown>;
+    /** Runs a function declaration with the handle as `this`, by value. */
     call(declaration: string, args?: readonly unknown[]): Promise<unknown>;
+    /**
+     * Retains one own property as its own handle, or returns `undefined` when the property is
+     * absent.
+     */
     property(name: string): Promise<BrowserHandleInterface | undefined>;
+    /** Reads every own property by value. */
     properties(): Promise<Readonly<Record<string, unknown>>>;
+    /** Releases the retained remote object. Idempotent. */
     dispose(): Promise<void>;
 }
 
@@ -1009,9 +1135,13 @@ export declare class BrowserHARManager implements BrowserHARManagerInterface {
 /** Provides HAR recording and replay operations. */
 export declare interface BrowserHARManagerInterface {
     readonly recording: boolean;
+    /** Begins recording exchanges, optionally capturing response content. */
     start(options?: BrowserHAROptions): Promise<void>;
+    /** Ends recording and returns the archive, writing it when a path was given. */
     stop(): Promise<BrowserHAR>;
+    /** Serves matching requests from an archive instead of from the network. */
     replay(har: BrowserHAR, options?: BrowserHARReplayOptions): Promise<void>;
+    /** Drops the recorded entries and any active replay without ending the recording. */
     clear(): Promise<void>;
 }
 
@@ -1132,10 +1262,22 @@ export declare class BrowserKeyboard implements BrowserKeyboardInterface {
 
 /** Provides keyboard input operations bound to one frame target session. */
 export declare interface BrowserKeyboardInterface {
+    /**
+     * Presses one key and holds it, retaining it in the modifier mask when it is a modifier.
+     */
     down(key: string): Promise<void>;
+    /**
+     * Releases one key, dropping it from the modifier mask even when the release frame fails.
+     */
     up(key: string): Promise<void>;
+    /**
+     * Presses a chord: holds its modifiers, presses and releases its terminal key, then
+     * releases the modifiers.
+     */
     press(key: string, options?: BrowserInputOptions): Promise<void>;
+    /** Types a string as one press and release per character. */
     type(value: string, options?: BrowserInputOptions): Promise<void>;
+    /** Inserts composed text in one frame, firing no per-key events. */
     insert(value: string): Promise<void>;
 }
 
@@ -1219,34 +1361,69 @@ export declare interface BrowserLocatorFilter {
 export declare interface BrowserLocatorInterface {
     readonly frame: BrowserFrameInterface;
     readonly query: BrowserQuery;
+    /** Narrows to a descendant matching the CSS selector. */
     locator(selector: string): BrowserLocatorInterface;
+    /** Narrows to the matches satisfying the filter. */
     filter(options: BrowserLocatorFilter): BrowserLocatorInterface;
+    /** Narrows to the first match. */
     first(): BrowserLocatorInterface;
+    /** Narrows to the last match. */
     last(): BrowserLocatorInterface;
+    /** Narrows to the match at the given index. */
     item(index: number): BrowserLocatorInterface;
+    /** Counts the current matches. */
     count(): Promise<number>;
+    /** Resolves one indexed locator per current match. */
     all(): Promise<readonly BrowserLocatorInterface[]>;
+    /** Clicks the match with trusted input after its actionability checks pass. */
     click(options?: BrowserLocatorClickOptions): Promise<void>;
+    /** Replaces the match's value with the given text. */
     fill(value: string, options?: BrowserActionOptions): Promise<void>;
+    /** Selects the given option values on the match. */
     select(values: readonly string[], options?: BrowserActionOptions): Promise<void>;
+    /** Clicks the match unless it already reports checked. */
     check(options?: BrowserLocatorClickOptions): Promise<void>;
+    /** Clicks the match unless it already reports unchecked. */
     uncheck(options?: BrowserLocatorClickOptions): Promise<void>;
+    /** Moves trusted pointer input over the match. */
     hover(options?: BrowserPointerOptions): Promise<void>;
+    /** Gives the match keyboard focus. */
     focus(options?: BrowserActionOptions): Promise<void>;
+    /** Focuses the match and presses one key or chord. */
     press(key: string, options?: BrowserLocatorTypeOptions): Promise<void>;
+    /** Focuses the match and types the value one key at a time. */
     type(value: string, options?: BrowserLocatorTypeOptions): Promise<void>;
+    /** Empties the match's value. */
     clear(options?: BrowserActionOptions): Promise<void>;
+    /** Waits until the match reaches the requested state. Rejects on timeout. */
     wait(options?: BrowserWaitOptions): Promise<void>;
+    /** Reads the first match's rendered text. */
     text(): Promise<string>;
+    /** Reads the rendered text of every match. */
     texts(): Promise<readonly string[]>;
+    /** Reads the first match's inner HTML. */
     html(): Promise<string>;
+    /** Reads the first match's form value. */
     value(): Promise<string>;
+    /**
+     * Reads one attribute of the first match, or returns `undefined` when the match carries
+     * none.
+     */
     attribute(name: string): Promise<string | undefined>;
+    /** Reports whether the first match renders a non-empty box. */
     visible(): Promise<boolean>;
+    /** Reports whether the first match accepts input. */
     enabled(): Promise<boolean>;
+    /** Reports whether the first match accepts typed text. */
     editable(): Promise<boolean>;
+    /**
+     * Captures the first match's box, persisting it through the page writer when a path is
+     * given.
+     */
     screenshot(options?: BrowserScreenshotOptions): Promise<BrowserScreenshotResult>;
+    /** Sets the file selection on the matched file input. */
     upload(options: BrowserUploadOptions): Promise<void>;
+    /** Drags the match onto the target locator with trusted pointer input. */
     drag(target: BrowserLocatorInterface, options?: BrowserLocatorDragOptions): Promise<void>;
 }
 
@@ -1314,11 +1491,20 @@ export declare type BrowserMouseButton = 'left' | 'middle' | 'right' | 'back' |
 
 /** Provides mouse input operations bound to one frame target session. */
 export declare interface BrowserMouseInterface {
+    /** Moves the pointer to a point, carrying the pressed buttons. */
     move(point: BrowserPoint): Promise<void>;
+    /** Presses a button at the current point, adding it to the pressed mask. */
     down(button?: BrowserMouseButton, count?: number): Promise<void>;
+    /**
+     * Releases a button at the current point, dropping it from the mask even when the frame
+     * fails.
+     */
     up(button?: BrowserMouseButton, count?: number): Promise<void>;
+    /** Moves to the given point, presses, optionally delays, and releases. */
     click(point: BrowserPoint, options?: BrowserClickOptions): Promise<void>;
+    /** Presses at the start, moves in the requested steps to the end, and releases. */
     drag(start: BrowserPoint, end: BrowserPoint, options?: BrowserDragOptions): Promise<void>;
+    /** Sends a wheel delta at the current point. */
     wheel(delta: BrowserPoint): Promise<void>;
 }
 
@@ -1343,7 +1529,15 @@ export declare class BrowserNavigationManager implements BrowserNavigationManage
 
 /** Provides URL and in-page predicate waits associated with one page. */
 export declare interface BrowserNavigationManagerInterface {
+    /**
+     * Resolves with the URL of the next navigation matching the `*` and `**` glob pattern.
+     * Rejects on timeout.
+     */
     wait(pattern: string, options?: BrowserNavigationWaitOptions): Promise<string>;
+    /**
+     * Polls an expression in the page until it returns a truthy value, and resolves with that
+     * value.
+     */
     until(expression: string, options?: BrowserNavigationWaitOptions): Promise<unknown>;
 }
 
@@ -1428,15 +1622,25 @@ export declare class BrowserNetworkManager implements BrowserNetworkManagerInter
 export declare interface BrowserNetworkManagerInterface {
     readonly emitter: EmitterInterface<BrowserNetworkEventMap>;
     readonly har: BrowserHARManagerInterface;
+    /** Enables the Network domain and subscribes to its events. Idempotent. */
     start(): Promise<void>;
+    /** Reads one observed response body as bytes. */
     body(id: string): Promise<Uint8Array>;
+    /** Reads one observed response body as text. */
     text(id: string): Promise<string>;
+    /** Reads one observed response body as parsed JSON. */
     json(id: string): Promise<unknown>;
+    /** Intercepts requests matching the query and hands each one to the handler. */
     route(query: BrowserRouteQuery, handler: BrowserRouteHandler): Promise<void>;
+    /** Removes one handler's routes, or every route when given none. */
     unroute(handler?: BrowserRouteHandler): Promise<void>;
+    /** Applies extra HTTP headers to every request the page makes. */
     headers(headers: Readonly<Record<string, string>>): Promise<void>;
+    /** Emulates an offline connection, or restores connectivity. */
     offline(offline: boolean): Promise<void>;
+    /** Applies HTTP basic-auth credentials, or clears them when given none. */
     credentials(credentials?: BrowserCredentials): Promise<void>;
+    /** Removes every route, unsubscribes, and disables the domains this manager enabled. */
     destroy(): Promise<void>;
 }
 
@@ -1570,7 +1774,8 @@ export declare type BrowserPageEventMap = {
 };
 
 /**
- * Abstracts a single top-level browser page.
+ * Abstracts a single top-level browser page, extending `BrowserFrameInterface` with
+ * navigation, screenshots, frame discovery, DOM snapshots, codegen, and target teardown.
  *
  * @remarks
  * Inherits every {@link BrowserFrameInterface} document operation for the
@@ -1597,22 +1802,47 @@ export declare interface BrowserPageInterface extends BrowserFrameInterface {
     readonly opener: BrowserPageInterface | undefined;
     readonly target: string;
     readonly closed: boolean;
+    /**
+     * Goes to a URL, waits for the requested load condition, and returns the final URL with
+     * its response correlation.
+     */
     navigate(url: string, options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    /** Reloads the page and returns the final URL with its response correlation. */
     reload(options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    /**
+     * Navigates to the previous history entry, or returns the unchanged URL when none exists.
+     */
     back(options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    /**
+     * Navigates to the next history entry, or returns the unchanged URL when none exists.
+     */
     forward(options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    /**
+     * Captures PNG or JPEG bytes, optionally full-page and persisted through an injected
+     * writer.
+     */
     screenshot(options?: BrowserScreenshotOptions): Promise<BrowserScreenshotResult>;
+    /** Prints the page to PDF bytes, optionally persisted through the injected writer. */
     pdf(options?: BrowserPDFOptions): Promise<BrowserPDFResult>;
+    /** Looks up a first-class frame by name or URL. */
     frame(name: string): Promise<BrowserFrameInterface | undefined>;
+    /** Decodes the flattened frame tree, main frame first. */
     frames(): Promise<readonly BrowserFrameInterface[]>;
+    /**
+     * Captures and decodes every attached document, shadow root, template content, layout box,
+     * and requested computed style.
+     */
     snapshot(options?: BrowserSnapshotOptions): Promise<BrowserSnapshotInterface>;
+    /** Starts the action recorder, or returns the running one. */
     codegen(options?: BrowserCodegenOptions): Promise<BrowserCodegenInterface>;
+    /** Releases local resources and detaches without closing the remote target. */
     destroy(): Promise<void>;
+    /** Closes the remote target and releases its resources. */
     close(): Promise<void>;
 }
 
 /**
- * Describes the options for creating a browser page.
+ * Describes the options for creating a `BrowserPage` instance.
  *
  * @remarks
  * - `on` — initial event listeners wired at construction
@@ -1688,6 +1918,7 @@ export declare class BrowserPerformance implements BrowserPerformanceInterface {
  * is {@link BrowserProfilerInterface}, its peer under `diagnostics`.
  */
 export declare interface BrowserPerformanceInterface {
+    /** Enables the domain, reads every metric, and disables the domain again. */
     metrics(): Promise<readonly BrowserMetric[]>;
 }
 
@@ -1713,8 +1944,11 @@ export declare class BrowserPermissionManager implements BrowserPermissionManage
 
 /** Provides permission override operations scoped to one browser context. */
 export declare interface BrowserPermissionManagerInterface {
+    /** Grants each named permission, optionally for one origin, as its own CDP frame. */
     grant(permissions: readonly string[], origin?: string): Promise<void>;
+    /** Denies each named permission, optionally for one origin, as its own CDP frame. */
     deny(permissions: readonly string[], origin?: string): Promise<void>;
+    /** Resets every permission override on the context. */
     clear(): Promise<void>;
 }
 
@@ -1784,8 +2018,16 @@ export declare class BrowserProfiler implements BrowserProfilerInterface {
 /** Drives the sampled CPU profile lifecycle. */
 export declare interface BrowserProfilerInterface {
     readonly active: boolean;
+    /**
+     * Begins sampling, optionally at an explicit positive integer interval in microseconds.
+     */
     start(interval?: number): Promise<void>;
+    /** Ends sampling and decodes the profile's nodes, samples, and time deltas. */
     stop(): Promise<BrowserProfile>;
+    /**
+     * Stops an active profiler, discarding any failure, and does nothing when no profile is
+     * running.
+     */
     destroy(): Promise<void>;
 }
 
@@ -1859,8 +2101,9 @@ export declare interface BrowserResponse {
 }
 
 /**
- * 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`.
  */
 export declare class BrowserResultLimitError extends BrowserError {
     constructor(message: string, context?: Readonly<Record<string, unknown>>);
@@ -1902,8 +2145,15 @@ export declare interface BrowserRouteInterface {
     readonly id: string;
     readonly request: BrowserRequest;
     readonly handled: boolean;
+    /** Fails the request with a Chromium error reason, `'Failed'` by default. */
     abort(reason?: string): Promise<void>;
+    /**
+     * Lets the request proceed, optionally overriding its URL, method, headers, or post body.
+     */
     continue(options?: BrowserRouteContinueOptions): Promise<void>;
+    /**
+     * Answers the request locally. Throws when the status is not an integer from 100 to 999.
+     */
     fulfill(options: BrowserRouteFulfillOptions): Promise<void>;
 }
 
@@ -2000,10 +2250,15 @@ export declare class BrowserScriptManager implements BrowserScriptManagerInterfa
 
 /** Manages initialization scripts and host bindings for one page. */
 export declare interface BrowserScriptManagerInterface {
+    /** Installs a script evaluated on every new document, and returns its identifier. */
     add(source: string): Promise<string>;
+    /** Removes one installed script by identifier. */
     remove(id: string): Promise<void>;
+    /** Binds a host function to a page-global name, callable from page JavaScript. */
     expose(name: string, handler: BrowserBindingHandler): Promise<void>;
+    /** Removes one exposed binding and its installed bridge script. */
     revoke(name: string): Promise<void>;
+    /** Removes every installed script and binding this manager owns. */
     destroy(): Promise<void>;
 }
 
@@ -2024,7 +2279,8 @@ export declare interface BrowserSecurity {
 export declare type BrowserSelector = 'css' | 'role' | 'text' | 'label' | 'placeholder' | 'testId';
 
 /**
- * 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`.
  */
 export declare class BrowserSelectorError extends BrowserError {
     constructor(message: string, context?: Readonly<Record<string, unknown>>);
@@ -2057,11 +2313,17 @@ export declare class BrowserSelectorManager implements BrowserSelectorManagerInt
  * Groups the locator factories by selector semantics.
  */
 export declare interface BrowserSelectorManagerInterface {
+    /** Locates by CSS selector. */
     css(value: string): BrowserLocatorInterface;
+    /** Locates by ARIA role, optionally by accessible name and exactness. */
     role(value: string, options?: BrowserRoleOptions): BrowserLocatorInterface;
+    /** Locates by rendered text, optionally exact. */
     text(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
+    /** Locates a labelled control by its label text, optionally exact. */
     label(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
+    /** Locates an input by its placeholder text, optionally exact. */
     placeholder(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
+    /** Locates by the test-id attribute. */
     testId(value: string): BrowserLocatorInterface;
 }
 
@@ -2115,26 +2377,70 @@ export declare class BrowserSnapshot implements BrowserSnapshotInterface {
     path(node: BrowserNode): string;
 }
 
-/** Describes the serializable input for a navigable browser snapshot. */
+/**
+ * Describes the serializable input for a navigable browser snapshot — the form a
+ * `BrowserSnapshot` is built from and serializes back to.
+ */
 export declare interface BrowserSnapshotInput {
     readonly documents: readonly BrowserDocument[];
     readonly styles: readonly string[];
 }
 
-/** Represents a navigable, serializable snapshot of every document attached to a page. */
+/**
+ * Represents a navigable, serializable snapshot of every document attached to a page,
+ * extending `BrowserSnapshotInput` with walking, structural relationships, search, and path
+ * derivation over plain `BrowserNode` values.
+ */
 export declare interface BrowserSnapshotInterface extends BrowserSnapshotInput {
+    /**
+     * Traverses the whole capture, or one subtree when `root` is given and yielded first, in
+     * `'depth'` order by default or in `'breadth'` order. Visits each node exactly once.
+     */
     walk(options?: BrowserWalkOptions): Generator<BrowserNode, void, unknown>;
+    /** Traverses one node's subtree in depth-first order, excluding the node itself. */
     descendants(node: BrowserNode): Generator<BrowserNode, void, unknown>;
+    /** Resolves the captured document a node belongs to. */
     document(node: BrowserNode): BrowserDocument | undefined;
+    /**
+     * Returns the direct children of a node, entering a linked iframe's content document.
+     */
     children(node: BrowserNode): readonly BrowserNode[];
+    /**
+     * Returns the structural parent of a node, crossing a document boundary to the owning
+     * iframe.
+     */
     parent(node: BrowserNode): BrowserNode | undefined;
+    /**
+     * Returns the structural siblings of a node; `'preceding'` or `'following'` narrows to one
+     * side, and omitting the relation returns every sibling but the node itself.
+     */
     siblings(node: BrowserNode, relation?: BrowserSiblingRelation): readonly BrowserNode[];
+    /**
+     * Returns the ancestors of a node, nearest first, across document and iframe boundaries.
+     */
     ancestors(node: BrowserNode): readonly BrowserNode[];
+    /**
+     * Returns the nearest common ancestor of two nodes, counting each node as its own
+     * candidate.
+     */
     common(first: BrowserNode, second: BrowserNode): BrowserNode | undefined;
+    /**
+     * Returns the structural edge count between two nodes, or `undefined` when they share no
+     * ancestor.
+     */
     distance(first: BrowserNode, second: BrowserNode): number | undefined;
+    /** Returns the first node matching a `BrowserNodeQuery` or a `BrowserNodePredicate`. */
     find(query: BrowserNodeQuery | BrowserNodePredicate): BrowserNode | undefined;
+    /**
+     * Returns every matching node, bounded by an optional `limit`; a negative or fractional
+     * limit throws a coded `BrowserError`.
+     */
     filter(query: BrowserNodeQuery | BrowserNodePredicate, limit?: number): readonly BrowserNode[];
+    /**
+     * Returns the nearest match from a node through its ancestors, testing the node first.
+     */
     closest(node: BrowserNode, query: BrowserNodeQuery | BrowserNodePredicate): BrowserNode | undefined;
+    /** Returns a deterministic frame-qualified structural path for one node. */
     path(node: BrowserNode): string;
 }
 
@@ -2191,8 +2497,11 @@ export declare class BrowserStorageManager implements BrowserStorageManagerInter
 
 /** Provides storage-state import, export, and clearing operations. */
 export declare interface BrowserStorageManagerInterface {
+    /** Reads the context cookies and the per-origin local and session storage. */
     state(options?: BrowserStorageOptions): Promise<BrowserStorageState>;
+    /** Writes a previously read state back into the context. */
     restore(state: BrowserStorageState): Promise<void>;
+    /** Drops the storage of one origin, or of every origin when given none. */
     clear(origin?: string): Promise<void>;
 }
 
@@ -2270,6 +2579,9 @@ export declare class BrowserTouch implements BrowserTouchInterface {
 
 /** Provides touch input operations bound to one frame target session. */
 export declare interface BrowserTouchInterface {
+    /**
+     * Dispatches a touch start at the point and a touch end, cancelling the touch on failure.
+     */
     tap(point: BrowserPoint): Promise<void>;
 }
 
@@ -2297,8 +2609,20 @@ export declare class BrowserTracing implements BrowserTracingInterface {
 /** Drives the trace capture lifecycle. */
 export declare interface BrowserTracingInterface {
     readonly active: boolean;
+    /**
+     * Begins tracing with the given categories. Throws a `BrowserError` when a trace is
+     * already active.
+     */
     start(options?: BrowserTracingOptions): Promise<void>;
+    /**
+     * Ends tracing, drains the IO stream, and writes it through the page writer when a path
+     * was set.
+     */
     stop(): Promise<BrowserTracingResult>;
+    /**
+     * Stops an active trace, discarding any failure, and does nothing when no trace is
+     * running.
+     */
     destroy(): Promise<void>;
 }
 
@@ -2357,6 +2681,10 @@ export declare type BrowserTransitionFunction<T> = () => Promise<T>;
  */
 export declare interface BrowserTransitionInterface<T> {
     readonly pending: Promise<T> | undefined;
+    /**
+     * Starts the work when nothing is in flight, and otherwise joins the running transition
+     * and returns its result.
+     */
     execute(work: BrowserTransitionFunction<T>): Promise<T>;
 }
 
@@ -2485,9 +2813,13 @@ export declare interface BrowserWorkerInterface {
     readonly id: string;
     readonly url: string;
     readonly category: BrowserWorkerCategory;
+    /** Evaluates a guarded expression in the worker and returns its value. */
     evaluate(expression: string, timeout?: number): Promise<unknown>;
+    /** Issues one CDP method call on the worker's session. */
     send(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
+    /** Stops driving the worker locally without closing its target. */
     detach(): void;
+    /** Closes the worker target, tolerating a worker that already terminated. Idempotent. */
     close(): Promise<void>;
 }
 
@@ -2500,6 +2832,7 @@ export declare interface BrowserWorkerInterface {
  * screenshot, PDF, trace, or HAR request carries a `path`.
  */
 export declare interface BrowserWriterInterface {
+    /** Persists the captured bytes to the given path, creating its parent directories. */
     write(path: string, data: Uint8Array): Promise<void>;
 }
 
@@ -2598,16 +2931,26 @@ export declare type CDPClientEventMap = {
 export declare interface CDPClientInterface {
     readonly emitter: EmitterInterface<CDPClientEventMap>;
     readonly connected: boolean;
+    /** Starts the transport and begins dispatching. Idempotent. */
     connect(): Promise<void>;
+    /** Closes the transport and re-establishes it. */
     reconnect(): Promise<void>;
+    /**
+     * Issues a CDP method call with optional params and a trailing `CDPSendOptions` carrying
+     * the `session` to scope it to and a per-call `timeout` overriding the client-wide
+     * default; rejects on timeout.
+     */
     send(method: string, params?: Readonly<Record<string, unknown>>, options?: CDPSendOptions): Promise<unknown>;
+    /** Registers a handler for a CDP event, optionally session-scoped. */
     subscribe(method: string, handler: CDPHandler, session?: string): void;
+    /** Removes a handler for a CDP event, optionally session-scoped. */
     unsubscribe(method: string, handler: CDPHandler, session?: string): void;
+    /** Tears down the transport and rejects every pending request. */
     close(): Promise<void>;
 }
 
 /**
- * Describes the options for creating a CDPClient.
+ * Describes the options for creating a `CDPClient` instance.
  *
  * @remarks
  * - `transport` — the text pipe the client sends/receives JSON-RPC frames over
@@ -2628,21 +2971,21 @@ export declare interface CDPClientOptions {
 }
 
 /**
- * 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`.
  */
 export declare class CDPConnectionError extends BrowserError {
     constructor(message: string, context?: Readonly<Record<string, unknown>>);
 }
 
 /**
- * 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.
  */
 export declare class CDPError extends BrowserError {
     constructor(message: string, context?: Readonly<Record<string, unknown>>);
@@ -2678,7 +3021,8 @@ export declare interface CDPTarget {
 }
 
 /**
- * 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`.
  */
 export declare class CDPTimeoutError extends BrowserError {
     constructor(message: string, context?: Readonly<Record<string, unknown>>);
@@ -2700,7 +3044,7 @@ export declare type CDPTransportEventMap = {
 };
 
 /**
- * Represents a dumb text transport CDPClient sends and receives JSON-RPC frames over.
+ * Represents the text pipe a `CDPClient` sends and receives JSON-RPC frames over.
  *
  * @remarks
  * The transport owns the connection (WebSocket, pipe, or any other duplex
@@ -2711,8 +3055,14 @@ export declare type CDPTransportEventMap = {
  */
 export declare interface CDPTransportInterface {
     readonly emitter: EmitterInterface<CDPTransportEventMap>;
+    /** Opens the underlying connection. */
     start(): Promise<void>;
+    /**
+     * Writes one raw text frame to the connection. Throws a coded `BrowserConnectionError`
+     * carrying the transport `url` when called before the connection opens or after it closes.
+     */
     send(data: string): Promise<void>;
+    /** Closes the underlying connection and releases its resources. */
     close(): Promise<void>;
 }
 
@@ -2776,7 +3126,7 @@ export declare function compileBrowserBindingSource(name: string): string;
 export declare function compileClickExpression(selector: string, strict: boolean): string;
 
 /**
- * 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
@@ -2826,9 +3176,9 @@ export declare function compileFillExpression(selector: string, value: string, s
 export declare function compileFunctionWaitExpression(expression: string, timeout: number): string;
 
 /**
- * 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
@@ -2946,7 +3296,7 @@ export declare function compileVisibleWaitExpression(selector: string, strict: b
 /**
  * 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
  */
 export declare function computeBrowserButtons(buttons: readonly BrowserMouseButton[]): number;
@@ -2987,7 +3337,7 @@ export declare function cookieToProtocol(cookie: BrowserCookieInput): Readonly<R
 export declare function createBrowserHAREntry(pending: BrowserHARPending, duration: number, body?: Uint8Array, error?: string): BrowserHAREntry;
 
 /**
- * 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}
@@ -3003,7 +3353,7 @@ export declare function createBrowserHAREntry(pending: BrowserHARPending, durati
 export declare function createBrowserSnapshot(input: BrowserSnapshotInput): BrowserSnapshotInterface;
 
 /**
- * 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}
@@ -3045,7 +3395,8 @@ export declare function decodeBase64(text: string): Uint8Array;
 export declare function encodeBase64(bytes: Uint8Array): string;
 
 /**
- * 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
@@ -3054,7 +3405,7 @@ export declare function encodeBase64(bytes: Uint8Array): string;
 export declare function extractBrowserChord(value: string): BrowserChord;
 
 /**
- * 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
@@ -3062,7 +3413,7 @@ export declare function extractBrowserChord(value: string): BrowserChord;
 export declare function isBrowserError(value: unknown): value is BrowserError;
 
 /**
- * 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
@@ -3086,7 +3437,7 @@ export declare function isBrowserNodeQuery(value: BrowserNodeQuery | BrowserNode
 export declare function isBrowserNodeVisible(node: BrowserNode): boolean;
 
 /**
- * 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
@@ -3094,7 +3445,7 @@ export declare function isBrowserNodeVisible(node: BrowserNode): boolean;
 export declare function isBrowserResultLimitError(value: unknown): value is BrowserResultLimitError;
 
 /**
- * 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
@@ -3102,7 +3453,7 @@ export declare function isBrowserResultLimitError(value: unknown): value is Brow
 export declare function isBrowserSelectorError(value: unknown): value is BrowserSelectorError;
 
 /**
- * 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
@@ -3110,7 +3461,7 @@ export declare function isBrowserSelectorError(value: unknown): value is Browser
 export declare function isCDPConnectionError(value: unknown): value is CDPConnectionError;
 
 /**
- * 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
@@ -3118,7 +3469,7 @@ export declare function isCDPConnectionError(value: unknown): value is CDPConnec
 export declare function isCDPError(value: unknown): value is CDPError;
 
 /**
- * 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
@@ -3178,13 +3529,12 @@ export declare function matchesBrowserURL(url: string, pattern: string): boolean
 export declare function mediaToFeatures(media: BrowserMedia): ReadonlyArray<Readonly<Record<string, string>>>;
 
 /**
- * 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
@@ -3255,8 +3605,7 @@ export declare function parseBrowserDownloadStart(value: unknown): BrowserDownlo
 export declare function parseBrowserPageError(value: unknown): BrowserPageError | undefined;
 
 /**
- * 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
@@ -3356,8 +3705,8 @@ export declare function parseBrowserWebSocketFrame(value: unknown): BrowserWebSo
 export declare function parseCodegenActionPayload(payload: unknown): BrowserCodegenAction | undefined;
 
 /**
- * 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
@@ -3388,7 +3737,8 @@ export declare function parseNumberArray(value: unknown): readonly number[] | un
 export declare function parseSnapshotString(strings: readonly string[], index: unknown): string | undefined;
 
 /**
- * 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
@@ -3396,7 +3746,7 @@ export declare function parseSnapshotString(strings: readonly string[], index: u
 export declare function readBrowserAccessibility(value: unknown): BrowserAccessibilitySnapshot;
 
 /**
- * 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
@@ -3405,7 +3755,7 @@ export declare function readBrowserAccessibility(value: unknown): BrowserAccessi
 export declare function readBrowserAttributes(value: unknown, strings: readonly string[]): Readonly<Record<string, string>>;
 
 /**
- * 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
@@ -3413,7 +3763,7 @@ export declare function readBrowserAttributes(value: unknown, strings: readonly
 export declare function readBrowserAXValue(value: unknown): unknown;
 
 /**
- * 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
@@ -3422,7 +3772,7 @@ export declare function readBrowserAXValue(value: unknown): unknown;
 export declare function readBrowserCookie(value: unknown, index: number): BrowserCookie;
 
 /**
- * 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
@@ -3430,7 +3780,7 @@ export declare function readBrowserCookie(value: unknown, index: number): Browse
 export declare function readBrowserCookies(value: unknown): readonly BrowserCookie[];
 
 /**
- * Decodes coverage ranges.
+ * Decodes and normalizes coverage ranges, throwing a `BrowserError` off-shape.
  *
  * @param value - Unknown ranges
  * @param script - Script index for diagnostics
@@ -3439,7 +3789,8 @@ export declare function readBrowserCookies(value: unknown): readonly BrowserCook
 export declare function readBrowserCoverageRanges(value: unknown, script: number): readonly BrowserCoverageRange[];
 
 /**
- * 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
@@ -3447,7 +3798,8 @@ export declare function readBrowserCoverageRanges(value: unknown, script: number
 export declare function readBrowserFrames(value: unknown): readonly BrowserFrameInfo[];
 
 /**
- * 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
@@ -3455,7 +3807,7 @@ export declare function readBrowserFrames(value: unknown): readonly BrowserFrame
 export declare function readBrowserHeaders(value: unknown): Readonly<Record<string, string>>;
 
 /**
- * Decodes Performance-domain metrics.
+ * Decodes Performance-domain metrics, throwing a `BrowserError` off-shape.
  *
  * @param value - Unknown metrics result
  * @returns Valid metrics
@@ -3463,7 +3815,7 @@ export declare function readBrowserHeaders(value: unknown): Readonly<Record<stri
 export declare function readBrowserMetrics(value: unknown): readonly BrowserMetric[];
 
 /**
- * Decodes one CPU profile.
+ * Decodes one CPU profile, throwing a `BrowserError` off-shape.
  *
  * @param value - Unknown `Profiler.stop` result
  * @returns Valid profile
@@ -3471,7 +3823,7 @@ export declare function readBrowserMetrics(value: unknown): readonly BrowserMetr
 export declare function readBrowserProfile(value: unknown): BrowserProfile;
 
 /**
- * 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
@@ -3480,7 +3832,8 @@ export declare function readBrowserProfile(value: unknown): BrowserProfile;
 export declare function readBrowserProfileFrame(value: unknown, node: number): BrowserProfileFrame;
 
 /**
- * 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
@@ -3488,7 +3841,8 @@ export declare function readBrowserProfileFrame(value: unknown, node: number): B
 export declare function readBrowserQuad(value: unknown): BrowserQuad;
 
 /**
- * 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
@@ -3496,7 +3850,7 @@ export declare function readBrowserQuad(value: unknown): BrowserQuad;
 export declare function readBrowserRemoteValue(value: unknown): unknown;
 
 /**
- * Decodes JavaScript precise coverage.
+ * Decodes JavaScript precise coverage, throwing a `BrowserError` off-shape.
  *
  * @param value - Unknown `Profiler.takePreciseCoverage` result
  * @returns Script coverage
@@ -3504,7 +3858,8 @@ export declare function readBrowserRemoteValue(value: unknown): unknown;
 export declare function readBrowserScriptCoverage(value: unknown): readonly BrowserScriptCoverage[];
 
 /**
- * Decodes the `Page.addScriptToEvaluateOnNewDocument` result.
+ * Decodes the `Page.addScriptToEvaluateOnNewDocument` result, throwing a `BrowserError`
+ * off-shape.
  *
  * @param value - Unknown protocol result
  * @returns Script identifier
@@ -3512,7 +3867,9 @@ export declare function readBrowserScriptCoverage(value: unknown): readonly Brow
 export declare function readBrowserScriptIdentifier(value: unknown): string;
 
 /**
- * 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
@@ -3522,7 +3879,7 @@ export declare function readBrowserScriptIdentifier(value: unknown): string;
 export declare function readBrowserSnapshot(value: unknown, styles?: readonly string[], limit?: number): BrowserSnapshotInput;
 
 /**
- * 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
@@ -3530,7 +3887,7 @@ export declare function readBrowserSnapshot(value: unknown, styles?: readonly st
 export declare function readBrowserStack(value: unknown): readonly BrowserStackFrame[];
 
 /**
- * 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
@@ -3540,7 +3897,7 @@ export declare function readBrowserStack(value: unknown): readonly BrowserStackF
 export declare function readBrowserStorageEntries(value: unknown, origin: string, storage: 'local' | 'session'): readonly BrowserStorageEntry[];
 
 /**
- * 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
@@ -3549,7 +3906,7 @@ export declare function readBrowserStorageEntries(value: unknown, origin: string
 export declare function readBrowserStorageOrigin(value: unknown, origin: string): BrowserStorageOrigin;
 
 /**
- * Decodes one `IO.read` response.
+ * Decodes one `IO.read` response, throwing a `BrowserError` off-shape.
  *
  * @param value - Unknown protocol result
  * @returns Valid stream chunk
@@ -3557,7 +3914,7 @@ export declare function readBrowserStorageOrigin(value: unknown, origin: string)
 export declare function readBrowserStreamChunk(value: unknown): BrowserStreamChunk;
 
 /**
- * Decodes CSS rule usage.
+ * Decodes CSS rule usage, throwing a `BrowserError` off-shape.
  *
  * @param value - Unknown `CSS.stopRuleUsageTracking` result
  * @returns Stylesheet coverage
@@ -3565,7 +3922,8 @@ export declare function readBrowserStreamChunk(value: unknown): BrowserStreamChu
 export declare function readBrowserStyleCoverage(value: unknown): readonly BrowserStyleCoverage[];
 
 /**
- * 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
@@ -3573,7 +3931,8 @@ export declare function readBrowserStyleCoverage(value: unknown): readonly Brows
 export declare function readEvaluationResult(value: unknown): unknown;
 
 /**
- * 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
@@ -3581,7 +3940,8 @@ export declare function readEvaluationResult(value: unknown): unknown;
 export declare function readRareBooleanData(value: unknown): ReadonlySet<number>;
 
 /**
- * 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
@@ -3589,7 +3949,8 @@ export declare function readRareBooleanData(value: unknown): ReadonlySet<number>
 export declare function readRareIntegerData(value: unknown): ReadonlyMap<number, number>;
 
 /**
- * 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
@@ -3666,7 +4027,7 @@ export declare function validateBrowserEmulationOptions(options: BrowserEmulatio
 export declare function validateBrowserHAR(value: unknown): asserts value is BrowserHAR;
 
 /**
- * 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