browserclaw 0.5.7 → 0.6.0

package/dist/index.d.cts

@@ -1,8 +1,128 @@
-import * as playwright_core from 'playwright-core';
-import { BrowserContext } from 'playwright-core';
-import * as node_dns from 'node:dns';
-import { lookup as lookup$1 } from 'node:dns';
-import { lookup } from 'node:dns/promises';
+import { BrowserContext, Page, CDPSession } from 'playwright-core';
+import { lookup } from 'node:dns';
+import { lookup as lookup$1 } from 'node:dns/promises';
+
+/** A single action within a batch. */
+type BatchAction = {
+    kind: 'click';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    doubleClick?: boolean;
+    button?: string;
+    modifiers?: string[];
+    delayMs?: number;
+    timeoutMs?: number;
+} | {
+    kind: 'type';
+    ref?: string;
+    selector?: string;
+    text: string;
+    targetId?: string;
+    submit?: boolean;
+    slowly?: boolean;
+    timeoutMs?: number;
+} | {
+    kind: 'press';
+    key: string;
+    targetId?: string;
+    delayMs?: number;
+} | {
+    kind: 'hover';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'scrollIntoView';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'drag';
+    startRef?: string;
+    startSelector?: string;
+    endRef?: string;
+    endSelector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'select';
+    ref?: string;
+    selector?: string;
+    values: string[];
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'fill';
+    fields: {
+        ref: string;
+        type?: string;
+        value?: string | number | boolean;
+    }[];
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'resize';
+    width: number;
+    height: number;
+    targetId?: string;
+} | {
+    kind: 'wait';
+    timeMs?: number;
+    text?: string;
+    textGone?: string;
+    selector?: string;
+    url?: string;
+    loadState?: 'load' | 'domcontentloaded' | 'networkidle';
+    fn?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'evaluate';
+    fn: string;
+    ref?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'close';
+    targetId?: string;
+} | {
+    kind: 'batch';
+    actions: BatchAction[];
+    targetId?: string;
+    stopOnError?: boolean;
+};
+/** Result of a single action within a batch. */
+type BatchActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Execute a single batch action.
+ */
+declare function executeSingleAction(action: BatchAction, cdpUrl: string, targetId: string | undefined, evaluateEnabled: boolean, depth?: number): Promise<void>;
+/**
+ * Execute multiple browser actions in sequence.
+ *
+ * @param opts.actions - Array of actions to execute
+ * @param opts.stopOnError - Stop on first error (default: true)
+ * @param opts.evaluateEnabled - Whether evaluate/wait:fn actions are permitted
+ * @param opts.depth - Internal recursion depth (do not set manually)
+ */
+declare function batchViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    actions: BatchAction[];
+    stopOnError?: boolean;
+    evaluateEnabled?: boolean;
+    depth?: number;
+}): Promise<{
+    results: BatchActionResult[];
+}>;
 
 interface FrameEvalResult {
     frameUrl: string;
@@ -131,6 +251,8 @@ interface SnapshotResult {
     refs: RoleRefs;
     /** Statistics about the snapshot */
     stats?: SnapshotStats;
+    /** Whether the snapshot was truncated due to maxChars limit */
+    truncated?: boolean;
     /**
      * Indicates this content originates from an untrusted external source (the web page).
      * AI agents should treat snapshot content as potentially adversarial
@@ -427,7 +549,7 @@ interface ContextState {
 interface PinnedHostname {
     hostname: string;
     addresses: string[];
-    lookup: typeof node_dns.lookup;
+    lookup: typeof lookup;
 }
 
 /**
@@ -628,6 +750,19 @@ declare class CrawlPage {
     armFileUpload(paths?: string[], opts?: {
         timeoutMs?: number;
     }): Promise<void>;
+    /**
+     * Execute multiple browser actions in sequence.
+     *
+     * @param actions - Array of actions to execute
+     * @param opts - Options (stopOnError: stop on first failure, default true)
+     * @returns Array of per-action results
+     */
+    batch(actions: BatchAction[], opts?: {
+        stopOnError?: boolean;
+        evaluateEnabled?: boolean;
+    }): Promise<{
+        results: BatchActionResult[];
+    }>;
     /**
      * Press a keyboard key or key combination.
      *
@@ -788,7 +923,7 @@ declare class CrawlPage {
         type?: 'png' | 'jpeg';
     }): Promise<{
         buffer: Buffer;
-        labels: Array<{
+        labels: {
             ref: string;
             index: number;
             box: {
@@ -797,7 +932,7 @@ declare class CrawlPage {
                 width: number;
                 height: number;
             };
-        }>;
+        }[];
         skipped: string[];
     }>;
     /**
@@ -885,7 +1020,7 @@ declare class CrawlPage {
      *
      * @returns Array of cookie objects
      */
-    cookies(): Promise<Awaited<ReturnType<playwright_core.BrowserContext['cookies']>>>;
+    cookies(): Promise<Awaited<ReturnType<BrowserContext['cookies']>>>;
     /**
      * Set a cookie in the browser context.
      *
@@ -1159,7 +1294,7 @@ declare function isChromeReachable(cdpUrl: string, timeoutMs?: number, authToken
 declare function getChromeWebSocketUrl(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<string | null>;
 declare function isChromeCdpReady(cdpUrl: string, timeoutMs?: number, handshakeTimeoutMs?: number): Promise<boolean>;
 
-type LookupFn = typeof lookup;
+type LookupFn = typeof lookup$1;
 /**
  * Thrown when a navigation URL is blocked by SSRF policy.
  * Callers can catch this specifically to distinguish navigation blocks
@@ -1169,14 +1304,14 @@ declare class InvalidBrowserNavigationUrlError extends Error {
     constructor(message: string);
 }
 /** Options for browser navigation SSRF policy. */
-type BrowserNavigationPolicyOptions = {
+interface BrowserNavigationPolicyOptions {
     ssrfPolicy?: SsrfPolicy;
-};
+}
 /** Playwright-compatible request interface for redirect chain inspection. */
-type BrowserNavigationRequestLike = {
+interface BrowserNavigationRequestLike {
     url(): string;
     redirectedFrom(): BrowserNavigationRequestLike | null;
-};
+}
 /** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
 declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNavigationPolicyOptions;
 /**
@@ -1186,8 +1321,8 @@ declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNa
 declare function createPinnedLookup(params: {
     hostname: string;
     addresses: string[];
-    fallback?: typeof lookup$1;
-}): typeof lookup$1;
+    fallback?: typeof lookup;
+}): typeof lookup;
 /**
  * Resolve DNS for a hostname and validate resolved addresses against SSRF policy.
  * Returns a PinnedHostname with pre-resolved addresses and a pinned lookup function.
@@ -1204,6 +1339,24 @@ declare function assertBrowserNavigationAllowed(opts: {
     url: string;
     lookupFn?: LookupFn;
 } & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Validate upload file paths immediately before use.
+ */
+declare function assertSafeUploadPaths(paths: string[]): Promise<void>;
+/**
+ * Resolve and validate upload file paths, returning them if all are safe.
+ * Returns `{ ok: true, paths }` or `{ ok: false, error }`.
+ */
+declare function resolveStrictExistingUploadPaths(params: {
+    requestedPaths: string[];
+    scopeLabel?: string;
+}): Promise<{
+    ok: true;
+    paths: string[];
+} | {
+    ok: false;
+    error: string;
+}>;
 /**
  * Sanitize an untrusted file name (e.g. from a download) to prevent path traversal.
  */
@@ -1237,6 +1390,22 @@ declare function assertBrowserNavigationRedirectChainAllowed(opts: {
  */
 declare function requiresInspectableBrowserNavigationRedirects(ssrfPolicy?: SsrfPolicy): boolean;
 
+declare class BrowserTabNotFoundError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Run a function with a scoped Playwright CDP session, detaching when done.
+ */
+declare function withPlaywrightPageCdpSession<T>(page: Page, fn: (session: CDPSession) => Promise<T>): Promise<T>;
+/**
+ * Run a function with a page-scoped CDP client.
+ */
+declare function withPageScopedCdpClient<T>(opts: {
+    cdpUrl: string;
+    page: Page;
+    targetId?: string;
+    fn: (send: (method: string, params?: Record<string, unknown>) => Promise<unknown>) => Promise<T>;
+}): Promise<T>;
 declare function ensureContextState(context: BrowserContext): ContextState;
 /**
  * Force-disconnect a Playwright browser connection for a given CDP target.
@@ -1248,5 +1417,41 @@ declare function forceDisconnectPlaywrightForTarget(opts: {
     targetId?: string;
     reason?: string;
 }): Promise<void>;
+/**
+ * Resolve a page by targetId or throw BrowserTabNotFoundError.
+ */
+declare function resolvePageByTargetIdOrThrow(opts: {
+    cdpUrl: string;
+    targetId: string;
+}): Promise<Page>;
+/**
+ * Parse a role ref string (e.g. "e1", "@e1", "ref=e1") to a normalized ref ID.
+ * Returns null if the string is not a valid role ref.
+ */
+declare function parseRoleRef(raw: string): string | null;
+/**
+ * Require a ref string, normalizing and validating it.
+ * Throws if the ref is empty.
+ */
+declare function requireRef(value: string | undefined): string;
+/**
+ * Require either a ref or selector, returning whichever is provided.
+ * Throws if neither is provided.
+ */
+declare function requireRefOrSelector(ref?: string, selector?: string): {
+    ref?: string;
+    selector?: string;
+};
+/** Clamp interaction timeout to [500, 60000]ms range, defaulting to 8000ms. */
+declare function resolveInteractionTimeoutMs(timeoutMs?: number): number;
+/** Bounded delay validator for animation/interaction delays. */
+declare function resolveBoundedDelayMs(value: number | undefined, label: string, maxMs: number): number;
+/**
+ * Get a page for a target, ensuring page state is initialized and role refs are restored.
+ */
+declare function getRestoredPageForTarget(opts: {
+    cdpUrl: string;
+    targetId?: string;
+}): Promise<Page>;
 
-export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, createPinnedLookup, ensureContextState, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, requiresInspectableBrowserNavigationRedirects, resolvePinnedHostnameWithPolicy, sanitizeUntrustedFileName, withBrowserNavigationPolicy, writeViaSiblingTempPath };
+export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };

package/dist/index.d.ts

@@ -1,8 +1,128 @@
-import * as playwright_core from 'playwright-core';
-import { BrowserContext } from 'playwright-core';
-import * as node_dns from 'node:dns';
-import { lookup as lookup$1 } from 'node:dns';
-import { lookup } from 'node:dns/promises';
+import { BrowserContext, Page, CDPSession } from 'playwright-core';
+import { lookup } from 'node:dns';
+import { lookup as lookup$1 } from 'node:dns/promises';
+
+/** A single action within a batch. */
+type BatchAction = {
+    kind: 'click';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    doubleClick?: boolean;
+    button?: string;
+    modifiers?: string[];
+    delayMs?: number;
+    timeoutMs?: number;
+} | {
+    kind: 'type';
+    ref?: string;
+    selector?: string;
+    text: string;
+    targetId?: string;
+    submit?: boolean;
+    slowly?: boolean;
+    timeoutMs?: number;
+} | {
+    kind: 'press';
+    key: string;
+    targetId?: string;
+    delayMs?: number;
+} | {
+    kind: 'hover';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'scrollIntoView';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'drag';
+    startRef?: string;
+    startSelector?: string;
+    endRef?: string;
+    endSelector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'select';
+    ref?: string;
+    selector?: string;
+    values: string[];
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'fill';
+    fields: {
+        ref: string;
+        type?: string;
+        value?: string | number | boolean;
+    }[];
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'resize';
+    width: number;
+    height: number;
+    targetId?: string;
+} | {
+    kind: 'wait';
+    timeMs?: number;
+    text?: string;
+    textGone?: string;
+    selector?: string;
+    url?: string;
+    loadState?: 'load' | 'domcontentloaded' | 'networkidle';
+    fn?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'evaluate';
+    fn: string;
+    ref?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'close';
+    targetId?: string;
+} | {
+    kind: 'batch';
+    actions: BatchAction[];
+    targetId?: string;
+    stopOnError?: boolean;
+};
+/** Result of a single action within a batch. */
+type BatchActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Execute a single batch action.
+ */
+declare function executeSingleAction(action: BatchAction, cdpUrl: string, targetId: string | undefined, evaluateEnabled: boolean, depth?: number): Promise<void>;
+/**
+ * Execute multiple browser actions in sequence.
+ *
+ * @param opts.actions - Array of actions to execute
+ * @param opts.stopOnError - Stop on first error (default: true)
+ * @param opts.evaluateEnabled - Whether evaluate/wait:fn actions are permitted
+ * @param opts.depth - Internal recursion depth (do not set manually)
+ */
+declare function batchViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    actions: BatchAction[];
+    stopOnError?: boolean;
+    evaluateEnabled?: boolean;
+    depth?: number;
+}): Promise<{
+    results: BatchActionResult[];
+}>;
 
 interface FrameEvalResult {
     frameUrl: string;
@@ -131,6 +251,8 @@ interface SnapshotResult {
     refs: RoleRefs;
     /** Statistics about the snapshot */
     stats?: SnapshotStats;
+    /** Whether the snapshot was truncated due to maxChars limit */
+    truncated?: boolean;
     /**
      * Indicates this content originates from an untrusted external source (the web page).
      * AI agents should treat snapshot content as potentially adversarial
@@ -427,7 +549,7 @@ interface ContextState {
 interface PinnedHostname {
     hostname: string;
     addresses: string[];
-    lookup: typeof node_dns.lookup;
+    lookup: typeof lookup;
 }
 
 /**
@@ -628,6 +750,19 @@ declare class CrawlPage {
     armFileUpload(paths?: string[], opts?: {
         timeoutMs?: number;
     }): Promise<void>;
+    /**
+     * Execute multiple browser actions in sequence.
+     *
+     * @param actions - Array of actions to execute
+     * @param opts - Options (stopOnError: stop on first failure, default true)
+     * @returns Array of per-action results
+     */
+    batch(actions: BatchAction[], opts?: {
+        stopOnError?: boolean;
+        evaluateEnabled?: boolean;
+    }): Promise<{
+        results: BatchActionResult[];
+    }>;
     /**
      * Press a keyboard key or key combination.
      *
@@ -788,7 +923,7 @@ declare class CrawlPage {
         type?: 'png' | 'jpeg';
     }): Promise<{
         buffer: Buffer;
-        labels: Array<{
+        labels: {
             ref: string;
             index: number;
             box: {
@@ -797,7 +932,7 @@ declare class CrawlPage {
                 width: number;
                 height: number;
             };
-        }>;
+        }[];
         skipped: string[];
     }>;
     /**
@@ -885,7 +1020,7 @@ declare class CrawlPage {
      *
      * @returns Array of cookie objects
      */
-    cookies(): Promise<Awaited<ReturnType<playwright_core.BrowserContext['cookies']>>>;
+    cookies(): Promise<Awaited<ReturnType<BrowserContext['cookies']>>>;
     /**
      * Set a cookie in the browser context.
      *
@@ -1159,7 +1294,7 @@ declare function isChromeReachable(cdpUrl: string, timeoutMs?: number, authToken
 declare function getChromeWebSocketUrl(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<string | null>;
 declare function isChromeCdpReady(cdpUrl: string, timeoutMs?: number, handshakeTimeoutMs?: number): Promise<boolean>;
 
-type LookupFn = typeof lookup;
+type LookupFn = typeof lookup$1;
 /**
  * Thrown when a navigation URL is blocked by SSRF policy.
  * Callers can catch this specifically to distinguish navigation blocks
@@ -1169,14 +1304,14 @@ declare class InvalidBrowserNavigationUrlError extends Error {
     constructor(message: string);
 }
 /** Options for browser navigation SSRF policy. */
-type BrowserNavigationPolicyOptions = {
+interface BrowserNavigationPolicyOptions {
     ssrfPolicy?: SsrfPolicy;
-};
+}
 /** Playwright-compatible request interface for redirect chain inspection. */
-type BrowserNavigationRequestLike = {
+interface BrowserNavigationRequestLike {
     url(): string;
     redirectedFrom(): BrowserNavigationRequestLike | null;
-};
+}
 /** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
 declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNavigationPolicyOptions;
 /**
@@ -1186,8 +1321,8 @@ declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNa
 declare function createPinnedLookup(params: {
     hostname: string;
     addresses: string[];
-    fallback?: typeof lookup$1;
-}): typeof lookup$1;
+    fallback?: typeof lookup;
+}): typeof lookup;
 /**
  * Resolve DNS for a hostname and validate resolved addresses against SSRF policy.
  * Returns a PinnedHostname with pre-resolved addresses and a pinned lookup function.
@@ -1204,6 +1339,24 @@ declare function assertBrowserNavigationAllowed(opts: {
     url: string;
     lookupFn?: LookupFn;
 } & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Validate upload file paths immediately before use.
+ */
+declare function assertSafeUploadPaths(paths: string[]): Promise<void>;
+/**
+ * Resolve and validate upload file paths, returning them if all are safe.
+ * Returns `{ ok: true, paths }` or `{ ok: false, error }`.
+ */
+declare function resolveStrictExistingUploadPaths(params: {
+    requestedPaths: string[];
+    scopeLabel?: string;
+}): Promise<{
+    ok: true;
+    paths: string[];
+} | {
+    ok: false;
+    error: string;
+}>;
 /**
  * Sanitize an untrusted file name (e.g. from a download) to prevent path traversal.
  */
@@ -1237,6 +1390,22 @@ declare function assertBrowserNavigationRedirectChainAllowed(opts: {
  */
 declare function requiresInspectableBrowserNavigationRedirects(ssrfPolicy?: SsrfPolicy): boolean;
 
+declare class BrowserTabNotFoundError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Run a function with a scoped Playwright CDP session, detaching when done.
+ */
+declare function withPlaywrightPageCdpSession<T>(page: Page, fn: (session: CDPSession) => Promise<T>): Promise<T>;
+/**
+ * Run a function with a page-scoped CDP client.
+ */
+declare function withPageScopedCdpClient<T>(opts: {
+    cdpUrl: string;
+    page: Page;
+    targetId?: string;
+    fn: (send: (method: string, params?: Record<string, unknown>) => Promise<unknown>) => Promise<T>;
+}): Promise<T>;
 declare function ensureContextState(context: BrowserContext): ContextState;
 /**
  * Force-disconnect a Playwright browser connection for a given CDP target.
@@ -1248,5 +1417,41 @@ declare function forceDisconnectPlaywrightForTarget(opts: {
     targetId?: string;
     reason?: string;
 }): Promise<void>;
+/**
+ * Resolve a page by targetId or throw BrowserTabNotFoundError.
+ */
+declare function resolvePageByTargetIdOrThrow(opts: {
+    cdpUrl: string;
+    targetId: string;
+}): Promise<Page>;
+/**
+ * Parse a role ref string (e.g. "e1", "@e1", "ref=e1") to a normalized ref ID.
+ * Returns null if the string is not a valid role ref.
+ */
+declare function parseRoleRef(raw: string): string | null;
+/**
+ * Require a ref string, normalizing and validating it.
+ * Throws if the ref is empty.
+ */
+declare function requireRef(value: string | undefined): string;
+/**
+ * Require either a ref or selector, returning whichever is provided.
+ * Throws if neither is provided.
+ */
+declare function requireRefOrSelector(ref?: string, selector?: string): {
+    ref?: string;
+    selector?: string;
+};
+/** Clamp interaction timeout to [500, 60000]ms range, defaulting to 8000ms. */
+declare function resolveInteractionTimeoutMs(timeoutMs?: number): number;
+/** Bounded delay validator for animation/interaction delays. */
+declare function resolveBoundedDelayMs(value: number | undefined, label: string, maxMs: number): number;
+/**
+ * Get a page for a target, ensuring page state is initialized and role refs are restored.
+ */
+declare function getRestoredPageForTarget(opts: {
+    cdpUrl: string;
+    targetId?: string;
+}): Promise<Page>;
 
-export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, createPinnedLookup, ensureContextState, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, requiresInspectableBrowserNavigationRedirects, resolvePinnedHostnameWithPolicy, sanitizeUntrustedFileName, withBrowserNavigationPolicy, writeViaSiblingTempPath };
+export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };