browser-pilot 0.0.11 → 0.0.13

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 export { BatchExecutor, ValidationError, ValidationResult, addBatchToPage, validateSteps } from './actions.cjs';
-import { R as RequestPattern, a as RequestHandler, C as CaptureResult } from './types-GWuQJs_e.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-GWuQJs_e.cjs';
-import { C as CDPClient } from './client-7Nqka5MV.cjs';
-export { a as CDPClientOptions, c as createCDPClient } from './client-7Nqka5MV.cjs';
+import { R as RequestPattern, a as RequestHandler, C as CaptureResult } from './types-BXMGFtnB.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, a6 as ClearCookiesOptions, m as ConsoleHandler, n as ConsoleMessage, o as ConsoleMessageType, $ as ContinueRequestOptions, a7 as Cookie, p as CustomSelectConfig, a8 as DeleteCookieOptions, Y as DeviceDescriptor, Z 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, a0 as FailRequestOptions, F as FileInput, w as FillOptions, x as FormField, y as FormOption, a1 as FulfillRequestOptions, G as GeolocationOptions, I as InteractiveElement, a2 as InterceptedRequest, N as NavigationError, z as NetworkIdleOptions, H as Page, J as PageError, K as PageSnapshot, P as PlayOptions, a3 as RequestActions, a4 as ResourceType, i as RoundTripOptions, j as RoundTripResult, a5 as RouteOptions, a9 as SetCookieOptions, L as SnapshotNode, M as SnapshotOptions, S as Step, c as StepResult, O as SubmitOptions, T as TimeoutError, Q as TypeOptions, U as UserAgentMetadata, V as UserAgentOptions, W as ViewportOptions, X as WaitForOptions, aa as WaitOptions, ab as WaitResult, ac as WaitState, _ as devices, ad as waitForAnyElement, ae as waitForElement, af as waitForNavigation, ag as waitForNetworkIdle } from './types-BXMGFtnB.cjs';
+import { C as CDPClient } from './client-DRqxBdHv.cjs';
+export { a as CDPClientOptions, c as createCDPClient } from './client-DRqxBdHv.cjs';
 export { Browser, BrowserOptions, PageOptions, connect } from './browser.cjs';
 export { CDPError } from './cdp.cjs';
 export { BrowserBaseProvider, BrowserlessProvider, GenericProvider, createProvider, discoverTargets, getBrowserWebSocketUrl } from './providers.cjs';

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { BatchExecutor, ValidationError, ValidationResult, addBatchToPage, validateSteps } from './actions.js';
-import { R as RequestPattern, a as RequestHandler, C as CaptureResult } from './types-DtGF3yGl.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-DtGF3yGl.js';
-import { C as CDPClient } from './client-7Nqka5MV.js';
-export { a as CDPClientOptions, c as createCDPClient } from './client-7Nqka5MV.js';
+import { R as RequestPattern, a as RequestHandler, C as CaptureResult } from './types-CzgQjai9.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, a6 as ClearCookiesOptions, m as ConsoleHandler, n as ConsoleMessage, o as ConsoleMessageType, $ as ContinueRequestOptions, a7 as Cookie, p as CustomSelectConfig, a8 as DeleteCookieOptions, Y as DeviceDescriptor, Z 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, a0 as FailRequestOptions, F as FileInput, w as FillOptions, x as FormField, y as FormOption, a1 as FulfillRequestOptions, G as GeolocationOptions, I as InteractiveElement, a2 as InterceptedRequest, N as NavigationError, z as NetworkIdleOptions, H as Page, J as PageError, K as PageSnapshot, P as PlayOptions, a3 as RequestActions, a4 as ResourceType, i as RoundTripOptions, j as RoundTripResult, a5 as RouteOptions, a9 as SetCookieOptions, L as SnapshotNode, M as SnapshotOptions, S as Step, c as StepResult, O as SubmitOptions, T as TimeoutError, Q as TypeOptions, U as UserAgentMetadata, V as UserAgentOptions, W as ViewportOptions, X as WaitForOptions, aa as WaitOptions, ab as WaitResult, ac as WaitState, _ as devices, ad as waitForAnyElement, ae as waitForElement, af as waitForNavigation, ag as waitForNetworkIdle } from './types-CzgQjai9.js';
+import { C as CDPClient } from './client-DRqxBdHv.js';
+export { a as CDPClientOptions, c as createCDPClient } from './client-DRqxBdHv.js';
 export { Browser, BrowserOptions, PageOptions, connect } from './browser.js';
 export { CDPError } from './cdp.js';
 export { BrowserBaseProvider, BrowserlessProvider, GenericProvider, createProvider, discoverTargets, getBrowserWebSocketUrl } from './providers.js';

package/dist/index.mjs

@@ -16,11 +16,10 @@ import {
   waitForElement,
   waitForNavigation,
   waitForNetworkIdle
-} from "./chunk-JHAF52FA.mjs";
+} from "./chunk-VDAMDOS6.mjs";
 import {
-  CDPError,
   createCDPClient
-} from "./chunk-BCOZUKWS.mjs";
+} from "./chunk-HP6R3W32.mjs";
 import {
   BrowserBaseProvider,
   BrowserlessProvider,
@@ -36,7 +35,10 @@ import {
   TimeoutError,
   addBatchToPage,
   validateSteps
-} from "./chunk-FAUNIZR7.mjs";
+} from "./chunk-A2ZRAEO3.mjs";
+import {
+  CDPError
+} from "./chunk-JXAUPHZM.mjs";
 
 // src/audio/flags.ts
 function getAudioChromeFlags(options) {

package/dist/{types-GWuQJs_e.d.cts → types-BXMGFtnB.d.cts}

@@ -1,4 +1,4 @@
-import { C as CDPClient } from './client-7Nqka5MV.cjs';
+import { C as CDPClient } from './client-DRqxBdHv.cjs';
 
 /**
  * Audio I/O type definitions
@@ -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>;
 /**
@@ -278,6 +280,8 @@ interface FillOptions extends ActionOptions {
 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' */
@@ -363,6 +367,10 @@ interface PageSnapshot {
     /** Text representation of the page */
     text: string;
 }
+interface SnapshotOptions {
+    /** Restrict the snapshot to these accessibility roles */
+    roles?: string[];
+}
 interface SnapshotNode {
     /** Accessibility role */
     role: string;
@@ -392,6 +400,29 @@ interface InteractiveElement {
     selector: string;
     /** Whether the element is disabled */
     disabled?: boolean;
+    /** Whether the element is checked */
+    checked?: boolean;
+    /** Current value where relevant */
+    value?: string;
+}
+interface FormOption {
+    value: string;
+    text: string;
+    selected: boolean;
+    disabled: boolean;
+}
+interface FormField {
+    tag: string;
+    type: string;
+    id?: string;
+    name?: string;
+    value?: string | string[] | null;
+    checked?: boolean;
+    required: boolean;
+    disabled: boolean;
+    label?: string;
+    placeholder?: string;
+    options?: FormOption[];
 }
 interface FailureHint {
     /** Suggested selector */
@@ -705,6 +736,8 @@ 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 */
@@ -809,9 +842,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): Promise<void>;
+    press(key: string, options?: {
+        modifiers?: Array<'Control' | 'Shift' | 'Alt' | 'Meta'>;
+    }): Promise<void>;
+    /**
+     * Execute a keyboard shortcut (e.g. "Control+a", "Meta+Shift+z")
+     */
+    shortcut(combo: string): Promise<void>;
     /**
      * Focus an element
      */
@@ -870,6 +909,10 @@ declare class Page {
      * Get text content from the page or a specific element
      */
     text(selector?: string): Promise<string>;
+    /**
+     * Enumerate form controls on the page with labels and current state.
+     */
+    forms(): Promise<FormField[]>;
     /**
      * Set files on a file input
      */
@@ -892,7 +935,7 @@ declare class Page {
     /**
      * Get an accessibility tree snapshot of the page
      */
-    snapshot(): Promise<PageSnapshot>;
+    snapshot(options?: SnapshotOptions): Promise<PageSnapshot>;
     /**
      * Export the current ref map for cross-exec reuse (CLI).
      */
@@ -1082,9 +1125,17 @@ declare class Page {
     private withStaleNodeRetry;
     /**
      * Find an element using single or multiple selectors
-     * Supports ref: prefix for ref-based selectors (e.g., "ref:e4")
+     * Supports ref:, text:, and role: selectors.
      */
     private findElement;
+    private formatEvaluationError;
+    private resolveSpecialSelector;
+    private readCheckedState;
+    private readInputType;
+    private getAssociatedLabelNodeId;
+    private objectIdToNode;
+    private tryClickAssociatedLabel;
+    private tryToggleViaLabel;
     /**
      * Ensure we have a valid root node ID
      */
@@ -1095,9 +1146,13 @@ 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)
      */
@@ -1115,6 +1170,7 @@ declare class Page {
     private resolveObjectId;
     private dispatchKeyDefinition;
     private dispatchKey;
+    private dispatchKeyWithModifiers;
     /**
      * Audio input controller (fake microphone).
      * Lazy-initialized on first access.
@@ -1150,13 +1206,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' | 'forms' | 'screenshot' | 'evaluate' | 'text' | 'newTab' | 'closeTab' | 'switchFrame' | 'switchToMain' | 'assertVisible' | 'assertExists' | 'assertText' | 'assertUrl' | 'assertValue';
 interface Step {
     /** Action type */
     action: ActionType;
@@ -1166,8 +1231,14 @@ interface Step {
     url?: string;
     /** Value for fill, type, select, evaluate actions */
     value?: string | string[];
+    /** Target ID for tab operations */
+    targetId?: 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) */
@@ -1199,6 +1270,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) */
@@ -1232,6 +1309,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 */
@@ -1244,4 +1331,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 ContinueRequestOptions 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, Page as H, type InteractiveElement as I, type PageError as J, type PageSnapshot as K, type SnapshotNode as L, type SnapshotOptions as M, NavigationError as N, type SubmitOptions as O, type PlayOptions as P, type TypeOptions as Q, type RequestPattern as R, type Step as S, TimeoutError as T, type UserAgentMetadata as U, type UserAgentOptions as V, type ViewportOptions as W, type WaitForOptions as X, type DeviceDescriptor as Y, type DeviceName as Z, devices as _, type RequestHandler as a, type FailRequestOptions as a0, type FulfillRequestOptions as a1, type InterceptedRequest as a2, type RequestActions as a3, type ResourceType as a4, type RouteOptions as a5, type ClearCookiesOptions as a6, type Cookie as a7, type DeleteCookieOptions as a8, type SetCookieOptions as a9, type WaitOptions as aa, type WaitResult as ab, type WaitState as ac, waitForAnyElement as ad, waitForElement as ae, waitForNavigation as af, waitForNetworkIdle as ag, type FailureHint as ah, type FailureReason as ai, 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 FormField as x, type FormOption as y, type NetworkIdleOptions as z };

package/dist/{types-DtGF3yGl.d.ts → types-CzgQjai9.d.ts}

@@ -1,4 +1,4 @@
-import { C as CDPClient } from './client-7Nqka5MV.js';
+import { C as CDPClient } from './client-DRqxBdHv.js';
 
 /**
  * Audio I/O type definitions
@@ -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>;
 /**
@@ -278,6 +280,8 @@ interface FillOptions extends ActionOptions {
 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' */
@@ -363,6 +367,10 @@ interface PageSnapshot {
     /** Text representation of the page */
     text: string;
 }
+interface SnapshotOptions {
+    /** Restrict the snapshot to these accessibility roles */
+    roles?: string[];
+}
 interface SnapshotNode {
     /** Accessibility role */
     role: string;
@@ -392,6 +400,29 @@ interface InteractiveElement {
     selector: string;
     /** Whether the element is disabled */
     disabled?: boolean;
+    /** Whether the element is checked */
+    checked?: boolean;
+    /** Current value where relevant */
+    value?: string;
+}
+interface FormOption {
+    value: string;
+    text: string;
+    selected: boolean;
+    disabled: boolean;
+}
+interface FormField {
+    tag: string;
+    type: string;
+    id?: string;
+    name?: string;
+    value?: string | string[] | null;
+    checked?: boolean;
+    required: boolean;
+    disabled: boolean;
+    label?: string;
+    placeholder?: string;
+    options?: FormOption[];
 }
 interface FailureHint {
     /** Suggested selector */
@@ -705,6 +736,8 @@ 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 */
@@ -809,9 +842,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): Promise<void>;
+    press(key: string, options?: {
+        modifiers?: Array<'Control' | 'Shift' | 'Alt' | 'Meta'>;
+    }): Promise<void>;
+    /**
+     * Execute a keyboard shortcut (e.g. "Control+a", "Meta+Shift+z")
+     */
+    shortcut(combo: string): Promise<void>;
     /**
      * Focus an element
      */
@@ -870,6 +909,10 @@ declare class Page {
      * Get text content from the page or a specific element
      */
     text(selector?: string): Promise<string>;
+    /**
+     * Enumerate form controls on the page with labels and current state.
+     */
+    forms(): Promise<FormField[]>;
     /**
      * Set files on a file input
      */
@@ -892,7 +935,7 @@ declare class Page {
     /**
      * Get an accessibility tree snapshot of the page
      */
-    snapshot(): Promise<PageSnapshot>;
+    snapshot(options?: SnapshotOptions): Promise<PageSnapshot>;
     /**
      * Export the current ref map for cross-exec reuse (CLI).
      */
@@ -1082,9 +1125,17 @@ declare class Page {
     private withStaleNodeRetry;
     /**
      * Find an element using single or multiple selectors
-     * Supports ref: prefix for ref-based selectors (e.g., "ref:e4")
+     * Supports ref:, text:, and role: selectors.
      */
     private findElement;
+    private formatEvaluationError;
+    private resolveSpecialSelector;
+    private readCheckedState;
+    private readInputType;
+    private getAssociatedLabelNodeId;
+    private objectIdToNode;
+    private tryClickAssociatedLabel;
+    private tryToggleViaLabel;
     /**
      * Ensure we have a valid root node ID
      */
@@ -1095,9 +1146,13 @@ 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)
      */
@@ -1115,6 +1170,7 @@ declare class Page {
     private resolveObjectId;
     private dispatchKeyDefinition;
     private dispatchKey;
+    private dispatchKeyWithModifiers;
     /**
      * Audio input controller (fake microphone).
      * Lazy-initialized on first access.
@@ -1150,13 +1206,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' | 'forms' | 'screenshot' | 'evaluate' | 'text' | 'newTab' | 'closeTab' | 'switchFrame' | 'switchToMain' | 'assertVisible' | 'assertExists' | 'assertText' | 'assertUrl' | 'assertValue';
 interface Step {
     /** Action type */
     action: ActionType;
@@ -1166,8 +1231,14 @@ interface Step {
     url?: string;
     /** Value for fill, type, select, evaluate actions */
     value?: string | string[];
+    /** Target ID for tab operations */
+    targetId?: 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) */
@@ -1199,6 +1270,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) */
@@ -1232,6 +1309,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 */
@@ -1244,4 +1331,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 ContinueRequestOptions 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, Page as H, type InteractiveElement as I, type PageError as J, type PageSnapshot as K, type SnapshotNode as L, type SnapshotOptions as M, NavigationError as N, type SubmitOptions as O, type PlayOptions as P, type TypeOptions as Q, type RequestPattern as R, type Step as S, TimeoutError as T, type UserAgentMetadata as U, type UserAgentOptions as V, type ViewportOptions as W, type WaitForOptions as X, type DeviceDescriptor as Y, type DeviceName as Z, devices as _, type RequestHandler as a, type FailRequestOptions as a0, type FulfillRequestOptions as a1, type InterceptedRequest as a2, type RequestActions as a3, type ResourceType as a4, type RouteOptions as a5, type ClearCookiesOptions as a6, type Cookie as a7, type DeleteCookieOptions as a8, type SetCookieOptions as a9, type WaitOptions as aa, type WaitResult as ab, type WaitState as ac, waitForAnyElement as ad, waitForElement as ae, waitForNavigation as af, waitForNetworkIdle as ag, type FailureHint as ah, type FailureReason as ai, 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 FormField as x, type FormOption as y, type NetworkIdleOptions as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-pilot",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "Lightweight CDP-based browser automation for Node.js, Bun, and Cloudflare Workers",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -57,8 +57,10 @@
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
+    "lint:type": "oxlint --type-aware --tsconfig ./tsconfig.json src/",
     "format": "biome format --write .",
-    "check": "bun run typecheck && bun run lint",
+    "check": "bun run typecheck && bun run lint && bun run lint:type",
+    "check:quiet": "bash scripts/check.sh",
     "prepublishOnly": "bun run build",
     "bp": "bun ./src/cli/index.ts",
     "dev:bp": "bun ./src/cli/index.ts",
@@ -69,6 +71,8 @@
     "@biomejs/biome": "^2.3.10",
     "@types/bun": "latest",
     "chrome-launcher": "^1.2.1",
+    "oxlint": "^1.51.0",
+    "oxlint-tsgolint": "^0.16.0",
     "tsup": "^8.0.0"
   },
   "peerDependencies": {