browser-pilot 0.0.10 → 0.0.12

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 export { BatchExecutor, ValidationError, ValidationResult, addBatchToPage, validateSteps } from './actions.cjs';
-import { R as RequestPattern, a as RequestHandler, C as CaptureResult } from './types-CYw-7vx1.cjs';
-export { k as ActionOptions, l as ActionResult, A as ActionType, d as AudioChunk, e as AudioInput, f as AudioInputState, g as AudioOutput, B as BatchOptions, b as BatchResult, h as CaptureOptions, a3 as ClearCookiesOptions, m as ConsoleHandler, n as ConsoleMessage, o as ConsoleMessageType, Y as ContinueRequestOptions, a4 as Cookie, p as CustomSelectConfig, a5 as DeleteCookieOptions, O as DeviceDescriptor, Q as DeviceName, D as Dialog, q as DialogHandler, r as DialogType, s as Download, E as ElementInfo, t as ElementNotFoundError, u as EmulationState, v as ErrorHandler, Z as FailRequestOptions, F as FileInput, w as FillOptions, _ as FulfillRequestOptions, G as GeolocationOptions, I as InteractiveElement, $ as InterceptedRequest, N as NavigationError, x as NetworkIdleOptions, y as Page, z as PageError, H as PageSnapshot, P as PlayOptions, a0 as RequestActions, a1 as ResourceType, i as RoundTripOptions, j as RoundTripResult, a2 as RouteOptions, a6 as SetCookieOptions, J as SnapshotNode, S as Step, c as StepResult, K as SubmitOptions, T as TimeoutError, L as TypeOptions, U as UserAgentMetadata, M as UserAgentOptions, V as ViewportOptions, W as WaitForOptions, a7 as WaitOptions, a8 as WaitResult, a9 as WaitState, X as devices, aa as waitForAnyElement, ab as waitForElement, ac as waitForNavigation, ad as waitForNetworkIdle } from './types-CYw-7vx1.cjs';
+import { R as RequestPattern, a as RequestHandler, C as CaptureResult } from './types-BOPu0OQZ.cjs';
+export { k as ActionOptions, l as ActionResult, A as ActionType, d as AudioChunk, e as AudioInput, f as AudioInputState, g as AudioOutput, B as BatchOptions, b as BatchResult, h as CaptureOptions, a3 as ClearCookiesOptions, m as ConsoleHandler, n as ConsoleMessage, o as ConsoleMessageType, Y as ContinueRequestOptions, a4 as Cookie, p as CustomSelectConfig, a5 as DeleteCookieOptions, O as DeviceDescriptor, Q as DeviceName, D as Dialog, q as DialogHandler, r as DialogType, s as Download, E as ElementInfo, t as ElementNotFoundError, u as EmulationState, v as ErrorHandler, Z as FailRequestOptions, F as FileInput, w as FillOptions, _ as FulfillRequestOptions, G as GeolocationOptions, I as InteractiveElement, $ as InterceptedRequest, N as NavigationError, x as NetworkIdleOptions, y as Page, z as PageError, H as PageSnapshot, P as PlayOptions, a0 as RequestActions, a1 as ResourceType, i as RoundTripOptions, j as RoundTripResult, a2 as RouteOptions, a6 as SetCookieOptions, J as SnapshotNode, S as Step, c as StepResult, K as SubmitOptions, T as TimeoutError, L as TypeOptions, U as UserAgentMetadata, M as UserAgentOptions, V as ViewportOptions, W as WaitForOptions, a7 as WaitOptions, a8 as WaitResult, a9 as WaitState, X as devices, aa as waitForAnyElement, ab as waitForElement, ac as waitForNavigation, ad as waitForNetworkIdle } from './types-BOPu0OQZ.cjs';
 import { C as CDPClient } from './client-7Nqka5MV.cjs';
 export { a as CDPClientOptions, c as createCDPClient } from './client-7Nqka5MV.cjs';
-export { Browser, BrowserOptions, connect } from './browser.cjs';
+export { Browser, BrowserOptions, PageOptions, connect } from './browser.cjs';
 export { CDPError } from './cdp.cjs';
 export { BrowserBaseProvider, BrowserlessProvider, GenericProvider, createProvider, discoverTargets, getBrowserWebSocketUrl } from './providers.cjs';
 export { b as ConnectOptions, C as CreateSessionOptions, P as Provider, a as ProviderSession } from './types--wXNHUwt.cjs';

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { BatchExecutor, ValidationError, ValidationResult, addBatchToPage, validateSteps } from './actions.js';
-import { R as RequestPattern, a as RequestHandler, C as CaptureResult } from './types-DOGsEYQa.js';
-export { k as ActionOptions, l as ActionResult, A as ActionType, d as AudioChunk, e as AudioInput, f as AudioInputState, g as AudioOutput, B as BatchOptions, b as BatchResult, h as CaptureOptions, a3 as ClearCookiesOptions, m as ConsoleHandler, n as ConsoleMessage, o as ConsoleMessageType, Y as ContinueRequestOptions, a4 as Cookie, p as CustomSelectConfig, a5 as DeleteCookieOptions, O as DeviceDescriptor, Q as DeviceName, D as Dialog, q as DialogHandler, r as DialogType, s as Download, E as ElementInfo, t as ElementNotFoundError, u as EmulationState, v as ErrorHandler, Z as FailRequestOptions, F as FileInput, w as FillOptions, _ as FulfillRequestOptions, G as GeolocationOptions, I as InteractiveElement, $ as InterceptedRequest, N as NavigationError, x as NetworkIdleOptions, y as Page, z as PageError, H as PageSnapshot, P as PlayOptions, a0 as RequestActions, a1 as ResourceType, i as RoundTripOptions, j as RoundTripResult, a2 as RouteOptions, a6 as SetCookieOptions, J as SnapshotNode, S as Step, c as StepResult, K as SubmitOptions, T as TimeoutError, L as TypeOptions, U as UserAgentMetadata, M as UserAgentOptions, V as ViewportOptions, W as WaitForOptions, a7 as WaitOptions, a8 as WaitResult, a9 as WaitState, X as devices, aa as waitForAnyElement, ab as waitForElement, ac as waitForNavigation, ad as waitForNetworkIdle } from './types-DOGsEYQa.js';
+import { R as RequestPattern, a as RequestHandler, C as CaptureResult } from './types-j23Iqo2L.js';
+export { k as ActionOptions, l as ActionResult, A as ActionType, d as AudioChunk, e as AudioInput, f as AudioInputState, g as AudioOutput, B as BatchOptions, b as BatchResult, h as CaptureOptions, a3 as ClearCookiesOptions, m as ConsoleHandler, n as ConsoleMessage, o as ConsoleMessageType, Y as ContinueRequestOptions, a4 as Cookie, p as CustomSelectConfig, a5 as DeleteCookieOptions, O as DeviceDescriptor, Q as DeviceName, D as Dialog, q as DialogHandler, r as DialogType, s as Download, E as ElementInfo, t as ElementNotFoundError, u as EmulationState, v as ErrorHandler, Z as FailRequestOptions, F as FileInput, w as FillOptions, _ as FulfillRequestOptions, G as GeolocationOptions, I as InteractiveElement, $ as InterceptedRequest, N as NavigationError, x as NetworkIdleOptions, y as Page, z as PageError, H as PageSnapshot, P as PlayOptions, a0 as RequestActions, a1 as ResourceType, i as RoundTripOptions, j as RoundTripResult, a2 as RouteOptions, a6 as SetCookieOptions, J as SnapshotNode, S as Step, c as StepResult, K as SubmitOptions, T as TimeoutError, L as TypeOptions, U as UserAgentMetadata, M as UserAgentOptions, V as ViewportOptions, W as WaitForOptions, a7 as WaitOptions, a8 as WaitResult, a9 as WaitState, X as devices, aa as waitForAnyElement, ab as waitForElement, ac as waitForNavigation, ad as waitForNetworkIdle } from './types-j23Iqo2L.js';
 import { C as CDPClient } from './client-7Nqka5MV.js';
 export { a as CDPClientOptions, c as createCDPClient } from './client-7Nqka5MV.js';
-export { Browser, BrowserOptions, connect } from './browser.js';
+export { Browser, BrowserOptions, PageOptions, connect } from './browser.js';
 export { CDPError } from './cdp.js';
 export { BrowserBaseProvider, BrowserlessProvider, GenericProvider, createProvider, discoverTargets, getBrowserWebSocketUrl } from './providers.js';
 export { b as ConnectOptions, C as CreateSessionOptions, P as Provider, a as ProviderSession } from './types--wXNHUwt.js';

package/dist/index.mjs

@@ -16,11 +16,10 @@ import {
   waitForElement,
   waitForNavigation,
   waitForNetworkIdle
-} from "./chunk-7OSR2CAE.mjs";
+} from "./chunk-RUWAXHDX.mjs";
 import {
-  CDPError,
   createCDPClient
-} from "./chunk-BCOZUKWS.mjs";
+} from "./chunk-4MBSALQL.mjs";
 import {
   BrowserBaseProvider,
   BrowserlessProvider,
@@ -28,7 +27,7 @@ import {
   createProvider,
   discoverTargets,
   getBrowserWebSocketUrl
-} from "./chunk-R3PS4PCM.mjs";
+} from "./chunk-BRAFQUMG.mjs";
 import {
   BatchExecutor,
   ElementNotFoundError,
@@ -36,7 +35,10 @@ import {
   TimeoutError,
   addBatchToPage,
   validateSteps
-} from "./chunk-KKW2SZLV.mjs";
+} from "./chunk-NLIARNEE.mjs";
+import {
+  CDPError
+} from "./chunk-JXAUPHZM.mjs";
 
 // src/audio/flags.ts
 function getAudioChromeFlags(options) {

package/dist/providers.cjs

@@ -160,6 +160,34 @@ var BrowserlessProvider = class {
 };
 
 // src/providers/generic.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchDevToolsJson(host, path, errorPrefix, options = {}) {
+  const protocol = host.includes("://") ? "" : "http://";
+  const attempts = options.attempts ?? 1;
+  let delayMs = options.initialDelayMs ?? 50;
+  const maxDelayMs = options.maxDelayMs ?? 250;
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      const response = await fetch(`${protocol}${host}${path}`);
+      if (response.ok) {
+        return await response.json();
+      }
+      lastError = new Error(`${errorPrefix}: ${response.status}`);
+    } catch (error) {
+      lastError = new Error(
+        `${errorPrefix}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    if (attempt < attempts) {
+      await sleep(delayMs);
+      delayMs = Math.min(delayMs * 2, maxDelayMs);
+    }
+  }
+  throw lastError ?? new Error(errorPrefix);
+}
 var GenericProvider = class {
   name = "generic";
   wsUrl;
@@ -178,20 +206,14 @@ var GenericProvider = class {
   }
 };
 async function discoverTargets(host = "localhost:9222") {
-  const protocol = host.includes("://") ? "" : "http://";
-  const response = await fetch(`${protocol}${host}/json/list`);
-  if (!response.ok) {
-    throw new Error(`Failed to discover targets: ${response.status}`);
-  }
-  return await response.json();
+  return fetchDevToolsJson(host, "/json/list", "Failed to discover targets");
 }
 async function getBrowserWebSocketUrl(host = "localhost:9222") {
-  const protocol = host.includes("://") ? "" : "http://";
-  const response = await fetch(`${protocol}${host}/json/version`);
-  if (!response.ok) {
-    throw new Error(`Failed to get browser info: ${response.status}`);
-  }
-  const info = await response.json();
+  const info = await fetchDevToolsJson(host, "/json/version", "Failed to get browser info", {
+    attempts: 10,
+    initialDelayMs: 50,
+    maxDelayMs: 250
+  });
   return info.webSocketDebuggerUrl;
 }
 

package/dist/providers.mjs

@@ -5,7 +5,7 @@ import {
   createProvider,
   discoverTargets,
   getBrowserWebSocketUrl
-} from "./chunk-R3PS4PCM.mjs";
+} from "./chunk-BRAFQUMG.mjs";
 export {
   BrowserBaseProvider,
   BrowserlessProvider,

package/dist/{types-CYw-7vx1.d.cts → types-BOPu0OQZ.d.cts}

@@ -224,7 +224,9 @@ interface WaitResult {
     waitedMs: number;
 }
 /**
- * Wait for an element to reach a specific state
+ * Wait for an element to reach a specific state.
+ * Uses fast-fail: if the element is not found on a static page (no DOM mutations),
+ * returns early instead of polling for the full timeout.
  */
 declare function waitForElement(cdp: CDPClient, selector: string, options?: WaitOptions): Promise<WaitResult>;
 /**
@@ -270,14 +272,16 @@ interface ActionOptions {
     optional?: boolean;
 }
 interface FillOptions extends ActionOptions {
-    /** Clear existing content before filling */
-    clear?: boolean;
     /** Trigger blur after filling (useful for React/Vue frameworks that update on blur) */
     blur?: boolean;
+    /** Verify value stuck after fill; falls back to char-by-char typing if not (default: true) */
+    verify?: boolean;
 }
 interface TypeOptions extends ActionOptions {
     /** Delay between keystrokes in ms */
     delay?: number;
+    /** Blur the element after typing */
+    blur?: boolean;
 }
 interface SubmitOptions extends ActionOptions {
     /** How to submit: 'enter' | 'click' | 'enter+click' */
@@ -705,8 +709,12 @@ declare class Page {
     private frameExecutionContexts;
     /** Current frame's execution context ID (null = main frame default) */
     private currentFrameContextId;
+    /** Frame selector if context acquisition failed (cross-origin/sandboxed) */
+    private brokenFrame;
     /** Last matched selector from findElement (for selectorUsed tracking) */
     private _lastMatchedSelector;
+    /** Last snapshot for stale ref recovery */
+    private lastSnapshot?;
     /** Audio input controller (lazy-initialized) */
     private _audioInput?;
     /** Audio output controller (lazy-initialized) */
@@ -730,6 +738,7 @@ declare class Page {
      * Initialize the page (enable required CDP domains)
      */
     init(): Promise<void>;
+    private installEventListenerTracker;
     /**
      * Navigate to a URL
      */
@@ -757,8 +766,9 @@ declare class Page {
     /**
      * Click an element (supports multi-selector)
      *
-     * Uses CDP mouse events for regular elements. For form submit buttons,
-     * uses dispatchEvent to reliably trigger form submission in headless Chrome.
+     * Uses CDP mouse events (mouseMoved + mousePressed + mouseReleased) to
+     * simulate a real click. Real mouse events on submit buttons naturally
+     * trigger native form submission — no JS dispatch needed.
      */
     click(selector: string | string[], options?: ActionOptions): Promise<boolean>;
     /**
@@ -767,6 +777,10 @@ declare class Page {
     fill(selector: string | string[], value: string, options?: FillOptions): Promise<boolean>;
     /**
      * Type text character by character (for autocomplete fields, etc.)
+     *
+     * Uses proper keyDown/rawKeyDown distinction with US keyboard layout.
+     * Printable chars use 'keyDown' with text, non-text keys use 'rawKeyDown',
+     * and non-layout chars (emoji, CJK) fall back to Input.insertText.
      */
     type(selector: string | string[], text: string, options?: TypeOptions): Promise<boolean>;
     /**
@@ -779,11 +793,13 @@ declare class Page {
      */
     private selectCustom;
     /**
-     * Check a checkbox or radio button
+     * Check a checkbox or radio button using real mouse click.
+     * No-op if already checked. Verifies state changed after click.
      */
     check(selector: string | string[], options?: ActionOptions): Promise<boolean>;
     /**
-     * Uncheck a checkbox
+     * Uncheck a checkbox using real mouse click.
+     * No-op if already unchecked. Radio buttons can't be unchecked (returns true).
      */
     uncheck(selector: string | string[], options?: ActionOptions): Promise<boolean>;
     /**
@@ -799,9 +815,15 @@ declare class Page {
      */
     submit(selector: string | string[], options?: SubmitOptions): Promise<boolean>;
     /**
-     * Press a key
+     * Press a key, optionally with modifier keys held down
+     */
+    press(key: string, options?: {
+        modifiers?: Array<'Control' | 'Shift' | 'Alt' | 'Meta'>;
+    }): Promise<void>;
+    /**
+     * Execute a keyboard shortcut (e.g. "Control+a", "Meta+Shift+z")
      */
-    press(key: string): Promise<void>;
+    shortcut(combo: string): Promise<void>;
     /**
      * Focus an element
      */
@@ -864,6 +886,17 @@ declare class Page {
      * Set files on a file input
      */
     setInputFiles(selector: string | string[], files: FileInput[], options?: ActionOptions): Promise<boolean>;
+    private getNativeSelectMetadata;
+    private readNativeSelectValues;
+    private selectValuesMatch;
+    private applyNativeSelectByKeyboard;
+    private applyNativeSelectFallback;
+    private selectEditableContent;
+    private clearEditableSelection;
+    private readEditableValue;
+    private typeEditableFallback;
+    private applyRecordedSelectFallback;
+    private invokeRecordedEventListeners;
     /**
      * Wait for a download to complete, triggered by an action
      */
@@ -1074,17 +1107,31 @@ declare class Page {
      */
     private evaluateInFrame;
     /**
-     * Scroll an element into view
+     * Scroll an element into view, with fallback to center-scroll if clipped by fixed headers
      */
     private scrollIntoView;
+    /**
+     * Check if element is within the visible viewport
+     */
+    private isInViewport;
     /**
      * Get element box model (position and dimensions)
      */
     private getBoxModel;
     /**
-     * Click an element by node ID
+     * Click an element by node ID using Playwright's 3-event sequence:
+     * mouseMoved → mousePressed → mouseReleased (sequential).
+     * Uses DOM.getContentQuads for accurate coordinates (handles CSS transforms).
+     * Falls back to JS this.click() if CDP mouse dispatch fails.
      */
     private clickElement;
+    /**
+     * Resolve a nodeId to a Remote Object ID for use with Runtime.callFunctionOn
+     */
+    private resolveObjectId;
+    private dispatchKeyDefinition;
+    private dispatchKey;
+    private dispatchKeyWithModifiers;
     /**
      * Audio input controller (fake microphone).
      * Lazy-initialized on first access.
@@ -1120,13 +1167,22 @@ declare class Page {
      * ```
      */
     audioRoundTrip(options: RoundTripOptions): Promise<RoundTripResult>;
+    /**
+     * Wait for a DOM mutation in the current frame (used for detecting client-side form handling)
+     */
+    private waitForDOMMutation;
+    /**
+     * Wait for a frame execution context via Runtime.executionContextCreated event
+     */
+    private waitForFrameContext;
 }
 
 /**
  * Action/Step types for batch execution
  */
 
-type ActionType = 'goto' | 'click' | 'fill' | 'type' | 'select' | 'check' | 'uncheck' | 'submit' | 'press' | 'focus' | 'hover' | 'scroll' | 'wait' | 'snapshot' | 'screenshot' | 'evaluate' | 'text' | 'switchFrame' | 'switchToMain';
+type FailureReason = 'missing' | 'hidden' | 'covered' | 'disabled' | 'readonly' | 'detached' | 'replaced' | 'notEditable' | 'timeout' | 'navigation' | 'cdpError' | 'unknown';
+type ActionType = 'goto' | 'click' | 'fill' | 'type' | 'select' | 'check' | 'uncheck' | 'submit' | 'press' | 'shortcut' | 'focus' | 'hover' | 'scroll' | 'wait' | 'snapshot' | 'screenshot' | 'evaluate' | 'text' | 'switchFrame' | 'switchToMain' | 'assertVisible' | 'assertExists' | 'assertText' | 'assertUrl' | 'assertValue';
 interface Step {
     /** Action type */
     action: ActionType;
@@ -1138,6 +1194,10 @@ interface Step {
     value?: string | string[];
     /** Key for press action */
     key?: string;
+    /** Key combo for shortcut action (e.g. "Control+a", "Meta+Shift+z") */
+    combo?: string;
+    /** Modifier keys for press action */
+    modifiers?: Array<'Control' | 'Shift' | 'Alt' | 'Meta'>;
     /** What to wait for (wait action) */
     waitFor?: 'visible' | 'hidden' | 'attached' | 'detached' | 'navigation' | 'networkIdle';
     /** Step-specific timeout override (ms) */
@@ -1146,14 +1206,12 @@ interface Step {
     optional?: boolean;
     /** Submit method */
     method?: 'enter' | 'click' | 'enter+click';
-    /** Clear input before filling */
-    clear?: boolean;
     /** Trigger blur after filling (for React/Vue frameworks) */
     blur?: boolean;
     /** Delay between keystrokes for type action */
     delay?: number;
-    /** Wait for navigation after click action completes */
-    waitForNavigation?: boolean;
+    /** Wait mode after click/submit: true, false, or 'auto' for submit heuristics */
+    waitForNavigation?: boolean | 'auto';
     /** Custom select: trigger selector */
     trigger?: string | string[];
     /** Custom select: option selector */
@@ -1171,6 +1229,12 @@ interface Step {
     format?: 'png' | 'jpeg' | 'webp';
     quality?: number;
     fullPage?: boolean;
+    /** Expected value for assertion steps (substring match for assertText, exact for assertValue/assertUrl) */
+    expect?: string;
+    /** Retry count for assertion or action steps (default: 0 = no retry) */
+    retry?: number;
+    /** Delay between retries in ms (default: 500) */
+    retryDelay?: number;
 }
 interface BatchOptions {
     /** Default timeout for all steps (ms) */
@@ -1204,6 +1268,16 @@ interface StepResult {
     text?: string;
     /** Failure hints when element not found */
     hints?: FailureHint[];
+    /** Structured failure classification */
+    failureReason?: FailureReason;
+    /** Element covering the target (when failureReason is 'covered') */
+    coveringElement?: {
+        tag: string;
+        id?: string;
+        className?: string;
+    };
+    /** AI-friendly suggestion for what to try next */
+    suggestion?: string;
 }
 interface BatchResult {
     /** Whether all steps succeeded */
@@ -1216,4 +1290,4 @@ interface BatchResult {
     totalDurationMs: number;
 }
 
-export { type InterceptedRequest as $, type ActionType as A, type BatchOptions as B, type CaptureResult as C, type Dialog as D, type ElementInfo as E, type FileInput as F, type GeolocationOptions as G, type PageSnapshot as H, type InteractiveElement as I, type SnapshotNode as J, type SubmitOptions as K, type TypeOptions as L, type UserAgentOptions as M, NavigationError as N, type DeviceDescriptor as O, type PlayOptions as P, type DeviceName as Q, type RequestPattern as R, type Step as S, TimeoutError as T, type UserAgentMetadata as U, type ViewportOptions as V, type WaitForOptions as W, devices as X, type ContinueRequestOptions as Y, type FailRequestOptions as Z, type FulfillRequestOptions as _, type RequestHandler as a, type RequestActions as a0, type ResourceType as a1, type RouteOptions as a2, type ClearCookiesOptions as a3, type Cookie as a4, type DeleteCookieOptions as a5, type SetCookieOptions as a6, type WaitOptions as a7, type WaitResult as a8, type WaitState as a9, waitForAnyElement as aa, waitForElement as ab, waitForNavigation as ac, waitForNetworkIdle as ad, type FailureHint as ae, type BatchResult as b, type StepResult as c, type AudioChunk as d, AudioInput as e, type AudioInputState as f, AudioOutput as g, type CaptureOptions as h, type RoundTripOptions as i, type RoundTripResult as j, type ActionOptions as k, type ActionResult as l, type ConsoleHandler as m, type ConsoleMessage as n, type ConsoleMessageType as o, type CustomSelectConfig as p, type DialogHandler as q, type DialogType as r, type Download as s, ElementNotFoundError as t, type EmulationState as u, type ErrorHandler as v, type FillOptions as w, type NetworkIdleOptions as x, Page as y, type PageError as z };
+export { type InterceptedRequest as $, type ActionType as A, type BatchOptions as B, type CaptureResult as C, type Dialog as D, type ElementInfo as E, type FileInput as F, type GeolocationOptions as G, type PageSnapshot as H, type InteractiveElement as I, type SnapshotNode as J, type SubmitOptions as K, type TypeOptions as L, type UserAgentOptions as M, NavigationError as N, type DeviceDescriptor as O, type PlayOptions as P, type DeviceName as Q, type RequestPattern as R, type Step as S, TimeoutError as T, type UserAgentMetadata as U, type ViewportOptions as V, type WaitForOptions as W, devices as X, type ContinueRequestOptions as Y, type FailRequestOptions as Z, type FulfillRequestOptions as _, type RequestHandler as a, type RequestActions as a0, type ResourceType as a1, type RouteOptions as a2, type ClearCookiesOptions as a3, type Cookie as a4, type DeleteCookieOptions as a5, type SetCookieOptions as a6, type WaitOptions as a7, type WaitResult as a8, type WaitState as a9, waitForAnyElement as aa, waitForElement as ab, waitForNavigation as ac, waitForNetworkIdle as ad, type FailureHint as ae, type FailureReason as af, type BatchResult as b, type StepResult as c, type AudioChunk as d, AudioInput as e, type AudioInputState as f, AudioOutput as g, type CaptureOptions as h, type RoundTripOptions as i, type RoundTripResult as j, type ActionOptions as k, type ActionResult as l, type ConsoleHandler as m, type ConsoleMessage as n, type ConsoleMessageType as o, type CustomSelectConfig as p, type DialogHandler as q, type DialogType as r, type Download as s, ElementNotFoundError as t, type EmulationState as u, type ErrorHandler as v, type FillOptions as w, type NetworkIdleOptions as x, Page as y, type PageError as z };

package/dist/{types-DOGsEYQa.d.ts → types-j23Iqo2L.d.ts}

@@ -224,7 +224,9 @@ interface WaitResult {
     waitedMs: number;
 }
 /**
- * Wait for an element to reach a specific state
+ * Wait for an element to reach a specific state.
+ * Uses fast-fail: if the element is not found on a static page (no DOM mutations),
+ * returns early instead of polling for the full timeout.
  */
 declare function waitForElement(cdp: CDPClient, selector: string, options?: WaitOptions): Promise<WaitResult>;
 /**
@@ -270,14 +272,16 @@ interface ActionOptions {
     optional?: boolean;
 }
 interface FillOptions extends ActionOptions {
-    /** Clear existing content before filling */
-    clear?: boolean;
     /** Trigger blur after filling (useful for React/Vue frameworks that update on blur) */
     blur?: boolean;
+    /** Verify value stuck after fill; falls back to char-by-char typing if not (default: true) */
+    verify?: boolean;
 }
 interface TypeOptions extends ActionOptions {
     /** Delay between keystrokes in ms */
     delay?: number;
+    /** Blur the element after typing */
+    blur?: boolean;
 }
 interface SubmitOptions extends ActionOptions {
     /** How to submit: 'enter' | 'click' | 'enter+click' */
@@ -705,8 +709,12 @@ declare class Page {
     private frameExecutionContexts;
     /** Current frame's execution context ID (null = main frame default) */
     private currentFrameContextId;
+    /** Frame selector if context acquisition failed (cross-origin/sandboxed) */
+    private brokenFrame;
     /** Last matched selector from findElement (for selectorUsed tracking) */
     private _lastMatchedSelector;
+    /** Last snapshot for stale ref recovery */
+    private lastSnapshot?;
     /** Audio input controller (lazy-initialized) */
     private _audioInput?;
     /** Audio output controller (lazy-initialized) */
@@ -730,6 +738,7 @@ declare class Page {
      * Initialize the page (enable required CDP domains)
      */
     init(): Promise<void>;
+    private installEventListenerTracker;
     /**
      * Navigate to a URL
      */
@@ -757,8 +766,9 @@ declare class Page {
     /**
      * Click an element (supports multi-selector)
      *
-     * Uses CDP mouse events for regular elements. For form submit buttons,
-     * uses dispatchEvent to reliably trigger form submission in headless Chrome.
+     * Uses CDP mouse events (mouseMoved + mousePressed + mouseReleased) to
+     * simulate a real click. Real mouse events on submit buttons naturally
+     * trigger native form submission — no JS dispatch needed.
      */
     click(selector: string | string[], options?: ActionOptions): Promise<boolean>;
     /**
@@ -767,6 +777,10 @@ declare class Page {
     fill(selector: string | string[], value: string, options?: FillOptions): Promise<boolean>;
     /**
      * Type text character by character (for autocomplete fields, etc.)
+     *
+     * Uses proper keyDown/rawKeyDown distinction with US keyboard layout.
+     * Printable chars use 'keyDown' with text, non-text keys use 'rawKeyDown',
+     * and non-layout chars (emoji, CJK) fall back to Input.insertText.
      */
     type(selector: string | string[], text: string, options?: TypeOptions): Promise<boolean>;
     /**
@@ -779,11 +793,13 @@ declare class Page {
      */
     private selectCustom;
     /**
-     * Check a checkbox or radio button
+     * Check a checkbox or radio button using real mouse click.
+     * No-op if already checked. Verifies state changed after click.
      */
     check(selector: string | string[], options?: ActionOptions): Promise<boolean>;
     /**
-     * Uncheck a checkbox
+     * Uncheck a checkbox using real mouse click.
+     * No-op if already unchecked. Radio buttons can't be unchecked (returns true).
      */
     uncheck(selector: string | string[], options?: ActionOptions): Promise<boolean>;
     /**
@@ -799,9 +815,15 @@ declare class Page {
      */
     submit(selector: string | string[], options?: SubmitOptions): Promise<boolean>;
     /**
-     * Press a key
+     * Press a key, optionally with modifier keys held down
+     */
+    press(key: string, options?: {
+        modifiers?: Array<'Control' | 'Shift' | 'Alt' | 'Meta'>;
+    }): Promise<void>;
+    /**
+     * Execute a keyboard shortcut (e.g. "Control+a", "Meta+Shift+z")
      */
-    press(key: string): Promise<void>;
+    shortcut(combo: string): Promise<void>;
     /**
      * Focus an element
      */
@@ -864,6 +886,17 @@ declare class Page {
      * Set files on a file input
      */
     setInputFiles(selector: string | string[], files: FileInput[], options?: ActionOptions): Promise<boolean>;
+    private getNativeSelectMetadata;
+    private readNativeSelectValues;
+    private selectValuesMatch;
+    private applyNativeSelectByKeyboard;
+    private applyNativeSelectFallback;
+    private selectEditableContent;
+    private clearEditableSelection;
+    private readEditableValue;
+    private typeEditableFallback;
+    private applyRecordedSelectFallback;
+    private invokeRecordedEventListeners;
     /**
      * Wait for a download to complete, triggered by an action
      */
@@ -1074,17 +1107,31 @@ declare class Page {
      */
     private evaluateInFrame;
     /**
-     * Scroll an element into view
+     * Scroll an element into view, with fallback to center-scroll if clipped by fixed headers
      */
     private scrollIntoView;
+    /**
+     * Check if element is within the visible viewport
+     */
+    private isInViewport;
     /**
      * Get element box model (position and dimensions)
      */
     private getBoxModel;
     /**
-     * Click an element by node ID
+     * Click an element by node ID using Playwright's 3-event sequence:
+     * mouseMoved → mousePressed → mouseReleased (sequential).
+     * Uses DOM.getContentQuads for accurate coordinates (handles CSS transforms).
+     * Falls back to JS this.click() if CDP mouse dispatch fails.
      */
     private clickElement;
+    /**
+     * Resolve a nodeId to a Remote Object ID for use with Runtime.callFunctionOn
+     */
+    private resolveObjectId;
+    private dispatchKeyDefinition;
+    private dispatchKey;
+    private dispatchKeyWithModifiers;
     /**
      * Audio input controller (fake microphone).
      * Lazy-initialized on first access.
@@ -1120,13 +1167,22 @@ declare class Page {
      * ```
      */
     audioRoundTrip(options: RoundTripOptions): Promise<RoundTripResult>;
+    /**
+     * Wait for a DOM mutation in the current frame (used for detecting client-side form handling)
+     */
+    private waitForDOMMutation;
+    /**
+     * Wait for a frame execution context via Runtime.executionContextCreated event
+     */
+    private waitForFrameContext;
 }
 
 /**
  * Action/Step types for batch execution
  */
 
-type ActionType = 'goto' | 'click' | 'fill' | 'type' | 'select' | 'check' | 'uncheck' | 'submit' | 'press' | 'focus' | 'hover' | 'scroll' | 'wait' | 'snapshot' | 'screenshot' | 'evaluate' | 'text' | 'switchFrame' | 'switchToMain';
+type FailureReason = 'missing' | 'hidden' | 'covered' | 'disabled' | 'readonly' | 'detached' | 'replaced' | 'notEditable' | 'timeout' | 'navigation' | 'cdpError' | 'unknown';
+type ActionType = 'goto' | 'click' | 'fill' | 'type' | 'select' | 'check' | 'uncheck' | 'submit' | 'press' | 'shortcut' | 'focus' | 'hover' | 'scroll' | 'wait' | 'snapshot' | 'screenshot' | 'evaluate' | 'text' | 'switchFrame' | 'switchToMain' | 'assertVisible' | 'assertExists' | 'assertText' | 'assertUrl' | 'assertValue';
 interface Step {
     /** Action type */
     action: ActionType;
@@ -1138,6 +1194,10 @@ interface Step {
     value?: string | string[];
     /** Key for press action */
     key?: string;
+    /** Key combo for shortcut action (e.g. "Control+a", "Meta+Shift+z") */
+    combo?: string;
+    /** Modifier keys for press action */
+    modifiers?: Array<'Control' | 'Shift' | 'Alt' | 'Meta'>;
     /** What to wait for (wait action) */
     waitFor?: 'visible' | 'hidden' | 'attached' | 'detached' | 'navigation' | 'networkIdle';
     /** Step-specific timeout override (ms) */
@@ -1146,14 +1206,12 @@ interface Step {
     optional?: boolean;
     /** Submit method */
     method?: 'enter' | 'click' | 'enter+click';
-    /** Clear input before filling */
-    clear?: boolean;
     /** Trigger blur after filling (for React/Vue frameworks) */
     blur?: boolean;
     /** Delay between keystrokes for type action */
     delay?: number;
-    /** Wait for navigation after click action completes */
-    waitForNavigation?: boolean;
+    /** Wait mode after click/submit: true, false, or 'auto' for submit heuristics */
+    waitForNavigation?: boolean | 'auto';
     /** Custom select: trigger selector */
     trigger?: string | string[];
     /** Custom select: option selector */
@@ -1171,6 +1229,12 @@ interface Step {
     format?: 'png' | 'jpeg' | 'webp';
     quality?: number;
     fullPage?: boolean;
+    /** Expected value for assertion steps (substring match for assertText, exact for assertValue/assertUrl) */
+    expect?: string;
+    /** Retry count for assertion or action steps (default: 0 = no retry) */
+    retry?: number;
+    /** Delay between retries in ms (default: 500) */
+    retryDelay?: number;
 }
 interface BatchOptions {
     /** Default timeout for all steps (ms) */
@@ -1204,6 +1268,16 @@ interface StepResult {
     text?: string;
     /** Failure hints when element not found */
     hints?: FailureHint[];
+    /** Structured failure classification */
+    failureReason?: FailureReason;
+    /** Element covering the target (when failureReason is 'covered') */
+    coveringElement?: {
+        tag: string;
+        id?: string;
+        className?: string;
+    };
+    /** AI-friendly suggestion for what to try next */
+    suggestion?: string;
 }
 interface BatchResult {
     /** Whether all steps succeeded */
@@ -1216,4 +1290,4 @@ interface BatchResult {
     totalDurationMs: number;
 }
 
-export { type InterceptedRequest as $, type ActionType as A, type BatchOptions as B, type CaptureResult as C, type Dialog as D, type ElementInfo as E, type FileInput as F, type GeolocationOptions as G, type PageSnapshot as H, type InteractiveElement as I, type SnapshotNode as J, type SubmitOptions as K, type TypeOptions as L, type UserAgentOptions as M, NavigationError as N, type DeviceDescriptor as O, type PlayOptions as P, type DeviceName as Q, type RequestPattern as R, type Step as S, TimeoutError as T, type UserAgentMetadata as U, type ViewportOptions as V, type WaitForOptions as W, devices as X, type ContinueRequestOptions as Y, type FailRequestOptions as Z, type FulfillRequestOptions as _, type RequestHandler as a, type RequestActions as a0, type ResourceType as a1, type RouteOptions as a2, type ClearCookiesOptions as a3, type Cookie as a4, type DeleteCookieOptions as a5, type SetCookieOptions as a6, type WaitOptions as a7, type WaitResult as a8, type WaitState as a9, waitForAnyElement as aa, waitForElement as ab, waitForNavigation as ac, waitForNetworkIdle as ad, type FailureHint as ae, type BatchResult as b, type StepResult as c, type AudioChunk as d, AudioInput as e, type AudioInputState as f, AudioOutput as g, type CaptureOptions as h, type RoundTripOptions as i, type RoundTripResult as j, type ActionOptions as k, type ActionResult as l, type ConsoleHandler as m, type ConsoleMessage as n, type ConsoleMessageType as o, type CustomSelectConfig as p, type DialogHandler as q, type DialogType as r, type Download as s, ElementNotFoundError as t, type EmulationState as u, type ErrorHandler as v, type FillOptions as w, type NetworkIdleOptions as x, Page as y, type PageError as z };
+export { type InterceptedRequest as $, type ActionType as A, type BatchOptions as B, type CaptureResult as C, type Dialog as D, type ElementInfo as E, type FileInput as F, type GeolocationOptions as G, type PageSnapshot as H, type InteractiveElement as I, type SnapshotNode as J, type SubmitOptions as K, type TypeOptions as L, type UserAgentOptions as M, NavigationError as N, type DeviceDescriptor as O, type PlayOptions as P, type DeviceName as Q, type RequestPattern as R, type Step as S, TimeoutError as T, type UserAgentMetadata as U, type ViewportOptions as V, type WaitForOptions as W, devices as X, type ContinueRequestOptions as Y, type FailRequestOptions as Z, type FulfillRequestOptions as _, type RequestHandler as a, type RequestActions as a0, type ResourceType as a1, type RouteOptions as a2, type ClearCookiesOptions as a3, type Cookie as a4, type DeleteCookieOptions as a5, type SetCookieOptions as a6, type WaitOptions as a7, type WaitResult as a8, type WaitState as a9, waitForAnyElement as aa, waitForElement as ab, waitForNavigation as ac, waitForNetworkIdle as ad, type FailureHint as ae, type FailureReason as af, type BatchResult as b, type StepResult as c, type AudioChunk as d, AudioInput as e, type AudioInputState as f, AudioOutput as g, type CaptureOptions as h, type RoundTripOptions as i, type RoundTripResult as j, type ActionOptions as k, type ActionResult as l, type ConsoleHandler as m, type ConsoleMessage as n, type ConsoleMessageType as o, type CustomSelectConfig as p, type DialogHandler as q, type DialogType as r, type Download as s, ElementNotFoundError as t, type EmulationState as u, type ErrorHandler as v, type FillOptions as w, type NetworkIdleOptions as x, Page as y, type PageError as z };