@orkestrel/browser 0.0.14 → 0.0.15

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

@@ -2,26 +2,17 @@ import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 
-/**
- * Read one captured node attribute.
- *
- * @param node - Captured browser node
- * @param name - Attribute name
- * @returns Attribute value, or undefined
- */
-export declare function attributeOfBrowserNode(node: BrowserNode, name: string): string | undefined;
-
-/** Base64 alphabet, index-ordered, used to build {@link BASE64_LOOKUP}. */
+/** Holds the index-ordered base64 alphabet used to build {@link BASE64_LOOKUP}. */
 export declare const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 
-/** Base64 character to 6-bit value lookup table, derived from {@link BASE64_CHARS}. */
+/** Maps each base64 character to its 6-bit value, derived from {@link BASE64_CHARS}. */
 export declare const BASE64_LOOKUP: Readonly<Record<string, number>>;
 
-/** Name of the CDP runtime binding the codegen recorder script calls into. */
+/** Names the CDP runtime binding the codegen recorder script calls into. */
 export declare const BROWSER_CODEGEN_BINDING_NAME = "__orkestrelBrowserCodegen";
 
 /**
- * In-page recorder script injected via `Page.addScriptToEvaluateOnNewDocument`
+ * Holds the in-page recorder script injected through `Page.addScriptToEvaluateOnNewDocument`
  * and `Runtime.evaluate`.
  *
  * @remarks
@@ -34,32 +25,39 @@ export declare const BROWSER_CODEGEN_BINDING_NAME = "__orkestrelBrowserCodegen";
  */
 export declare const BROWSER_CODEGEN_SOURCE: string;
 
-/** Default timeout in milliseconds for browser connection, requests, and navigation. */
+/** Sets the default timeout in milliseconds for browser connection, requests, and navigation. */
 export declare const BROWSER_DEFAULT_TIMEOUT_MS = 30000;
 
-/** Default viewport height in pixels. */
+/** Sets the default viewport height in pixels. */
 export declare const BROWSER_DEFAULT_VIEWPORT_HEIGHT = 720;
 
-/** Default viewport width in pixels. */
+/** Sets the default viewport width in pixels. */
 export declare const BROWSER_DEFAULT_VIEWPORT_WIDTH = 1280;
 
-/** Isolated-world name used for iframe evaluation. */
+/** Names the isolated world used for iframe evaluation. */
 export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
 
-/** Tool identity embedded in HAR 1.2 documents. */
+/**
+ * Names the tool identity embedded in HAR 1.2 documents.
+ *
+ * @remarks
+ * `version` is this package's own released version. A parity test in
+ * `tests/src/core/BrowserHARManager.test.ts` compares it against the manifest,
+ * so the archive stamp cannot drift away from the release that wrote it.
+ */
 export declare const BROWSER_HAR_CREATOR: Readonly<{
     name: "@orkestrel/browser";
-    version: "0.0.11";
+    version: "0.0.15";
 }>;
 
-/** CDP Input modifier bit values keyed by canonical key name. */
+/** Maps a canonical modifier name to its CDP Input modifier bit value. */
 export declare const BROWSER_KEY_MODIFIERS: Readonly<Record<string, number>>;
 
-/** CDP Input pressed-button bit values keyed by public mouse button. */
+/** Maps each public mouse button to its CDP Input pressed-button bit value. */
 export declare const BROWSER_MOUSE_BUTTON_MASKS: Readonly<Record<BrowserMouseButton, number>>;
 
 /**
- * Maximum serialized-character length for an `evaluate()`/`content()` result,
+ * Caps the serialized-character length for an `evaluate()`/`content()` result,
  * enforced IN-PAGE before the result is returned to CDP.
  *
  * @remarks
@@ -89,7 +87,7 @@ export declare const BROWSER_RESULT_LIMIT = 2500000;
 export declare const BROWSER_RESULT_LIMIT_PATTERN: RegExp;
 
 /**
- * Distinctive prefix for the in-page result-limit sentinel error, immediately
+ * Names the distinctive prefix for the in-page result-limit sentinel error, immediately
  * followed by the serialized length.
  *
  * @remarks
@@ -100,17 +98,17 @@ export declare const BROWSER_RESULT_LIMIT_PATTERN: RegExp;
  */
 export declare const BROWSER_RESULT_LIMIT_SENTINEL_PREFIX = "[[ORKESTREL_BROWSER_RESULT_LIMIT]]";
 
-/** Attribute used to tag temporary screenshot styles and masks. */
+/** Names the attribute that tags temporary screenshot styles and masks. */
 export declare const BROWSER_SCREENSHOT_ATTRIBUTE = "data-orkestrel-screenshot";
 
-/** Default maximum node count accepted from a decoded CDP DOM snapshot. */
+/** Sets the default maximum node count accepted from a decoded CDP DOM snapshot. */
 export declare const BROWSER_SNAPSHOT_NODE_LIMIT = 100000;
 
-/** Number of animation frames whose element bounds must agree before trusted input. */
+/** Sets the number of animation frames whose element bounds must agree before trusted input. */
 export declare const BROWSER_STABLE_FRAME_COUNT = 2;
 
 /**
- * Bound (in milliseconds) on the best-effort `Page.stopLoading` call issued
+ * Bounds (in milliseconds) the best-effort `Page.stopLoading` call issued
  * after a failed `navigate()`.
  *
  * @remarks
@@ -121,14 +119,33 @@ export declare const BROWSER_STABLE_FRAME_COUNT = 2;
  */
 export declare const BROWSER_STOP_LOADING_TIMEOUT_MS = 1000;
 
-/** Attribute used by the semantic test-id selector. */
+/** Names the attribute the semantic test-id selector uses. */
 export declare const BROWSER_TEST_ID_ATTRIBUTE = "data-testid";
 
-/** Poll interval in milliseconds while waiting for a selector to appear. */
+/**
+ * Holds the in-page visibility predicate source, over a `style` computed style and a
+ * `rect` bounding box already in scope at the interpolation site.
+ *
+ * @remarks
+ * Every compiled expression that decides whether an element is visible
+ * interpolates this one source, so what "visible" means has a single
+ * definition rather than one copy per compiler.
+ */
+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. */
 export declare const BROWSER_WAIT_POLL_INTERVAL_MS = 100;
 
 /**
- * Chromium Accessibility-domain snapshots for one page.
+ * Captures Chromium Accessibility-domain snapshots for one page.
+ *
+ * @example
+ * ```ts
+ * import { BrowserAccessibility } from '@orkestrel/browser'
+ *
+ * const accessibility = new BrowserAccessibility(page)
+ * const tree = await accessibility.snapshot({ depth: 3 }) // { roots, nodes }
+ * ```
  */
 export declare class BrowserAccessibility implements BrowserAccessibilityInterface {
     #private;
@@ -136,24 +153,24 @@ export declare class BrowserAccessibility implements BrowserAccessibilityInterfa
     snapshot(options?: BrowserAccessibilityOptions): Promise<BrowserAccessibilitySnapshot>;
 }
 
-/** Accessibility tree inspection. */
+/** Inspects the accessibility tree. */
 export declare interface BrowserAccessibilityInterface {
     snapshot(options?: BrowserAccessibilityOptions): Promise<BrowserAccessibilitySnapshot>;
 }
 
-/** Accessibility snapshot options. */
+/** Describes the options for an accessibility snapshot. */
 export declare interface BrowserAccessibilityOptions {
     readonly root?: number;
     readonly depth?: number;
 }
 
-/** Serializable accessibility-tree snapshot. */
+/** Describes a serializable accessibility-tree snapshot. */
 export declare interface BrowserAccessibilitySnapshot {
     readonly roots: readonly string[];
     readonly nodes: readonly BrowserAXNode[];
 }
 
-/** Actionability checks performed before locator input. */
+/** Describes the actionability checks performed before locator input. */
 export declare interface BrowserActionabilityOptions {
     readonly visible?: boolean;
     readonly stable?: boolean;
@@ -164,24 +181,22 @@ export declare interface BrowserActionabilityOptions {
 }
 
 /**
- * Options for element interaction (click, fill, select, wait).
+ * Describes the options for element interaction (click, fill, select, wait).
  *
  * @remarks
  * - `timeout` — maximum time to wait for the selector in milliseconds
+ * - `strict` — require the selector to resolve to exactly one element
+ * - `force` — skip the actionability checks
+ * - `trial` — run the checks and stop before dispatching input
  */
 export declare interface BrowserActionOptions {
     readonly timeout?: number;
     readonly strict?: boolean;
     readonly force?: boolean;
     readonly trial?: boolean;
-    readonly delay?: number;
-    readonly button?: BrowserMouseButton;
-    readonly count?: number;
-    readonly position?: BrowserPoint;
-    readonly steps?: number;
 }
 
-/** One decoded Chromium accessibility node. */
+/** Represents one decoded Chromium accessibility node. */
 export declare interface BrowserAXNode {
     readonly id: string;
     readonly parent: string | undefined;
@@ -196,7 +211,7 @@ export declare interface BrowserAXNode {
     readonly properties: Readonly<Record<string, unknown>>;
 }
 
-/** Decoded page-to-host binding call. */
+/** Describes a decoded page-to-host binding call. */
 export declare interface BrowserBindingCall {
     readonly id: string;
     readonly name: string;
@@ -204,17 +219,39 @@ export declare interface BrowserBindingCall {
     readonly context: number;
 }
 
-/** Host function exposed into page JavaScript. */
+/** Runs a host function exposed into page JavaScript. */
 export declare type BrowserBindingHandler = (...args: unknown[]) => unknown | Promise<unknown>;
 
-/** Parsed keyboard chord. */
+/** Describes a parsed keyboard chord. */
 export declare interface BrowserChord {
     readonly modifiers: readonly string[];
     readonly key: string;
 }
 
 /**
- * Chromium virtual-time budget controls for deterministic page timers.
+ * Describes the options for a trusted mouse click.
+ *
+ * @remarks
+ * - `button` — pressed mouse button (default `'left'`)
+ * - `count` — click count reported to the page (default `1`)
+ */
+export declare interface BrowserClickOptions extends BrowserInputOptions {
+    readonly button?: BrowserMouseButton;
+    readonly count?: number;
+}
+
+/**
+ * Controls the Chromium virtual-time budget for deterministic page timers.
+ *
+ * @example
+ * ```ts
+ * import { BrowserClock } from '@orkestrel/browser'
+ *
+ * const clock = new BrowserClock(page)
+ * await clock.install(Date.UTC(2026, 0, 1))
+ * await clock.advance(5_000)
+ * await clock.uninstall()
+ * ```
  */
 export declare class BrowserClock implements BrowserClockInterface {
     #private;
@@ -227,7 +264,7 @@ export declare class BrowserClock implements BrowserClockInterface {
     uninstall(): Promise<void>;
 }
 
-/** Chromium virtual-time control for deterministic page timers. */
+/** Controls Chromium virtual time for deterministic page timers. */
 export declare interface BrowserClockInterface {
     readonly installed: boolean;
     install(time?: number): Promise<void>;
@@ -239,10 +276,20 @@ export declare interface BrowserClockInterface {
 
 /**
  * Records page navigation and form interactions and compiles replayable scripts.
+ *
+ * @example
+ * ```ts
+ * import { BrowserCodegen } from '@orkestrel/browser'
+ *
+ * const codegen = new BrowserCodegen(client, 'session-1')
+ * await codegen.start()
+ * const actions = await codegen.stop()
+ * const script = codegen.script({ language: 'typescript' })
+ * ```
  */
 export declare class BrowserCodegen implements BrowserCodegenInterface {
     #private;
-    constructor(client: CDPClientInterface, sessionId: string, options?: BrowserCodegenOptions);
+    constructor(client: CDPClientInterface, session: string, options?: BrowserCodegenOptions);
     get emitter(): EmitterInterface<BrowserCodegenEventMap>;
     get started(): boolean;
     start(): Promise<void>;
@@ -253,7 +300,7 @@ export declare class BrowserCodegen implements BrowserCodegenInterface {
     destroy(): Promise<void>;
 }
 
-/** One recorded browser action captured during a codegen session. */
+/** Represents one recorded browser action captured during a codegen session. */
 export declare type BrowserCodegenAction = {
     readonly action: 'navigate';
     readonly url: string;
@@ -271,7 +318,7 @@ export declare type BrowserCodegenAction = {
 };
 
 /**
- * Event map for a {@link BrowserCodegenInterface}.
+ * Maps the events a {@link BrowserCodegenInterface} emits.
  *
  * @remarks
  * - `start` — recording started
@@ -311,11 +358,11 @@ export declare interface BrowserCodegenInterface {
     destroy(): Promise<void>;
 }
 
-/** Target language for a compiled codegen script. */
+/** Names the target language for a compiled codegen script. */
 export declare type BrowserCodegenLanguage = 'javascript' | 'typescript';
 
 /**
- * Options for creating a BrowserCodegen recorder.
+ * Describes the options for creating a BrowserCodegen recorder.
  *
  * @remarks
  * - `on` — initial event listeners wired at construction
@@ -327,7 +374,7 @@ export declare interface BrowserCodegenOptions {
 }
 
 /**
- * Options for compiling recorded actions into a script.
+ * Describes the options for compiling recorded actions into a script.
  *
  * @remarks
  * - `language` — target output language (default `'javascript'`)
@@ -336,7 +383,7 @@ export declare interface BrowserCodegenScriptOptions {
     readonly language?: BrowserCodegenLanguage;
 }
 
-/** One console API call. */
+/** Represents one console API call. */
 export declare interface BrowserConsoleMessage {
     readonly level: string;
     readonly text: string;
@@ -346,7 +393,7 @@ export declare interface BrowserConsoleMessage {
 }
 
 /**
- * Result of page content extraction.
+ * Describes the result of page content extraction.
  *
  * @remarks
  * - `url` — current page URL after navigation
@@ -363,10 +410,19 @@ export declare interface BrowserContentResult {
 
 /**
  * Owns pages and shared state inside one Chromium browser context.
+ *
+ * @example
+ * ```ts
+ * import { BrowserContext } from '@orkestrel/browser'
+ *
+ * const context = new BrowserContext(client)
+ * const page = await context.create({ url: 'https://example.com' })
+ * await context.destroy()
+ * ```
  */
 export declare class BrowserContext implements BrowserContextInterface {
     #private;
-    constructor(client: CDPClientInterface, id?: string, viewport?: BrowserViewport, writer?: ScreenshotWriterInterface, emulation?: BrowserEmulationOptions, downloads?: BrowserDownloadOptions);
+    constructor(client: CDPClientInterface, id?: string, viewport?: BrowserViewport, writer?: BrowserWriterInterface, emulation?: BrowserEmulationOptions, downloads?: BrowserDownloadOptions, options?: BrowserContextOptions);
     get emitter(): EmitterInterface<BrowserContextEventMap>;
     get id(): string | undefined;
     get cookies(): BrowserCookieManagerInterface;
@@ -381,14 +437,14 @@ export declare class BrowserContext implements BrowserContextInterface {
     close(): Promise<void>;
 }
 
-/** Browser-context lifecycle events. */
+/** Maps the browser-context lifecycle events. */
 export declare type BrowserContextEventMap = {
     readonly page: readonly [page: BrowserPageInterface];
     readonly close: readonly [];
 };
 
 /**
- * Isolated browser session over a CDP browser context.
+ * Represents an isolated browser session over a CDP browser context.
  *
  * @remarks
  * Follows the manager accessor pattern:
@@ -416,15 +472,27 @@ export declare interface BrowserContextInterface {
     close(): Promise<void>;
 }
 
-/** Options for creating and configuring an isolated browser context. */
+/**
+ * Describes the options for creating and configuring an isolated browser context.
+ *
+ * @remarks
+ * - `on` — initial event listeners wired at construction
+ * - `error` — observer error handler forwarded to the emitter
+ * - `proxy` — proxy server and bypass list for the context
+ * - `origins` — origins granted universal network access
+ * - `downloads` — download policy for the context
+ * - `emulation` — emulation overrides inherited by every page of the context
+ */
 export declare interface BrowserContextOptions {
+    readonly on?: EmitterHooks<BrowserContextEventMap>;
+    readonly error?: EmitterErrorHandler;
     readonly proxy?: BrowserProxy;
     readonly origins?: readonly string[];
     readonly downloads?: BrowserDownloadOptions;
     readonly emulation?: BrowserEmulationOptions;
 }
 
-/** One cookie returned from a browser context. */
+/** Represents one cookie returned from a browser context. */
 export declare interface BrowserCookie {
     readonly name: string;
     readonly value: string;
@@ -437,14 +505,14 @@ export declare interface BrowserCookie {
     readonly partition: BrowserCookiePartition | undefined;
 }
 
-/** Optional narrowing criteria for clearing context cookies. */
+/** Describes optional narrowing criteria for clearing context cookies. */
 export declare interface BrowserCookieFilter {
     readonly name?: string;
     readonly domain?: string;
     readonly path?: string;
 }
 
-/** Input used to create or replace a browser cookie. */
+/** Describes the input used to create or replace a browser cookie. */
 export declare interface BrowserCookieInput {
     readonly name: string;
     readonly value: string;
@@ -460,31 +528,49 @@ export declare interface BrowserCookieInput {
 }
 
 /**
- * Cookie operations isolated to one browser context.
+ * Performs cookie operations isolated to one browser context.
+ *
+ * @example
+ * ```ts
+ * import { BrowserCookieManager } from '@orkestrel/browser'
+ *
+ * const cookies = new BrowserCookieManager(client)
+ * await cookies.set([{ name: 'session', value: 'value', url: 'https://example.com/' }])
+ * const current = await cookies.cookies(['https://example.com/'])
+ * ```
  */
 export declare class BrowserCookieManager implements BrowserCookieManagerInterface {
     #private;
     constructor(client: CDPClientInterface, context?: string);
-    list(urls?: readonly string[]): Promise<readonly BrowserCookie[]>;
+    cookies(urls?: readonly string[]): Promise<readonly BrowserCookie[]>;
     set(cookies: readonly BrowserCookieInput[]): Promise<void>;
     clear(filter?: BrowserCookieFilter): Promise<void>;
 }
 
-/** Cookie operations scoped to one browser context. */
+/** Provides cookie operations scoped to one browser context. */
 export declare interface BrowserCookieManagerInterface {
-    list(urls?: readonly string[]): Promise<readonly BrowserCookie[]>;
+    cookies(urls?: readonly string[]): Promise<readonly BrowserCookie[]>;
     set(cookies: readonly BrowserCookieInput[]): Promise<void>;
     clear(filter?: BrowserCookieFilter): Promise<void>;
 }
 
-/** Cookie partition key used by CHIPS-partitioned cookies. */
+/** Describes a cookie partition key used by CHIPS-partitioned cookies. */
 export declare interface BrowserCookiePartition {
     readonly site: string;
     readonly ancestor?: boolean;
 }
 
 /**
- * JavaScript precise coverage and CSS rule usage for one page target.
+ * Collects JavaScript precise coverage and CSS rule usage for one page target.
+ *
+ * @example
+ * ```ts
+ * import { BrowserCoverage } from '@orkestrel/browser'
+ *
+ * const coverage = new BrowserCoverage(page)
+ * await coverage.start({ javascript: true, css: true })
+ * const usage = await coverage.stop() // { scripts, styles }
+ * ```
  */
 export declare class BrowserCoverage implements BrowserCoverageInterface {
     #private;
@@ -495,7 +581,7 @@ export declare class BrowserCoverage implements BrowserCoverageInterface {
     destroy(): Promise<void>;
 }
 
-/** Coverage capture lifecycle. */
+/** Drives the coverage capture lifecycle. */
 export declare interface BrowserCoverageInterface {
     readonly active: boolean;
     start(options?: BrowserCoverageOptions): Promise<void>;
@@ -503,69 +589,67 @@ export declare interface BrowserCoverageInterface {
     destroy(): Promise<void>;
 }
 
-/** Coverage capture options. */
+/** Describes the options for a coverage capture. */
 export declare interface BrowserCoverageOptions {
     readonly javascript?: boolean;
     readonly css?: boolean;
     readonly detailed?: boolean;
 }
 
-/** Source range reported by JavaScript or CSS coverage. */
+/** Describes a source range reported by JavaScript or CSS coverage. */
 export declare interface BrowserCoverageRange {
     readonly start: number;
     readonly end: number;
     readonly count: number;
 }
 
-/** Combined JavaScript and CSS usage. */
+/** Describes combined JavaScript and CSS usage. */
 export declare interface BrowserCoverageResult {
     readonly scripts: readonly BrowserScriptCoverage[];
     readonly styles: readonly BrowserStyleCoverage[];
 }
 
-/** HTTP basic-auth credentials applied to context pages. */
+/** Describes the HTTP basic-auth credentials applied to context pages. */
 export declare interface BrowserCredentials {
     readonly username: string;
     readonly password: string;
 }
 
 /**
- * Diagnostic subentities grouped beneath one page.
+ * Groups the diagnostic subentities beneath one page.
+ *
+ * @example
+ * ```ts
+ * import { BrowserDiagnostics } from '@orkestrel/browser'
+ *
+ * const diagnostics = new BrowserDiagnostics(page)
+ * const metrics = await diagnostics.performance.metrics()
+ * await diagnostics.destroy()
+ * ```
  */
 export declare class BrowserDiagnostics implements BrowserDiagnosticsInterface {
     #private;
-    constructor(frame: BrowserFrameInterface, writer?: ScreenshotWriterInterface);
+    constructor(frame: BrowserFrameInterface, writer?: BrowserWriterInterface);
     get tracing(): BrowserTracingInterface;
     get coverage(): BrowserCoverageInterface;
     get performance(): BrowserPerformanceInterface;
+    get profiler(): BrowserProfilerInterface;
     destroy(): Promise<void>;
 }
 
-/** Diagnostics grouped by capability. */
+/** Groups the diagnostics by capability. */
 export declare interface BrowserDiagnosticsInterface {
     readonly tracing: BrowserTracingInterface;
     readonly coverage: BrowserCoverageInterface;
     readonly performance: BrowserPerformanceInterface;
+    readonly profiler: BrowserProfilerInterface;
     destroy(): Promise<void>;
 }
 
-/**
- * One JavaScript dialog awaiting a user decision.
- */
-export declare class BrowserDialog implements BrowserDialogInterface {
-    #private;
-    constructor(frame: BrowserFrameInterface, category: BrowserDialogCategory, message: string, value: string);
-    get category(): BrowserDialogCategory;
-    get message(): string;
-    get default(): string;
-    accept(value?: string): Promise<void>;
-    dismiss(): Promise<void>;
-}
-
-/** JavaScript dialog category reported by Chromium. */
+/** Names a JavaScript dialog category reported by Chromium. */
 export declare type BrowserDialogCategory = 'alert' | 'confirm' | 'prompt' | 'beforeunload';
 
-/** One active JavaScript dialog. */
+/** Represents one active JavaScript dialog. */
 export declare interface BrowserDialogInterface {
     readonly category: BrowserDialogCategory;
     readonly message: string;
@@ -574,7 +658,7 @@ export declare interface BrowserDialogInterface {
     dismiss(): Promise<void>;
 }
 
-/** One document captured in a CDP DOM snapshot. */
+/** Represents one document captured in a CDP DOM snapshot. */
 export declare interface BrowserDocument {
     readonly index: number;
     readonly frame: string;
@@ -586,32 +670,21 @@ export declare interface BrowserDocument {
     readonly height: number | undefined;
 }
 
-/**
- * One Chromium download and its progress lifecycle.
- */
-export declare class BrowserDownload implements BrowserDownloadInterface {
-    #private;
-    constructor(client: CDPClientInterface, id: string, url: string, name: string, context?: string);
-    get emitter(): EmitterInterface<BrowserDownloadEventMap>;
-    get id(): string;
-    get url(): string;
-    get name(): string;
-    get status(): BrowserDownloadStatus;
-    get received(): number;
-    get total(): number;
-    get path(): string | undefined;
-    cancel(): Promise<void>;
-    update(progress: BrowserDownloadProgress): void;
-}
-
-/** Download progress events. */
+/** Maps the download progress events. */
 export declare type BrowserDownloadEventMap = {
     readonly progress: readonly [received: number, total: number];
     readonly complete: readonly [path: string | undefined];
     readonly cancel: readonly [];
 };
 
-/** One context download tracked through Chromium's Browser domain. */
+/**
+ * Represents one context download tracked through Chromium's Browser domain.
+ *
+ * @remarks
+ * Progress arrives from the owning page, which drives the concrete
+ * `BrowserDownload`. `update` is on this contract because the class exposes
+ * exactly its interface methods.
+ */
 export declare interface BrowserDownloadInterface {
     readonly emitter: EmitterInterface<BrowserDownloadEventMap>;
     readonly id: string;
@@ -622,16 +695,17 @@ export declare interface BrowserDownloadInterface {
     readonly total: number;
     readonly path: string | undefined;
     cancel(): Promise<void>;
+    /** Records one step of the download's progress. The owning page drives it. */
     update(progress: BrowserDownloadProgress): void;
 }
 
-/** Download policy for a browser context. */
+/** Describes the download policy for a browser context. */
 export declare interface BrowserDownloadOptions {
     readonly path: string;
     readonly named?: boolean;
 }
 
-/** Protocol-neutral download progress update. */
+/** Describes a protocol-neutral download progress update. */
 export declare interface BrowserDownloadProgress {
     readonly status: BrowserDownloadStatus;
     readonly received: number;
@@ -639,7 +713,7 @@ export declare interface BrowserDownloadProgress {
     readonly path?: string;
 }
 
-/** Decoded `Browser.downloadWillBegin` event. */
+/** Describes a decoded `Browser.downloadWillBegin` event. */
 export declare interface BrowserDownloadStart {
     readonly id: string;
     readonly url: string;
@@ -647,28 +721,49 @@ export declare interface BrowserDownloadStart {
     readonly frame: string;
 }
 
-/** Download lifecycle phase. */
+/** Names a download lifecycle phase. */
 export declare type BrowserDownloadStatus = 'pending' | 'complete' | 'cancelled';
 
 /**
- * Rendering, identity, location, and network emulation for context pages.
+ * Describes the options for a trusted mouse drag.
+ *
+ * @remarks
+ * - `button` — pressed mouse button (default `'left'`)
+ * - `steps` — interpolated move events between start and end (default `10`)
+ */
+export declare interface BrowserDragOptions extends BrowserInputOptions {
+    readonly button?: BrowserMouseButton;
+    readonly steps?: number;
+}
+
+/**
+ * Applies rendering, identity, location, and network emulation for context pages.
+ *
+ * @example
+ * ```ts
+ * import { BrowserEmulationManager } from '@orkestrel/browser'
+ *
+ * const emulation = new BrowserEmulationManager(() => context.pages())
+ * await emulation.apply({ locale: 'en-US', media: { scheme: 'dark' } })
+ * await emulation.clear()
+ * ```
  */
 export declare class BrowserEmulationManager implements BrowserEmulationManagerInterface {
     #private;
-    constructor(pages: () => readonly BrowserPageInterface[], options?: BrowserEmulationOptions);
+    constructor(pages: BrowserPagesFunction, options?: BrowserEmulationOptions);
     apply(options: BrowserEmulationOptions): Promise<void>;
     clear(): Promise<void>;
     attach(page: BrowserPageInterface): Promise<void>;
 }
 
-/** Context-scoped emulation configuration. */
+/** Configures context-scoped emulation. */
 export declare interface BrowserEmulationManagerInterface {
     apply(options: BrowserEmulationOptions): Promise<void>;
     clear(): Promise<void>;
     attach(page: BrowserPageInterface): Promise<void>;
 }
 
-/** Network and rendering overrides inherited by context pages. */
+/** Describes network and rendering overrides inherited by context pages. */
 export declare interface BrowserEmulationOptions {
     readonly viewport?: BrowserViewport;
     readonly user?: BrowserUserAgent;
@@ -682,10 +777,10 @@ export declare interface BrowserEmulationOptions {
 }
 
 /**
- * Base error for all browser automation operations.
+ * Represents the base error for all browser automation operations.
  *
  * @remarks
- * Carries a machine-readable `code` and optional `context` (AGENTS §12) so
+ * Carries a machine-readable `code` and optional `context` so
  * callers can branch in a `catch` without parsing message strings.
  */
 export declare class BrowserError extends Error {
@@ -694,30 +789,24 @@ export declare class BrowserError extends Error {
     constructor(message: string, code?: string, context?: Readonly<Record<string, unknown>>);
 }
 
-/**
- * One intercepted file input selection.
- */
-export declare class BrowserFileChooser implements BrowserFileChooserInterface {
-    #private;
-    constructor(frame: BrowserFrameInterface, backend: number, multiple: boolean);
-    get multiple(): boolean;
-    upload(files: readonly string[]): Promise<void>;
-    cancel(): Promise<void>;
-}
-
-/** One intercepted file chooser. */
+/** Represents one intercepted file chooser. */
 export declare interface BrowserFileChooserInterface {
     readonly multiple: boolean;
     upload(files: readonly string[]): Promise<void>;
     cancel(): Promise<void>;
 }
 
-/** Options for filtering a locator. */
-export declare interface BrowserFilterOptions extends BrowserLocatorFilter {
-}
-
 /**
- * One attached document frame, evaluated through its own CDP execution world.
+ * Represents one attached document frame, evaluated through its own CDP execution world.
+ *
+ * @example
+ * ```ts
+ * import { BrowserFrame } from '@orkestrel/browser'
+ *
+ * const frame = new BrowserFrame(client, 'session-1', 'frame-1', 'https://example.com')
+ * await frame.fill('[name=email]', 'ada@example.com')
+ * const title = await frame.title()
+ * ```
  */
 export declare class BrowserFrame implements BrowserFrameInterface {
     #private;
@@ -739,7 +828,7 @@ export declare class BrowserFrame implements BrowserFrameInterface {
     evaluate(expression: string, timeout?: number): Promise<unknown>;
     handle(expression: string): Promise<BrowserHandleInterface>;
     wait(selector: string, options?: BrowserWaitOptions): Promise<void>;
-    send(method: string, params?: Readonly<Record<string, unknown>>, timeout?: number): Promise<unknown>;
+    send(method: string, params?: Readonly<Record<string, unknown>>, options?: BrowserSendOptions): Promise<unknown>;
     subscribe(method: string, handler: CDPHandler): Promise<void>;
     unsubscribe(method: string, handler: CDPHandler): Promise<void>;
     save(path: string, _bytes: Uint8Array): Promise<void>;
@@ -748,7 +837,7 @@ export declare class BrowserFrame implements BrowserFrameInterface {
 }
 
 /**
- * Serializable frame metadata decoded from CDP `Page.getFrameTree`.
+ * Describes serializable frame metadata decoded from CDP `Page.getFrameTree`.
  *
  * @remarks
  * - `id` — the frame's CDP frame id
@@ -764,7 +853,7 @@ export declare interface BrowserFrameInfo {
 }
 
 /**
- * Operations shared by a top-level page and an iframe document.
+ * Provides the operations shared by a top-level page and an iframe document.
  *
  * @remarks
  * - `id` — CDP frame id
@@ -801,7 +890,7 @@ export declare interface BrowserFrameInterface {
     evaluate(expression: string, timeout?: number): Promise<unknown>;
     handle(expression: string): Promise<BrowserHandleInterface>;
     wait(selector: string, options?: BrowserWaitOptions): Promise<void>;
-    send(method: string, params?: Readonly<Record<string, unknown>>, timeout?: number): Promise<unknown>;
+    send(method: string, params?: Readonly<Record<string, unknown>>, options?: BrowserSendOptions): Promise<unknown>;
     subscribe(method: string, handler: CDPHandler): Promise<void>;
     unsubscribe(method: string, handler: CDPHandler): Promise<void>;
     save(path: string, bytes: Uint8Array): Promise<void>;
@@ -809,14 +898,14 @@ export declare interface BrowserFrameInterface {
     update(url: string): void;
 }
 
-/** Function coverage inside one script. */
+/** Describes function coverage inside one script. */
 export declare interface BrowserFunctionCoverage {
     readonly name: string;
     readonly ranges: readonly BrowserCoverageRange[];
     readonly block: boolean;
 }
 
-/** Geographic location override. */
+/** Describes a geographic location override. */
 export declare interface BrowserGeolocation {
     readonly latitude: number;
     readonly longitude: number;
@@ -824,21 +913,7 @@ export declare interface BrowserGeolocation {
 }
 
 /**
- * One retained remote object in a frame execution context.
- */
-export declare class BrowserHandle implements BrowserHandleInterface {
-    #private;
-    constructor(client: CDPClientInterface, session: string, id: string);
-    get id(): string;
-    value(): Promise<unknown>;
-    call(declaration: string, args?: readonly unknown[]): Promise<unknown>;
-    property(name: string): Promise<BrowserHandleInterface | undefined>;
-    properties(): Promise<Readonly<Record<string, unknown>>>;
-    dispose(): Promise<void>;
-}
-
-/**
- * A remote JavaScript object retained in one frame execution context.
+ * Represents a remote JavaScript object retained in one frame execution context.
  */
 export declare interface BrowserHandleInterface {
     readonly id: string;
@@ -849,12 +924,12 @@ export declare interface BrowserHandleInterface {
     dispose(): Promise<void>;
 }
 
-/** Standards-shaped HAR 1.2 document produced by the network manager. */
+/** Describes the standards-shaped HAR 1.2 document produced by the network manager. */
 export declare interface BrowserHAR {
     readonly log: BrowserHARLog;
 }
 
-/** Response body metadata in an HTTP archive. */
+/** Describes response body metadata in an HTTP archive. */
 export declare interface BrowserHARContent {
     readonly size: number;
     readonly mimeType: string;
@@ -863,7 +938,7 @@ export declare interface BrowserHARContent {
 }
 
 /**
- * One cookie in an HTTP archive.
+ * Represents one cookie in an HTTP archive.
  *
  * @remarks
  * HAR data preserves the official HAR 1.2 JSON field names. These compound
@@ -878,13 +953,13 @@ export declare interface BrowserHARCookie extends BrowserHARValue {
     readonly secure?: boolean;
 }
 
-/** Tool identity embedded in an HTTP archive. */
+/** Describes the tool identity embedded in an HTTP archive. */
 export declare interface BrowserHARCreator {
     readonly name: string;
     readonly version: string;
 }
 
-/** One completed HTTP exchange in a HAR recording. */
+/** Represents one completed HTTP exchange in a HAR recording. */
 export declare interface BrowserHAREntry {
     readonly startedDateTime: string;
     readonly time: number;
@@ -895,14 +970,14 @@ export declare interface BrowserHAREntry {
 }
 
 /**
- * Convert HAR name/value headers into a Fetch-domain header record.
+ * Converts HAR name/value headers into a Fetch-domain header record.
  *
  * @param headers - HAR header entries
  * @returns Header record with later duplicate names replacing earlier values
  */
 export declare function browserHARHeadersToRecord(headers: readonly BrowserHARValue[]): Readonly<Record<string, string>>;
 
-/** HAR 1.2 log object. */
+/** Describes the HAR 1.2 log object. */
 export declare interface BrowserHARLog {
     readonly version: '1.2';
     readonly creator: BrowserHARCreator;
@@ -910,11 +985,20 @@ export declare interface BrowserHARLog {
 }
 
 /**
- * HTTP archive recording and replay over one page network manager.
+ * Records and replays HTTP archives over one page network manager.
+ *
+ * @example
+ * ```ts
+ * import { BrowserHARManager } from '@orkestrel/browser'
+ *
+ * const har = new BrowserHARManager(page.network)
+ * await har.start({ content: true })
+ * const archive = await har.stop() // { log: { version: '1.2', creator, entries } }
+ * ```
  */
 export declare class BrowserHARManager implements BrowserHARManagerInterface {
     #private;
-    constructor(network: BrowserNetworkManagerInterface, writer?: ScreenshotWriterInterface);
+    constructor(network: BrowserNetworkManagerInterface, writer?: BrowserWriterInterface);
     get recording(): boolean;
     start(options?: BrowserHAROptions): Promise<void>;
     stop(): Promise<BrowserHAR>;
@@ -922,7 +1006,7 @@ export declare class BrowserHARManager implements BrowserHARManagerInterface {
     clear(): Promise<void>;
 }
 
-/** HAR recording and replay operations. */
+/** Provides HAR recording and replay operations. */
 export declare interface BrowserHARManagerInterface {
     readonly recording: boolean;
     start(options?: BrowserHAROptions): Promise<void>;
@@ -931,31 +1015,31 @@ export declare interface BrowserHARManagerInterface {
     clear(): Promise<void>;
 }
 
-/** HAR recording options. */
+/** Describes the options for a HAR recording. */
 export declare interface BrowserHAROptions {
     readonly path?: string;
     readonly content?: boolean;
 }
 
-/** Mutable recording state held until a request finishes. */
+/** Holds recording state until a request finishes; a new value replaces it on each update. */
 export declare interface BrowserHARPending {
     readonly request: BrowserRequest;
     readonly started: number;
     readonly response: BrowserResponse | undefined;
 }
 
-/** Request body metadata in an HTTP archive. */
+/** Describes request body metadata in an HTTP archive. */
 export declare interface BrowserHARPost {
     readonly mimeType: string;
     readonly text: string;
 }
 
-/** HAR replay behavior. */
+/** Describes HAR replay behavior. */
 export declare interface BrowserHARReplayOptions {
     readonly fallback?: boolean;
 }
 
-/** HAR 1.2 request entry. */
+/** Describes a HAR 1.2 request entry. */
 export declare interface BrowserHARRequest {
     readonly method: string;
     readonly url: string;
@@ -968,7 +1052,7 @@ export declare interface BrowserHARRequest {
     readonly bodySize: number;
 }
 
-/** HAR 1.2 response entry. */
+/** Describes a HAR 1.2 response entry. */
 export declare interface BrowserHARResponse {
     readonly status: number;
     readonly statusText: string;
@@ -981,7 +1065,7 @@ export declare interface BrowserHARResponse {
     readonly bodySize: number;
 }
 
-/** HAR 1.2 phase timings in milliseconds. */
+/** Holds HAR 1.2 phase timings in milliseconds. */
 export declare interface BrowserHARTimings {
     readonly blocked: number;
     readonly dns: number;
@@ -992,21 +1076,31 @@ export declare interface BrowserHARTimings {
     readonly ssl: number;
 }
 
-/** One name/value pair in an HTTP archive. */
+/** Represents one name/value pair in an HTTP archive. */
 export declare interface BrowserHARValue {
     readonly name: string;
     readonly value: string;
 }
 
 /**
- * Convert a header record to Fetch-domain name/value entries.
+ * Converts a header record to Fetch-domain name/value entries.
  *
  * @param headers - Header record
  * @returns Protocol header entries
  */
 export declare function browserHeadersToProtocol(headers: Readonly<Record<string, string>>): ReadonlyArray<Readonly<Record<string, string>>>;
 
-/** Normalized CDP keyboard key data. */
+/**
+ * Describes the options shared by every trusted input operation.
+ *
+ * @remarks
+ * - `delay` — milliseconds between the transitions the operation dispatches
+ */
+export declare interface BrowserInputOptions {
+    readonly delay?: number;
+}
+
+/** Describes normalized CDP keyboard key data. */
 export declare interface BrowserKey {
     readonly key: string;
     readonly code: string;
@@ -1015,28 +1109,37 @@ export declare interface BrowserKey {
 }
 
 /**
- * Trusted keyboard input through Chromium's CDP Input domain.
+ * Sends trusted keyboard input through Chromium's CDP Input domain.
+ *
+ * @example
+ * ```ts
+ * import { BrowserKeyboard } from '@orkestrel/browser'
+ *
+ * const keyboard = new BrowserKeyboard(page)
+ * await keyboard.type('orkestrel', { delay: 10 })
+ * await keyboard.press('Control+Enter')
+ * ```
  */
 export declare class BrowserKeyboard implements BrowserKeyboardInterface {
     #private;
     constructor(frame: BrowserFrameInterface);
     down(value: string): Promise<void>;
     up(value: string): Promise<void>;
-    press(value: string, options?: BrowserActionOptions): Promise<void>;
-    type(value: string, options?: BrowserActionOptions): Promise<void>;
+    press(value: string, options?: BrowserInputOptions): Promise<void>;
+    type(value: string, options?: BrowserInputOptions): Promise<void>;
     insert(value: string): Promise<void>;
 }
 
-/** Keyboard input operations bound to one frame target session. */
+/** Provides keyboard input operations bound to one frame target session. */
 export declare interface BrowserKeyboardInterface {
     down(key: string): Promise<void>;
     up(key: string): Promise<void>;
-    press(key: string, options?: BrowserActionOptions): Promise<void>;
-    type(value: string, options?: BrowserActionOptions): Promise<void>;
+    press(key: string, options?: BrowserInputOptions): Promise<void>;
+    type(value: string, options?: BrowserInputOptions): Promise<void>;
     insert(value: string): Promise<void>;
 }
 
-/** Layout data associated with one captured DOM node. */
+/** Describes layout data associated with one captured DOM node. */
 export declare interface BrowserLayout {
     readonly bounds: BrowserRect | undefined;
     readonly styles: Readonly<Record<string, string>>;
@@ -1048,7 +1151,16 @@ export declare interface BrowserLayout {
 }
 
 /**
- * Reusable strict semantic locator over one frame.
+ * Represents a reusable strict semantic locator over one frame.
+ *
+ * @example
+ * ```ts
+ * import { BrowserLocator } from '@orkestrel/browser'
+ *
+ * const save = new BrowserLocator(page, { selector: 'role', value: 'button', name: 'Save' })
+ * await save.click({ count: 2 })
+ * const label = await save.text()
+ * ```
  */
 export declare class BrowserLocator implements BrowserLocatorInterface {
     #private;
@@ -1056,24 +1168,25 @@ export declare class BrowserLocator implements BrowserLocatorInterface {
     get frame(): BrowserFrameInterface;
     get query(): BrowserQuery;
     locator(selector: string): BrowserLocatorInterface;
-    filter(options: BrowserFilterOptions): BrowserLocatorInterface;
+    filter(options: BrowserLocatorFilter): BrowserLocatorInterface;
     first(): BrowserLocatorInterface;
     last(): BrowserLocatorInterface;
     item(index: number): BrowserLocatorInterface;
     count(): Promise<number>;
     all(): Promise<readonly BrowserLocatorInterface[]>;
-    click(options?: BrowserActionOptions): Promise<void>;
+    click(options?: BrowserLocatorClickOptions): Promise<void>;
     fill(value: string, options?: BrowserActionOptions): Promise<void>;
     select(values: readonly string[], options?: BrowserActionOptions): Promise<void>;
-    check(options?: BrowserActionOptions): Promise<void>;
-    uncheck(options?: BrowserActionOptions): Promise<void>;
-    hover(options?: BrowserActionOptions): Promise<void>;
+    check(options?: BrowserLocatorClickOptions): Promise<void>;
+    uncheck(options?: BrowserLocatorClickOptions): Promise<void>;
+    hover(options?: BrowserPointerOptions): Promise<void>;
     focus(options?: BrowserActionOptions): Promise<void>;
-    press(key: string, options?: BrowserActionOptions): Promise<void>;
-    type(value: string, options?: BrowserActionOptions): Promise<void>;
+    press(key: string, options?: BrowserLocatorTypeOptions): Promise<void>;
+    type(value: string, options?: BrowserLocatorTypeOptions): Promise<void>;
     clear(options?: BrowserActionOptions): Promise<void>;
     wait(options?: BrowserWaitOptions): Promise<void>;
-    text(options?: BrowserTextResultOptions): Promise<string | readonly string[]>;
+    text(): Promise<string>;
+    texts(): Promise<readonly string[]>;
     html(): Promise<string>;
     value(): Promise<string>;
     attribute(name: string): Promise<string | undefined>;
@@ -1082,10 +1195,18 @@ export declare class BrowserLocator implements BrowserLocatorInterface {
     editable(): Promise<boolean>;
     screenshot(options?: BrowserScreenshotOptions): Promise<BrowserScreenshotResult>;
     upload(options: BrowserUploadOptions): Promise<void>;
-    drag(target: BrowserLocatorInterface, options?: BrowserActionOptions): Promise<void>;
+    drag(target: BrowserLocatorInterface, options?: BrowserLocatorDragOptions): Promise<void>;
+}
+
+/** Describes the options for a locator click, combining element resolution with mouse input. */
+export declare interface BrowserLocatorClickOptions extends BrowserPointerOptions, BrowserClickOptions {
 }
 
-/** Declarative locator filter applied after selector resolution. */
+/** Describes the options for a locator drag, combining element resolution with mouse input. */
+export declare interface BrowserLocatorDragOptions extends BrowserPointerOptions, BrowserDragOptions {
+}
+
+/** Describes a declarative locator filter applied after selector resolution. */
 export declare interface BrowserLocatorFilter {
     readonly text?: string;
     readonly exact?: boolean;
@@ -1093,30 +1214,31 @@ export declare interface BrowserLocatorFilter {
 }
 
 /**
- * Reusable strict locator over one frame.
+ * Represents a reusable strict locator over one frame.
  */
 export declare interface BrowserLocatorInterface {
     readonly frame: BrowserFrameInterface;
     readonly query: BrowserQuery;
     locator(selector: string): BrowserLocatorInterface;
-    filter(options: BrowserFilterOptions): BrowserLocatorInterface;
+    filter(options: BrowserLocatorFilter): BrowserLocatorInterface;
     first(): BrowserLocatorInterface;
     last(): BrowserLocatorInterface;
     item(index: number): BrowserLocatorInterface;
     count(): Promise<number>;
     all(): Promise<readonly BrowserLocatorInterface[]>;
-    click(options?: BrowserActionOptions): Promise<void>;
+    click(options?: BrowserLocatorClickOptions): Promise<void>;
     fill(value: string, options?: BrowserActionOptions): Promise<void>;
     select(values: readonly string[], options?: BrowserActionOptions): Promise<void>;
-    check(options?: BrowserActionOptions): Promise<void>;
-    uncheck(options?: BrowserActionOptions): Promise<void>;
-    hover(options?: BrowserActionOptions): Promise<void>;
+    check(options?: BrowserLocatorClickOptions): Promise<void>;
+    uncheck(options?: BrowserLocatorClickOptions): Promise<void>;
+    hover(options?: BrowserPointerOptions): Promise<void>;
     focus(options?: BrowserActionOptions): Promise<void>;
-    press(key: string, options?: BrowserActionOptions): Promise<void>;
-    type(value: string, options?: BrowserActionOptions): Promise<void>;
+    press(key: string, options?: BrowserLocatorTypeOptions): Promise<void>;
+    type(value: string, options?: BrowserLocatorTypeOptions): Promise<void>;
     clear(options?: BrowserActionOptions): Promise<void>;
     wait(options?: BrowserWaitOptions): Promise<void>;
-    text(options?: BrowserTextResultOptions): Promise<string | readonly string[]>;
+    text(): Promise<string>;
+    texts(): Promise<readonly string[]>;
     html(): Promise<string>;
     value(): Promise<string>;
     attribute(name: string): Promise<string | undefined>;
@@ -1125,10 +1247,14 @@ export declare interface BrowserLocatorInterface {
     editable(): Promise<boolean>;
     screenshot(options?: BrowserScreenshotOptions): Promise<BrowserScreenshotResult>;
     upload(options: BrowserUploadOptions): Promise<void>;
-    drag(target: BrowserLocatorInterface, options?: BrowserActionOptions): Promise<void>;
+    drag(target: BrowserLocatorInterface, options?: BrowserLocatorDragOptions): Promise<void>;
+}
+
+/** Describes the options for locator keyboard entry, combining element resolution with key input. */
+export declare interface BrowserLocatorTypeOptions extends BrowserActionOptions, BrowserInputOptions {
 }
 
-/** Paper margin lengths accepted by Chromium print-to-PDF. */
+/** Describes the paper margin lengths accepted by Chromium print-to-PDF. */
 export declare interface BrowserMargin {
     readonly top?: number;
     readonly right?: number;
@@ -1136,23 +1262,41 @@ export declare interface BrowserMargin {
     readonly left?: number;
 }
 
-/** Browser color and media feature overrides. */
+/**
+ * Describes browser color and media feature overrides.
+ *
+ * @remarks
+ * - `output` — emulated output medium, mirroring the CSS `media` type
+ * - `scheme` — emulated `prefers-color-scheme` value
+ * - `contrast` — emulated `prefers-contrast` value
+ * - `motion` — emulated `prefers-reduced-motion` value
+ * - `colors` — emulated `forced-colors` value, keeping the CSS feature's word
+ */
 export declare interface BrowserMedia {
-    readonly media?: 'screen' | 'print';
-    readonly color?: 'light' | 'dark' | 'no-preference';
+    readonly output?: 'screen' | 'print';
+    readonly scheme?: 'light' | 'dark' | 'no-preference';
     readonly contrast?: 'more' | 'less' | 'no-preference';
     readonly motion?: 'reduce' | 'no-preference';
     readonly colors?: 'active' | 'none';
 }
 
-/** One Performance-domain metric. */
+/** Represents one Performance-domain metric. */
 export declare interface BrowserMetric {
     readonly name: string;
     readonly value: number;
 }
 
 /**
- * Trusted mouse input through Chromium's CDP Input domain.
+ * Sends trusted mouse input through Chromium's CDP Input domain.
+ *
+ * @example
+ * ```ts
+ * import { BrowserMouse } from '@orkestrel/browser'
+ *
+ * const mouse = new BrowserMouse(page)
+ * await mouse.click({ x: 50, y: 20 }, { button: 'left', count: 2 })
+ * await mouse.drag({ x: 10, y: 10 }, { x: 90, y: 90 }, { steps: 20 })
+ * ```
  */
 export declare class BrowserMouse implements BrowserMouseInterface {
     #private;
@@ -1160,26 +1304,35 @@ export declare class BrowserMouse implements BrowserMouseInterface {
     move(point: BrowserPoint): Promise<void>;
     down(button?: BrowserMouseButton, count?: number): Promise<void>;
     up(button?: BrowserMouseButton, count?: number): Promise<void>;
-    click(point: BrowserPoint, options?: BrowserActionOptions): Promise<void>;
-    drag(start: BrowserPoint, end: BrowserPoint, options?: BrowserActionOptions): Promise<void>;
+    click(point: BrowserPoint, options?: BrowserClickOptions): Promise<void>;
+    drag(start: BrowserPoint, end: BrowserPoint, options?: BrowserDragOptions): Promise<void>;
     wheel(delta: BrowserPoint): Promise<void>;
 }
 
-/** Mouse button understood by Chromium's Input domain. */
+/** Names a mouse button understood by Chromium's Input domain. */
 export declare type BrowserMouseButton = 'left' | 'middle' | 'right' | 'back' | 'forward';
 
-/** Mouse input operations bound to one frame target session. */
+/** Provides mouse input operations bound to one frame target session. */
 export declare interface BrowserMouseInterface {
     move(point: BrowserPoint): Promise<void>;
     down(button?: BrowserMouseButton, count?: number): Promise<void>;
     up(button?: BrowserMouseButton, count?: number): Promise<void>;
-    click(point: BrowserPoint, options?: BrowserActionOptions): Promise<void>;
-    drag(start: BrowserPoint, end: BrowserPoint, options?: BrowserActionOptions): Promise<void>;
+    click(point: BrowserPoint, options?: BrowserClickOptions): Promise<void>;
+    drag(start: BrowserPoint, end: BrowserPoint, options?: BrowserDragOptions): Promise<void>;
     wheel(delta: BrowserPoint): Promise<void>;
 }
 
 /**
- * URL and page-predicate waits resilient to ordinary navigation events.
+ * Runs URL and page-predicate waits resilient to ordinary navigation events.
+ *
+ * @example
+ * ```ts
+ * import { BrowserNavigationManager } from '@orkestrel/browser'
+ *
+ * const navigation = new BrowserNavigationManager(page)
+ * const url = await navigation.wait('https://example.com/checkout', { timeout: 5_000 })
+ * await navigation.until('document.readyState === "complete"')
+ * ```
  */
 export declare class BrowserNavigationManager implements BrowserNavigationManagerInterface {
     #private;
@@ -1188,14 +1341,14 @@ export declare class BrowserNavigationManager implements BrowserNavigationManage
     until(expression: string, options?: BrowserNavigationWaitOptions): Promise<unknown>;
 }
 
-/** URL and in-page predicate waits associated with one page. */
+/** Provides URL and in-page predicate waits associated with one page. */
 export declare interface BrowserNavigationManagerInterface {
     wait(pattern: string, options?: BrowserNavigationWaitOptions): Promise<string>;
     until(expression: string, options?: BrowserNavigationWaitOptions): Promise<unknown>;
 }
 
 /**
- * Options for page navigation.
+ * Describes the options for page navigation.
  *
  * @remarks
  * - `condition` — page load condition to wait for (default `'load'`)
@@ -1207,14 +1360,14 @@ export declare interface BrowserNavigationOptions {
     readonly timeout?: number;
 }
 
-/** Outcome of a top-level navigation command. */
+/** Describes the outcome of a top-level navigation command. */
 export declare interface BrowserNavigationResult {
     readonly url: string;
     readonly response: BrowserResponse | undefined;
     readonly same: boolean;
 }
 
-/** One pending URL-pattern wait. */
+/** Represents one pending URL-pattern wait. */
 export declare interface BrowserNavigationWait {
     readonly pattern: string;
     readonly timer: ReturnType<typeof setTimeout>;
@@ -1222,17 +1375,17 @@ export declare interface BrowserNavigationWait {
     readonly reject: (error: unknown) => void;
 }
 
-/** Options for URL and predicate waits. */
+/** Describes the options for URL and predicate waits. */
 export declare interface BrowserNavigationWaitOptions {
     readonly timeout?: number;
 }
 
-/** State retained while correlating navigation with Network events. */
+/** Holds the state retained while correlating navigation with Network events. */
 export declare interface BrowserNavigationWatch {
-    readonly responses: BrowserResponse[];
+    readonly responses: readonly BrowserResponse[];
 }
 
-/** Network events emitted by a page's network manager. */
+/** Maps the network events a page's network manager emits. */
 export declare type BrowserNetworkEventMap = {
     readonly request: readonly [request: BrowserRequest];
     readonly response: readonly [response: BrowserResponse];
@@ -1242,11 +1395,21 @@ export declare type BrowserNetworkEventMap = {
 };
 
 /**
- * Page-scoped Network and Fetch domain lifecycle.
+ * Drives the page-scoped Network and Fetch domain lifecycle.
+ *
+ * @example
+ * ```ts
+ * import { BrowserNetworkManager } from '@orkestrel/browser'
+ *
+ * const network = new BrowserNetworkManager(page)
+ * await network.start()
+ * network.emitter.on('response', (response) => log(response.status))
+ * await network.destroy()
+ * ```
  */
 export declare class BrowserNetworkManager implements BrowserNetworkManagerInterface {
     #private;
-    constructor(frame: BrowserFrameInterface, writer?: ScreenshotWriterInterface);
+    constructor(frame: BrowserFrameInterface, writer?: BrowserWriterInterface);
     get emitter(): EmitterInterface<BrowserNetworkEventMap>;
     get har(): BrowserHARManagerInterface;
     start(): Promise<void>;
@@ -1261,7 +1424,7 @@ export declare class BrowserNetworkManager implements BrowserNetworkManagerInter
     destroy(): Promise<void>;
 }
 
-/** Page-scoped network observation and interception. */
+/** Provides page-scoped network observation and interception. */
 export declare interface BrowserNetworkManagerInterface {
     readonly emitter: EmitterInterface<BrowserNetworkEventMap>;
     readonly har: BrowserHARManagerInterface;
@@ -1277,14 +1440,20 @@ export declare interface BrowserNetworkManagerInterface {
     destroy(): Promise<void>;
 }
 
-/** One serializable DOM node decoded from a CDP DOM snapshot. */
+/**
+ * Represents one serializable DOM node decoded from a CDP DOM snapshot.
+ *
+ * @remarks
+ * `category` mirrors the DOM `nodeType` value — `1` for an element, `3` for
+ * text, `9` for a document, and the rest of the DOM node categories.
+ */
 export declare interface BrowserNode {
     readonly document: number;
     readonly frame: string;
     readonly index: number;
     readonly id: number | undefined;
     readonly parent: number | undefined;
-    readonly type: number;
+    readonly category: number;
     readonly name: string;
     readonly value: string;
     readonly attributes: Readonly<Record<string, string>>;
@@ -1301,11 +1470,11 @@ export declare interface BrowserNode {
     readonly layout: BrowserLayout | undefined;
 }
 
-/** Predicate form accepted by {@link BrowserSnapshotInterface} find, filter, and closest methods. */
+/** Names the predicate form accepted by {@link BrowserSnapshotInterface} find, filter, and closest methods. */
 export declare type BrowserNodePredicate = (node: BrowserNode) => boolean;
 
 /**
- * Declarative browser-node matcher used by {@link matchesBrowserNode}.
+ * Describes a declarative browser-node matcher used by {@link matchesBrowserNode}.
  *
  * @remarks
  * Every supplied field must match. `name` is case-insensitive, `text`
@@ -1322,11 +1491,31 @@ export declare interface BrowserNodeQuery {
 }
 
 /**
- * A top-level browser page, including its target lifecycle and child frames.
+ * Collects every option a trusted-input operation can carry.
+ *
+ * @remarks
+ * The intersection of each option type that carries a bounded key, so one
+ * validator answers for a locator click, a locator drag, a mouse click, a
+ * mouse drag, and keyboard entry alike.
+ */
+export declare type BrowserOperationOptions = BrowserPointerOptions & BrowserClickOptions & BrowserDragOptions;
+
+/**
+ * Represents a top-level browser page, including its target lifecycle and child frames.
+ *
+ * @example
+ * ```ts
+ * import { BrowserPage } from '@orkestrel/browser'
+ *
+ * const page = new BrowserPage(client, 'target-1', 'session-1')
+ * await page.navigate('https://example.com')
+ * const shot = await page.screenshot({ format: 'png' })
+ * await page.close()
+ * ```
  */
 export declare class BrowserPage extends BrowserFrame implements BrowserPageInterface {
     #private;
-    constructor(client: CDPClientInterface, targetId: string, sessionId: string, writer?: ScreenshotWriterInterface, url?: string, frameId?: string, contextId?: string, opener?: BrowserPageInterface);
+    constructor(client: CDPClientInterface, targetId: string, sessionId: string, writer?: BrowserWriterInterface, url?: string, frameId?: string, contextId?: string, opener?: BrowserPageInterface, options?: BrowserPageOptions);
     get emitter(): EmitterInterface<BrowserPageEventMap>;
     get network(): BrowserNetworkManagerInterface;
     get navigation(): BrowserNavigationManagerInterface;
@@ -1353,14 +1542,14 @@ export declare class BrowserPage extends BrowserFrame implements BrowserPageInte
     assert(): void;
 }
 
-/** One uncaught page exception. */
+/** Represents one uncaught page exception. */
 export declare interface BrowserPageError {
     readonly message: string;
     readonly stack: readonly BrowserStackFrame[];
     readonly timestamp: number;
 }
 
-/** Typed page, frame, target, and user-visible browser events. */
+/** Maps the typed page, frame, target, and user-visible browser events. */
 export declare type BrowserPageEventMap = {
     readonly navigate: readonly [url: string];
     readonly attach: readonly [frame: BrowserFrameInterface];
@@ -1381,7 +1570,7 @@ export declare type BrowserPageEventMap = {
 };
 
 /**
- * Abstraction over a single top-level browser page.
+ * Abstracts a single top-level browser page.
  *
  * @remarks
  * Inherits every {@link BrowserFrameInterface} document operation for the
@@ -1423,20 +1612,27 @@ export declare interface BrowserPageInterface extends BrowserFrameInterface {
 }
 
 /**
- * Options for creating a browser page.
+ * Describes the options for creating a browser page.
  *
  * @remarks
+ * - `on` — initial event listeners wired at construction
+ * - `error` — observer error handler forwarded to the emitter
  * - `url` — navigate to this URL immediately after creation
  * - `viewport` — override the context-level default viewport
  * - `timeout` — navigation timeout for the initial URL
  */
 export declare interface BrowserPageOptions {
+    readonly on?: EmitterHooks<BrowserPageEventMap>;
+    readonly error?: EmitterErrorHandler;
     readonly url?: string;
     readonly viewport?: BrowserViewport;
     readonly timeout?: number;
 }
 
-/** Options for printing a Chromium page to PDF. */
+/** Returns the context's live pages at call time. */
+export declare type BrowserPagesFunction = () => readonly BrowserPageInterface[];
+
+/** Describes the options for printing a Chromium page to PDF. */
 export declare interface BrowserPDFOptions {
     readonly path?: string;
     readonly landscape?: boolean;
@@ -1452,14 +1648,14 @@ export declare interface BrowserPDFOptions {
     readonly outline?: boolean;
 }
 
-/** Result of printing a page to PDF. */
+/** Describes the result of printing a page to PDF. */
 export declare interface BrowserPDFResult {
     readonly bytes: Uint8Array;
     readonly path: string | undefined;
 }
 
 /**
- * Validate and compile Page.printToPDF parameters.
+ * Validates and compiles Page.printToPDF parameters.
  *
  * @param options - Public PDF options
  * @returns Protocol parameter record
@@ -1467,29 +1663,45 @@ export declare interface BrowserPDFResult {
 export declare function browserPDFToParams(options?: BrowserPDFOptions): Readonly<Record<string, unknown>>;
 
 /**
- * Performance-domain metrics and sampled JavaScript CPU profiles.
+ * Reads Performance-domain metrics for one frame.
+ *
+ * @example
+ * ```ts
+ * import { BrowserPerformance } from '@orkestrel/browser'
+ *
+ * const performance = new BrowserPerformance(page)
+ * const metrics = await performance.metrics() // readonly BrowserMetric[]
+ * ```
  */
 export declare class BrowserPerformance implements BrowserPerformanceInterface {
     #private;
     constructor(frame: BrowserFrameInterface);
-    get active(): boolean;
     metrics(): Promise<readonly BrowserMetric[]>;
-    start(interval?: number): Promise<void>;
-    stop(): Promise<BrowserProfile>;
-    destroy(): Promise<void>;
 }
 
-/** Performance metrics and CPU profile lifecycle. */
+/**
+ * Reads Performance-domain metrics.
+ *
+ * @remarks
+ * Each call enables the Performance domain and disables it again, so the
+ * reader holds no protocol state and needs no teardown. Sampled CPU profiling
+ * is {@link BrowserProfilerInterface}, its peer under `diagnostics`.
+ */
 export declare interface BrowserPerformanceInterface {
-    readonly active: boolean;
     metrics(): Promise<readonly BrowserMetric[]>;
-    start(interval?: number): Promise<void>;
-    stop(): Promise<BrowserProfile>;
-    destroy(): Promise<void>;
 }
 
 /**
- * Permission overrides isolated to one browser context.
+ * Applies permission overrides isolated to one browser context.
+ *
+ * @example
+ * ```ts
+ * import { BrowserPermissionManager } from '@orkestrel/browser'
+ *
+ * const permissions = new BrowserPermissionManager(client)
+ * await permissions.grant(['geolocation'], 'https://example.com')
+ * await permissions.clear()
+ * ```
  */
 export declare class BrowserPermissionManager implements BrowserPermissionManagerInterface {
     #private;
@@ -1499,20 +1711,30 @@ export declare class BrowserPermissionManager implements BrowserPermissionManage
     clear(): Promise<void>;
 }
 
-/** Permission override operations scoped to one browser context. */
+/** Provides permission override operations scoped to one browser context. */
 export declare interface BrowserPermissionManagerInterface {
     grant(permissions: readonly string[], origin?: string): Promise<void>;
     deny(permissions: readonly string[], origin?: string): Promise<void>;
     clear(): Promise<void>;
 }
 
-/** Point in viewport CSS pixels. */
+/** Describes a point in viewport CSS pixels. */
 export declare interface BrowserPoint {
     readonly x: number;
     readonly y: number;
 }
 
-/** Sampled CPU profile. */
+/**
+ * Describes the options for a locator operation that aims at a point inside the element.
+ *
+ * @remarks
+ * - `position` — offset from the element's top-left corner, in CSS pixels
+ */
+export declare interface BrowserPointerOptions extends BrowserActionOptions {
+    readonly position?: BrowserPoint;
+}
+
+/** Describes a sampled CPU profile. */
 export declare interface BrowserProfile {
     readonly start: number;
     readonly end: number;
@@ -1521,7 +1743,7 @@ export declare interface BrowserProfile {
     readonly deltas: readonly number[];
 }
 
-/** JavaScript call frame from a CPU profile. */
+/** Describes a JavaScript call frame from a CPU profile. */
 export declare interface BrowserProfileFrame {
     readonly function: string;
     readonly script: string;
@@ -1530,7 +1752,7 @@ export declare interface BrowserProfileFrame {
     readonly column: number;
 }
 
-/** One node in a sampled CPU profile. */
+/** Represents one node in a sampled CPU profile. */
 export declare interface BrowserProfileNode {
     readonly id: number;
     readonly frame: BrowserProfileFrame;
@@ -1538,19 +1760,48 @@ export declare interface BrowserProfileNode {
     readonly children: readonly number[];
 }
 
-/** Proxy settings used when creating an isolated browser context. */
+/**
+ * Records sampled JavaScript CPU profiles over one frame's Profiler domain.
+ *
+ * @example
+ * ```ts
+ * import { BrowserProfiler } from '@orkestrel/browser'
+ *
+ * const profiler = new BrowserProfiler(page)
+ * await profiler.start(100)
+ * const profile = await profiler.stop() // { start, end, nodes, samples, deltas }
+ * ```
+ */
+export declare class BrowserProfiler implements BrowserProfilerInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface);
+    get active(): boolean;
+    start(interval?: number): Promise<void>;
+    stop(): Promise<BrowserProfile>;
+    destroy(): Promise<void>;
+}
+
+/** Drives the sampled CPU profile lifecycle. */
+export declare interface BrowserProfilerInterface {
+    readonly active: boolean;
+    start(interval?: number): Promise<void>;
+    stop(): Promise<BrowserProfile>;
+    destroy(): Promise<void>;
+}
+
+/** Describes proxy settings used when creating an isolated browser context. */
 export declare interface BrowserProxy {
     readonly server: string;
     readonly bypass?: readonly string[];
 }
 
-/** Decoded content quad and its actionable center. */
+/** Describes a decoded content quad and its actionable center. */
 export declare interface BrowserQuad {
     readonly points: readonly [number, number, number, number, number, number, number, number];
     readonly center: BrowserPoint;
 }
 
-/** Serializable selector query, including optional ancestry and filtering. */
+/** Describes a serializable selector query, including optional ancestry and filtering. */
 export declare interface BrowserQuery {
     readonly selector: BrowserSelector;
     readonly value: string;
@@ -1561,10 +1812,10 @@ export declare interface BrowserQuery {
     readonly index?: number;
 }
 
-/** A rectangle in CSS pixels: x, y, width, height. */
+/** Represents a rectangle in CSS pixels: x, y, width, height. */
 export declare type BrowserRect = readonly [x: number, y: number, width: number, height: number];
 
-/** One observed browser request. */
+/** Represents one observed browser request. */
 export declare interface BrowserRequest {
     readonly id: string;
     readonly loader: string | undefined;
@@ -1579,7 +1830,7 @@ export declare interface BrowserRequest {
     readonly redirect: BrowserResponse | undefined;
 }
 
-/** One failed browser request. */
+/** Represents one failed browser request. */
 export declare interface BrowserRequestFailure {
     readonly id: string;
     readonly error: string;
@@ -1587,7 +1838,7 @@ export declare interface BrowserRequestFailure {
     readonly blocked: string | undefined;
 }
 
-/** One observed browser response. */
+/** Represents one observed browser response. */
 export declare interface BrowserResponse {
     readonly id: string;
     readonly loader: string;
@@ -1608,34 +1859,20 @@ export declare interface BrowserResponse {
 }
 
 /**
- * An `evaluate()`/`content()` result exceeded {@link BROWSER_RESULT_LIMIT}
+ * Reports that an `evaluate()`/`content()` result exceeded {@link BROWSER_RESULT_LIMIT}
  * and was rejected in-page before it could overflow the CDP transport frame.
  */
 export declare class BrowserResultLimitError extends BrowserError {
     constructor(message: string, context?: Readonly<Record<string, unknown>>);
 }
 
-/** Options for role-based locator creation. */
+/** Describes the options for role-based locator creation. */
 export declare interface BrowserRoleOptions {
     readonly name?: string;
     readonly exact?: boolean;
 }
 
-/**
- * One paused request that can be aborted, continued, or fulfilled exactly once.
- */
-export declare class BrowserRoute implements BrowserRouteInterface {
-    #private;
-    constructor(frame: BrowserFrameInterface, id: string, request: BrowserRequest);
-    get id(): string;
-    get request(): BrowserRequest;
-    get handled(): boolean;
-    abort(reason?: string): Promise<void>;
-    continue(options?: BrowserRouteContinueOptions): Promise<void>;
-    fulfill(options: BrowserRouteFulfillOptions): Promise<void>;
-}
-
-/** Overrides supplied when continuing an intercepted request. */
+/** Describes the overrides supplied when continuing an intercepted request. */
 export declare interface BrowserRouteContinueOptions {
     readonly url?: string;
     readonly method?: string;
@@ -1643,13 +1880,13 @@ export declare interface BrowserRouteContinueOptions {
     readonly post?: string;
 }
 
-/** One installed network route. */
+/** Represents one installed network route. */
 export declare interface BrowserRouteDefinition {
     readonly query: BrowserRouteQuery;
     readonly handler: BrowserRouteHandler;
 }
 
-/** Synthetic response supplied when fulfilling an intercepted request. */
+/** Describes the synthetic response supplied when fulfilling an intercepted request. */
 export declare interface BrowserRouteFulfillOptions {
     readonly status?: number;
     readonly phrase?: string;
@@ -1657,10 +1894,10 @@ export declare interface BrowserRouteFulfillOptions {
     readonly body?: string | Uint8Array;
 }
 
-/** Function invoked for a matching intercepted request. */
+/** Runs for a matching intercepted request. */
 export declare type BrowserRouteHandler = (route: BrowserRouteInterface) => void | Promise<void>;
 
-/** One paused Fetch-domain request. */
+/** Represents one paused Fetch-domain request. */
 export declare interface BrowserRouteInterface {
     readonly id: string;
     readonly request: BrowserRequest;
@@ -1670,29 +1907,29 @@ export declare interface BrowserRouteInterface {
     fulfill(options: BrowserRouteFulfillOptions): Promise<void>;
 }
 
-/** Route matching criteria. Omitted fields match all values. */
+/** Describes route matching criteria. Omitted fields match all values. */
 export declare interface BrowserRouteQuery {
     readonly url?: string;
     readonly method?: string;
     readonly resource?: string;
 }
 
-/** Cookie same-site policy understood by Chromium. */
+/** Names a cookie same-site policy understood by Chromium. */
 export declare type BrowserSameSite = 'Strict' | 'Lax' | 'None';
 
 /**
- * Options for taking a page screenshot.
+ * Describes the options for taking a page screenshot.
  *
  * @remarks
- * - `path` — file path to persist the screenshot to, via the page's writer
+ * - `path` — file path to persist the screenshot to, through the page's writer
  * - `full` — capture the full scrollable page (default `false`)
- * - `type` — image format (default `'png'`)
+ * - `format` — image format (default `'png'`)
  * - `quality` — JPEG quality 0–100 (ignored for PNG)
  */
 export declare interface BrowserScreenshotOptions {
     readonly path?: string;
     readonly full?: boolean;
-    readonly type?: 'png' | 'jpeg';
+    readonly format?: 'png' | 'jpeg';
     readonly quality?: number;
     readonly clip?: BrowserRect;
     readonly transparent?: boolean;
@@ -1704,47 +1941,56 @@ export declare interface BrowserScreenshotOptions {
 }
 
 /**
- * Result of a page screenshot.
+ * Describes the result of a page screenshot.
  *
  * @remarks
  * - `bytes` — raw image bytes
- * - `path` — file path if persisted via the page's writer, otherwise undefined
+ * - `path` — file path if persisted through the page's writer, otherwise undefined
  */
 export declare interface BrowserScreenshotResult {
     readonly bytes: Uint8Array;
     readonly path: string | undefined;
 }
 
-/** Screenshot coordinate scale. */
+/** Names a screenshot coordinate scale. */
 export declare type BrowserScreenshotScale = 'css' | 'device';
 
 /**
- * Validate and compile basic Page.captureScreenshot parameters.
+ * Validates and compiles basic Page.captureScreenshot parameters.
  *
  * @param options - Public screenshot options
  * @returns Protocol parameter record
  */
 export declare function browserScreenshotToParams(options?: BrowserScreenshotOptions): Readonly<Record<string, unknown>>;
 
-/** JavaScript script coverage. */
+/** Describes JavaScript script coverage. */
 export declare interface BrowserScriptCoverage {
     readonly id: string;
     readonly url: string;
     readonly functions: readonly BrowserFunctionCoverage[];
 }
 
-/** One installed new-document script and its optional host binding owner. */
+/** Represents one installed new-document script and its optional host binding owner. */
 export declare interface BrowserScriptEntry {
     readonly source: string;
     readonly binding: string | undefined;
 }
 
 /**
- * New-document scripts and promise-based host functions for one page.
- */
-export declare class BrowserScriptManager implements BrowserScriptManagerInterface {
-    #private;
-    constructor(frame: BrowserFrameInterface);
+ * Installs new-document scripts and promise-based host functions for one page.
+ *
+ * @example
+ * ```ts
+ * import { BrowserScriptManager } from '@orkestrel/browser'
+ *
+ * const scripts = new BrowserScriptManager(page)
+ * const id = await scripts.add('window.__ready = true')
+ * await scripts.remove(id)
+ * ```
+ */
+export declare class BrowserScriptManager implements BrowserScriptManagerInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface);
     add(source: string): Promise<string>;
     remove(id: string): Promise<void>;
     expose(name: string, handler: BrowserBindingHandler): Promise<void>;
@@ -1752,7 +1998,7 @@ export declare class BrowserScriptManager implements BrowserScriptManagerInterfa
     destroy(): Promise<void>;
 }
 
-/** Initialization scripts and host bindings for one page. */
+/** Manages initialization scripts and host bindings for one page. */
 export declare interface BrowserScriptManagerInterface {
     add(source: string): Promise<string>;
     remove(id: string): Promise<void>;
@@ -1761,7 +2007,7 @@ export declare interface BrowserScriptManagerInterface {
     destroy(): Promise<void>;
 }
 
-/** TLS details supplied with a browser response. */
+/** Describes the TLS details supplied with a browser response. */
 export declare interface BrowserSecurity {
     readonly protocol: string;
     readonly issuer: string;
@@ -1769,18 +2015,32 @@ export declare interface BrowserSecurity {
     readonly to: number;
 }
 
-/** Selector axis supported by {@link BrowserSelectorManagerInterface}. */
-export declare type BrowserSelector = 'css' | 'role' | 'text' | 'label' | 'placeholder' | 'test';
+/**
+ * Names a selector axis supported by {@link BrowserSelectorManagerInterface}.
+ *
+ * @remarks
+ * `testId` mirrors the `data-testid` attribute {@link BROWSER_TEST_ID_ATTRIBUTE} names.
+ */
+export declare type BrowserSelector = 'css' | 'role' | 'text' | 'label' | 'placeholder' | 'testId';
 
 /**
- * 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.
  */
 export declare class BrowserSelectorError extends BrowserError {
     constructor(message: string, context?: Readonly<Record<string, unknown>>);
 }
 
 /**
- * Semantic locator factory for one frame.
+ * Creates semantic locators for one frame.
+ *
+ * @example
+ * ```ts
+ * import { BrowserSelectorManager } from '@orkestrel/browser'
+ *
+ * const selectors = new BrowserSelectorManager(page)
+ * await selectors.role('button', { name: 'Save' }).click()
+ * await selectors.testId('checkout').click()
+ * ```
  */
 export declare class BrowserSelectorManager implements BrowserSelectorManagerInterface {
     #private;
@@ -1790,11 +2050,11 @@ export declare class BrowserSelectorManager implements BrowserSelectorManagerInt
     text(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
     label(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
     placeholder(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
-    test(value: string): BrowserLocatorInterface;
+    testId(value: string): BrowserLocatorInterface;
 }
 
 /**
- * Locator factory grouped by selector semantics.
+ * Groups the locator factories by selector semantics.
  */
 export declare interface BrowserSelectorManagerInterface {
     css(value: string): BrowserLocatorInterface;
@@ -1802,16 +2062,39 @@ export declare interface BrowserSelectorManagerInterface {
     text(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
     label(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
     placeholder(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
-    test(value: string): BrowserLocatorInterface;
+    testId(value: string): BrowserLocatorInterface;
 }
 
-/** Resolve the current CDP session for a frame id. */
+/**
+ * Describes the options for one raw CDP method call issued in a frame's target session.
+ *
+ * @remarks
+ * The frame supplies its own session, so a caller bounds the call and nothing
+ * else.
+ *
+ * - `timeout` — ms before this one request fails, overriding the client-wide default
+ */
+export declare interface BrowserSendOptions {
+    readonly timeout?: number;
+}
+
+/** Resolves the current CDP session for a frame id. */
 export declare type BrowserSessionFunction = (frame: string) => Promise<string>;
 
-/** Structural sibling relationship relative to a browser node. */
+/** Names a structural sibling relationship relative to a browser node. */
 export declare type BrowserSiblingRelation = 'preceding' | 'following';
 
-/** A navigable, serializable browser DOM snapshot. */
+/**
+ * Represents a navigable, serializable browser DOM snapshot.
+ *
+ * @example
+ * ```ts
+ * import { BrowserSnapshot } from '@orkestrel/browser'
+ *
+ * const snapshot = new BrowserSnapshot({ documents, styles: ['display'] })
+ * const main = snapshot.find({ name: 'main', visible: true })
+ * ```
+ */
 export declare class BrowserSnapshot implements BrowserSnapshotInterface {
     #private;
     readonly documents: readonly BrowserDocument[];
@@ -1832,13 +2115,13 @@ export declare class BrowserSnapshot implements BrowserSnapshotInterface {
     path(node: BrowserNode): string;
 }
 
-/** Serializable input for a navigable browser snapshot. */
+/** Describes the serializable input for a navigable browser snapshot. */
 export declare interface BrowserSnapshotInput {
     readonly documents: readonly BrowserDocument[];
     readonly styles: readonly string[];
 }
 
-/** A navigable, serializable snapshot of every document attached to a page. */
+/** Represents a navigable, serializable snapshot of every document attached to a page. */
 export declare interface BrowserSnapshotInterface extends BrowserSnapshotInput {
     walk(options?: BrowserWalkOptions): Generator<BrowserNode, void, unknown>;
     descendants(node: BrowserNode): Generator<BrowserNode, void, unknown>;
@@ -1856,7 +2139,7 @@ export declare interface BrowserSnapshotInterface extends BrowserSnapshotInput {
 }
 
 /**
- * Options configuring capture through {@link BrowserPageInterface} `snapshot()`.
+ * Describes the options configuring capture through {@link BrowserPageInterface} `snapshot()`.
  * The snapshot entity's creation input is {@link BrowserSnapshotInput}.
  *
  * @remarks
@@ -1872,7 +2155,7 @@ export declare interface BrowserSnapshotOptions {
     readonly limit?: number;
 }
 
-/** One browser-side stack frame. */
+/** Represents one browser-side stack frame. */
 export declare interface BrowserStackFrame {
     readonly url: string;
     readonly function: string;
@@ -1880,71 +2163,78 @@ export declare interface BrowserStackFrame {
     readonly column: number;
 }
 
-/** One key/value pair from web storage. */
+/** Represents one key/value pair from web storage. */
 export declare interface BrowserStorageEntry {
     readonly name: string;
     readonly value: string;
 }
 
 /**
- * Portable cookie and web-storage state for one browser context.
+ * Imports, exports, and clears cookie and web-storage state for one browser context.
+ *
+ * @example
+ * ```ts
+ * import { BrowserStorageManager } from '@orkestrel/browser'
+ *
+ * const storage = new BrowserStorageManager(context.cookies, () => context.pages())
+ * const state = await storage.state({ origins: ['https://example.com'] })
+ * await storage.restore(state)
+ * ```
  */
 export declare class BrowserStorageManager implements BrowserStorageManagerInterface {
     #private;
-    constructor(cookies: BrowserCookieManagerInterface, pages: () => readonly BrowserPageInterface[]);
+    constructor(cookies: BrowserCookieManagerInterface, pages: BrowserPagesFunction);
     state(options?: BrowserStorageOptions): Promise<BrowserStorageState>;
     restore(state: BrowserStorageState): Promise<void>;
     clear(origin?: string): Promise<void>;
 }
 
-/** Storage-state import, export, and clearing operations. */
+/** Provides storage-state import, export, and clearing operations. */
 export declare interface BrowserStorageManagerInterface {
     state(options?: BrowserStorageOptions): Promise<BrowserStorageState>;
     restore(state: BrowserStorageState): Promise<void>;
     clear(origin?: string): Promise<void>;
 }
 
-/** Options for collecting storage state from selected origins. */
+/** Describes the options for collecting storage state from selected origins. */
 export declare interface BrowserStorageOptions {
     readonly origins?: readonly string[];
 }
 
-/** Origin-scoped local and session storage snapshot. */
+/** Describes an origin-scoped local and session storage snapshot. */
 export declare interface BrowserStorageOrigin {
     readonly origin: string;
     readonly local: readonly BrowserStorageEntry[];
     readonly session: readonly BrowserStorageEntry[];
 }
 
-/** Portable browser authentication and storage snapshot. */
+/** Describes a portable browser authentication and storage snapshot. */
 export declare interface BrowserStorageState {
     readonly cookies: readonly BrowserCookieInput[];
     readonly origins: readonly BrowserStorageOrigin[];
 }
 
-/** One decoded IO stream read. */
+/** Represents one decoded IO stream read. */
 export declare interface BrowserStreamChunk {
     readonly bytes: Uint8Array;
     readonly eof: boolean;
 }
 
-/** CSS stylesheet coverage. */
+/** Describes CSS stylesheet coverage. */
 export declare interface BrowserStyleCoverage {
     readonly id: string;
     readonly ranges: readonly BrowserCoverageRange[];
 }
 
-/** Options for text-like locator creation. */
+/** Runs one teardown step to settlement while the first failure is retained. */
+export declare type BrowserTeardownFunction = () => Promise<unknown>;
+
+/** Describes the options for text-like locator creation. */
 export declare interface BrowserTextOptions {
     readonly exact?: boolean;
 }
 
-/** Options for locator text extraction. */
-export declare interface BrowserTextResultOptions {
-    readonly all?: boolean;
-}
-
-/** Network timing values in milliseconds relative to request time. */
+/** Holds network timing values in milliseconds relative to request time. */
 export declare interface BrowserTiming {
     readonly request: number;
     readonly proxy: BrowserTimingRange | undefined;
@@ -1955,14 +2245,22 @@ export declare interface BrowserTiming {
     readonly receive: number | undefined;
 }
 
-/** Start/end pair for one network timing phase. */
+/** Describes the start/end pair for one network timing phase. */
 export declare interface BrowserTimingRange {
     readonly start: number;
     readonly end: number;
 }
 
 /**
- * Trusted touch input through Chromium's CDP Input domain.
+ * Sends trusted touch input through Chromium's CDP Input domain.
+ *
+ * @example
+ * ```ts
+ * import { BrowserTouch } from '@orkestrel/browser'
+ *
+ * const touch = new BrowserTouch(page)
+ * await touch.tap({ x: 120, y: 240 })
+ * ```
  */
 export declare class BrowserTouch implements BrowserTouchInterface {
     #private;
@@ -1970,24 +2268,33 @@ export declare class BrowserTouch implements BrowserTouchInterface {
     tap(point: BrowserPoint): Promise<void>;
 }
 
-/** Touch input operations bound to one frame target session. */
+/** Provides touch input operations bound to one frame target session. */
 export declare interface BrowserTouchInterface {
     tap(point: BrowserPoint): Promise<void>;
 }
 
 /**
- * Chromium trace capture streamed through the IO domain.
+ * Captures Chromium traces streamed through the IO domain.
+ *
+ * @example
+ * ```ts
+ * import { BrowserTracing } from '@orkestrel/browser'
+ *
+ * const tracing = new BrowserTracing(page)
+ * await tracing.start({ screenshots: true })
+ * const trace = await tracing.stop() // { bytes, path }
+ * ```
  */
 export declare class BrowserTracing implements BrowserTracingInterface {
     #private;
-    constructor(frame: BrowserFrameInterface, writer?: ScreenshotWriterInterface);
+    constructor(frame: BrowserFrameInterface, writer?: BrowserWriterInterface);
     get active(): boolean;
     start(options?: BrowserTracingOptions): Promise<void>;
     stop(): Promise<BrowserTracingResult>;
     destroy(): Promise<void>;
 }
 
-/** Trace capture lifecycle. */
+/** Drives the trace capture lifecycle. */
 export declare interface BrowserTracingInterface {
     readonly active: boolean;
     start(options?: BrowserTracingOptions): Promise<void>;
@@ -1995,7 +2302,7 @@ export declare interface BrowserTracingInterface {
     destroy(): Promise<void>;
 }
 
-/** Chromium trace capture options. */
+/** Describes the options for a Chromium trace capture. */
 export declare interface BrowserTracingOptions {
     readonly path?: string;
     readonly categories?: readonly string[];
@@ -2003,25 +2310,69 @@ export declare interface BrowserTracingOptions {
     readonly sampling?: boolean;
 }
 
-/** Trace capture result. */
+/** Describes the result of a trace capture. */
 export declare interface BrowserTracingResult {
     readonly bytes: Uint8Array;
     readonly path: string | undefined;
 }
 
-/** Options for setting files on a file input. */
+/**
+ * Runs one asynchronous transition at a time, shared by every caller that joins it.
+ *
+ * @remarks
+ * An entity with a lifecycle runs the same guard around every transition: take
+ * the promise already in flight when one exists, otherwise start the work, hold
+ * its promise, and release the field afterwards only when it is still this
+ * run's. Holding that guard in one place keeps the identity check — the part a
+ * hand-written copy drops — identical at every site. The entry guards stay with
+ * each entity, because what makes a transition unnecessary is the entity's own
+ * state.
+ *
+ * @example
+ * ```ts
+ * import { BrowserTransition } from '@orkestrel/browser'
+ *
+ * const starting = new BrowserTransition()
+ * await starting.execute(() => transport.start())
+ * const joined = starting.pending // the in-flight promise, or undefined
+ * ```
+ */
+export declare class BrowserTransition<T = void> implements BrowserTransitionInterface<T> {
+    #private;
+    get pending(): Promise<T> | undefined;
+    execute(work: BrowserTransitionFunction<T>): Promise<T>;
+}
+
+/** Runs the work one {@link BrowserTransitionInterface} transition performs. */
+export declare type BrowserTransitionFunction<T> = () => Promise<T>;
+
+/**
+ * Represents one asynchronous transition shared by every caller that arrives while it runs.
+ *
+ * @remarks
+ * `pending` is the promise of the transition in flight, or undefined when none
+ * is running; an entity reads it to answer a question about its own state, such
+ * as whether a close must wait for an in-flight connect. `execute` starts the
+ * work when nothing is in flight, and joins the running transition otherwise.
+ */
+export declare interface BrowserTransitionInterface<T> {
+    readonly pending: Promise<T> | undefined;
+    execute(work: BrowserTransitionFunction<T>): Promise<T>;
+}
+
+/** Describes the options for setting files on a file input. */
 export declare interface BrowserUploadOptions extends BrowserActionOptions {
     readonly files: readonly string[];
 }
 
-/** User-agent metadata accepted by Chromium emulation. */
+/** Describes user-agent metadata accepted by Chromium emulation. */
 export declare interface BrowserUserAgent {
     readonly value: string;
     readonly language?: string;
     readonly platform?: string;
 }
 
-/** Viewport dimensions for a browser page. */
+/** Describes the viewport dimensions for a browser page. */
 export declare interface BrowserViewport {
     readonly width: number;
     readonly height: number;
@@ -2032,7 +2383,7 @@ export declare interface BrowserViewport {
 }
 
 /**
- * Options for waiting on an element.
+ * Describes the options for waiting on an element.
  *
  * @remarks
  * - `timeout` — maximum time to wait in milliseconds
@@ -2043,14 +2394,14 @@ export declare interface BrowserWaitOptions extends BrowserActionOptions {
     readonly state?: BrowserWaitState;
 }
 
-/** Element state a frame or page can wait for. */
+/** Names an element state a frame or page can wait for. */
 export declare type BrowserWaitState = 'attached' | 'detached' | 'visible' | 'hidden';
 
-/** Page load condition for navigation — the CDP load event awaited by `navigate()`. */
+/** Names the page load condition for navigation — the CDP load event awaited by `navigate()`. */
 export declare type BrowserWaitUntil = 'commit' | 'load' | 'domcontentloaded';
 
 /**
- * Options for walking a browser snapshot.
+ * Describes the options for walking a browser snapshot.
  *
  * @remarks
  * - `root` — optional subtree root, included in the walk
@@ -2061,11 +2412,19 @@ export declare interface BrowserWalkOptions {
     readonly order?: BrowserWalkOrder;
 }
 
-/** Structural ordering for a browser snapshot walk. */
+/** Names the structural ordering for a browser snapshot walk. */
 export declare type BrowserWalkOrder = 'depth' | 'breadth';
 
 /**
- * Observable WebSocket connection reconstructed from Network-domain events.
+ * Represents an observable WebSocket connection reconstructed from Network-domain events.
+ *
+ * @example
+ * ```ts
+ * import { BrowserWebSocket } from '@orkestrel/browser'
+ *
+ * const socket = new BrowserWebSocket('request-1', 'wss://example.com/live')
+ * socket.emitter.on('receive', (frame) => log(frame.data))
+ * ```
  */
 export declare class BrowserWebSocket implements BrowserWebSocketInterface {
     #private;
@@ -2079,7 +2438,7 @@ export declare class BrowserWebSocket implements BrowserWebSocketInterface {
     close(timestamp: number): void;
 }
 
-/** WebSocket lifecycle events. */
+/** Maps the WebSocket lifecycle events. */
 export declare type BrowserWebSocketEventMap = {
     readonly receive: readonly [frame: BrowserWebSocketFrame];
     readonly transmit: readonly [frame: BrowserWebSocketFrame];
@@ -2087,7 +2446,7 @@ export declare type BrowserWebSocketEventMap = {
     readonly close: readonly [timestamp: number];
 };
 
-/** WebSocket frame payload. */
+/** Describes a WebSocket frame payload. */
 export declare interface BrowserWebSocketFrame {
     readonly opcode: number;
     readonly data: string;
@@ -2095,36 +2454,33 @@ export declare interface BrowserWebSocketFrame {
     readonly timestamp: number;
 }
 
-/** One observed WebSocket connection. */
+/**
+ * Represents one observed WebSocket connection.
+ *
+ * @remarks
+ * The connection is an observation: a page's network manager reconstructs it
+ * from Network-domain events and drives the concrete `BrowserWebSocket`. The
+ * drive methods are on this contract because the class exposes exactly its
+ * interface methods.
+ */
 export declare interface BrowserWebSocketInterface {
     readonly emitter: EmitterInterface<BrowserWebSocketEventMap>;
     readonly id: string;
     readonly url: string;
+    /** Reports one received frame. The page's network manager drives it. */
     receive(frame: BrowserWebSocketFrame): void;
+    /** Reports one sent frame. The page's network manager drives it. */
     transmit(frame: BrowserWebSocketFrame): void;
+    /** Reports a connection fault. The page's network manager drives it. */
     fail(message: string): void;
+    /** Reports the connection closing and destroys the emitter. The page's network manager drives it. */
     close(timestamp: number): void;
 }
 
-/**
- * Dedicated, shared, or service worker attached through a flattened target session.
- */
-export declare class BrowserWorker implements BrowserWorkerInterface {
-    #private;
-    constructor(client: CDPClientInterface, session: string, id: string, url: string, category: BrowserWorkerCategory);
-    get id(): string;
-    get url(): string;
-    get category(): BrowserWorkerCategory;
-    evaluate(expression: string, timeout?: number): Promise<unknown>;
-    send(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
-    detach(): void;
-    close(): Promise<void>;
-}
-
-/** Worker target category. */
+/** Names a worker target category. */
 export declare type BrowserWorkerCategory = 'worker' | 'service_worker' | 'shared_worker';
 
-/** Script worker attached to a page target. */
+/** Represents a script worker attached to a page target. */
 export declare interface BrowserWorkerInterface {
     readonly id: string;
     readonly url: string;
@@ -2135,11 +2491,23 @@ export declare interface BrowserWorkerInterface {
     close(): Promise<void>;
 }
 
-/** Decode UTF-8 bytes as text. */
+/**
+ * Provides a pluggable sink for persisting captured browser bytes to a path.
+ *
+ * @remarks
+ * Core never touches a filesystem directly — a page accepts an optional
+ * writer (server supplies an `fs`-backed implementation) and calls it when a
+ * screenshot, PDF, trace, or HAR request carries a `path`.
+ */
+export declare interface BrowserWriterInterface {
+    write(path: string, data: Uint8Array): Promise<void>;
+}
+
+/** Decodes UTF-8 bytes as text. */
 export declare function bytesToText(value: Uint8Array): string;
 
 /**
- * Lightweight Chrome DevTools Protocol client over a {@link CDPTransportInterface}.
+ * Provides a lightweight Chrome DevTools Protocol client over a {@link CDPTransportInterface}.
  *
  * @remarks
  * Sends JSON-RPC messages over the injected transport and dispatches
@@ -2147,18 +2515,28 @@ export declare function bytesToText(value: Uint8Array): string;
  * (WebSocket, pipe, or any other duplex channel); this class owns only
  * the JSON-RPC framing and id/session correlation.
  *
- * Supports session-scoped event subscriptions: when a sessionId is
- * provided to subscribe/unsubscribe, the handler only fires for CDP
- * events carrying that sessionId. Global subscriptions (no sessionId)
- * continue to see ALL events for backwards compatibility.
+ * Supports session-scoped event subscriptions: a subscription registered
+ * without a session id receives the event whatever session carries it, and a
+ * session-scoped subscription receives only its own session's events.
+ *
+ * @example
+ * ```ts
+ * import { CDPClient } from '@orkestrel/browser'
+ *
+ * const client = new CDPClient({ transport })
+ * await client.connect()
+ * const targets = await client.send('Target.getTargets')
+ * await client.close()
+ * ```
  */
 export declare class CDPClient implements CDPClientInterface {
     #private;
     constructor(options: CDPClientOptions);
+    get emitter(): EmitterInterface<CDPClientEventMap>;
     get connected(): boolean;
     connect(): Promise<void>;
     /**
-     * Close the transport and re-establish a fresh connection.
+     * Closes the transport and re-establishes a fresh connection.
      *
      * @remarks
      * Client-level subscriptions (`subscribe`/`unsubscribe` registrations)
@@ -2167,14 +2545,14 @@ export declare class CDPClient implements CDPClientInterface {
      * transport without re-registering every handler.
      */
     reconnect(): Promise<void>;
-    send(method: string, params?: Readonly<Record<string, unknown>>, sessionId?: string, timeout?: number): Promise<unknown>;
-    subscribe(method: string, handler: CDPHandler, sessionId?: string): void;
-    unsubscribe(method: string, handler: CDPHandler, sessionId?: string): void;
+    send(method: string, params?: Readonly<Record<string, unknown>>, options?: CDPSendOptions): Promise<unknown>;
+    subscribe(method: string, handler: CDPHandler, session?: string): void;
+    unsubscribe(method: string, handler: CDPHandler, session?: string): void;
     /**
-     * Close the transport and reject all pending requests.
+     * Closes the transport and rejects all pending requests.
      *
      * @remarks
-     * Subscriptions registered via `subscribe()` are client-level
+     * Subscriptions registered through `subscribe()` are client-level
      * registrations, not connection-level state — they survive `close()`
      * (and a subsequent `reconnect()`/`connect()`) and keep firing once the
      * transport is active again. Only pending requests are rejected here.
@@ -2186,9 +2564,27 @@ export declare class CDPClient implements CDPClientInterface {
 }
 
 /**
- * Lightweight Chrome DevTools Protocol client over a {@link CDPTransportInterface}.
+ * Maps the events a {@link CDPClientInterface} emits.
+ *
+ * @remarks
+ * `connect` fires once the transport started and dispatch began; `close`
+ * fires after an explicit teardown, including one that interrupted a
+ * pending `connect()`; `drop` fires when the transport ended without a
+ * close request; `error` carries a transport-level fault (unknown shape —
+ * narrow before use).
+ */
+export declare type CDPClientEventMap = {
+    readonly connect: readonly [];
+    readonly close: readonly [];
+    readonly drop: readonly [];
+    readonly error: readonly [error: unknown];
+};
+
+/**
+ * Provides a lightweight Chrome DevTools Protocol client over a {@link CDPTransportInterface}.
  *
  * @remarks
+ * - `emitter` — subscribe to the client's own connection lifecycle
  * - `connected` — true while the transport is active
  * - `connect` — start the transport and begin dispatching
  * - `reconnect` — close and re-establish the transport
@@ -2200,29 +2596,39 @@ export declare class CDPClient implements CDPClientInterface {
  * - `close` — tear down the transport and reject all pending requests
  */
 export declare interface CDPClientInterface {
+    readonly emitter: EmitterInterface<CDPClientEventMap>;
     readonly connected: boolean;
     connect(): Promise<void>;
     reconnect(): Promise<void>;
-    send(method: string, params?: Readonly<Record<string, unknown>>, sessionId?: string, timeout?: number): Promise<unknown>;
-    subscribe(method: string, handler: CDPHandler, sessionId?: string): void;
-    unsubscribe(method: string, handler: CDPHandler, sessionId?: string): void;
+    send(method: string, params?: Readonly<Record<string, unknown>>, options?: CDPSendOptions): Promise<unknown>;
+    subscribe(method: string, handler: CDPHandler, session?: string): void;
+    unsubscribe(method: string, handler: CDPHandler, session?: string): void;
     close(): Promise<void>;
 }
 
 /**
- * Options for creating a CDPClient.
+ * Describes the options for creating a CDPClient.
  *
  * @remarks
  * - `transport` — the text pipe the client sends/receives JSON-RPC frames over
  * - `timeout` — ms before a pending request or connection attempt fails (default from constants)
+ * - `on` — initial event listeners wired at construction
+ * - `error` — receives a throwing subscriber's error on both dispatch paths:
+ *   a CDP event subscriber's throw arrives with the CDP method that raised it,
+ *   and a lifecycle subscriber's throw arrives with the lifecycle event name
+ *   (`connect`, `close`, `drop`, `error`) as the second argument. Without it a
+ *   broken handler fails silently, because a throwing subscriber is never
+ *   allowed to reach its siblings or the dispatch loop
  */
 export declare interface CDPClientOptions {
     readonly transport: CDPTransportInterface;
     readonly timeout?: number;
+    readonly on?: EmitterHooks<CDPClientEventMap>;
+    readonly error?: EmitterErrorHandler;
 }
 
 /**
- * A CDP request could not be sent or completed because the client was not in
+ * 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).
  */
@@ -2231,7 +2637,7 @@ export declare class CDPConnectionError extends BrowserError {
 }
 
 /**
- * A CDP request received an error response from the remote endpoint.
+ * Reports that a CDP request received an error response from the remote endpoint.
  *
  * @remarks
  * Carries the originating `method` plus the CDP error's own `code`,
@@ -2242,26 +2648,44 @@ export declare class CDPError extends BrowserError {
     constructor(message: string, context?: Readonly<Record<string, unknown>>);
 }
 
-/** Handler invoked for a subscribed CDP event with its params record. */
+/** Receives a subscribed CDP event with its params record. */
 export declare type CDPHandler = (params: Readonly<Record<string, unknown>>) => void;
 
-/** One entry of the CDP `Target.getTargets` result. */
+/**
+ * Describes the options for one CDP method call.
+ *
+ * @remarks
+ * - `session` — scope the call to one attached CDP session
+ * - `timeout` — ms before this one request fails, overriding the client-wide default
+ */
+export declare interface CDPSendOptions {
+    readonly session?: string;
+    readonly timeout?: number;
+}
+
+/**
+ * Represents one entry of the CDP `Target.getTargets` result.
+ *
+ * @remarks
+ * `category` mirrors the protocol's `type` field — `'page'`, `'worker'`,
+ * `'browser'`, and the rest of Chromium's target categories.
+ */
 export declare interface CDPTarget {
     readonly id: string;
-    readonly type: string;
+    readonly category: string;
     readonly title: string;
     readonly url: string;
 }
 
 /**
- * A pending CDP request was not answered within its timeout window.
+ * Reports that a pending CDP request was not answered within its timeout window.
  */
 export declare class CDPTimeoutError extends BrowserError {
     constructor(message: string, context?: Readonly<Record<string, unknown>>);
 }
 
 /**
- * Event map for a {@link CDPTransportInterface} — the raw text pipe a
+ * Maps the events emitted by a {@link CDPTransportInterface} — the raw text pipe a
  * {@link CDPClientInterface} sends and receives JSON-RPC frames over.
  *
  * @remarks
@@ -2276,7 +2700,7 @@ export declare type CDPTransportEventMap = {
 };
 
 /**
- * A dumb text transport CDPClient sends and receives JSON-RPC frames over.
+ * Represents a dumb text transport CDPClient sends and receives JSON-RPC frames over.
  *
  * @remarks
  * The transport owns the connection (WebSocket, pipe, or any other duplex
@@ -2293,7 +2717,7 @@ export declare interface CDPTransportInterface {
 }
 
 /**
- * Compile the element-side actionability pass used before trusted input.
+ * Compiles the element-side actionability pass used before trusted input.
  *
  * @param options - Checks required for the action
  * @returns Async `Runtime.callFunctionOn` function declaration
@@ -2301,12 +2725,12 @@ export declare interface CDPTransportInterface {
 export declare function compileActionabilityFunction(options: BrowserActionabilityOptions): string;
 
 /**
- * Compile an attached-state locator wait.
+ * Compiles an attached-state locator wait.
  */
 export declare function compileAttachedLocatorWaitExpression(query: BrowserQuery, strict: boolean, timeout: number): string;
 
 /**
- * Compile an in-page wait for an attached selector.
+ * Compiles an in-page wait for an attached selector.
  *
  * @param selector - CSS selector
  * @param strict - Whether more than one match is an error
@@ -2316,7 +2740,7 @@ export declare function compileAttachedLocatorWaitExpression(query: BrowserQuery
 export declare function compileAttachedWaitExpression(selector: string, strict: boolean, timeout: number): string;
 
 /**
- * Compile current-document cleanup for one page-side host binding facade.
+ * Compiles current-document cleanup for one page-side host binding facade.
  *
  * @param name - Binding identifier
  * @returns Runtime cleanup expression
@@ -2324,7 +2748,7 @@ export declare function compileAttachedWaitExpression(selector: string, strict:
 export declare function compileBrowserBindingCleanup(name: string): string;
 
 /**
- * Compile delivery of a host binding result to one execution context.
+ * Compiles delivery of a host binding result to one execution context.
  *
  * @param name - Binding identifier
  * @param id - Call identifier
@@ -2335,7 +2759,7 @@ export declare function compileBrowserBindingCleanup(name: string): string;
 export declare function compileBrowserBindingResult(name: string, id: string, success: boolean, value: unknown): string;
 
 /**
- * Compile the page-side promise facade for one Runtime binding.
+ * Compiles the page-side promise facade for one Runtime binding.
  *
  * @param name - Binding identifier
  * @returns Self-installing script source
@@ -2343,7 +2767,7 @@ export declare function compileBrowserBindingResult(name: string, id: string, su
 export declare function compileBrowserBindingSource(name: string): string;
 
 /**
- * Compile a strict, visibility-checked click expression.
+ * Compiles a strict, visibility-checked click expression.
  *
  * @param selector - CSS selector
  * @param strict - Whether more than one match is an error
@@ -2352,7 +2776,7 @@ export declare function compileBrowserBindingSource(name: string): string;
 export declare function compileClickExpression(selector: string, strict: boolean): string;
 
 /**
- * Compile recorded codegen actions into a replayable script.
+ * Compiles recorded codegen actions into a replayable script.
  *
  * @remarks
  * Emits one statement per action against a `page` object shaped like
@@ -2368,12 +2792,12 @@ export declare function compileClickExpression(selector: string, strict: boolean
 export declare function compileCodegenScript(actions: readonly BrowserCodegenAction[], options?: BrowserCodegenScriptOptions): string;
 
 /**
- * Compile a detached-state locator wait.
+ * Compiles a detached-state locator wait.
  */
 export declare function compileDetachedLocatorWaitExpression(query: BrowserQuery, strict: boolean, timeout: number): string;
 
 /**
- * Compile an in-page wait for a detached selector.
+ * Compiles an in-page wait for a detached selector.
  *
  * @param selector - CSS selector
  * @param strict - Whether more than one match is an error
@@ -2383,7 +2807,7 @@ export declare function compileDetachedLocatorWaitExpression(query: BrowserQuery
 export declare function compileDetachedWaitExpression(selector: string, strict: boolean, timeout: number): string;
 
 /**
- * Compile a strict, editable fill expression.
+ * Compiles a strict, editable fill expression.
  *
  * @param selector - CSS selector
  * @param value - Value to assign
@@ -2393,7 +2817,7 @@ export declare function compileDetachedWaitExpression(selector: string, strict:
 export declare function compileFillExpression(selector: string, value: string, strict: boolean): string;
 
 /**
- * Compile an auto-retrying in-page predicate wait.
+ * Compiles an auto-retrying in-page predicate wait.
  *
  * @param expression - Value or function expression
  * @param timeout - Maximum wait in milliseconds
@@ -2402,12 +2826,36 @@ export declare function compileFillExpression(selector: string, value: string, s
 export declare function compileFunctionWaitExpression(expression: string, timeout: number): string;
 
 /**
- * Compile a hidden-state locator wait.
+ * 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.
+ *
+ * @remarks
+ * A result whose `JSON.stringify` length exceeds `limit` throws
+ * `Error('BROWSER_RESULT_LIMIT: <length>')` inside the page instead of being
+ * returned — the caller maps that sentinel to a coded
+ * {@link BrowserResultLimitError}. A non-serializable result (`undefined`,
+ * a function, a symbol) makes `JSON.stringify` return `undefined`, so the
+ * length check is skipped and today's undefined-passthrough behavior is
+ * unchanged.
+ *
+ * The expression is placed on its own line inside the wrapper (rather than
+ * inline with the guard code) so a trailing `//` line comment in the
+ * expression cannot swallow the closing guard syntax that follows it.
+ *
+ * @param expression - The candidate JavaScript expression to evaluate
+ * @param limit - Maximum serialized-character length (see {@link BROWSER_RESULT_LIMIT})
+ * @returns The wrapped, guarded expression
+ */
+export declare function compileGuardedEvaluateExpression(expression: string, limit: number): string;
+
+/**
+ * Compiles a hidden-state locator wait.
  */
 export declare function compileHiddenLocatorWaitExpression(query: BrowserQuery, strict: boolean, timeout: number): string;
 
 /**
- * Compile an in-page wait for a hidden selector.
+ * Compiles an in-page wait for a hidden selector.
  *
  * @param selector - CSS selector
  * @param strict - Whether more than one match is an error
@@ -2417,7 +2865,7 @@ export declare function compileHiddenLocatorWaitExpression(query: BrowserQuery,
 export declare function compileHiddenWaitExpression(selector: string, strict: boolean, timeout: number): string;
 
 /**
- * Compile a deep locator query returning its first match.
+ * Compiles a deep locator query returning its first match.
  *
  * @param query - Serializable locator query
  * @returns Runtime expression returning one element or undefined
@@ -2425,7 +2873,7 @@ export declare function compileHiddenWaitExpression(selector: string, strict: bo
 export declare function compileLocatorExpression(query: BrowserQuery): string;
 
 /**
- * Compile a deep, shadow-aware locator query returning every match.
+ * Compiles a deep, shadow-aware locator query returning every match.
  *
  * @param query - Serializable locator query
  * @returns Runtime expression returning an element array
@@ -2433,7 +2881,7 @@ export declare function compileLocatorExpression(query: BrowserQuery): string;
 export declare function compileLocatorListExpression(query: BrowserQuery): string;
 
 /**
- * Compile cleanup for temporary screenshot styles and masks.
+ * Compiles cleanup for temporary screenshot styles and masks.
  *
  * @param token - Preparation token
  * @returns Cleanup expression
@@ -2441,7 +2889,7 @@ export declare function compileLocatorListExpression(query: BrowserQuery): strin
 export declare function compileScreenshotCleanupExpression(token: string): string;
 
 /**
- * Compile temporary animation, caret, and mask setup for a screenshot.
+ * Compiles temporary animation, caret, and mask setup for a screenshot.
  *
  * @param options - Screenshot controls
  * @returns Setup expression or undefined when no preparation is required
@@ -2449,7 +2897,7 @@ export declare function compileScreenshotCleanupExpression(token: string): strin
 export declare function compileScreenshotPreparationExpression(options?: BrowserScreenshotOptions): string | undefined;
 
 /**
- * Compile a strict select expression.
+ * Compiles a strict select expression.
  *
  * @param selector - CSS selector
  * @param values - Option values to select
@@ -2459,21 +2907,21 @@ export declare function compileScreenshotPreparationExpression(options?: Browser
 export declare function compileSelectExpression(selector: string, values: readonly string[], strict: boolean): string;
 
 /**
- * Compile an expression that clears local and session storage.
+ * Compiles an expression that clears local and session storage.
  *
  * @returns In-page clear expression
  */
 export declare function compileStorageClearExpression(): string;
 
 /**
- * Compile an expression that serializes local and session storage.
+ * Compiles an expression that serializes local and session storage.
  *
  * @returns In-page storage expression
  */
 export declare function compileStorageReadExpression(): string;
 
 /**
- * Compile an expression that restores one origin's web storage.
+ * Compiles an expression that restores one origin's web storage.
  *
  * @param origin - Storage values to restore
  * @returns In-page restore expression
@@ -2481,12 +2929,12 @@ export declare function compileStorageReadExpression(): string;
 export declare function compileStorageRestoreExpression(origin: BrowserStorageOrigin): string;
 
 /**
- * Compile a visible-state locator wait.
+ * Compiles a visible-state locator wait.
  */
 export declare function compileVisibleLocatorWaitExpression(query: BrowserQuery, strict: boolean, timeout: number): string;
 
 /**
- * Compile an in-page wait for a visible selector.
+ * Compiles an in-page wait for a visible selector.
  *
  * @param selector - CSS selector
  * @param strict - Whether more than one match is an error
@@ -2496,7 +2944,7 @@ export declare function compileVisibleLocatorWaitExpression(query: BrowserQuery,
 export declare function compileVisibleWaitExpression(selector: string, strict: boolean, timeout: number): string;
 
 /**
- * Compute the CDP Input pressed-button bitmask.
+ * Computes the CDP Input pressed-button bitmask.
  *
  * @param buttons - Currently pressed public mouse buttons
  * @returns Combined CDP pressed-button mask
@@ -2504,7 +2952,7 @@ export declare function compileVisibleWaitExpression(selector: string, strict: b
 export declare function computeBrowserButtons(buttons: readonly BrowserMouseButton[]): number;
 
 /**
- * Compute the CDP Input modifier bitmask.
+ * Computes the CDP Input modifier bitmask.
  *
  * @param modifiers - Canonical modifier names
  * @returns Combined CDP modifier mask
@@ -2512,7 +2960,7 @@ export declare function computeBrowserButtons(buttons: readonly BrowserMouseButt
 export declare function computeBrowserModifiers(modifiers: readonly string[]): number;
 
 /**
- * Concatenate byte chunks without Node-specific buffers.
+ * Concatenates byte chunks without Node-specific buffers.
  *
  * @param chunks - Byte arrays in source order
  * @returns Combined bytes
@@ -2520,7 +2968,7 @@ export declare function computeBrowserModifiers(modifiers: readonly string[]): n
 export declare function concatBytes(chunks: readonly Uint8Array[]): Uint8Array;
 
 /**
- * Convert a typed cookie input into Chromium protocol fields.
+ * Converts a typed cookie input into Chromium protocol fields.
  *
  * @param cookie - Validated public cookie input
  * @returns Protocol cookie record
@@ -2528,7 +2976,7 @@ export declare function concatBytes(chunks: readonly Uint8Array[]): Uint8Array;
 export declare function cookieToProtocol(cookie: BrowserCookieInput): Readonly<Record<string, unknown>>;
 
 /**
- * Build a standards-shaped HAR 1.2 entry from one observed exchange.
+ * Builds a standards-shaped HAR 1.2 entry from one observed exchange.
  *
  * @param pending - Request and optional response captured by the recorder
  * @param duration - Whole exchange duration in milliseconds
@@ -2539,30 +2987,30 @@ export declare function cookieToProtocol(cookie: BrowserCookieInput): Readonly<R
 export declare function createBrowserHAREntry(pending: BrowserHARPending, duration: number, body?: Uint8Array, error?: string): BrowserHAREntry;
 
 /**
- * Create a navigable browser snapshot from decoded serializable data.
+ * Creates a navigable browser snapshot from decoded serializable data.
  *
  * @param input - Captured documents and computed-style names
  * @returns A {@link BrowserSnapshotInterface}
  *
  * @example
  * ```ts
- * import { createBrowserSnapshot, decodeBrowserSnapshot } from '@src/core'
+ * import { createBrowserSnapshot, readBrowserSnapshot } from '@orkestrel/browser'
  *
- * const snapshot = createBrowserSnapshot(decodeBrowserSnapshot(captured, ['display']))
+ * const snapshot = createBrowserSnapshot(readBrowserSnapshot(captured, ['display']))
  * snapshot.find({ name: 'main' })
  * ```
  */
 export declare function createBrowserSnapshot(input: BrowserSnapshotInput): BrowserSnapshotInterface;
 
 /**
- * Create a CDP client bound to the given transport.
+ * Creates a CDP client bound to the given transport.
  *
  * @param options - The transport (and optional timeout) the client uses
  * @returns A {@link CDPClientInterface}
  *
  * @example
  * ```ts
- * import { createCDPClient } from '@src/core'
+ * import { createCDPClient } from '@orkestrel/browser'
  *
  * const client = createCDPClient({ transport })
  * await client.connect()
@@ -2571,7 +3019,7 @@ export declare function createBrowserSnapshot(input: BrowserSnapshotInput): Brow
 export declare function createCDPClient(options: CDPClientOptions): CDPClientInterface;
 
 /**
- * Decode a base64-encoded string into raw bytes.
+ * Decodes a base64-encoded string into raw bytes.
  *
  * @remarks
  * Pure JS implementation — no `Buffer`, no `atob` (DOM-only) — so it runs
@@ -2589,51 +3037,7 @@ export declare function createCDPClient(options: CDPClientOptions): CDPClientInt
 export declare function decodeBase64(text: string): Uint8Array;
 
 /**
- * Decode flattened CDP node attributes.
- *
- * @param value - Candidate string-index array
- * @param strings - Snapshot string table
- * @returns Frozen attribute record
- */
-export declare function decodeBrowserAttributes(value: unknown, strings: readonly string[]): Readonly<Record<string, string>>;
-
-/**
- * Decode a CDP `DOMSnapshot.captureSnapshot` result.
- *
- * @param value - Unknown CDP result
- * @param styles - Requested computed-style names, in protocol order
- * @param limit - Maximum accepted node count
- * @returns A typed serializable browser snapshot
- */
-export declare function decodeBrowserSnapshot(value: unknown, styles?: readonly string[], limit?: number): BrowserSnapshotInput;
-
-/**
- * Decode CDP snapshot sparse boolean data.
- *
- * @param value - Sparse `{ index }` record
- * @returns Set of node indexes whose value is true
- */
-export declare function decodeRareBooleanData(value: unknown): ReadonlySet<number>;
-
-/**
- * Decode CDP snapshot sparse integer data.
- *
- * @param value - Sparse `{ index, value }` record
- * @returns Node-index to integer map
- */
-export declare function decodeRareIntegerData(value: unknown): ReadonlyMap<number, number>;
-
-/**
- * Decode CDP snapshot sparse string data.
- *
- * @param value - Sparse `{ index, value }` record
- * @param strings - Snapshot string table
- * @returns Node-index to string map
- */
-export declare function decodeRareStringData(value: unknown, strings: readonly string[]): ReadonlyMap<number, string>;
-
-/**
- * Encode raw bytes as base64 without relying on Node or DOM globals.
+ * Encodes raw bytes as base64 without relying on Node or DOM globals.
  *
  * @param bytes - Raw input bytes
  * @returns Base64 text
@@ -2641,46 +3045,31 @@ export declare function decodeRareStringData(value: unknown, strings: readonly s
 export declare function encodeBase64(bytes: Uint8Array): string;
 
 /**
- * Wrap 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.
+ * Extracts a keyboard chord such as `Control+Shift+P` into its parts.
  *
- * @remarks
- * A result whose `JSON.stringify` length exceeds `limit` throws
- * `Error('BROWSER_RESULT_LIMIT: <length>')` inside the page instead of being
- * returned — the caller maps that sentinel to a coded
- * {@link BrowserResultLimitError}. A non-serializable result (`undefined`,
- * a function, a symbol) makes `JSON.stringify` return `undefined`, so the
- * length check is skipped and today's undefined-passthrough behavior is
- * unchanged.
- *
- * The expression is placed on its own line inside the wrapper (rather than
- * inline with the guard code) so a trailing `//` line comment in the
- * expression cannot swallow the closing guard syntax that follows it.
- *
- * @param expression - The candidate JavaScript expression to evaluate
- * @param limit - Maximum serialized-character length (see {@link BROWSER_RESULT_LIMIT})
- * @returns The wrapped, guarded expression
+ * @param value - Chord source
+ * @returns Canonical modifiers and terminal key
+ * @throws Thrown when the chord is empty or names an unsupported modifier.
  */
-export declare function guardEvaluateExpression(expression: string, limit: number): string;
+export declare function extractBrowserChord(value: string): BrowserChord;
 
 /**
- * Narrow an unknown value to BrowserError.
+ * Narrows an unknown value to BrowserError.
  *
  * @param value - Value to check
- * @returns True when value is a BrowserError instance
+ * @returns True if value is a BrowserError instance; false otherwise
  */
 export declare function isBrowserError(value: unknown): value is BrowserError;
 
 /**
- * Test whether a browser-node matcher is a declarative query.
+ * Tests whether a browser-node matcher is a declarative query.
  *
  * @param value - Browser-node query or predicate
- * @returns Whether the matcher is a declarative query
+ * @returns True if the matcher is a declarative query; false otherwise
  *
  * @example
  * ```ts
- * import { isBrowserNodeQuery } from '@src/core'
+ * import { isBrowserNodeQuery } from '@orkestrel/browser'
  *
  * isBrowserNodeQuery({ name: 'main' }) // true
  * isBrowserNodeQuery(() => true) // false
@@ -2689,55 +3078,55 @@ export declare function isBrowserError(value: unknown): value is BrowserError;
 export declare function isBrowserNodeQuery(value: BrowserNodeQuery | BrowserNodePredicate): value is BrowserNodeQuery;
 
 /**
- * Test whether a captured node has a non-empty rendered layout box.
+ * Tests whether a captured node has a non-empty rendered layout box.
  *
  * @param node - Captured browser node
- * @returns Whether the snapshot reports a visible layout box
+ * @returns True if the snapshot reports a visible layout box; false otherwise
  */
 export declare function isBrowserNodeVisible(node: BrowserNode): boolean;
 
 /**
- * Narrow an unknown value to BrowserResultLimitError.
+ * Narrows an unknown value to BrowserResultLimitError.
  *
  * @param value - Value to check
- * @returns True when value is a BrowserResultLimitError instance
+ * @returns True if value is a BrowserResultLimitError instance; false otherwise
  */
 export declare function isBrowserResultLimitError(value: unknown): value is BrowserResultLimitError;
 
 /**
- * Narrow an unknown value to BrowserSelectorError.
+ * Narrows an unknown value to BrowserSelectorError.
  *
  * @param value - Value to check
- * @returns True when value is a BrowserSelectorError instance
+ * @returns True if value is a BrowserSelectorError instance; false otherwise
  */
 export declare function isBrowserSelectorError(value: unknown): value is BrowserSelectorError;
 
 /**
- * Narrow an unknown value to CDPConnectionError.
+ * Narrows an unknown value to CDPConnectionError.
  *
  * @param value - Value to check
- * @returns True when value is a CDPConnectionError instance
+ * @returns True if value is a CDPConnectionError instance; false otherwise
  */
 export declare function isCDPConnectionError(value: unknown): value is CDPConnectionError;
 
 /**
- * Narrow an unknown value to CDPError.
+ * Narrows an unknown value to CDPError.
  *
  * @param value - Value to check
- * @returns True when value is a CDPError instance
+ * @returns True if value is a CDPError instance; false otherwise
  */
 export declare function isCDPError(value: unknown): value is CDPError;
 
 /**
- * Narrow an unknown value to CDPTimeoutError.
+ * Narrows an unknown value to CDPTimeoutError.
  *
  * @param value - Value to check
- * @returns True when value is a CDPTimeoutError instance
+ * @returns True if value is a CDPTimeoutError instance; false otherwise
  */
 export declare function isCDPTimeoutError(value: unknown): value is CDPTimeoutError;
 
 /**
- * Normalize one key to CDP keyboard event data.
+ * Normalizes one key to CDP keyboard event data.
  *
  * @param value - Key value or canonical key name
  * @returns Normalized key data
@@ -2745,43 +3134,43 @@ export declare function isCDPTimeoutError(value: unknown): value is CDPTimeoutEr
 export declare function keyToBrowserInput(value: string): BrowserKey;
 
 /**
- * Match a decoded cookie against one request URL.
+ * Matches a decoded cookie against one request URL.
  *
  * @param cookie - Decoded context cookie
  * @param value - Candidate absolute URL
- * @returns Whether domain, path, and secure constraints match
+ * @returns True if domain, path, and secure constraints match; false otherwise
  */
 export declare function matchesBrowserCookieURL(cookie: BrowserCookie, value: string): boolean;
 
 /**
- * Test a captured node against a declarative query.
+ * Tests a captured node against a declarative query.
  *
  * @param node - Captured browser node
  * @param query - Fields every candidate must satisfy
- * @returns Whether the node matches
+ * @returns True if the node matches; false otherwise
  */
 export declare function matchesBrowserNode(node: BrowserNode, query: BrowserNodeQuery): boolean;
 
 /**
- * Match a request against route criteria.
+ * Matches a request against route criteria.
  *
  * @param request - Observed request
  * @param query - Match criteria
- * @returns Whether every supplied criterion matches
+ * @returns True if every supplied criterion matches; false otherwise
  */
 export declare function matchesBrowserRoute(request: BrowserRequest, query: BrowserRouteQuery): boolean;
 
 /**
- * Match a URL using Chromium-style `*` and `**` glob segments.
+ * Matches a URL using Chromium-style `*` and `**` glob segments.
  *
  * @param url - Candidate URL
  * @param pattern - Glob pattern
- * @returns Whether the whole URL matches
+ * @returns True if the whole URL matches; false otherwise
  */
 export declare function matchesBrowserURL(url: string, pattern: string): boolean;
 
 /**
- * Convert typed media preferences to Chromium emulated media features.
+ * Converts typed media preferences to Chromium emulated media features.
  *
  * @param media - Public media configuration
  * @returns Protocol feature records
@@ -2789,7 +3178,7 @@ export declare function matchesBrowserURL(url: string, pattern: string): boolean
 export declare function mediaToFeatures(media: BrowserMedia): ReadonlyArray<Readonly<Record<string, string>>>;
 
 /**
- * Normalize a raw list of recorded codegen actions.
+ * Normalizes a raw list of recorded codegen actions.
  *
  * @remarks
  * Collapses consecutive `fill` actions on the same selector into the latest
@@ -2803,15 +3192,158 @@ export declare function mediaToFeatures(media: BrowserMedia): ReadonlyArray<Read
 export declare function normalizeCodegenActions(actions: readonly BrowserCodegenAction[]): readonly BrowserCodegenAction[];
 
 /**
- * Parse a keyboard chord such as `Control+Shift+P`.
+ * Coerces a string-valued Accessibility-domain AXValue to a string, or
+ * `undefined` off-shape.
  *
- * @param value - Chord source
- * @returns Canonical modifiers and terminal key
+ * @param value - Unknown AX value
+ * @returns String or undefined
+ */
+export declare function parseBrowserAXString(value: unknown): string | undefined;
+
+/**
+ * Coerces one Runtime binding invocation to a `BrowserBindingCall`, or
+ * `undefined` off-shape.
+ *
+ * @param value - Unknown `Runtime.bindingCalled` parameters
+ * @returns Valid call or undefined
  */
-export declare function parseBrowserChord(value: string): BrowserChord;
+export declare function parseBrowserBindingCall(value: unknown): BrowserBindingCall | undefined;
 
 /**
- * Parse a codegen binding payload into a typed action.
+ * Coerces one `Runtime.consoleAPICalled` event to a `BrowserConsoleMessage`, or
+ * `undefined` off-shape.
+ *
+ * @param value - Unknown event parameters
+ * @returns Console message or undefined
+ */
+export declare function parseBrowserConsoleMessage(value: unknown): BrowserConsoleMessage | undefined;
+
+/**
+ * Coerces an optional Chromium cookie partition key to a
+ * `BrowserCookiePartition`, or `undefined` off-shape.
+ *
+ * @param value - Unknown partition value
+ * @returns Partition key or undefined
+ */
+export declare function parseBrowserCookiePartition(value: unknown): BrowserCookiePartition | undefined;
+
+/**
+ * Coerces one `Browser.downloadProgress` event to a `BrowserDownloadProgress`,
+ * or `undefined` off-shape.
+ *
+ * @param value - Unknown event parameters
+ * @returns Download id and progress, or undefined
+ */
+export declare function parseBrowserDownloadProgress(value: unknown): readonly [id: string, progress: BrowserDownloadProgress] | undefined;
+
+/**
+ * Coerces one `Browser.downloadWillBegin` event to a `BrowserDownloadStart`, or
+ * `undefined` off-shape.
+ *
+ * @param value - Unknown event parameters
+ * @returns Download start or undefined
+ */
+export declare function parseBrowserDownloadStart(value: unknown): BrowserDownloadStart | undefined;
+
+/**
+ * Coerces one `Runtime.exceptionThrown` event to a `BrowserPageError`, or
+ * `undefined` off-shape.
+ *
+ * @param value - Unknown event parameters
+ * @returns Page error or undefined
+ */
+export declare function parseBrowserPageError(value: unknown): BrowserPageError | undefined;
+
+/**
+ * Coerces a CDP snapshot rectangle to a `BrowserRect`, or `undefined`
+ * off-shape.
+ *
+ * @param value - Candidate four-number array
+ * @returns A rectangle, or undefined
+ */
+export declare function parseBrowserRect(value: unknown): BrowserRect | undefined;
+
+/**
+ * Coerces one `Network.requestWillBeSent` or `Fetch.requestPaused` event to a
+ * `BrowserRequest`, or `undefined` off-shape.
+ *
+ * @param value - Unknown event parameters
+ * @returns Request or undefined
+ */
+export declare function parseBrowserRequest(value: unknown): BrowserRequest | undefined;
+
+/**
+ * Coerces one `Network.loadingFailed` event to a `BrowserRequestFailure`, or
+ * `undefined` off-shape.
+ *
+ * @param value - Unknown event parameters
+ * @returns Failure or undefined
+ */
+export declare function parseBrowserRequestFailure(value: unknown): BrowserRequestFailure | undefined;
+
+/**
+ * Coerces one `Network.responseReceived` event to a `BrowserResponse`, or
+ * `undefined` off-shape.
+ *
+ * @param value - Unknown event parameters
+ * @returns Response or undefined
+ */
+export declare function parseBrowserResponse(value: unknown): BrowserResponse | undefined;
+
+/**
+ * Coerces one Chromium response object plus its event identity to a
+ * `BrowserResponse`, or `undefined` off-shape.
+ *
+ * @param value - Unknown response object
+ * @param id - Request id
+ * @param loader - Loader id
+ * @param frame - Optional frame id
+ * @param timestamp - Monotonic event timestamp
+ * @returns Response or undefined
+ */
+export declare function parseBrowserResponseRecord(value: unknown, id: string, loader: string, frame: string | undefined, timestamp: number): BrowserResponse | undefined;
+
+/**
+ * Coerces Chromium TLS security details to a `BrowserSecurity`, or `undefined`
+ * off-shape.
+ *
+ * @param value - Unknown security details
+ * @returns Security metadata or undefined
+ */
+export declare function parseBrowserSecurity(value: unknown): BrowserSecurity | undefined;
+
+/**
+ * Coerces Chromium response timing to a `BrowserTiming`, or `undefined`
+ * off-shape.
+ *
+ * @param value - Unknown timing object
+ * @returns Timing or undefined
+ */
+export declare function parseBrowserTiming(value: unknown): BrowserTiming | undefined;
+
+/**
+ * Coerces one named start/end pair of Chromium network timing to a
+ * `BrowserTimingRange`, or `undefined` off-shape.
+ *
+ * @param value - Unknown timing object
+ * @param start - Start field
+ * @param end - End field
+ * @returns Timing range or undefined
+ */
+export declare function parseBrowserTimingRange(value: unknown, start: string, end: string): BrowserTimingRange | undefined;
+
+/**
+ * Coerces one WebSocket frame event to a `BrowserWebSocketFrame`, or
+ * `undefined` off-shape.
+ *
+ * @param value - Unknown event parameters
+ * @returns Frame or undefined
+ */
+export declare function parseBrowserWebSocketFrame(value: unknown): BrowserWebSocketFrame | undefined;
+
+/**
+ * Coerces a codegen binding payload string to a `BrowserCodegenAction`, or
+ * `undefined` off-shape.
  *
  * @remarks
  * The in-page recorder script calls the CDP binding with a JSON string
@@ -2824,64 +3356,73 @@ export declare function parseBrowserChord(value: string): BrowserChord;
 export declare function parseCodegenActionPayload(payload: unknown): BrowserCodegenAction | undefined;
 
 /**
- * Decode Accessibility-domain nodes into a flat serializable tree.
+ * Coerces a `Page.frameNavigated` CDP event to a `navigate` codegen action, or
+ * `undefined` off-shape.
  *
- * @param value - Unknown full or partial AX-tree result
- * @returns Valid accessibility snapshot
+ * @remarks
+ * Only the top-level (main) frame's navigation is recorded — a frame
+ * carrying a `parentId` is a sub-frame and is ignored.
+ *
+ * @param params - The CDP `Page.frameNavigated` event params
+ * @returns A `navigate` action, or `undefined` when the event is not a
+ *   top-level navigation with a resolvable URL
  */
-export declare function readBrowserAccessibility(value: unknown): BrowserAccessibilitySnapshot;
+export declare function parseCodegenNavigateAction(params: Readonly<Record<string, unknown>>): BrowserCodegenAction | undefined;
 
 /**
- * Decode a string-valued Accessibility-domain AXValue.
+ * Coerces an unknown value to an all-number array, or `undefined` off-shape.
  *
- * @param value - Unknown AX value
- * @returns String or undefined
+ * @param value - Candidate value
+ * @returns The number array, or undefined
  */
-export declare function readBrowserAXString(value: unknown): string | undefined;
+export declare function parseNumberArray(value: unknown): readonly number[] | undefined;
 
 /**
- * Decode an Accessibility-domain AXValue.
+ * Coerces one CDP snapshot string-table index to its string, or `undefined`
+ * off-shape.
  *
- * @param value - Unknown AX value
- * @returns Underlying value
+ * @param strings - Snapshot string table
+ * @param index - Candidate string index
+ * @returns The resolved string, or undefined
  */
-export declare function readBrowserAXValue(value: unknown): unknown;
+export declare function parseSnapshotString(strings: readonly string[], index: unknown): string | undefined;
 
 /**
- * Decode one Runtime binding invocation.
+ * Decodes Accessibility-domain nodes into a flat serializable tree.
  *
- * @param value - Unknown `Runtime.bindingCalled` parameters
- * @returns Valid call or undefined
+ * @param value - Unknown full or partial AX-tree result
+ * @returns Valid accessibility snapshot
  */
-export declare function readBrowserBindingCall(value: unknown): BrowserBindingCall | undefined;
+export declare function readBrowserAccessibility(value: unknown): BrowserAccessibilitySnapshot;
 
 /**
- * Decode one `Runtime.consoleAPICalled` event.
+ * Decodes flattened CDP node attributes.
  *
- * @param value - Unknown event parameters
- * @returns Console message or undefined
+ * @param value - Candidate string-index array
+ * @param strings - Snapshot string table
+ * @returns Frozen attribute record
  */
-export declare function readBrowserConsoleMessage(value: unknown): BrowserConsoleMessage | undefined;
+export declare function readBrowserAttributes(value: unknown, strings: readonly string[]): Readonly<Record<string, string>>;
 
 /**
- * Decode one Chromium cookie.
+ * Decodes an Accessibility-domain AXValue.
  *
- * @param value - Unknown cookie record
- * @param index - Source array position for diagnostics
- * @returns Valid cookie
+ * @param value - Unknown AX value
+ * @returns Underlying value
  */
-export declare function readBrowserCookie(value: unknown, index: number): BrowserCookie;
+export declare function readBrowserAXValue(value: unknown): unknown;
 
 /**
- * Decode an optional Chromium cookie partition key.
+ * Decodes one Chromium cookie.
  *
- * @param value - Unknown partition value
- * @returns Partition key or undefined
+ * @param value - Unknown cookie record
+ * @param index - Source array position for diagnostics
+ * @returns Valid cookie
  */
-export declare function readBrowserCookiePartition(value: unknown): BrowserCookiePartition | undefined;
+export declare function readBrowserCookie(value: unknown, index: number): BrowserCookie;
 
 /**
- * Decode cookies returned by `Storage.getCookies`.
+ * Decodes cookies returned by `Storage.getCookies`.
  *
  * @param value - Unknown protocol result
  * @returns Valid cookies
@@ -2889,7 +3430,7 @@ export declare function readBrowserCookiePartition(value: unknown): BrowserCooki
 export declare function readBrowserCookies(value: unknown): readonly BrowserCookie[];
 
 /**
- * Decode coverage ranges.
+ * Decodes coverage ranges.
  *
  * @param value - Unknown ranges
  * @param script - Script index for diagnostics
@@ -2898,23 +3439,7 @@ export declare function readBrowserCookies(value: unknown): readonly BrowserCook
 export declare function readBrowserCoverageRanges(value: unknown, script: number): readonly BrowserCoverageRange[];
 
 /**
- * Decode one `Browser.downloadProgress` event.
- *
- * @param value - Unknown event parameters
- * @returns Download id and progress, or undefined
- */
-export declare function readBrowserDownloadProgress(value: unknown): readonly [id: string, progress: BrowserDownloadProgress] | undefined;
-
-/**
- * Decode one `Browser.downloadWillBegin` event.
- *
- * @param value - Unknown event parameters
- * @returns Download start or undefined
- */
-export declare function readBrowserDownloadStart(value: unknown): BrowserDownloadStart | undefined;
-
-/**
- * Decode a flattened CDP `Page.getFrameTree` result.
+ * Decodes a flattened CDP `Page.getFrameTree` result.
  *
  * @param value - Unknown CDP result
  * @returns Frame metadata in depth-first, main-frame-first order
@@ -2922,7 +3447,7 @@ export declare function readBrowserDownloadStart(value: unknown): BrowserDownloa
 export declare function readBrowserFrames(value: unknown): readonly BrowserFrameInfo[];
 
 /**
- * Decode a Chromium Headers object into string values.
+ * Decodes a Chromium Headers object into string values.
  *
  * @param value - Unknown headers
  * @returns Frozen-compatible header record
@@ -2930,7 +3455,7 @@ export declare function readBrowserFrames(value: unknown): readonly BrowserFrame
 export declare function readBrowserHeaders(value: unknown): Readonly<Record<string, string>>;
 
 /**
- * Decode Performance-domain metrics.
+ * Decodes Performance-domain metrics.
  *
  * @param value - Unknown metrics result
  * @returns Valid metrics
@@ -2938,15 +3463,7 @@ export declare function readBrowserHeaders(value: unknown): Readonly<Record<stri
 export declare function readBrowserMetrics(value: unknown): readonly BrowserMetric[];
 
 /**
- * Decode one `Runtime.exceptionThrown` event.
- *
- * @param value - Unknown event parameters
- * @returns Page error or undefined
- */
-export declare function readBrowserPageError(value: unknown): BrowserPageError | undefined;
-
-/**
- * Decode one CPU profile.
+ * Decodes one CPU profile.
  *
  * @param value - Unknown `Profiler.stop` result
  * @returns Valid profile
@@ -2954,7 +3471,7 @@ export declare function readBrowserPageError(value: unknown): BrowserPageError |
 export declare function readBrowserProfile(value: unknown): BrowserProfile;
 
 /**
- * Decode a CPU profile call frame.
+ * Decodes a CPU profile call frame.
  *
  * @param value - Unknown call frame
  * @param node - Node index for diagnostics
@@ -2963,7 +3480,7 @@ export declare function readBrowserProfile(value: unknown): BrowserProfile;
 export declare function readBrowserProfileFrame(value: unknown, node: number): BrowserProfileFrame;
 
 /**
- * Decode the first `DOM.getContentQuads` quad and its center.
+ * Decodes the first `DOM.getContentQuads` quad and its center.
  *
  * @param value - Unknown CDP result
  * @returns Decoded quad
@@ -2971,15 +3488,7 @@ export declare function readBrowserProfileFrame(value: unknown, node: number): B
 export declare function readBrowserQuad(value: unknown): BrowserQuad;
 
 /**
- * Decode a CDP snapshot rectangle.
- *
- * @param value - Candidate four-number array
- * @returns A rectangle, or undefined
- */
-export declare function readBrowserRect(value: unknown): BrowserRect | undefined;
-
-/**
- * Decode a Runtime remote object's printable value.
+ * Decodes a Runtime remote object's printable value.
  *
  * @param value - Unknown remote object
  * @returns By-value data or a description
@@ -2987,43 +3496,7 @@ export declare function readBrowserRect(value: unknown): BrowserRect | undefined
 export declare function readBrowserRemoteValue(value: unknown): unknown;
 
 /**
- * Decode one `Network.requestWillBeSent` or `Fetch.requestPaused` event.
- *
- * @param value - Unknown event parameters
- * @returns Request or undefined
- */
-export declare function readBrowserRequest(value: unknown): BrowserRequest | undefined;
-
-/**
- * Decode one `Network.loadingFailed` event.
- *
- * @param value - Unknown event parameters
- * @returns Failure or undefined
- */
-export declare function readBrowserRequestFailure(value: unknown): BrowserRequestFailure | undefined;
-
-/**
- * Decode one `Network.responseReceived` event.
- *
- * @param value - Unknown event parameters
- * @returns Response or undefined
- */
-export declare function readBrowserResponse(value: unknown): BrowserResponse | undefined;
-
-/**
- * Decode one Chromium response object with its event identity.
- *
- * @param value - Unknown response object
- * @param id - Request id
- * @param loader - Loader id
- * @param frame - Optional frame id
- * @param timestamp - Monotonic event timestamp
- * @returns Response or undefined
- */
-export declare function readBrowserResponseRecord(value: unknown, id: string, loader: string, frame: string | undefined, timestamp: number): BrowserResponse | undefined;
-
-/**
- * Decode JavaScript precise coverage.
+ * Decodes JavaScript precise coverage.
  *
  * @param value - Unknown `Profiler.takePreciseCoverage` result
  * @returns Script coverage
@@ -3031,7 +3504,7 @@ export declare function readBrowserResponseRecord(value: unknown, id: string, lo
 export declare function readBrowserScriptCoverage(value: unknown): readonly BrowserScriptCoverage[];
 
 /**
- * Decode `Page.addScriptToEvaluateOnNewDocument` result.
+ * Decodes the `Page.addScriptToEvaluateOnNewDocument` result.
  *
  * @param value - Unknown protocol result
  * @returns Script identifier
@@ -3039,15 +3512,17 @@ export declare function readBrowserScriptCoverage(value: unknown): readonly Brow
 export declare function readBrowserScriptIdentifier(value: unknown): string;
 
 /**
- * Decode Chromium TLS security details.
+ * Decodes a CDP `DOMSnapshot.captureSnapshot` result.
  *
- * @param value - Unknown security details
- * @returns Security metadata or undefined
+ * @param value - Unknown CDP result
+ * @param styles - Requested computed-style names, in protocol order
+ * @param limit - Maximum accepted node count
+ * @returns A typed serializable browser snapshot
  */
-export declare function readBrowserSecurity(value: unknown): BrowserSecurity | undefined;
+export declare function readBrowserSnapshot(value: unknown, styles?: readonly string[], limit?: number): BrowserSnapshotInput;
 
 /**
- * Decode a Chromium runtime stack trace.
+ * Decodes a Chromium runtime stack trace.
  *
  * @param value - Unknown stack trace or call-frame list
  * @returns Valid stack frames
@@ -3055,7 +3530,7 @@ export declare function readBrowserSecurity(value: unknown): BrowserSecurity | u
 export declare function readBrowserStack(value: unknown): readonly BrowserStackFrame[];
 
 /**
- * Decode a list of web-storage entries.
+ * Decodes a list of web-storage entries.
  *
  * @param value - Unknown entry list
  * @param origin - Origin used for diagnostics
@@ -3065,7 +3540,7 @@ export declare function readBrowserStack(value: unknown): readonly BrowserStackF
 export declare function readBrowserStorageEntries(value: unknown, origin: string, storage: 'local' | 'session'): readonly BrowserStorageEntry[];
 
 /**
- * Decode one in-page web-storage snapshot.
+ * Decodes one in-page web-storage snapshot.
  *
  * @param value - Unknown evaluation result
  * @param origin - Origin represented by the result
@@ -3074,7 +3549,7 @@ export declare function readBrowserStorageEntries(value: unknown, origin: string
 export declare function readBrowserStorageOrigin(value: unknown, origin: string): BrowserStorageOrigin;
 
 /**
- * Decode one `IO.read` response.
+ * Decodes one `IO.read` response.
  *
  * @param value - Unknown protocol result
  * @returns Valid stream chunk
@@ -3082,7 +3557,7 @@ export declare function readBrowserStorageOrigin(value: unknown, origin: string)
 export declare function readBrowserStreamChunk(value: unknown): BrowserStreamChunk;
 
 /**
- * Decode CSS rule usage.
+ * Decodes CSS rule usage.
  *
  * @param value - Unknown `CSS.stopRuleUsageTracking` result
  * @returns Stylesheet coverage
@@ -3090,71 +3565,40 @@ export declare function readBrowserStreamChunk(value: unknown): BrowserStreamChu
 export declare function readBrowserStyleCoverage(value: unknown): readonly BrowserStyleCoverage[];
 
 /**
- * Decode Chromium response timing.
- *
- * @param value - Unknown timing object
- * @returns Timing or undefined
- */
-export declare function readBrowserTiming(value: unknown): BrowserTiming | undefined;
-
-/**
- * Decode one start/end pair from Chromium network timing data.
- *
- * @param value - Unknown timing object
- * @param start - Start field
- * @param end - End field
- * @returns Timing range or undefined
- */
-export declare function readBrowserTimingRange(value: unknown, start: string, end: string): BrowserTimingRange | undefined;
-
-/**
- * Decode one WebSocket frame event.
- *
- * @param value - Unknown event parameters
- * @returns Frame or undefined
- */
-export declare function readBrowserWebSocketFrame(value: unknown): BrowserWebSocketFrame | undefined;
-
-/**
- * Derive a `navigate` codegen action from a `Page.frameNavigated` CDP event.
+ * Decodes one CDP `Runtime.evaluate` result.
  *
- * @remarks
- * Only the top-level (main) frame's navigation is recorded — a frame
- * carrying a `parentId` is a sub-frame and is ignored.
- *
- * @param params - The CDP `Page.frameNavigated` event params
- * @returns A `navigate` action, or `undefined` when the event is not a
- *   top-level navigation with a resolvable URL
+ * @param value - Unknown CDP result
+ * @returns The returned by-value payload, or undefined
  */
-export declare function readCodegenNavigateAction(params: Readonly<Record<string, unknown>>): BrowserCodegenAction | undefined;
+export declare function readEvaluationResult(value: unknown): unknown;
 
 /**
- * Decode one CDP `Runtime.evaluate` result.
+ * Decodes CDP snapshot sparse boolean data.
  *
- * @param value - Unknown CDP result
- * @returns The returned by-value payload, or undefined
+ * @param value - Sparse `{ index }` record
+ * @returns Set of node indexes whose value is true
  */
-export declare function readEvaluationResult(value: unknown): unknown;
+export declare function readRareBooleanData(value: unknown): ReadonlySet<number>;
 
 /**
- * Read an unknown value as an all-number array.
+ * Decodes CDP snapshot sparse integer data.
  *
- * @param value - Candidate value
- * @returns The number array, or undefined
+ * @param value - Sparse `{ index, value }` record
+ * @returns Node-index to integer map
  */
-export declare function readNumberArray(value: unknown): readonly number[] | undefined;
+export declare function readRareIntegerData(value: unknown): ReadonlyMap<number, number>;
 
 /**
- * Resolve one index from a CDP snapshot string table.
+ * Decodes CDP snapshot sparse string data.
  *
+ * @param value - Sparse `{ index, value }` record
  * @param strings - Snapshot string table
- * @param index - Candidate string index
- * @returns The resolved string, or undefined
+ * @returns Node-index to string map
  */
-export declare function readSnapshotString(strings: readonly string[], index: unknown): string | undefined;
+export declare function readRareStringData(value: unknown, strings: readonly string[]): ReadonlyMap<number, string>;
 
 /**
- * Require an evaluated browser value to be a string.
+ * Requires an evaluated browser value to be a string.
  *
  * @param value - Candidate evaluated value
  * @param field - Human-readable field name used in the error
@@ -3163,64 +3607,85 @@ export declare function readSnapshotString(strings: readonly string[], index: un
 export declare function requireBrowserString(value: unknown, field: string): string;
 
 /**
- * Pluggable sink for persisting screenshot bytes to a path.
+ * Awaits every teardown step in order and returns the first failure.
  *
  * @remarks
- * Core never touches a filesystem directly — a page accepts an optional
- * writer (server supplies an `fs`-backed implementation) and calls it when a
- * screenshot request carries a `path`.
+ * A teardown runs every step even after one of them fails, so a later release
+ * is never skipped by an earlier fault, and the failure the caller reports is
+ * the first one. The failure is returned rather than thrown, so the caller
+ * keeps the cleanup that must still run after the steps and decides where the
+ * throw belongs. A step may throw any value, `undefined` and `null` included,
+ * so the first throw is retained by a separate flag rather than by testing the
+ * retained value.
+ *
+ * @param steps - The teardown steps, in the order they must run
+ * @returns The value the first failing step threw, or undefined when no step threw
+ *
+ * @example
+ * ```ts
+ * import { settleBrowserTeardown } from '@orkestrel/browser'
+ *
+ * const failure = await settleBrowserTeardown(
+ * 	() => client.close(),
+ * 	() => transport.close(),
+ * )
+ * if (failure !== undefined) throw failure
+ * ```
  */
-export declare interface ScreenshotWriterInterface {
-    write(path: string, data: Uint8Array): Promise<void>;
-}
+export declare function settleBrowserTeardown(...steps: readonly BrowserTeardownFunction[]): Promise<unknown>;
 
-/** Encode UTF-8 text as bytes. */
+/** Encodes UTF-8 text as bytes. */
 export declare function textToBytes(value: string): Uint8Array;
 
 /**
- * Validate Accessibility-domain snapshot bounds.
+ * Validates Accessibility-domain snapshot bounds.
  *
  * @param options - Public accessibility snapshot options
  */
 export declare function validateBrowserAccessibilityOptions(options?: BrowserAccessibilityOptions): void;
 
 /**
- * Validate shared trusted-input options.
- *
- * @param options - Candidate action options
- */
-export declare function validateBrowserActionOptions(options?: BrowserActionOptions): void;
-
-/**
- * Validate isolated-context options before creating remote state.
+ * Validates isolated-context options before creating remote state.
  *
  * @param options - Public context configuration
  */
 export declare function validateBrowserContextOptions(options?: BrowserContextOptions): void;
 
 /**
- * Validate context emulation boundaries before partial application.
+ * Validates context emulation boundaries before partial application.
  *
  * @param options - Public emulation configuration
  */
 export declare function validateBrowserEmulationOptions(options: BrowserEmulationOptions): void;
 
 /**
- * Validate the HAR 1.2 fields required for deterministic replay.
+ * Validates the HAR 1.2 fields required for deterministic replay.
  *
  * @param value - Candidate archive
  */
 export declare function validateBrowserHAR(value: unknown): asserts value is BrowserHAR;
 
 /**
- * Validate viewport input coordinates.
+ * Validates the bounded keys of one trusted-input operation.
+ *
+ * @remarks
+ * The parameter is `BrowserOperationOptions`, so one validator answers for a
+ * locator click, a locator drag, a mouse click, a mouse drag, and keyboard
+ * entry alike.
+ *
+ * @param options - Candidate input options
+ */
+export declare function validateBrowserInputOptions(options?: BrowserOperationOptions): void;
+
+/**
+ * Validates viewport input coordinates.
  *
  * @param point - Candidate point
  */
 export declare function validateBrowserPoint(point: BrowserPoint): void;
 
 /**
- * Validate a finite numeric range.
+ * Validates a finite numeric range.
  *
  * @param value - Candidate number
  * @param field - Diagnostic field
@@ -3231,14 +3696,14 @@ export declare function validateBrowserPoint(point: BrowserPoint): void;
 export declare function validateBrowserRange(value: number, field: string, minimum: number, maximum: number, inclusive?: boolean): void;
 
 /**
- * Validate a public browser timeout before protocol work begins.
+ * Validates a public browser timeout before protocol work begins.
  *
  * @param timeout - Timeout in milliseconds
  */
 export declare function validateBrowserTimeout(timeout: number): void;
 
 /**
- * Validate Chromium viewport metrics.
+ * Validates Chromium viewport metrics.
  *
  * @param viewport - Public viewport configuration
  */