@orkestrel/browser 0.0.1

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

@@ -0,0 +1,742 @@
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+
+/** Base64 alphabet, index-ordered, used to build {@link BASE64_LOOKUP}. */
+export declare const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/** Base64 character to 6-bit value lookup table, derived from {@link BASE64_CHARS}. */
+export declare const BASE64_LOOKUP: Readonly<Record<string, number>>;
+
+/** Name of the CDP runtime binding the codegen recorder script calls into. */
+export declare const BROWSER_CODEGEN_BINDING_NAME = "__orkestrelBrowserCodegen";
+
+/**
+ * In-page recorder script injected via `Page.addScriptToEvaluateOnNewDocument`
+ * and `Runtime.evaluate`.
+ *
+ * @remarks
+ * Attaches capturing-phase listeners for `click`, `input` (fill), and
+ * `change` (select) on `document`, builds a stable CSS selector for the
+ * target element, and forwards each action to the CDP binding
+ * ({@link BROWSER_CODEGEN_BINDING_NAME}) as a JSON string payload. Guarded to
+ * install exactly once per document (`window[name]` sentinel) so repeated
+ * injection on every new document is idempotent.
+ */
+export declare const BROWSER_CODEGEN_SOURCE: string;
+
+/** Default timeout in milliseconds for browser connection, requests, and navigation. */
+export declare const BROWSER_DEFAULT_TIMEOUT_MS = 30000;
+
+/** Default viewport height in pixels. */
+export declare const BROWSER_DEFAULT_VIEWPORT_HEIGHT = 720;
+
+/** Default viewport width in pixels. */
+export declare const BROWSER_DEFAULT_VIEWPORT_WIDTH = 1280;
+
+/**
+ * Maximum serialized-character length for an `evaluate()`/`content()` result,
+ * enforced IN-PAGE before the result is returned to CDP.
+ *
+ * @remarks
+ * This counts UTF-16 STRING LENGTH (`String#length`), not transport BYTES —
+ * the actual CDP frame is UTF-8 encoded (up to 3 bytes/char for common
+ * multibyte content) and carries additional JSON/CDP framing overhead on top
+ * of the raw content. A `Runtime.evaluate` result above this size, once
+ * framed as a CDP JSON response, overflows the native WebSocket inbound frame
+ * limit and closes the whole CDP connection — a page-level failure with no
+ * clean error. The limit is set well under the observed ~3-4MB transport
+ * ceiling (rather than at it) to leave headroom for the length-vs-bytes gap
+ * and framing overhead. The cap is enforced by stringifying the candidate
+ * result in-page and throwing a recognizable sentinel error (see
+ * {@link BROWSER_RESULT_LIMIT_SENTINEL_PREFIX}) before the oversized frame is
+ * ever produced, so the caller gets a coded error instead of a dropped
+ * connection.
+ */
+export declare const BROWSER_RESULT_LIMIT = 2500000;
+
+/**
+ * Matches the in-page result-limit sentinel error message, anchored
+ * immediately after the `Error: ` (optionally `Uncaught Error: `) prefix that
+ * Chromium prepends to a thrown error's description — so the guard's own
+ * throw is recognized only at the message START, not wherever the substring
+ * happens to occur.
+ */
+export declare const BROWSER_RESULT_LIMIT_PATTERN: RegExp;
+
+/**
+ * Distinctive prefix for the in-page result-limit sentinel error, immediately
+ * followed by the serialized length.
+ *
+ * @remarks
+ * Deliberately unlikely to appear in a page's own thrown error text (unlike
+ * a plain `BROWSER_RESULT_LIMIT: ` label), so {@link BROWSER_RESULT_LIMIT_PATTERN}
+ * can distinguish the guard's own throw from a page error that merely
+ * mentions similar text.
+ */
+export declare const BROWSER_RESULT_LIMIT_SENTINEL_PREFIX = "[[ORKESTREL_BROWSER_RESULT_LIMIT]]";
+
+/**
+ * Bound (in milliseconds) on the best-effort `Page.stopLoading` call issued
+ * after a failed `navigate()`.
+ *
+ * @remarks
+ * A wedged renderer can make the underlying CDP call hang for the full
+ * per-call timeout; capping it to a small fixed bound keeps a navigate
+ * failure's total latency close to the original timeout instead of doubling
+ * it. Best-effort only — never masks the original navigate error.
+ */
+export declare const BROWSER_STOP_LOADING_TIMEOUT_MS = 1000;
+
+/** Poll interval in milliseconds while waiting for a selector to appear. */
+export declare const BROWSER_WAIT_POLL_INTERVAL_MS = 100;
+
+/**
+ * Options for element interaction (click, fill, select, wait).
+ *
+ * @remarks
+ * - `timeout` — maximum time to wait for the selector in milliseconds
+ */
+export declare interface BrowserActionOptions {
+    readonly timeout?: number;
+}
+
+export declare class BrowserCodegen implements BrowserCodegenInterface {
+    #private;
+    constructor(client: CDPClientInterface, sessionId: string, options?: BrowserCodegenOptions);
+    get emitter(): EmitterInterface<BrowserCodegenEventMap>;
+    get started(): boolean;
+    start(): Promise<void>;
+    stop(): Promise<readonly BrowserCodegenAction[]>;
+    actions(): readonly BrowserCodegenAction[];
+    script(options?: BrowserCodegenScriptOptions): string;
+    clear(): void;
+    destroy(): Promise<void>;
+}
+
+/** One recorded browser action captured during a codegen session. */
+export declare type BrowserCodegenAction = {
+    readonly action: 'navigate';
+    readonly url: string;
+} | {
+    readonly action: 'click';
+    readonly selector: string;
+} | {
+    readonly action: 'fill';
+    readonly selector: string;
+    readonly value: string;
+} | {
+    readonly action: 'select';
+    readonly selector: string;
+    readonly values: readonly string[];
+};
+
+/**
+ * Event map for a {@link BrowserCodegenInterface}.
+ *
+ * @remarks
+ * - `start` — recording started
+ * - `stop` — recording stopped, carrying the final action list
+ * - `action` — one new action was captured
+ * - `clear` — recorded actions were reset
+ */
+export declare type BrowserCodegenEventMap = {
+    readonly start: readonly [];
+    readonly stop: readonly [actions: readonly BrowserCodegenAction[]];
+    readonly action: readonly [action: BrowserCodegenAction];
+    readonly clear: readonly [];
+};
+
+/**
+ * Records page interactions (navigation, click, fill, select) as a session
+ * runs, for later compilation into a replayable script.
+ *
+ * @remarks
+ * - `emitter` — subscribe to recording lifecycle and capture events
+ * - `started` — true while actively recording
+ * - `start` — begin recording on the page's session
+ * - `stop` — stop recording and return the captured actions
+ * - `actions` — current normalized action list
+ * - `script` — compile the captured actions into a script
+ * - `clear` — reset the captured action list
+ * - `destroy` — tear down the recorder and detach CDP listeners
+ */
+export declare interface BrowserCodegenInterface {
+    readonly emitter: EmitterInterface<BrowserCodegenEventMap>;
+    readonly started: boolean;
+    start(): Promise<void>;
+    stop(): Promise<readonly BrowserCodegenAction[]>;
+    actions(): readonly BrowserCodegenAction[];
+    script(options?: BrowserCodegenScriptOptions): string;
+    clear(): void;
+    destroy(): Promise<void>;
+}
+
+/** Target language for a compiled codegen script. */
+export declare type BrowserCodegenLanguage = 'javascript' | 'typescript';
+
+/**
+ * Options for creating a BrowserCodegen recorder.
+ *
+ * @remarks
+ * - `on` — initial event listeners wired at construction
+ */
+export declare interface BrowserCodegenOptions {
+    readonly on?: EmitterHooks<BrowserCodegenEventMap>;
+}
+
+/**
+ * Options for compiling recorded actions into a script.
+ *
+ * @remarks
+ * - `language` — target output language (default `'javascript'`)
+ */
+export declare interface BrowserCodegenScriptOptions {
+    readonly language?: BrowserCodegenLanguage;
+}
+
+/**
+ * Result of page content extraction.
+ *
+ * @remarks
+ * - `url` — current page URL after navigation
+ * - `title` — document title
+ * - `html` — full HTML source
+ * - `text` — visible text content (no markup)
+ */
+export declare interface BrowserContentResult {
+    readonly url: string;
+    readonly title: string;
+    readonly html: string;
+    readonly text: string;
+}
+
+export declare class BrowserContext implements BrowserContextInterface {
+    #private;
+    constructor(client: CDPClientInterface, id?: string, viewport?: BrowserViewport, writer?: ScreenshotWriterInterface);
+    get id(): string | undefined;
+    page(index?: number): BrowserPageInterface | undefined;
+    pages(): readonly BrowserPageInterface[];
+    create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
+    sync(targets: readonly CDPTarget[]): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * Isolated browser session over a CDP browser context.
+ *
+ * @remarks
+ * Follows the manager accessor pattern:
+ * - `page(index?)` → one page by index or the first page
+ * - `pages()` → all pages in creation order
+ *
+ * - `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
+ */
+export declare interface BrowserContextInterface {
+    readonly id: string | undefined;
+    page(index?: number): BrowserPageInterface | undefined;
+    pages(): readonly BrowserPageInterface[];
+    create(options?: BrowserPageOptions): Promise<BrowserPageInterface>;
+    sync(targets: readonly CDPTarget[]): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * Base error for all browser automation operations.
+ *
+ * @remarks
+ * Carries a machine-readable `code` and optional `context` (AGENTS §12) so
+ * callers can branch in a `catch` without parsing message strings.
+ */
+export declare class BrowserError extends Error {
+    readonly code: string;
+    readonly context: Readonly<Record<string, unknown>> | undefined;
+    constructor(message: string, code?: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/**
+ * 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
+ */
+export declare type BrowserFrame = {
+    readonly id: string;
+    readonly parent?: string;
+    readonly name?: string;
+    readonly url: string;
+};
+
+/**
+ * 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;
+}
+
+export declare class BrowserPage implements BrowserPageInterface {
+    #private;
+    constructor(client: CDPClientInterface, targetId: string, sessionId: string, writer?: ScreenshotWriterInterface, url?: string);
+    get url(): string;
+    get closed(): boolean;
+    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>;
+}
+
+/**
+ * Abstraction over a single browser page or frame.
+ *
+ * @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
+ * - `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
+ */
+export declare interface BrowserPageInterface {
+    readonly url: string;
+    readonly closed: boolean;
+    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>;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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>>);
+}
+
+/** Viewport dimensions for a browser page. */
+export declare interface BrowserViewport {
+    readonly width: number;
+    readonly height: number;
+}
+
+/** Page load condition for navigation — the CDP load event awaited by `navigate()`. */
+export declare type BrowserWaitUntil = 'load' | 'domcontentloaded';
+
+/**
+ * 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>;
+}
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+/**
+ * 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 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[];
+
+/**
+ * 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;
+
+/**
+ * Derive a `navigate` codegen action from a `Page.frameNavigated` CDP event.
+ *
+ * @remarks
+ * Only the top-level (main) frame's navigation is recorded — a frame
+ * carrying a `parentId` is a sub-frame and is ignored.
+ *
+ * @param params - The CDP `Page.frameNavigated` event params
+ * @returns A `navigate` action, or `undefined` when the event is not a
+ *   top-level navigation with a resolvable URL
+ */
+export declare function readCodegenNavigateAction(params: Readonly<Record<string, unknown>>): BrowserCodegenAction | undefined;
+
+/**
+ * Pluggable sink for persisting screenshot bytes to a path.
+ *
+ * @remarks
+ * Core never touches a filesystem directly — a page accepts an optional
+ * writer (server supplies an `fs`-backed implementation) and calls it when a
+ * screenshot request carries a `path`.
+ */
+export declare interface ScreenshotWriterInterface {
+    write(path: string, data: Uint8Array): Promise<void>;
+}
+
+export { }