@orkestrel/browser 0.0.3 → 0.0.6

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

@@ -1,6 +1,25 @@
+import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 
+/**
+ * Return the nearest-first ancestor chain for a captured browser node.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param node - Descendant node
+ * @returns Nearest-first ancestor list
+ */
+export declare function ancestorsOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): readonly BrowserNode[];
+
+/**
+ * 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}. */
 export declare const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 
@@ -33,6 +52,21 @@ export declare const BROWSER_DEFAULT_VIEWPORT_HEIGHT = 720;
 /** Default viewport width in pixels. */
 export declare const BROWSER_DEFAULT_VIEWPORT_WIDTH = 1280;
 
+/** Isolated-world name used for iframe evaluation. */
+export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
+
+/** Tool identity embedded in HAR 1.2 documents. */
+export declare const BROWSER_HAR_CREATOR: Readonly<{
+    name: "@orkestrel/browser";
+    version: "0.0.5";
+}>;
+
+/** CDP Input modifier bit values keyed by canonical key name. */
+export declare const BROWSER_KEY_MODIFIERS: Readonly<Record<string, number>>;
+
+/** CDP Input pressed-button bit values keyed by public mouse button. */
+export declare const BROWSER_MOUSE_BUTTON_MASKS: Readonly<Record<BrowserMouseButton, number>>;
+
 /**
  * Maximum serialized-character length for an `evaluate()`/`content()` result,
  * enforced IN-PAGE before the result is returned to CDP.
@@ -75,6 +109,15 @@ 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. */
+export declare const BROWSER_SCREENSHOT_ATTRIBUTE = "data-orkestrel-screenshot";
+
+/** 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. */
+export declare const BROWSER_STABLE_FRAME_COUNT = 2;
+
 /**
  * Bound (in milliseconds) on the best-effort `Page.stopLoading` call issued
  * after a failed `navigate()`.
@@ -87,9 +130,48 @@ export declare const BROWSER_RESULT_LIMIT_SENTINEL_PREFIX = "[[ORKESTREL_BROWSER
  */
 export declare const BROWSER_STOP_LOADING_TIMEOUT_MS = 1000;
 
+/** Attribute used by the semantic test-id selector. */
+export declare const BROWSER_TEST_ID_ATTRIBUTE = "data-testid";
+
 /** 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.
+ */
+export declare class BrowserAccessibility implements BrowserAccessibilityInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface);
+    snapshot(options?: BrowserAccessibilityOptions): Promise<BrowserAccessibilitySnapshot>;
+}
+
+/** Accessibility tree inspection. */
+export declare interface BrowserAccessibilityInterface {
+    snapshot(options?: BrowserAccessibilityOptions): Promise<BrowserAccessibilitySnapshot>;
+}
+
+/** Accessibility snapshot options. */
+export declare interface BrowserAccessibilityOptions {
+    readonly root?: number;
+    readonly depth?: number;
+}
+
+/** Serializable accessibility-tree snapshot. */
+export declare interface BrowserAccessibilitySnapshot {
+    readonly roots: readonly string[];
+    readonly nodes: readonly BrowserAXNode[];
+}
+
+/** Actionability checks performed before locator input. */
+export declare interface BrowserActionabilityOptions {
+    readonly visible?: boolean;
+    readonly stable?: boolean;
+    readonly events?: boolean;
+    readonly enabled?: boolean;
+    readonly editable?: boolean;
+    readonly position?: BrowserPoint;
+}
+
 /**
  * Options for element interaction (click, fill, select, wait).
  *
@@ -98,8 +180,75 @@ export declare const BROWSER_WAIT_POLL_INTERVAL_MS = 100;
  */
 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. */
+export declare interface BrowserAXNode {
+    readonly id: string;
+    readonly parent: string | undefined;
+    readonly children: readonly string[];
+    readonly backend: number | undefined;
+    readonly frame: string | undefined;
+    readonly ignored: boolean;
+    readonly role: string | undefined;
+    readonly name: string | undefined;
+    readonly description: string | undefined;
+    readonly value: unknown;
+    readonly properties: Readonly<Record<string, unknown>>;
 }
 
+/** Decoded page-to-host binding call. */
+export declare interface BrowserBindingCall {
+    readonly id: string;
+    readonly name: string;
+    readonly args: readonly unknown[];
+    readonly context: number;
+}
+
+/** Host function exposed into page JavaScript. */
+export declare type BrowserBindingHandler = (...args: unknown[]) => unknown | Promise<unknown>;
+
+/** Parsed keyboard chord. */
+export declare interface BrowserChord {
+    readonly modifiers: readonly string[];
+    readonly key: string;
+}
+
+/**
+ * Chromium virtual-time budget controls for deterministic page timers.
+ */
+export declare class BrowserClock implements BrowserClockInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface);
+    get installed(): boolean;
+    install(time?: number): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    advance(ms: number): Promise<void>;
+    uninstall(): Promise<void>;
+}
+
+/** Chromium virtual-time control for deterministic page timers. */
+export declare interface BrowserClockInterface {
+    readonly installed: boolean;
+    install(time?: number): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    advance(ms: number): Promise<void>;
+    uninstall(): Promise<void>;
+}
+
+/**
+ * Records page navigation and form interactions and compiles replayable scripts.
+ */
 export declare class BrowserCodegen implements BrowserCodegenInterface {
     #private;
     constructor(client: CDPClientInterface, sessionId: string, options?: BrowserCodegenOptions);
@@ -179,9 +328,11 @@ export declare type BrowserCodegenLanguage = 'javascript' | 'typescript';
  *
  * @remarks
  * - `on` — initial event listeners wired at construction
+ * - `error` — observer error handler forwarded to the emitter
  */
 export declare interface BrowserCodegenOptions {
     readonly on?: EmitterHooks<BrowserCodegenEventMap>;
+    readonly error?: EmitterErrorHandler;
 }
 
 /**
@@ -194,6 +345,15 @@ export declare interface BrowserCodegenScriptOptions {
     readonly language?: BrowserCodegenLanguage;
 }
 
+/** One console API call. */
+export declare interface BrowserConsoleMessage {
+    readonly level: string;
+    readonly text: string;
+    readonly values: readonly unknown[];
+    readonly timestamp: number;
+    readonly stack: readonly BrowserStackFrame[];
+}
+
 /**
  * Result of page content extraction.
  *
@@ -210,17 +370,32 @@ export declare interface BrowserContentResult {
     readonly text: string;
 }
 
+/**
+ * Owns pages and shared state inside one Chromium browser context.
+ */
 export declare class BrowserContext implements BrowserContextInterface {
     #private;
-    constructor(client: CDPClientInterface, id?: string, viewport?: BrowserViewport, writer?: ScreenshotWriterInterface);
+    constructor(client: CDPClientInterface, id?: string, viewport?: BrowserViewport, writer?: ScreenshotWriterInterface, emulation?: BrowserEmulationOptions, downloads?: BrowserDownloadOptions);
+    get emitter(): EmitterInterface<BrowserContextEventMap>;
     get id(): string | undefined;
+    get cookies(): BrowserCookieManagerInterface;
+    get permissions(): BrowserPermissionManagerInterface;
+    get storage(): BrowserStorageManagerInterface;
+    get emulation(): BrowserEmulationManagerInterface;
     page(index?: number): BrowserPageInterface | undefined;
     pages(): readonly BrowserPageInterface[];
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
     sync(targets: readonly CDPTarget[]): Promise<void>;
+    destroy(): Promise<void>;
     close(): Promise<void>;
 }
 
+/** Browser-context lifecycle events. */
+export declare type BrowserContextEventMap = {
+    readonly page: readonly [page: BrowserPageInterface];
+    readonly close: readonly [];
+};
+
 /**
  * Isolated browser session over a CDP browser context.
  *
@@ -232,17 +407,289 @@ export declare class BrowserContext implements BrowserContextInterface {
  * - `create` — open a new page in this context
  * - `sync` — synchronize pages from the given CDP targets (server discovers
  *   the targets; core never fetches them itself)
- * - `close` — close the context and all its pages
+ * - `destroy` — release local pages and detach their sessions
+ * - `close` — close remote pages and dispose the remote context
  */
 export declare interface BrowserContextInterface {
+    readonly emitter: EmitterInterface<BrowserContextEventMap>;
     readonly id: string | undefined;
+    readonly cookies: BrowserCookieManagerInterface;
+    readonly permissions: BrowserPermissionManagerInterface;
+    readonly storage: BrowserStorageManagerInterface;
+    readonly emulation: BrowserEmulationManagerInterface;
     page(index?: number): BrowserPageInterface | undefined;
     pages(): readonly BrowserPageInterface[];
     create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
     sync(targets: readonly CDPTarget[]): Promise<void>;
+    destroy(): Promise<void>;
     close(): Promise<void>;
 }
 
+/** Options for creating and configuring an isolated browser context. */
+export declare interface BrowserContextOptions {
+    readonly proxy?: BrowserProxy;
+    readonly origins?: readonly string[];
+    readonly downloads?: BrowserDownloadOptions;
+    readonly emulation?: BrowserEmulationOptions;
+}
+
+/** One cookie returned from a browser context. */
+export declare interface BrowserCookie {
+    readonly name: string;
+    readonly value: string;
+    readonly domain: string;
+    readonly path: string;
+    readonly expires: number;
+    readonly http: boolean;
+    readonly secure: boolean;
+    readonly site: BrowserSameSite | undefined;
+    readonly partition: BrowserCookiePartition | undefined;
+}
+
+/** 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. */
+export declare interface BrowserCookieInput {
+    readonly name: string;
+    readonly value: string;
+    readonly url?: string;
+    readonly domain?: string;
+    readonly path?: string;
+    readonly expires?: number;
+    readonly http?: boolean;
+    readonly secure?: boolean;
+    readonly site?: BrowserSameSite;
+    readonly priority?: 'Low' | 'Medium' | 'High';
+    readonly partition?: BrowserCookiePartition;
+}
+
+/**
+ * Cookie operations isolated to one browser context.
+ */
+export declare class BrowserCookieManager implements BrowserCookieManagerInterface {
+    #private;
+    constructor(client: CDPClientInterface, context?: string);
+    list(urls?: readonly string[]): Promise<readonly BrowserCookie[]>;
+    set(cookies: readonly BrowserCookieInput[]): Promise<void>;
+    clear(filter?: BrowserCookieFilter): Promise<void>;
+}
+
+/** Cookie operations scoped to one browser context. */
+export declare interface BrowserCookieManagerInterface {
+    list(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. */
+export declare interface BrowserCookiePartition {
+    readonly site: string;
+    readonly ancestor?: boolean;
+}
+
+/**
+ * JavaScript precise coverage and CSS rule usage for one page target.
+ */
+export declare class BrowserCoverage implements BrowserCoverageInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface);
+    get active(): boolean;
+    start(options?: BrowserCoverageOptions): Promise<void>;
+    stop(): Promise<BrowserCoverageResult>;
+    destroy(): Promise<void>;
+}
+
+/** Coverage capture lifecycle. */
+export declare interface BrowserCoverageInterface {
+    readonly active: boolean;
+    start(options?: BrowserCoverageOptions): Promise<void>;
+    stop(): Promise<BrowserCoverageResult>;
+    destroy(): Promise<void>;
+}
+
+/** Coverage capture options. */
+export declare interface BrowserCoverageOptions {
+    readonly javascript?: boolean;
+    readonly css?: boolean;
+    readonly detailed?: boolean;
+}
+
+/** 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. */
+export declare interface BrowserCoverageResult {
+    readonly scripts: readonly BrowserScriptCoverage[];
+    readonly styles: readonly BrowserStyleCoverage[];
+}
+
+/** HTTP basic-auth credentials applied to context pages. */
+export declare interface BrowserCredentials {
+    readonly username: string;
+    readonly password: string;
+}
+
+/**
+ * Diagnostic subentities grouped beneath one page.
+ */
+export declare class BrowserDiagnostics implements BrowserDiagnosticsInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface, writer?: ScreenshotWriterInterface);
+    get tracing(): BrowserTracingInterface;
+    get coverage(): BrowserCoverageInterface;
+    get performance(): BrowserPerformanceInterface;
+    destroy(): Promise<void>;
+}
+
+/** Diagnostics grouped by capability. */
+export declare interface BrowserDiagnosticsInterface {
+    readonly tracing: BrowserTracingInterface;
+    readonly coverage: BrowserCoverageInterface;
+    readonly performance: BrowserPerformanceInterface;
+    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. */
+export declare type BrowserDialogCategory = 'alert' | 'confirm' | 'prompt' | 'beforeunload';
+
+/** One active JavaScript dialog. */
+export declare interface BrowserDialogInterface {
+    readonly category: BrowserDialogCategory;
+    readonly message: string;
+    readonly default: string;
+    accept(value?: string): Promise<void>;
+    dismiss(): Promise<void>;
+}
+
+/** One document captured in a CDP DOM snapshot. */
+export declare interface BrowserDocument {
+    readonly index: number;
+    readonly frame: string;
+    readonly url: string;
+    readonly title: string;
+    readonly nodes: readonly BrowserNode[];
+    readonly scroll: readonly [x: number | undefined, y: number | undefined];
+    readonly width: number | undefined;
+    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. */
+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. */
+export declare interface BrowserDownloadInterface {
+    readonly emitter: EmitterInterface<BrowserDownloadEventMap>;
+    readonly id: string;
+    readonly url: string;
+    readonly name: string;
+    readonly status: BrowserDownloadStatus;
+    readonly received: number;
+    readonly total: number;
+    readonly path: string | undefined;
+    cancel(): Promise<void>;
+    update(progress: BrowserDownloadProgress): void;
+}
+
+/** Download policy for a browser context. */
+export declare interface BrowserDownloadOptions {
+    readonly path: string;
+    readonly named?: boolean;
+}
+
+/** Protocol-neutral download progress update. */
+export declare interface BrowserDownloadProgress {
+    readonly status: BrowserDownloadStatus;
+    readonly received: number;
+    readonly total: number;
+    readonly path?: string;
+}
+
+/** Decoded `Browser.downloadWillBegin` event. */
+export declare interface BrowserDownloadStart {
+    readonly id: string;
+    readonly url: string;
+    readonly name: string;
+    readonly frame: string;
+}
+
+/** Download lifecycle phase. */
+export declare type BrowserDownloadStatus = 'pending' | 'complete' | 'cancelled';
+
+/**
+ * Rendering, identity, location, and network emulation for context pages.
+ */
+export declare class BrowserEmulationManager implements BrowserEmulationManagerInterface {
+    #private;
+    constructor(pages: () => readonly BrowserPageInterface[], options?: BrowserEmulationOptions);
+    apply(options: BrowserEmulationOptions): Promise<void>;
+    clear(): Promise<void>;
+    attach(page: BrowserPageInterface): Promise<void>;
+}
+
+/** Context-scoped emulation configuration. */
+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. */
+export declare interface BrowserEmulationOptions {
+    readonly viewport?: BrowserViewport;
+    readonly user?: BrowserUserAgent;
+    readonly locale?: string;
+    readonly timezone?: string;
+    readonly geolocation?: BrowserGeolocation;
+    readonly media?: BrowserMedia;
+    readonly offline?: boolean;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly credentials?: BrowserCredentials;
+}
+
 /**
  * Base error for all browser automation operations.
  *
@@ -257,462 +704,2470 @@ export declare class BrowserError extends Error {
 }
 
 /**
- * One frame in a page's frame tree, as reported by CDP `Page.getFrameTree`.
- *
- * @remarks
- * - `id` — the frame's CDP frame id
- * - `parent` — the parent frame's id, undefined for the main frame
- * - `name` — the frame's `name`/`id` HTML attribute, undefined when not set
- * - `url` — the frame's current URL
+ * One intercepted file input selection.
  */
-export declare type BrowserFrame = {
-    readonly id: string;
-    readonly parent?: string;
-    readonly name?: string;
-    readonly url: string;
-};
+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>;
+}
 
-/**
- * Options for page navigation.
- *
- * @remarks
- * - `condition` — page load condition to wait for (default `'load'`)
- * - `timeout` — bounds the whole navigate call (the `Page.navigate` send
- *   itself plus the load-event wait), in milliseconds
- */
-export declare interface BrowserNavigationOptions {
-    readonly condition?: BrowserWaitUntil;
-    readonly timeout?: number;
+/** 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 {
 }
 
-export declare class BrowserPage implements BrowserPageInterface {
+/**
+ * One attached document frame, evaluated through its own CDP execution world.
+ */
+export declare class BrowserFrame implements BrowserFrameInterface {
     #private;
-    constructor(client: CDPClientInterface, targetId: string, sessionId: string, writer?: ScreenshotWriterInterface, url?: string);
+    constructor(client: CDPClientInterface, session: string | BrowserSessionFunction, id: string, url: string, parent?: string, name?: string, isolated?: boolean);
+    get id(): string;
+    get parent(): string | undefined;
+    get name(): string | undefined;
     get url(): string;
-    get closed(): boolean;
+    get selectors(): BrowserSelectorManagerInterface;
+    get keyboard(): BrowserKeyboardInterface;
+    get mouse(): BrowserMouseInterface;
+    get touch(): BrowserTouchInterface;
     title(): Promise<string>;
-    navigate(url: string, options?: BrowserNavigationOptions): Promise<void>;
     content(): Promise<BrowserContentResult>;
-    screenshot(options?: BrowserScreenshotOptions): Promise<BrowserScreenshotResult>;
     click(selector: string, options?: BrowserActionOptions): Promise<void>;
     fill(selector: string, value: string, options?: BrowserActionOptions): Promise<void>;
     select(selector: string, values: readonly string[], options?: BrowserActionOptions): Promise<void>;
-    evaluate(expression: string): Promise<unknown>;
-    wait(selector: string, options?: BrowserActionOptions): Promise<void>;
-    frame(name: string): Promise<BrowserFrame | undefined>;
-    frames(): Promise<readonly BrowserFrame[]>;
-    codegen(options?: BrowserCodegenOptions): Promise<BrowserCodegenInterface>;
-    close(): Promise<void>;
+    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>>): Promise<unknown>;
+    subscribe(method: string, handler: CDPHandler): Promise<void>;
+    unsubscribe(method: string, handler: CDPHandler): Promise<void>;
+    save(path: string, _bytes: Uint8Array): Promise<void>;
+    protected assert(): void;
+    protected request(method: string, params?: Readonly<Record<string, unknown>>, timeout?: number): Promise<unknown>;
+    protected raw(expression: string, timeout?: number): Promise<unknown>;
+    protected update(url: string): void;
 }
 
 /**
- * Abstraction over a single browser page or frame.
+ * Serializable frame metadata decoded from CDP `Page.getFrameTree`.
  *
  * @remarks
- * - `url` — current URL; when the page was constructed with a seeded url
- *   (e.g. reattaching to an existing CDP target), reports that url
- *   immediately, before any `navigate()`/`content()` call refreshes it
- * - `closed` — true after `close()` is called
+ * - `id` — the frame's CDP frame id
+ * - `parent` — the parent frame's id, undefined for the main frame
+ * - `name` — the frame's `name`/`id` HTML attribute, undefined when not set
+ * - `url` — the frame's current URL
+ */
+export declare interface BrowserFrameInfo {
+    readonly id: string;
+    readonly parent: string | undefined;
+    readonly name: string | undefined;
+    readonly url: string;
+}
+
+/**
+ * Operations shared by a top-level page and an iframe document.
+ *
+ * @remarks
+ * - `id` — CDP frame id
+ * - `parent` — parent frame id, undefined for the main frame
+ * - `name` — frame `name`/`id`, undefined when absent
+ * - `url` — current frame URL
  * - `title` — resolve the document title
- * - `navigate` — go to a URL and wait for the specified load condition
  * - `content` — extract page URL, title, HTML, and visible text
- * - `screenshot` — capture a PNG or JPEG image of the page
  * - `click` — click an element matching the selector
  * - `fill` — type text into an input element
  * - `select` — choose option(s) in a `<select>` element
  * - `evaluate` — execute a JavaScript expression in the page context
- * - `wait` — wait for an element matching the selector to appear
- * - `frame` — look up a frame by name or URL in the page's flattened frame tree
- * - `frames` — list the page's flattened frame tree, main frame first
- * - `codegen` — start (or return the existing) action recorder for this page
- * - `close` — close the page
+ * - `wait` — wait for an element state
+ * - `send` — issue a raw CDP method in the frame's current target session
  */
-export declare interface BrowserPageInterface {
+export declare interface BrowserFrameInterface {
+    readonly id: string;
+    readonly parent: string | undefined;
+    readonly name: string | undefined;
     readonly url: string;
-    readonly closed: boolean;
+    readonly selectors: BrowserSelectorManagerInterface;
+    readonly keyboard: BrowserKeyboardInterface;
+    readonly mouse: BrowserMouseInterface;
+    readonly touch: BrowserTouchInterface;
     title(): Promise<string>;
-    navigate(url: string, options?: BrowserNavigationOptions): Promise<void>;
     content(): Promise<BrowserContentResult>;
-    screenshot(options?: BrowserScreenshotOptions): Promise<BrowserScreenshotResult>;
     click(selector: string, options?: BrowserActionOptions): Promise<void>;
     fill(selector: string, value: string, options?: BrowserActionOptions): Promise<void>;
     select(selector: string, values: readonly string[], options?: BrowserActionOptions): Promise<void>;
-    evaluate(expression: string): Promise<unknown>;
-    wait(selector: string, options?: BrowserActionOptions): Promise<void>;
-    frame(name: string): Promise<BrowserFrame | undefined>;
-    frames(): Promise<readonly BrowserFrame[]>;
-    codegen(options?: BrowserCodegenOptions): Promise<BrowserCodegenInterface>;
-    close(): Promise<void>;
+    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>>): Promise<unknown>;
+    subscribe(method: string, handler: CDPHandler): Promise<void>;
+    unsubscribe(method: string, handler: CDPHandler): Promise<void>;
+    save(path: string, bytes: Uint8Array): Promise<void>;
+}
+
+/** Function coverage inside one script. */
+export declare interface BrowserFunctionCoverage {
+    readonly name: string;
+    readonly ranges: readonly BrowserCoverageRange[];
+    readonly block: boolean;
+}
+
+/** Geographic location override. */
+export declare interface BrowserGeolocation {
+    readonly latitude: number;
+    readonly longitude: number;
+    readonly accuracy?: number;
 }
 
 /**
- * Options for creating a browser page.
- *
- * @remarks
- * - `url` — navigate to this URL immediately after creation
- * - `viewport` — override the context-level default viewport
- * - `timeout` — navigation timeout for the initial URL
+ * One retained remote object in a frame execution context.
  */
-export declare interface BrowserPageOptions {
-    readonly url?: string;
-    readonly viewport?: BrowserViewport;
-    readonly timeout?: number;
+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>;
 }
 
 /**
- * An `evaluate()`/`content()` result exceeded {@link BROWSER_RESULT_LIMIT}
- * and was rejected in-page before it could overflow the CDP transport frame.
+ * A remote JavaScript object retained in one frame execution context.
  */
-export declare class BrowserResultLimitError extends BrowserError {
-    constructor(message: string, context?: Readonly<Record<string, unknown>>);
+export declare interface BrowserHandleInterface {
+    readonly 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>;
+}
+
+/** 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. */
+export declare interface BrowserHARContent {
+    readonly size: number;
+    readonly mimeType: string;
+    readonly text?: string;
+    readonly encoding?: 'base64';
 }
 
 /**
- * Options for taking a page screenshot.
+ * One cookie in an HTTP archive.
  *
  * @remarks
- * - `path` — file path to persist the screenshot to, via the page's writer
- * - `full` — capture the full scrollable page (default `false`)
- * - `type` — image format (default `'png'`)
- * - `quality` — JPEG quality 0–100 (ignored for PNG)
+ * HAR data preserves the official HAR 1.2 JSON field names. These compound
+ * properties are external wire-schema keys, so archives remain interoperable
+ * without a lossy projection layer.
  */
-export declare interface BrowserScreenshotOptions {
+export declare interface BrowserHARCookie extends BrowserHARValue {
     readonly path?: string;
-    readonly full?: boolean;
-    readonly type?: 'png' | 'jpeg';
-    readonly quality?: number;
+    readonly domain?: string;
+    readonly expires?: string;
+    readonly httpOnly?: boolean;
+    readonly secure?: boolean;
+}
+
+/** 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. */
+export declare interface BrowserHAREntry {
+    readonly startedDateTime: string;
+    readonly time: number;
+    readonly request: BrowserHARRequest;
+    readonly response: BrowserHARResponse;
+    readonly cache: Readonly<Record<string, unknown>>;
+    readonly timings: BrowserHARTimings;
 }
 
 /**
- * Result of a page screenshot.
+ * Convert HAR name/value headers into a Fetch-domain header record.
  *
- * @remarks
- * - `bytes` — raw image bytes
- * - `path` — file path if persisted via the page's writer, otherwise undefined
+ * @param headers - HAR header entries
+ * @returns Header record with later duplicate names replacing earlier values
  */
-export declare interface BrowserScreenshotResult {
-    readonly bytes: Uint8Array;
-    readonly path: string | undefined;
+export declare function browserHARHeadersToRecord(headers: readonly BrowserHARValue[]): Readonly<Record<string, string>>;
+
+/** HAR 1.2 log object. */
+export declare interface BrowserHARLog {
+    readonly version: '1.2';
+    readonly creator: BrowserHARCreator;
+    readonly entries: readonly BrowserHAREntry[];
 }
 
 /**
- * A selector-based lookup or wait timed out without the element appearing.
+ * HTTP archive recording and replay over one page network manager.
  */
-export declare class BrowserSelectorError extends BrowserError {
-    constructor(message: string, context?: Readonly<Record<string, unknown>>);
+export declare class BrowserHARManager implements BrowserHARManagerInterface {
+    #private;
+    constructor(network: BrowserNetworkManagerInterface, writer?: ScreenshotWriterInterface);
+    get recording(): boolean;
+    start(options?: BrowserHAROptions): Promise<void>;
+    stop(): Promise<BrowserHAR>;
+    replay(har: BrowserHAR, options?: BrowserHARReplayOptions): Promise<void>;
+    clear(): Promise<void>;
 }
 
-/** Viewport dimensions for a browser page. */
-export declare interface BrowserViewport {
-    readonly width: number;
-    readonly height: number;
+/** HAR recording and replay operations. */
+export declare interface BrowserHARManagerInterface {
+    readonly recording: boolean;
+    start(options?: BrowserHAROptions): Promise<void>;
+    stop(): Promise<BrowserHAR>;
+    replay(har: BrowserHAR, options?: BrowserHARReplayOptions): Promise<void>;
+    clear(): Promise<void>;
 }
 
-/** Page load condition for navigation — the CDP load event awaited by `navigate()`. */
-export declare type BrowserWaitUntil = 'load' | 'domcontentloaded';
+/** HAR recording options. */
+export declare interface BrowserHAROptions {
+    readonly path?: string;
+    readonly content?: boolean;
+}
+
+/** Mutable recording state held until a request finishes. */
+export declare interface BrowserHARPending {
+    readonly request: BrowserRequest;
+    readonly started: number;
+    readonly response: BrowserResponse | undefined;
+}
+
+/** Request body metadata in an HTTP archive. */
+export declare interface BrowserHARPost {
+    readonly mimeType: string;
+    readonly text: string;
+}
+
+/** HAR replay behavior. */
+export declare interface BrowserHARReplayOptions {
+    readonly fallback?: boolean;
+}
+
+/** HAR 1.2 request entry. */
+export declare interface BrowserHARRequest {
+    readonly method: string;
+    readonly url: string;
+    readonly httpVersion: string;
+    readonly cookies: readonly BrowserHARCookie[];
+    readonly headers: readonly BrowserHARValue[];
+    readonly queryString: readonly BrowserHARValue[];
+    readonly postData?: BrowserHARPost;
+    readonly headersSize: number;
+    readonly bodySize: number;
+}
+
+/** HAR 1.2 response entry. */
+export declare interface BrowserHARResponse {
+    readonly status: number;
+    readonly statusText: string;
+    readonly httpVersion: string;
+    readonly cookies: readonly BrowserHARCookie[];
+    readonly headers: readonly BrowserHARValue[];
+    readonly content: BrowserHARContent;
+    readonly redirectURL: string;
+    readonly headersSize: number;
+    readonly bodySize: number;
+}
+
+/** HAR 1.2 phase timings in milliseconds. */
+export declare interface BrowserHARTimings {
+    readonly blocked: number;
+    readonly dns: number;
+    readonly connect: number;
+    readonly send: number;
+    readonly wait: number;
+    readonly receive: number;
+    readonly ssl: number;
+}
+
+/** One name/value pair in an HTTP archive. */
+export declare interface BrowserHARValue {
+    readonly name: string;
+    readonly value: string;
+}
 
 /**
- * Lightweight Chrome DevTools Protocol client over a {@link CDPTransportInterface}.
+ * Convert 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>>): readonly Readonly<Record<string, string>>[];
+
+/** Normalized CDP keyboard key data. */
+export declare interface BrowserKey {
+    readonly key: string;
+    readonly code: string;
+    readonly text: string | undefined;
+    readonly number: number;
+}
+
+/**
+ * Trusted keyboard input through Chromium's CDP Input domain.
+ */
+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>;
+    insert(value: string): Promise<void>;
+}
+
+/** 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>;
+    insert(value: string): Promise<void>;
+}
+
+/** Layout data associated with one captured DOM node. */
+export declare interface BrowserLayout {
+    readonly bounds: BrowserRect | undefined;
+    readonly styles: Readonly<Record<string, string>>;
+    readonly text: string | undefined;
+    readonly paint: number | undefined;
+    readonly offset: BrowserRect | undefined;
+    readonly scroll: BrowserRect | undefined;
+    readonly client: BrowserRect | undefined;
+}
+
+/**
+ * Reusable strict semantic locator over one frame.
+ */
+export declare class BrowserLocator implements BrowserLocatorInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface, query: BrowserQuery);
+    get frame(): BrowserFrameInterface;
+    get query(): BrowserQuery;
+    locator(selector: string): BrowserLocatorInterface;
+    filter(options: BrowserFilterOptions): BrowserLocatorInterface;
+    first(): BrowserLocatorInterface;
+    last(): BrowserLocatorInterface;
+    item(index: number): BrowserLocatorInterface;
+    count(): Promise<number>;
+    all(): Promise<readonly BrowserLocatorInterface[]>;
+    click(options?: BrowserActionOptions): 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>;
+    focus(options?: BrowserActionOptions): Promise<void>;
+    press(key: string, options?: BrowserActionOptions): Promise<void>;
+    type(value: string, options?: BrowserActionOptions): Promise<void>;
+    clear(options?: BrowserActionOptions): Promise<void>;
+    wait(options?: BrowserWaitOptions): Promise<void>;
+    text(options?: BrowserTextResultOptions): Promise<string | readonly string[]>;
+    html(): Promise<string>;
+    value(): Promise<string>;
+    attribute(name: string): Promise<string | undefined>;
+    visible(): Promise<boolean>;
+    enabled(): Promise<boolean>;
+    editable(): Promise<boolean>;
+    screenshot(options?: BrowserScreenshotOptions): Promise<BrowserScreenshotResult>;
+    upload(options: BrowserUploadOptions): Promise<void>;
+    drag(target: BrowserLocatorInterface, options?: BrowserActionOptions): Promise<void>;
+}
+
+/** Declarative locator filter applied after selector resolution. */
+export declare interface BrowserLocatorFilter {
+    readonly text?: string;
+    readonly exact?: boolean;
+    readonly visible?: boolean;
+}
+
+/**
+ * Reusable strict locator over one frame.
+ */
+export declare interface BrowserLocatorInterface {
+    readonly frame: BrowserFrameInterface;
+    readonly query: BrowserQuery;
+    locator(selector: string): BrowserLocatorInterface;
+    filter(options: BrowserFilterOptions): BrowserLocatorInterface;
+    first(): BrowserLocatorInterface;
+    last(): BrowserLocatorInterface;
+    item(index: number): BrowserLocatorInterface;
+    count(): Promise<number>;
+    all(): Promise<readonly BrowserLocatorInterface[]>;
+    click(options?: BrowserActionOptions): 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>;
+    focus(options?: BrowserActionOptions): Promise<void>;
+    press(key: string, options?: BrowserActionOptions): Promise<void>;
+    type(value: string, options?: BrowserActionOptions): Promise<void>;
+    clear(options?: BrowserActionOptions): Promise<void>;
+    wait(options?: BrowserWaitOptions): Promise<void>;
+    text(options?: BrowserTextResultOptions): Promise<string | readonly string[]>;
+    html(): Promise<string>;
+    value(): Promise<string>;
+    attribute(name: string): Promise<string | undefined>;
+    visible(): Promise<boolean>;
+    enabled(): Promise<boolean>;
+    editable(): Promise<boolean>;
+    screenshot(options?: BrowserScreenshotOptions): Promise<BrowserScreenshotResult>;
+    upload(options: BrowserUploadOptions): Promise<void>;
+    drag(target: BrowserLocatorInterface, options?: BrowserActionOptions): Promise<void>;
+}
+
+/** Paper margin lengths accepted by Chromium print-to-PDF. */
+export declare interface BrowserMargin {
+    readonly top?: number;
+    readonly right?: number;
+    readonly bottom?: number;
+    readonly left?: number;
+}
+
+/** Browser color and media feature overrides. */
+export declare interface BrowserMedia {
+    readonly media?: 'screen' | 'print';
+    readonly color?: 'light' | 'dark' | 'no-preference';
+    readonly contrast?: 'more' | 'less' | 'no-preference';
+    readonly motion?: 'reduce' | 'no-preference';
+    readonly colors?: 'active' | 'none';
+}
+
+/** One Performance-domain metric. */
+export declare interface BrowserMetric {
+    readonly name: string;
+    readonly value: number;
+}
+
+/**
+ * Trusted mouse input through Chromium's CDP Input domain.
+ */
+export declare class BrowserMouse implements BrowserMouseInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface);
+    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>;
+    wheel(delta: BrowserPoint): Promise<void>;
+}
+
+/** 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. */
+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>;
+    wheel(delta: BrowserPoint): Promise<void>;
+}
+
+/**
+ * URL and page-predicate waits resilient to ordinary navigation events.
+ */
+export declare class BrowserNavigationManager implements BrowserNavigationManagerInterface {
+    #private;
+    constructor(page: BrowserPageInterface);
+    wait(pattern: string, options?: BrowserNavigationWaitOptions): Promise<string>;
+    until(expression: string, options?: BrowserNavigationWaitOptions): Promise<unknown>;
+}
+
+/** 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.
  *
  * @remarks
- * Sends JSON-RPC messages over the injected transport and dispatches
- * responses and events. The transport owns the connection itself
- * (WebSocket, pipe, or any other duplex channel); this class owns only
- * the JSON-RPC framing and id/session correlation.
+ * - `condition` — page load condition to wait for (default `'load'`)
+ * - `timeout` — bounds the whole navigate call (the `Page.navigate` send
+ *   itself plus the load-event wait), in milliseconds
+ */
+export declare interface BrowserNavigationOptions {
+    readonly condition?: BrowserWaitUntil;
+    readonly timeout?: number;
+}
+
+/** 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. */
+export declare interface BrowserNavigationWait {
+    readonly pattern: string;
+    readonly timer: ReturnType<typeof setTimeout>;
+    readonly resolve: (url: string) => void;
+    readonly reject: (error: unknown) => void;
+}
+
+/** Options for URL and predicate waits. */
+export declare interface BrowserNavigationWaitOptions {
+    readonly timeout?: number;
+}
+
+/** State retained while correlating navigation with Network events. */
+export declare interface BrowserNavigationWatch {
+    readonly responses: BrowserResponse[];
+}
+
+/** Network events emitted by a page's network manager. */
+export declare type BrowserNetworkEventMap = {
+    readonly request: readonly [request: BrowserRequest];
+    readonly response: readonly [response: BrowserResponse];
+    readonly failure: readonly [failure: BrowserRequestFailure];
+    readonly finish: readonly [id: string];
+    readonly socket: readonly [socket: BrowserWebSocketInterface];
+};
+
+/**
+ * Page-scoped Network and Fetch domain lifecycle.
+ */
+export declare class BrowserNetworkManager implements BrowserNetworkManagerInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface, writer?: ScreenshotWriterInterface);
+    get emitter(): EmitterInterface<BrowserNetworkEventMap>;
+    get har(): BrowserHARManagerInterface;
+    start(): Promise<void>;
+    body(id: string): Promise<Uint8Array>;
+    text(id: string): Promise<string>;
+    json(id: string): Promise<unknown>;
+    route(query: BrowserRouteQuery, handler: BrowserRouteHandler): Promise<void>;
+    unroute(handler?: BrowserRouteHandler): Promise<void>;
+    headers(headers: Readonly<Record<string, string>>): Promise<void>;
+    offline(offline: boolean): Promise<void>;
+    credentials(credentials?: BrowserCredentials): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/** Page-scoped network observation and interception. */
+export declare interface BrowserNetworkManagerInterface {
+    readonly emitter: EmitterInterface<BrowserNetworkEventMap>;
+    readonly har: BrowserHARManagerInterface;
+    start(): Promise<void>;
+    body(id: string): Promise<Uint8Array>;
+    text(id: string): Promise<string>;
+    json(id: string): Promise<unknown>;
+    route(query: BrowserRouteQuery, handler: BrowserRouteHandler): Promise<void>;
+    unroute(handler?: BrowserRouteHandler): Promise<void>;
+    headers(headers: Readonly<Record<string, string>>): Promise<void>;
+    offline(offline: boolean): Promise<void>;
+    credentials(credentials?: BrowserCredentials): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/** One serializable DOM node decoded from a CDP DOM snapshot. */
+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 name: string;
+    readonly value: string;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly text: string | undefined;
+    readonly input: string | undefined;
+    readonly checked: boolean | undefined;
+    readonly selected: boolean | undefined;
+    readonly clickable: boolean | undefined;
+    readonly shadow: string | undefined;
+    readonly content: number | undefined;
+    readonly pseudo: string | undefined;
+    readonly source: string | undefined;
+    readonly origin: string | undefined;
+    readonly layout: BrowserLayout | undefined;
+}
+
+/** Predicate used by browser snapshot traversal helpers. */
+export declare type BrowserNodePredicate = (node: BrowserNode) => boolean;
+
+/**
+ * Declarative browser-node matcher used by {@link matchesBrowserNode}.
  *
- * 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.
+ * @remarks
+ * Every supplied field must match. `name` is case-insensitive, `text`
+ * searches layout text and node value, and `attributes` requires every
+ * supplied name/value pair.
  */
-export declare class CDPClient implements CDPClientInterface {
+export declare interface BrowserNodeQuery {
+    readonly name?: string;
+    readonly text?: string;
+    readonly attributes?: Readonly<Record<string, string>>;
+    readonly frame?: string;
+    readonly visible?: boolean;
+    readonly clickable?: boolean;
+}
+
+/**
+ * A top-level browser page, including its target lifecycle and child frames.
+ */
+export declare class BrowserPage extends BrowserFrame implements BrowserPageInterface {
     #private;
-    constructor(options: CDPClientOptions);
-    get connected(): boolean;
-    connect(): Promise<void>;
-    /**
-     * Close the transport and re-establish a fresh connection.
-     *
-     * @remarks
-     * Client-level subscriptions (`subscribe`/`unsubscribe` registrations)
-     * survive `close()` and remain active after the reconnect — only pending
-     * in-flight requests are rejected. This lets a caller reconnect a dropped
-     * 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;
-    /**
-     * Close the transport and reject all pending requests.
-     *
-     * @remarks
-     * Subscriptions registered via `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.
-     * If `close()` is called while `connect()` is still awaiting
-     * `transport.start()`, the in-flight connect is rejected and the
-     * transport is closed deterministically once `start()` resolves.
-     */
+    constructor(client: CDPClientInterface, targetId: string, sessionId: string, writer?: ScreenshotWriterInterface, url?: string, frameId?: string, contextId?: string, opener?: BrowserPageInterface);
+    get emitter(): EmitterInterface<BrowserPageEventMap>;
+    get network(): BrowserNetworkManagerInterface;
+    get navigation(): BrowserNavigationManagerInterface;
+    get scripts(): BrowserScriptManagerInterface;
+    get accessibility(): BrowserAccessibilityInterface;
+    get diagnostics(): BrowserDiagnosticsInterface;
+    get clock(): BrowserClockInterface;
+    get opener(): BrowserPageInterface | undefined;
+    get target(): string;
+    get closed(): boolean;
+    navigate(url: string, options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    reload(options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    back(options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    forward(options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    screenshot(options?: BrowserScreenshotOptions): Promise<BrowserScreenshotResult>;
+    pdf(options?: BrowserPDFOptions): Promise<BrowserPDFResult>;
+    save(path: string, bytes: Uint8Array): Promise<void>;
+    frame(name: string): Promise<BrowserFrameInterface | undefined>;
+    frames(): Promise<readonly BrowserFrameInterface[]>;
+    snapshot(options?: BrowserSnapshotOptions): Promise<BrowserSnapshot>;
+    codegen(options?: BrowserCodegenOptions): Promise<BrowserCodegenInterface>;
+    destroy(): Promise<void>;
     close(): Promise<void>;
+    protected assert(): void;
+}
+
+/** 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. */
+export declare type BrowserPageEventMap = {
+    readonly navigate: readonly [url: string];
+    readonly attach: readonly [frame: BrowserFrameInterface];
+    readonly detach: readonly [frame: string];
+    readonly popup: readonly [page: BrowserPageInterface];
+    readonly dialog: readonly [dialog: BrowserDialogInterface];
+    readonly chooser: readonly [chooser: BrowserFileChooserInterface];
+    readonly download: readonly [download: BrowserDownloadInterface];
+    readonly console: readonly [message: BrowserConsoleMessage];
+    readonly error: readonly [error: BrowserPageError];
+    readonly crash: readonly [];
+    readonly worker: readonly [worker: BrowserWorkerInterface];
+    readonly request: readonly [request: BrowserRequest];
+    readonly response: readonly [response: BrowserResponse];
+    readonly failure: readonly [failure: BrowserRequestFailure];
+    readonly socket: readonly [socket: BrowserWebSocketInterface];
+    readonly close: readonly [];
+};
+
 /**
- * Lightweight Chrome DevTools Protocol client over a {@link CDPTransportInterface}.
+ * Abstraction over a single top-level browser page.
  *
  * @remarks
- * - `connected` — true while the transport is active
- * - `connect` — start the transport and begin dispatching
- * - `reconnect` — close and re-establish the transport
- * - `send` — issue a CDP method call, optionally session-scoped, optionally
- *   bounded by a per-call timeout that overrides the client-wide default for
- *   this one request
- * - `subscribe` / `unsubscribe` — register/remove a handler for a CDP event,
- *   optionally session-scoped
- * - `close` — tear down the transport and reject all pending requests
+ * Inherits every {@link BrowserFrameInterface} document operation for the
+ * main frame.
+ *
+ * - `closed` — true after `close()` is called
+ * - `navigate` — go to a URL and wait for the specified load condition
+ * - `screenshot` — capture a PNG or JPEG image of the page
+ * - `frame` — look up a frame by name or URL in the page's flattened frame tree
+ * - `frames` — list the page's flattened frame tree, main frame first
+ * - `snapshot` — capture every attached document as serializable DOM data
+ * - `codegen` — start (or return the existing) action recorder for this page
+ * - `destroy` — release local resources and detach from the target
+ * - `close` — close the remote target and release local resources
  */
-export declare interface CDPClientInterface {
-    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;
+export declare interface BrowserPageInterface extends BrowserFrameInterface {
+    readonly emitter: EmitterInterface<BrowserPageEventMap>;
+    readonly network: BrowserNetworkManagerInterface;
+    readonly navigation: BrowserNavigationManagerInterface;
+    readonly scripts: BrowserScriptManagerInterface;
+    readonly accessibility: BrowserAccessibilityInterface;
+    readonly diagnostics: BrowserDiagnosticsInterface;
+    readonly clock: BrowserClockInterface;
+    readonly opener: BrowserPageInterface | undefined;
+    readonly target: string;
+    readonly closed: boolean;
+    navigate(url: string, options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    reload(options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    back(options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    forward(options?: BrowserNavigationOptions): Promise<BrowserNavigationResult>;
+    screenshot(options?: BrowserScreenshotOptions): Promise<BrowserScreenshotResult>;
+    pdf(options?: BrowserPDFOptions): Promise<BrowserPDFResult>;
+    frame(name: string): Promise<BrowserFrameInterface | undefined>;
+    frames(): Promise<readonly BrowserFrameInterface[]>;
+    snapshot(options?: BrowserSnapshotOptions): Promise<BrowserSnapshot>;
+    codegen(options?: BrowserCodegenOptions): Promise<BrowserCodegenInterface>;
+    destroy(): Promise<void>;
     close(): Promise<void>;
 }
 
 /**
- * Options for creating a CDPClient.
+ * Options for creating a browser page.
+ *
+ * @remarks
+ * - `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 url?: string;
+    readonly viewport?: BrowserViewport;
+    readonly timeout?: number;
+}
+
+/** Options for printing a Chromium page to PDF. */
+export declare interface BrowserPDFOptions {
+    readonly path?: string;
+    readonly landscape?: boolean;
+    readonly background?: boolean;
+    readonly scale?: number;
+    readonly width?: number;
+    readonly height?: number;
+    readonly margin?: BrowserMargin;
+    readonly ranges?: string;
+    readonly header?: string;
+    readonly footer?: string;
+    readonly tagged?: boolean;
+    readonly outline?: boolean;
+}
+
+/** Result of printing a page to PDF. */
+export declare interface BrowserPDFResult {
+    readonly bytes: Uint8Array;
+    readonly path: string | undefined;
+}
+
+/**
+ * Validate and compile Page.printToPDF parameters.
+ *
+ * @param options - Public PDF options
+ * @returns Protocol parameter record
+ */
+export declare function browserPDFToParams(options?: BrowserPDFOptions): Readonly<Record<string, unknown>>;
+
+/**
+ * Performance-domain metrics and sampled JavaScript CPU profiles.
+ */
+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. */
+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.
+ */
+export declare class BrowserPermissionManager implements BrowserPermissionManagerInterface {
+    #private;
+    constructor(client: CDPClientInterface, context?: string);
+    grant(permissions: readonly string[], origin?: string): Promise<void>;
+    deny(permissions: readonly string[], origin?: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/** 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. */
+export declare interface BrowserPoint {
+    readonly x: number;
+    readonly y: number;
+}
+
+/** Sampled CPU profile. */
+export declare interface BrowserProfile {
+    readonly start: number;
+    readonly end: number;
+    readonly nodes: readonly BrowserProfileNode[];
+    readonly samples: readonly number[];
+    readonly deltas: readonly number[];
+}
+
+/** JavaScript call frame from a CPU profile. */
+export declare interface BrowserProfileFrame {
+    readonly function: string;
+    readonly script: string;
+    readonly url: string;
+    readonly line: number;
+    readonly column: number;
+}
+
+/** One node in a sampled CPU profile. */
+export declare interface BrowserProfileNode {
+    readonly id: number;
+    readonly frame: BrowserProfileFrame;
+    readonly hit: number | undefined;
+    readonly children: readonly number[];
+}
+
+/** 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. */
+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. */
+export declare interface BrowserQuery {
+    readonly selector: BrowserSelector;
+    readonly value: string;
+    readonly name?: string;
+    readonly exact?: boolean;
+    readonly parent?: BrowserQuery;
+    readonly filter?: BrowserLocatorFilter;
+    readonly index?: number;
+}
+
+/** 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. */
+export declare interface BrowserRequest {
+    readonly id: string;
+    readonly loader: string | undefined;
+    readonly frame: string | undefined;
+    readonly url: string;
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly post: string | undefined;
+    readonly resource: string | undefined;
+    readonly timestamp: number | undefined;
+    readonly walltime: number | undefined;
+    readonly redirect: BrowserResponse | undefined;
+}
+
+/** One failed browser request. */
+export declare interface BrowserRequestFailure {
+    readonly id: string;
+    readonly error: string;
+    readonly cancelled: boolean;
+    readonly blocked: string | undefined;
+}
+
+/** One observed browser response. */
+export declare interface BrowserResponse {
+    readonly id: string;
+    readonly loader: string;
+    readonly frame: string | undefined;
+    readonly url: string;
+    readonly status: number;
+    readonly phrase: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly mime: string;
+    readonly protocol: string;
+    readonly address: string | undefined;
+    readonly port: number | undefined;
+    readonly cached: boolean;
+    readonly worker: boolean;
+    readonly timestamp: number;
+    readonly timing: BrowserTiming | undefined;
+    readonly security: BrowserSecurity | undefined;
+}
+
+/**
+ * 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. */
+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. */
+export declare interface BrowserRouteContinueOptions {
+    readonly url?: string;
+    readonly method?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly post?: string;
+}
+
+/** One installed network route. */
+export declare interface BrowserRouteDefinition {
+    readonly query: BrowserRouteQuery;
+    readonly handler: BrowserRouteHandler;
+}
+
+/** Synthetic response supplied when fulfilling an intercepted request. */
+export declare interface BrowserRouteFulfillOptions {
+    readonly status?: number;
+    readonly phrase?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string | Uint8Array;
+}
+
+/** Function invoked for a matching intercepted request. */
+export declare type BrowserRouteHandler = (route: BrowserRouteInterface) => void | Promise<void>;
+
+/** One paused Fetch-domain request. */
+export declare interface BrowserRouteInterface {
+    readonly id: string;
+    readonly request: BrowserRequest;
+    readonly handled: boolean;
+    abort(reason?: string): Promise<void>;
+    continue(options?: BrowserRouteContinueOptions): Promise<void>;
+    fulfill(options: BrowserRouteFulfillOptions): Promise<void>;
+}
+
+/** 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. */
+export declare type BrowserSameSite = 'Strict' | 'Lax' | 'None';
+
+/**
+ * Options for taking a page screenshot.
+ *
+ * @remarks
+ * - `path` — file path to persist the screenshot to, via the page's writer
+ * - `full` — capture the full scrollable page (default `false`)
+ * - `type` — 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 quality?: number;
+    readonly clip?: BrowserRect;
+    readonly transparent?: boolean;
+    readonly animations?: boolean;
+    readonly caret?: boolean;
+    readonly scale?: BrowserScreenshotScale;
+    readonly mask?: readonly BrowserLocatorInterface[];
+    readonly color?: string;
+}
+
+/**
+ * Result of a page screenshot.
+ *
+ * @remarks
+ * - `bytes` — raw image bytes
+ * - `path` — file path if persisted via the page's writer, otherwise undefined
+ */
+export declare interface BrowserScreenshotResult {
+    readonly bytes: Uint8Array;
+    readonly path: string | undefined;
+}
+
+/** Screenshot coordinate scale. */
+export declare type BrowserScreenshotScale = 'css' | 'device';
+
+/**
+ * Validate and compile 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. */
+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. */
+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);
+    add(source: string): Promise<string>;
+    remove(id: string): Promise<void>;
+    expose(name: string, handler: BrowserBindingHandler): Promise<void>;
+    revoke(name: string): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/** Initialization scripts and host bindings for one page. */
+export declare interface BrowserScriptManagerInterface {
+    add(source: string): Promise<string>;
+    remove(id: string): Promise<void>;
+    expose(name: string, handler: BrowserBindingHandler): Promise<void>;
+    revoke(name: string): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/** TLS details supplied with a browser response. */
+export declare interface BrowserSecurity {
+    readonly protocol: string;
+    readonly issuer: string;
+    readonly from: number;
+    readonly to: number;
+}
+
+/** Selector axis supported by {@link BrowserSelectorManagerInterface}. */
+export declare type BrowserSelector = 'css' | 'role' | 'text' | 'label' | 'placeholder' | 'test';
+
+/**
+ * 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.
+ */
+export declare class BrowserSelectorManager implements BrowserSelectorManagerInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface);
+    css(value: string): BrowserLocatorInterface;
+    role(value: string, options?: BrowserRoleOptions): BrowserLocatorInterface;
+    text(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
+    label(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
+    placeholder(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
+    test(value: string): BrowserLocatorInterface;
+}
+
+/**
+ * Locator factory grouped by selector semantics.
+ */
+export declare interface BrowserSelectorManagerInterface {
+    css(value: string): BrowserLocatorInterface;
+    role(value: string, options?: BrowserRoleOptions): BrowserLocatorInterface;
+    text(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
+    label(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
+    placeholder(value: string, options?: BrowserTextOptions): BrowserLocatorInterface;
+    test(value: string): BrowserLocatorInterface;
+}
+
+/** Resolve the current CDP session for a frame id. */
+export declare type BrowserSessionFunction = (frame: string) => Promise<string>;
+
+/** A flattened, serializable snapshot of every document attached to a page. */
+export declare interface BrowserSnapshot {
+    readonly documents: readonly BrowserDocument[];
+    readonly styles: readonly string[];
+}
+
+/**
+ * Options for capturing a browser DOM snapshot.
+ *
+ * @remarks
+ * - `styles` — computed CSS property names to capture
+ * - `paint` — include global paint order
+ * - `rects` — include offset, scroll, and client rectangles
+ * - `limit` — maximum decoded node count
+ */
+export declare interface BrowserSnapshotOptions {
+    readonly styles?: readonly string[];
+    readonly paint?: boolean;
+    readonly rects?: boolean;
+    readonly limit?: number;
+}
+
+/** One browser-side stack frame. */
+export declare interface BrowserStackFrame {
+    readonly url: string;
+    readonly function: string;
+    readonly line: number;
+    readonly column: number;
+}
+
+/** 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.
+ */
+export declare class BrowserStorageManager implements BrowserStorageManagerInterface {
+    #private;
+    constructor(cookies: BrowserCookieManagerInterface, pages: () => readonly BrowserPageInterface[]);
+    state(options?: BrowserStorageOptions): Promise<BrowserStorageState>;
+    restore(state: BrowserStorageState): Promise<void>;
+    clear(origin?: string): Promise<void>;
+}
+
+/** 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. */
+export declare interface BrowserStorageOptions {
+    readonly origins?: readonly string[];
+}
+
+/** 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. */
+export declare interface BrowserStorageState {
+    readonly cookies: readonly BrowserCookieInput[];
+    readonly origins: readonly BrowserStorageOrigin[];
+}
+
+/** One decoded IO stream read. */
+export declare interface BrowserStreamChunk {
+    readonly bytes: Uint8Array;
+    readonly eof: boolean;
+}
+
+/** CSS stylesheet coverage. */
+export declare interface BrowserStyleCoverage {
+    readonly id: string;
+    readonly ranges: readonly BrowserCoverageRange[];
+}
+
+/** 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. */
+export declare interface BrowserTiming {
+    readonly request: number;
+    readonly proxy: BrowserTimingRange | undefined;
+    readonly dns: BrowserTimingRange | undefined;
+    readonly connect: BrowserTimingRange | undefined;
+    readonly ssl: BrowserTimingRange | undefined;
+    readonly send: BrowserTimingRange | undefined;
+    readonly receive: number | undefined;
+}
+
+/** 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.
+ */
+export declare class BrowserTouch implements BrowserTouchInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface);
+    tap(point: BrowserPoint): Promise<void>;
+}
+
+/** 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.
+ */
+export declare class BrowserTracing implements BrowserTracingInterface {
+    #private;
+    constructor(frame: BrowserFrameInterface, writer?: ScreenshotWriterInterface);
+    get active(): boolean;
+    start(options?: BrowserTracingOptions): Promise<void>;
+    stop(): Promise<BrowserTracingResult>;
+    destroy(): Promise<void>;
+}
+
+/** Trace capture lifecycle. */
+export declare interface BrowserTracingInterface {
+    readonly active: boolean;
+    start(options?: BrowserTracingOptions): Promise<void>;
+    stop(): Promise<BrowserTracingResult>;
+    destroy(): Promise<void>;
+}
+
+/** Chromium trace capture options. */
+export declare interface BrowserTracingOptions {
+    readonly path?: string;
+    readonly categories?: readonly string[];
+    readonly screenshots?: boolean;
+    readonly sampling?: boolean;
+}
+
+/** Trace capture result. */
+export declare interface BrowserTracingResult {
+    readonly bytes: Uint8Array;
+    readonly path: string | undefined;
+}
+
+/** 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. */
+export declare interface BrowserUserAgent {
+    readonly value: string;
+    readonly language?: string;
+    readonly platform?: string;
+}
+
+/** Viewport dimensions for a browser page. */
+export declare interface BrowserViewport {
+    readonly width: number;
+    readonly height: number;
+    readonly scale?: number;
+    readonly mobile?: boolean;
+    readonly touch?: boolean;
+    readonly landscape?: boolean;
+}
+
+/**
+ * Options for waiting on an element.
+ *
+ * @remarks
+ * - `timeout` — maximum time to wait in milliseconds
+ * - `strict` — require the selector to resolve to exactly one element
+ * - `state` — target state (default `'attached'`)
+ */
+export declare interface BrowserWaitOptions extends BrowserActionOptions {
+    readonly state?: BrowserWaitState;
+}
+
+/** 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()`. */
+export declare type BrowserWaitUntil = 'commit' | 'load' | 'domcontentloaded';
+
+/**
+ * Observable WebSocket connection reconstructed from Network-domain events.
+ */
+export declare class BrowserWebSocket implements BrowserWebSocketInterface {
+    #private;
+    constructor(id: string, url: string);
+    get emitter(): EmitterInterface<BrowserWebSocketEventMap>;
+    get id(): string;
+    get url(): string;
+    receive(frame: BrowserWebSocketFrame): void;
+    transmit(frame: BrowserWebSocketFrame): void;
+    fail(message: string): void;
+    close(timestamp: number): void;
+}
+
+/** WebSocket lifecycle events. */
+export declare type BrowserWebSocketEventMap = {
+    readonly receive: readonly [frame: BrowserWebSocketFrame];
+    readonly transmit: readonly [frame: BrowserWebSocketFrame];
+    readonly error: readonly [message: string];
+    readonly close: readonly [timestamp: number];
+};
+
+/** WebSocket frame payload. */
+export declare interface BrowserWebSocketFrame {
+    readonly opcode: number;
+    readonly data: string;
+    readonly masked: boolean;
+    readonly timestamp: number;
+}
+
+/** One observed WebSocket connection. */
+export declare interface BrowserWebSocketInterface {
+    readonly emitter: EmitterInterface<BrowserWebSocketEventMap>;
+    readonly id: string;
+    readonly url: string;
+    receive(frame: BrowserWebSocketFrame): void;
+    transmit(frame: BrowserWebSocketFrame): void;
+    fail(message: string): void;
+    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. */
+export declare type BrowserWorkerCategory = 'worker' | 'service_worker' | 'shared_worker';
+
+/** Script worker attached to a page target. */
+export declare interface BrowserWorkerInterface {
+    readonly id: string;
+    readonly url: string;
+    readonly category: BrowserWorkerCategory;
+    evaluate(expression: string, timeout?: number): Promise<unknown>;
+    send(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
+    detach(): void;
+    close(): Promise<void>;
+}
+
+/** Decode UTF-8 bytes as text. */
+export declare function bytesToText(value: Uint8Array): string;
+
+/**
+ * Lightweight Chrome DevTools Protocol client over a {@link CDPTransportInterface}.
+ *
+ * @remarks
+ * Sends JSON-RPC messages over the injected transport and dispatches
+ * responses and events. The transport owns the connection itself
+ * (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.
+ */
+export declare class CDPClient implements CDPClientInterface {
+    #private;
+    constructor(options: CDPClientOptions);
+    get connected(): boolean;
+    connect(): Promise<void>;
+    /**
+     * Close the transport and re-establish a fresh connection.
+     *
+     * @remarks
+     * Client-level subscriptions (`subscribe`/`unsubscribe` registrations)
+     * survive `close()` and remain active after the reconnect — only pending
+     * in-flight requests are rejected. This lets a caller reconnect a dropped
+     * 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;
+    /**
+     * Close the transport and reject all pending requests.
+     *
+     * @remarks
+     * Subscriptions registered via `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.
+     * If `close()` is called while `connect()` is still awaiting
+     * `transport.start()`, the in-flight connect is rejected and the
+     * transport is closed deterministically once `start()` resolves.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Lightweight Chrome DevTools Protocol client over a {@link CDPTransportInterface}.
+ *
+ * @remarks
+ * - `connected` — true while the transport is active
+ * - `connect` — start the transport and begin dispatching
+ * - `reconnect` — close and re-establish the transport
+ * - `send` — issue a CDP method call, optionally session-scoped, optionally
+ *   bounded by a per-call timeout that overrides the client-wide default for
+ *   this one request
+ * - `subscribe` / `unsubscribe` — register/remove a handler for a CDP event,
+ *   optionally session-scoped
+ * - `close` — tear down the transport and reject all pending requests
+ */
+export declare interface CDPClientInterface {
+    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;
+    close(): Promise<void>;
+}
+
+/**
+ * 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)
+ */
+export declare interface CDPClientOptions {
+    readonly transport: CDPTransportInterface;
+    readonly timeout?: number;
+}
+
+/**
+ * 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).
+ */
+export declare class CDPConnectionError extends BrowserError {
+    constructor(message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/**
+ * A CDP request received an error response from the remote endpoint.
+ *
+ * @remarks
+ * Carries the originating `method` plus the CDP error's own `code`,
+ * `message`, and `data` (when present) in `context`, so callers can branch
+ * on the protocol-level error instead of parsing the message string.
+ */
+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. */
+export declare type CDPHandler = (params: Readonly<Record<string, unknown>>) => void;
+
+/** One entry of the CDP `Target.getTargets` result. */
+export declare interface CDPTarget {
+    readonly id: string;
+    readonly type: string;
+    readonly title: string;
+    readonly url: string;
+}
+
+/**
+ * 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
+ * {@link CDPClientInterface} sends and receives JSON-RPC frames over.
+ *
+ * @remarks
+ * `message` carries one raw text frame; `close` signals the underlying
+ * connection ended; `error` carries a transport-level fault (unknown shape —
+ * narrow before use).
+ */
+export declare type CDPTransportEventMap = {
+    readonly message: readonly [data: string];
+    readonly close: readonly [];
+    readonly error: readonly [error: unknown];
+};
+
+/**
+ * A dumb text transport CDPClient sends and receives JSON-RPC frames over.
+ *
+ * @remarks
+ * The transport owns the connection (WebSocket, pipe, or any other duplex
+ * channel) and the endpoint URL; it does no JSON framing of its own — that
+ * stays in {@link CDPClientInterface}. Environment-specific transports
+ * (a Node `WebSocket`, a browser `WebSocket`) live outside core and satisfy
+ * this contract.
+ */
+export declare interface CDPTransportInterface {
+    readonly emitter: EmitterInterface<CDPTransportEventMap>;
+    start(): Promise<void>;
+    send(data: string): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * Return direct children of a captured browser node.
+ *
+ * @remarks
+ * Includes the root nodes of an iframe's linked content document. Shadow DOM
+ * and template content already carry flattened parent indexes from CDP.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param node - Parent node
+ * @returns Direct children in snapshot order
+ */
+export declare function childrenOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): readonly BrowserNode[];
+
+/**
+ * Find the nearest matching node from the candidate through its ancestors.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param node - Starting node, included in the search
+ * @param predicate - Node predicate
+ * @returns Closest matching node, or undefined
+ */
+export declare function closestBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode, predicate: BrowserNodePredicate): BrowserNode | undefined;
+
+/**
+ * Resolve the nearest common ancestor of two captured browser nodes.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param first - First node
+ * @param second - Second node
+ * @returns Common ancestor, or undefined
+ */
+export declare function commonAncestorOfBrowserNodes(snapshot: BrowserSnapshot, first: BrowserNode, second: BrowserNode): BrowserNode | undefined;
+
+/**
+ * Compile the element-side actionability pass used before trusted input.
+ *
+ * @param options - Checks required for the action
+ * @returns Async `Runtime.callFunctionOn` function declaration
+ */
+export declare function compileActionabilityFunction(options: BrowserActionabilityOptions): string;
+
+/**
+ * Compile 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.
+ *
+ * @param selector - CSS selector
+ * @param strict - Whether more than one match is an error
+ * @param timeout - Maximum wait in milliseconds
+ * @returns Runtime expression resolving to whether the state was reached
+ */
+export declare function compileAttachedWaitExpression(selector: string, strict: boolean, timeout: number): string;
+
+/**
+ * Compile current-document cleanup for one page-side host binding facade.
+ *
+ * @param name - Binding identifier
+ * @returns Runtime cleanup expression
+ */
+export declare function compileBrowserBindingCleanup(name: string): string;
+
+/**
+ * Compile delivery of a host binding result to one execution context.
+ *
+ * @param name - Binding identifier
+ * @param id - Call identifier
+ * @param success - Resolve rather than reject
+ * @param value - Serializable result or error
+ * @returns Runtime expression
+ */
+export declare function compileBrowserBindingResult(name: string, id: string, success: boolean, value: unknown): string;
+
+/**
+ * Compile the page-side promise facade for one Runtime binding.
+ *
+ * @param name - Binding identifier
+ * @returns Self-installing script source
+ */
+export declare function compileBrowserBindingSource(name: string): string;
+
+/**
+ * Compile a strict, visibility-checked click expression.
+ *
+ * @param selector - CSS selector
+ * @param strict - Whether more than one match is an error
+ * @returns Runtime expression
+ */
+export declare function compileClickExpression(selector: string, strict: boolean): string;
+
+/**
+ * Compile recorded codegen actions into a replayable script.
+ *
+ * @remarks
+ * Emits one statement per action against a `page` object shaped like
+ * {@link BrowserPageInterface} (`page.navigate(...)`, `page.click(...)`, …).
+ * Both target languages emit an `async function run(page)` body whose
+ * statements are `await`-ed; `language` only toggles whether the `page`
+ * parameter carries a TypeScript type annotation (default `'javascript'`).
+ *
+ * @param actions - Normalized actions to compile
+ * @param options - Compilation options (target language)
+ * @returns The compiled script source
+ */
+export declare function compileCodegenScript(actions: readonly BrowserCodegenAction[], options?: BrowserCodegenScriptOptions): string;
+
+/**
+ * Compile 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.
+ *
+ * @param selector - CSS selector
+ * @param strict - Whether more than one match is an error
+ * @param timeout - Maximum wait in milliseconds
+ * @returns Runtime expression resolving to whether the state was reached
+ */
+export declare function compileDetachedWaitExpression(selector: string, strict: boolean, timeout: number): string;
+
+/**
+ * Compile a strict, editable fill expression.
+ *
+ * @param selector - CSS selector
+ * @param value - Value to assign
+ * @param strict - Whether more than one match is an error
+ * @returns Runtime expression
+ */
+export declare function compileFillExpression(selector: string, value: string, strict: boolean): string;
+
+/**
+ * Compile an auto-retrying in-page predicate wait.
+ *
+ * @param expression - Value or function expression
+ * @param timeout - Maximum wait in milliseconds
+ * @returns Promise expression resolving to the first truthy value or false
+ */
+export declare function compileFunctionWaitExpression(expression: string, timeout: number): string;
+
+/**
+ * Compile 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.
+ *
+ * @param selector - CSS selector
+ * @param strict - Whether more than one match is an error
+ * @param timeout - Maximum wait in milliseconds
+ * @returns Runtime expression resolving to whether the state was reached
+ */
+export declare function compileHiddenWaitExpression(selector: string, strict: boolean, timeout: number): string;
+
+/**
+ * Compile a deep locator query returning its first match.
+ *
+ * @param query - Serializable locator query
+ * @returns Runtime expression returning one element or undefined
+ */
+export declare function compileLocatorExpression(query: BrowserQuery): string;
+
+/**
+ * Compile a deep, shadow-aware locator query returning every match.
+ *
+ * @param query - Serializable locator query
+ * @returns Runtime expression returning an element array
+ */
+export declare function compileLocatorListExpression(query: BrowserQuery): string;
+
+/**
+ * Compile cleanup for temporary screenshot styles and masks.
+ *
+ * @param token - Preparation token
+ * @returns Cleanup expression
+ */
+export declare function compileScreenshotCleanupExpression(token: string): string;
+
+/**
+ * Compile temporary animation, caret, and mask setup for a screenshot.
+ *
+ * @param options - Screenshot controls
+ * @returns Setup expression or undefined when no preparation is required
+ */
+export declare function compileScreenshotPreparationExpression(options?: BrowserScreenshotOptions): string | undefined;
+
+/**
+ * Compile a strict select expression.
+ *
+ * @param selector - CSS selector
+ * @param values - Option values to select
+ * @param strict - Whether more than one match is an error
+ * @returns Runtime expression
+ */
+export declare function compileSelectExpression(selector: string, values: readonly string[], strict: boolean): string;
+
+/**
+ * Compile 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.
+ *
+ * @returns In-page storage expression
+ */
+export declare function compileStorageReadExpression(): string;
+
+/**
+ * Compile an expression that restores one origin's web storage.
+ *
+ * @param origin - Storage values to restore
+ * @returns In-page restore expression
+ */
+export declare function compileStorageRestoreExpression(origin: BrowserStorageOrigin): string;
+
+/**
+ * Compile 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.
+ *
+ * @param selector - CSS selector
+ * @param strict - Whether more than one match is an error
+ * @param timeout - Maximum wait in milliseconds
+ * @returns Runtime expression resolving to whether the state was reached
+ */
+export declare function compileVisibleWaitExpression(selector: string, strict: boolean, timeout: number): string;
+
+/**
+ * Compute the CDP Input pressed-button bitmask.
+ *
+ * @param buttons - Currently pressed public mouse buttons
+ * @returns Combined CDP pressed-button mask
+ */
+export declare function computeBrowserButtons(buttons: readonly BrowserMouseButton[]): number;
+
+/**
+ * Compute the CDP Input modifier bitmask.
+ *
+ * @param modifiers - Canonical modifier names
+ * @returns Combined CDP modifier mask
+ */
+export declare function computeBrowserModifiers(modifiers: readonly string[]): number;
+
+/**
+ * Compute the edge count between two captured browser nodes.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param first - First node
+ * @param second - Second node
+ * @returns Tree distance, or undefined when no common ancestor exists
+ */
+export declare function computeBrowserNodeDistance(snapshot: BrowserSnapshot, first: BrowserNode, second: BrowserNode): number | undefined;
+
+/**
+ * Concatenate byte chunks without Node-specific buffers.
+ *
+ * @param chunks - Byte arrays in source order
+ * @returns Combined bytes
+ */
+export declare function concatBytes(chunks: readonly Uint8Array[]): Uint8Array;
+
+/**
+ * Convert a typed cookie input into Chromium protocol fields.
+ *
+ * @param cookie - Validated public cookie input
+ * @returns Protocol cookie record
+ */
+export declare function cookieToProtocol(cookie: BrowserCookieInput): Readonly<Record<string, unknown>>;
+
+/**
+ * Build 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
+ * @param body - Optional decoded response body
+ * @param error - Optional request failure description
+ * @returns HAR 1.2 entry
+ */
+export declare function createBrowserHAREntry(pending: BrowserHARPending, duration: number, body?: Uint8Array, error?: string): BrowserHAREntry;
+
+/**
+ * Create 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'
+ *
+ * const client = createCDPClient({ transport })
+ * await client.connect()
+ * ```
+ */
+export declare function createCDPClient(options: CDPClientOptions): CDPClientInterface;
+
+/**
+ * Decode a base64-encoded string into raw bytes.
+ *
+ * @remarks
+ * Pure JS implementation — no `Buffer`, no `atob` (DOM-only) — so it runs
+ * identically in Node and browser environments. Whitespace and `=` padding
+ * are ignored; invalid characters are skipped.
+ *
+ * @param text - Base64-encoded input string
+ * @returns Decoded bytes
+ *
+ * @example
+ * ```ts
+ * decodeBase64('aGVsbG8=') // Uint8Array [104, 101, 108, 108, 111]
+ * ```
+ */
+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): BrowserSnapshot;
+
+/**
+ * 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>;
+
+/**
+ * Lazily walk descendants of one captured node, excluding the node itself.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param root - Root whose descendants are required
+ * @returns A lazy descendant generator
+ */
+export declare function descendantsOfBrowserNode(snapshot: BrowserSnapshot, root: BrowserNode): Generator<BrowserNode, void, unknown>;
+
+/**
+ * Resolve the document containing a browser node.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param node - Node whose document is required
+ * @returns The containing document, or undefined
+ */
+export declare function documentOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): BrowserDocument | undefined;
+
+/**
+ * Encode raw bytes as base64 without relying on Node or DOM globals.
+ *
+ * @param bytes - Raw input bytes
+ * @returns Base64 text
+ */
+export declare function encodeBase64(bytes: Uint8Array): string;
+
+/**
+ * Find the first matching descendant beneath one captured node.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param root - Root whose descendants are searched
+ * @param predicate - Node predicate
+ * @returns First matching descendant, or undefined
+ */
+export declare function findBrowserDescendant(snapshot: BrowserSnapshot, root: BrowserNode, predicate: BrowserNodePredicate): BrowserNode | undefined;
+
+/**
+ * Find the first captured node satisfying a predicate.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param predicate - Node predicate
+ * @returns First matching node, or undefined
+ */
+export declare function findBrowserNode(snapshot: BrowserSnapshot, predicate: BrowserNodePredicate): BrowserNode | undefined;
+
+/**
+ * Find captured nodes satisfying a predicate.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param predicate - Node predicate
+ * @param limit - Optional maximum result count
+ * @returns Matching nodes in snapshot order
+ */
+export declare function findBrowserNodes(snapshot: BrowserSnapshot, predicate: BrowserNodePredicate, limit?: number): readonly BrowserNode[];
+
+/**
+ * Return structural siblings after the supplied browser node.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param node - Reference node
+ * @returns Later siblings in structural order
+ */
+export declare function followingSiblingsOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): readonly BrowserNode[];
+
+/**
+ * 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.
+ *
+ * @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 guardEvaluateExpression(expression: string, limit: number): string;
+
+/**
+ * Narrow an unknown value to BrowserError.
+ *
+ * @param value - Value to check
+ * @returns True when value is a BrowserError instance
+ */
+export declare function isBrowserError(value: unknown): value is BrowserError;
+
+/**
+ * Test whether one captured node is below another across frame boundaries.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param node - Candidate descendant
+ * @param ancestor - Candidate ancestor
+ * @returns Whether the relationship exists
+ */
+export declare function isBrowserNodeDescendant(snapshot: BrowserSnapshot, node: BrowserNode, ancestor: BrowserNode): boolean;
+
+/**
+ * Test 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
+ */
+export declare function isBrowserNodeVisible(node: BrowserNode): boolean;
+
+/**
+ * Narrow an unknown value to BrowserResultLimitError.
+ *
+ * @param value - Value to check
+ * @returns True when value is a BrowserResultLimitError instance
+ */
+export declare function isBrowserResultLimitError(value: unknown): value is BrowserResultLimitError;
+
+/**
+ * Narrow an unknown value to BrowserSelectorError.
+ *
+ * @param value - Value to check
+ * @returns True when value is a BrowserSelectorError instance
+ */
+export declare function isBrowserSelectorError(value: unknown): value is BrowserSelectorError;
+
+/**
+ * Narrow an unknown value to CDPConnectionError.
+ *
+ * @param value - Value to check
+ * @returns True when value is a CDPConnectionError instance
+ */
+export declare function isCDPConnectionError(value: unknown): value is CDPConnectionError;
+
+/**
+ * Narrow an unknown value to CDPError.
+ *
+ * @param value - Value to check
+ * @returns True when value is a CDPError instance
+ */
+export declare function isCDPError(value: unknown): value is CDPError;
+
+/**
+ * Narrow an unknown value to CDPTimeoutError.
+ *
+ * @param value - Value to check
+ * @returns True when value is a CDPTimeoutError instance
+ */
+export declare function isCDPTimeoutError(value: unknown): value is CDPTimeoutError;
+
+/**
+ * Normalize one key to CDP keyboard event data.
+ *
+ * @param value - Key value or canonical key name
+ * @returns Normalized key data
+ */
+export declare function keyToBrowserInput(value: string): BrowserKey;
+
+/**
+ * Match 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
+ */
+export declare function matchesBrowserCookieURL(cookie: BrowserCookie, value: string): boolean;
+
+/**
+ * Test a captured node against a declarative query.
+ *
+ * @param node - Captured browser node
+ * @param query - Fields every candidate must satisfy
+ * @returns Whether the node matches
+ */
+export declare function matchesBrowserNode(node: BrowserNode, query: BrowserNodeQuery): boolean;
+
+/**
+ * Match a request against route criteria.
+ *
+ * @param request - Observed request
+ * @param query - Match criteria
+ * @returns Whether every supplied criterion matches
+ */
+export declare function matchesBrowserRoute(request: BrowserRequest, query: BrowserRouteQuery): boolean;
+
+/**
+ * Match a URL using Chromium-style `*` and `**` glob segments.
+ *
+ * @param url - Candidate URL
+ * @param pattern - Glob pattern
+ * @returns Whether the whole URL matches
+ */
+export declare function matchesBrowserURL(url: string, pattern: string): boolean;
+
+/**
+ * Convert typed media preferences to Chromium emulated media features.
+ *
+ * @param media - Public media configuration
+ * @returns Protocol feature records
+ */
+export declare function mediaToFeatures(media: BrowserMedia): readonly Readonly<Record<string, string>>[];
+
+/**
+ * Build a deterministic, serializable path for a captured browser node.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param node - Captured browser node
+ * @returns Frame-qualified structural path
+ */
+export declare function nodeToPath(snapshot: BrowserSnapshot, node: BrowserNode): string;
+
+/**
+ * Normalize a raw list of recorded codegen actions.
+ *
+ * @remarks
+ * Collapses consecutive `fill` actions on the same selector into the latest
+ * value (a text input fires one `input` event per keystroke) so the
+ * compiled script reflects the final typed value rather than every
+ * intermediate keystroke.
+ *
+ * @param actions - Raw recorded actions, in capture order
+ * @returns Normalized actions, in the same order
+ */
+export declare function normalizeCodegenActions(actions: readonly BrowserCodegenAction[]): readonly BrowserCodegenAction[];
+
+/**
+ * Resolve the structural parent of a captured browser node.
+ *
+ * @remarks
+ * An iframe content-document root resolves to its owning iframe node.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param node - Child node
+ * @returns Parent node, or undefined for a top-level document root
+ */
+export declare function parentOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): BrowserNode | undefined;
+
+/**
+ * Parse a keyboard chord such as `Control+Shift+P`.
+ *
+ * @param value - Chord source
+ * @returns Canonical modifiers and terminal key
+ */
+export declare function parseBrowserChord(value: string): BrowserChord;
+
+/**
+ * Parse a codegen binding payload into a typed action.
+ *
+ * @remarks
+ * The in-page recorder script calls the CDP binding with a JSON string
+ * payload shaped like a {@link BrowserCodegenAction}. Returns `undefined`
+ * when the payload is not valid JSON or does not match a known action shape.
+ *
+ * @param payload - Raw binding call payload (the CDP `payload` param)
+ * @returns The parsed action, or `undefined` when the payload is malformed
+ */
+export declare function parseCodegenActionPayload(payload: unknown): BrowserCodegenAction | undefined;
+
+/**
+ * Return structural siblings before the supplied browser node.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param node - Reference node
+ * @returns Earlier siblings in structural order
+ */
+export declare function precedingSiblingsOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): readonly BrowserNode[];
+
+/**
+ * Decode Accessibility-domain nodes into a flat serializable tree.
+ *
+ * @param value - Unknown full or partial AX-tree result
+ * @returns Valid accessibility snapshot
+ */
+export declare function readBrowserAccessibility(value: unknown): BrowserAccessibilitySnapshot;
+
+/**
+ * Decode a string-valued Accessibility-domain AXValue.
+ *
+ * @param value - Unknown AX value
+ * @returns String or undefined
+ */
+export declare function readBrowserAXString(value: unknown): string | undefined;
+
+/**
+ * Decode an Accessibility-domain AXValue.
+ *
+ * @param value - Unknown AX value
+ * @returns Underlying value
+ */
+export declare function readBrowserAXValue(value: unknown): unknown;
+
+/**
+ * Decode one Runtime binding invocation.
+ *
+ * @param value - Unknown `Runtime.bindingCalled` parameters
+ * @returns Valid call or undefined
+ */
+export declare function readBrowserBindingCall(value: unknown): BrowserBindingCall | undefined;
+
+/**
+ * Decode one `Runtime.consoleAPICalled` event.
+ *
+ * @param value - Unknown event parameters
+ * @returns Console message or undefined
+ */
+export declare function readBrowserConsoleMessage(value: unknown): BrowserConsoleMessage | undefined;
+
+/**
+ * Decode one Chromium cookie.
+ *
+ * @param value - Unknown cookie record
+ * @param index - Source array position for diagnostics
+ * @returns Valid cookie
+ */
+export declare function readBrowserCookie(value: unknown, index: number): BrowserCookie;
+
+/**
+ * Decode an optional Chromium cookie partition key.
+ *
+ * @param value - Unknown partition value
+ * @returns Partition key or undefined
+ */
+export declare function readBrowserCookiePartition(value: unknown): BrowserCookiePartition | undefined;
+
+/**
+ * Decode cookies returned by `Storage.getCookies`.
+ *
+ * @param value - Unknown protocol result
+ * @returns Valid cookies
+ */
+export declare function readBrowserCookies(value: unknown): readonly BrowserCookie[];
+
+/**
+ * Decode coverage ranges.
+ *
+ * @param value - Unknown ranges
+ * @param script - Script index for diagnostics
+ * @returns Valid ranges
+ */
+export declare function readBrowserCoverageRanges(value: unknown, script: number): readonly BrowserCoverageRange[];
+
+/**
+ * Decode one `Browser.downloadProgress` event.
  *
- * @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)
+ * @param value - Unknown event parameters
+ * @returns Download id and progress, or undefined
  */
-export declare interface CDPClientOptions {
-    readonly transport: CDPTransportInterface;
-    readonly timeout?: number;
-}
+export declare function readBrowserDownloadProgress(value: unknown): readonly [id: string, progress: BrowserDownloadProgress] | undefined;
 
 /**
- * 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).
+ * Decode one `Browser.downloadWillBegin` event.
+ *
+ * @param value - Unknown event parameters
+ * @returns Download start or undefined
  */
-export declare class CDPConnectionError extends BrowserError {
-    constructor(message: string, context?: Readonly<Record<string, unknown>>);
-}
+export declare function readBrowserDownloadStart(value: unknown): BrowserDownloadStart | undefined;
 
 /**
- * A CDP request received an error response from the remote endpoint.
+ * Decode a flattened CDP `Page.getFrameTree` result.
  *
- * @remarks
- * Carries the originating `method` plus the CDP error's own `code`,
- * `message`, and `data` (when present) in `context`, so callers can branch
- * on the protocol-level error instead of parsing the message string.
+ * @param value - Unknown CDP result
+ * @returns Frame metadata in depth-first, main-frame-first order
  */
-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. */
-export declare type CDPHandler = (params: Readonly<Record<string, unknown>>) => void;
-
-/** One entry of the CDP `Target.getTargets` result. */
-export declare interface CDPTarget {
-    readonly id: string;
-    readonly type: string;
-    readonly title: string;
-    readonly url: string;
-}
+export declare function readBrowserFrames(value: unknown): readonly BrowserFrameInfo[];
 
 /**
- * A pending CDP request was not answered within its timeout window.
+ * Decode a Chromium Headers object into string values.
+ *
+ * @param value - Unknown headers
+ * @returns Frozen-compatible header record
  */
-export declare class CDPTimeoutError extends BrowserError {
-    constructor(message: string, context?: Readonly<Record<string, unknown>>);
-}
+export declare function readBrowserHeaders(value: unknown): Readonly<Record<string, string>>;
 
 /**
- * Event map for a {@link CDPTransportInterface} — the raw text pipe a
- * {@link CDPClientInterface} sends and receives JSON-RPC frames over.
+ * Decode Performance-domain metrics.
  *
- * @remarks
- * `message` carries one raw text frame; `close` signals the underlying
- * connection ended; `error` carries a transport-level fault (unknown shape —
- * narrow before use).
+ * @param value - Unknown metrics result
+ * @returns Valid metrics
  */
-export declare type CDPTransportEventMap = {
-    readonly message: readonly [data: string];
-    readonly close: readonly [];
-    readonly error: readonly [error: unknown];
-};
+export declare function readBrowserMetrics(value: unknown): readonly BrowserMetric[];
 
 /**
- * A dumb text transport CDPClient sends and receives JSON-RPC frames over.
+ * Decode one `Runtime.exceptionThrown` event.
  *
- * @remarks
- * The transport owns the connection (WebSocket, pipe, or any other duplex
- * channel) and the endpoint URL; it does no JSON framing of its own — that
- * stays in {@link CDPClientInterface}. Environment-specific transports
- * (a Node `WebSocket`, a browser `WebSocket`) live outside core and satisfy
- * this contract.
+ * @param value - Unknown event parameters
+ * @returns Page error or undefined
  */
-export declare interface CDPTransportInterface {
-    readonly emitter: EmitterInterface<CDPTransportEventMap>;
-    start(): Promise<void>;
-    send(data: string): Promise<void>;
-    close(): Promise<void>;
-}
+export declare function readBrowserPageError(value: unknown): BrowserPageError | undefined;
 
 /**
- * Compile recorded codegen actions into a replayable script.
- *
- * @remarks
- * Emits one statement per action against a `page` object shaped like
- * {@link BrowserPageInterface} (`page.navigate(...)`, `page.click(...)`, …).
- * Both target languages emit an `async function run(page)` body whose
- * statements are `await`-ed; `language` only toggles whether the `page`
- * parameter carries a TypeScript type annotation (default `'javascript'`).
+ * Decode one CPU profile.
  *
- * @param actions - Normalized actions to compile
- * @param options - Compilation options (target language)
- * @returns The compiled script source
+ * @param value - Unknown `Profiler.stop` result
+ * @returns Valid profile
  */
-export declare function compileCodegenScript(actions: readonly BrowserCodegenAction[], options?: BrowserCodegenScriptOptions): string;
+export declare function readBrowserProfile(value: unknown): BrowserProfile;
 
 /**
- * Create a CDP client bound to the given transport.
+ * Decode a CPU profile call frame.
  *
- * @param options - The transport (and optional timeout) the client uses
- * @returns A {@link CDPClientInterface}
+ * @param value - Unknown call frame
+ * @param node - Node index for diagnostics
+ * @returns Valid call frame
+ */
+export declare function readBrowserProfileFrame(value: unknown, node: number): BrowserProfileFrame;
+
+/**
+ * Decode the first `DOM.getContentQuads` quad and its center.
  *
- * @example
- * ```ts
- * import { createCDPClient } from '@src/core'
+ * @param value - Unknown CDP result
+ * @returns Decoded quad
+ */
+export declare function readBrowserQuad(value: unknown): BrowserQuad;
+
+/**
+ * Decode a CDP snapshot rectangle.
  *
- * const client = createCDPClient({ transport })
- * await client.connect()
- * ```
+ * @param value - Candidate four-number array
+ * @returns A rectangle, or undefined
  */
-export declare function createCDPClient(options: CDPClientOptions): CDPClientInterface;
+export declare function readBrowserRect(value: unknown): BrowserRect | undefined;
 
 /**
- * Decode a base64-encoded string into raw bytes.
+ * Decode a Runtime remote object's printable value.
  *
- * @remarks
- * Pure JS implementation — no `Buffer`, no `atob` (DOM-only) — so it runs
- * identically in Node and browser environments. Whitespace and `=` padding
- * are ignored; invalid characters are skipped.
+ * @param value - Unknown remote object
+ * @returns By-value data or a description
+ */
+export declare function readBrowserRemoteValue(value: unknown): unknown;
+
+/**
+ * Decode one `Network.requestWillBeSent` or `Fetch.requestPaused` event.
  *
- * @param text - Base64-encoded input string
- * @returns Decoded bytes
+ * @param value - Unknown event parameters
+ * @returns Request or undefined
+ */
+export declare function readBrowserRequest(value: unknown): BrowserRequest | undefined;
+
+/**
+ * Decode one `Network.loadingFailed` event.
  *
- * @example
- * ```ts
- * decodeBase64('aGVsbG8=') // Uint8Array [104, 101, 108, 108, 111]
- * ```
+ * @param value - Unknown event parameters
+ * @returns Failure or undefined
  */
-export declare function decodeBase64(text: string): Uint8Array;
+export declare function readBrowserRequestFailure(value: unknown): BrowserRequestFailure | undefined;
 
 /**
- * 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.
+ * Decode one `Network.responseReceived` event.
  *
- * @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.
+ * @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.
  *
- * 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 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.
  *
- * @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 - Unknown `Profiler.takePreciseCoverage` result
+ * @returns Script coverage
  */
-export declare function guardEvaluateExpression(expression: string, limit: number): string;
+export declare function readBrowserScriptCoverage(value: unknown): readonly BrowserScriptCoverage[];
 
 /**
- * Narrow an unknown value to BrowserError.
+ * Decode `Page.addScriptToEvaluateOnNewDocument` result.
  *
- * @param value - Value to check
- * @returns True when value is a BrowserError instance
+ * @param value - Unknown protocol result
+ * @returns Script identifier
  */
-export declare function isBrowserError(value: unknown): value is BrowserError;
+export declare function readBrowserScriptIdentifier(value: unknown): string;
 
 /**
- * Narrow an unknown value to BrowserResultLimitError.
+ * Decode Chromium TLS security details.
  *
- * @param value - Value to check
- * @returns True when value is a BrowserResultLimitError instance
+ * @param value - Unknown security details
+ * @returns Security metadata or undefined
  */
-export declare function isBrowserResultLimitError(value: unknown): value is BrowserResultLimitError;
+export declare function readBrowserSecurity(value: unknown): BrowserSecurity | undefined;
 
 /**
- * Narrow an unknown value to BrowserSelectorError.
+ * Decode a Chromium runtime stack trace.
  *
- * @param value - Value to check
- * @returns True when value is a BrowserSelectorError instance
+ * @param value - Unknown stack trace or call-frame list
+ * @returns Valid stack frames
  */
-export declare function isBrowserSelectorError(value: unknown): value is BrowserSelectorError;
+export declare function readBrowserStack(value: unknown): readonly BrowserStackFrame[];
 
 /**
- * Narrow an unknown value to CDPConnectionError.
+ * Decode a list of web-storage entries.
  *
- * @param value - Value to check
- * @returns True when value is a CDPConnectionError instance
+ * @param value - Unknown entry list
+ * @param origin - Origin used for diagnostics
+ * @param storage - Storage family used for diagnostics
+ * @returns Valid key/value entries
  */
-export declare function isCDPConnectionError(value: unknown): value is CDPConnectionError;
+export declare function readBrowserStorageEntries(value: unknown, origin: string, storage: 'local' | 'session'): readonly BrowserStorageEntry[];
 
 /**
- * Narrow an unknown value to CDPError.
+ * Decode one in-page web-storage snapshot.
  *
- * @param value - Value to check
- * @returns True when value is a CDPError instance
+ * @param value - Unknown evaluation result
+ * @param origin - Origin represented by the result
+ * @returns Valid origin storage
  */
-export declare function isCDPError(value: unknown): value is CDPError;
+export declare function readBrowserStorageOrigin(value: unknown, origin: string): BrowserStorageOrigin;
 
 /**
- * Narrow an unknown value to CDPTimeoutError.
+ * Decode one `IO.read` response.
  *
- * @param value - Value to check
- * @returns True when value is a CDPTimeoutError instance
+ * @param value - Unknown protocol result
+ * @returns Valid stream chunk
  */
-export declare function isCDPTimeoutError(value: unknown): value is CDPTimeoutError;
+export declare function readBrowserStreamChunk(value: unknown): BrowserStreamChunk;
 
 /**
- * Normalize a raw list of recorded codegen actions.
+ * Decode CSS rule usage.
  *
- * @remarks
- * Collapses consecutive `fill` actions on the same selector into the latest
- * value (a text input fires one `input` event per keystroke) so the
- * compiled script reflects the final typed value rather than every
- * intermediate keystroke.
+ * @param value - Unknown `CSS.stopRuleUsageTracking` result
+ * @returns Stylesheet coverage
+ */
+export declare function readBrowserStyleCoverage(value: unknown): readonly BrowserStyleCoverage[];
+
+/**
+ * Decode Chromium response timing.
  *
- * @param actions - Raw recorded actions, in capture order
- * @returns Normalized actions, in the same order
+ * @param value - Unknown timing object
+ * @returns Timing or undefined
  */
-export declare function normalizeCodegenActions(actions: readonly BrowserCodegenAction[]): readonly BrowserCodegenAction[];
+export declare function readBrowserTiming(value: unknown): BrowserTiming | undefined;
 
 /**
- * Parse a codegen binding payload into a typed action.
+ * Decode one start/end pair from Chromium network timing data.
  *
- * @remarks
- * The in-page recorder script calls the CDP binding with a JSON string
- * payload shaped like a {@link BrowserCodegenAction}. Returns `undefined`
- * when the payload is not valid JSON or does not match a known action shape.
+ * @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 payload - Raw binding call payload (the CDP `payload` param)
- * @returns The parsed action, or `undefined` when the payload is malformed
+ * @param value - Unknown event parameters
+ * @returns Frame or undefined
  */
-export declare function parseCodegenActionPayload(payload: unknown): BrowserCodegenAction | undefined;
+export declare function readBrowserWebSocketFrame(value: unknown): BrowserWebSocketFrame | undefined;
 
 /**
  * Derive a `navigate` codegen action from a `Page.frameNavigated` CDP event.
@@ -727,6 +3182,40 @@ export declare function parseCodegenActionPayload(payload: unknown): BrowserCode
  */
 export declare function readCodegenNavigateAction(params: Readonly<Record<string, unknown>>): BrowserCodegenAction | undefined;
 
+/**
+ * Decode one CDP `Runtime.evaluate` result.
+ *
+ * @param value - Unknown CDP result
+ * @returns The returned by-value payload, or undefined
+ */
+export declare function readEvaluationResult(value: unknown): unknown;
+
+/**
+ * Read an unknown value as an all-number array.
+ *
+ * @param value - Candidate value
+ * @returns The number array, or undefined
+ */
+export declare function readNumberArray(value: unknown): readonly number[] | undefined;
+
+/**
+ * Resolve one index from a CDP snapshot string table.
+ *
+ * @param strings - Snapshot string table
+ * @param index - Candidate string index
+ * @returns The resolved string, or undefined
+ */
+export declare function readSnapshotString(strings: readonly string[], index: unknown): string | undefined;
+
+/**
+ * Require an evaluated browser value to be a string.
+ *
+ * @param value - Candidate evaluated value
+ * @param field - Human-readable field name used in the error
+ * @returns The narrowed string
+ */
+export declare function requireBrowserString(value: unknown, field: string): string;
+
 /**
  * Pluggable sink for persisting screenshot bytes to a path.
  *
@@ -739,4 +3228,121 @@ export declare interface ScreenshotWriterInterface {
     write(path: string, data: Uint8Array): Promise<void>;
 }
 
+/**
+ * Return every structural sibling except the supplied browser node.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param node - Node whose siblings are required
+ * @returns Siblings in structural order
+ */
+export declare function siblingsOfBrowserNode(snapshot: BrowserSnapshot, node: BrowserNode): readonly BrowserNode[];
+
+/** Encode UTF-8 text as bytes. */
+export declare function textToBytes(value: string): Uint8Array;
+
+/**
+ * Validate 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.
+ *
+ * @param options - Public context configuration
+ */
+export declare function validateBrowserContextOptions(options?: BrowserContextOptions): void;
+
+/**
+ * Validate 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.
+ *
+ * @param value - Candidate archive
+ */
+export declare function validateBrowserHAR(value: unknown): asserts value is BrowserHAR;
+
+/**
+ * Validate viewport input coordinates.
+ *
+ * @param point - Candidate point
+ */
+export declare function validateBrowserPoint(point: BrowserPoint): void;
+
+/**
+ * Validate a finite numeric range.
+ *
+ * @param value - Candidate number
+ * @param field - Diagnostic field
+ * @param minimum - Inclusive lower bound
+ * @param maximum - Inclusive upper bound
+ * @param inclusive - Whether the lower bound is inclusive
+ */
+export declare function validateBrowserRange(value: number, field: string, minimum: number, maximum: number, inclusive?: boolean): void;
+
+/**
+ * Validate a public browser timeout before protocol work begins.
+ *
+ * @param timeout - Timeout in milliseconds
+ */
+export declare function validateBrowserTimeout(timeout: number): void;
+
+/**
+ * Validate Chromium viewport metrics.
+ *
+ * @param viewport - Public viewport configuration
+ */
+export declare function validateBrowserViewport(viewport: BrowserViewport): void;
+
+/**
+ * Lazily walk one captured browser-node subtree in depth-first order.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param root - Root node, included as the first result
+ * @returns A lazy subtree generator
+ */
+export declare function walkBrowserNode(snapshot: BrowserSnapshot, root: BrowserNode): Generator<BrowserNode, void, unknown>;
+
+/**
+ * Lazily walk one captured browser-node subtree in breadth-first order.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @param root - Root node, included as the first result
+ * @returns A lazy breadth-first subtree generator
+ */
+export declare function walkBrowserNodeBreadthFirst(snapshot: BrowserSnapshot, root: BrowserNode): Generator<BrowserNode, void, unknown>;
+
+/**
+ * Lazily walk every captured browser node in structural depth-first order.
+ *
+ * @remarks
+ * Iframe content documents are entered at their owner element. Orphaned or
+ * cyclic protocol nodes are still yielded once through an identity guard.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @returns A lazy node generator
+ */
+export declare function walkBrowserSnapshot(snapshot: BrowserSnapshot): Generator<BrowserNode, void, unknown>;
+
+/**
+ * Lazily walk every captured node in structural breadth-first order.
+ *
+ * @param snapshot - Captured browser snapshot
+ * @returns A lazy breadth-first generator
+ */
+export declare function walkBrowserSnapshotBreadthFirst(snapshot: BrowserSnapshot): Generator<BrowserNode, void, unknown>;
+
 export { }