browser-pilot 0.0.16 → 0.0.17

package/dist/browser.d.cts

@@ -1,8 +1,8 @@
 import { C as CDPClient } from './client-B5QBRgIy.cjs';
-import { TargetInfo } from './cdp.cjs';
+import { TargetInfo as TargetInfo$1 } from './cdp.cjs';
 import { b as ConnectOptions } from './types-DeVSWhXj.cjs';
-import { J as Page } from './types-BflRmiDz.cjs';
-export { l as ActionOptions, m as ActionResult, n as ConsoleHandler, o as ConsoleMessage, p as ConsoleMessageType, q as CustomSelectConfig, D as Dialog, r as DialogHandler, s as DialogType, t as Download, E as ElementInfo, u as ElementNotFoundError, v as EmulationState, w as ErrorHandler, ai as FailureHint, F as FileInput, x as FillOptions, y as FormField, z as FormOption, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, H as NetworkIdleOptions, K as PageError, L as PageSnapshot, M as SnapshotNode, O as SnapshotOptions, Q as SubmitOptions, T as TimeoutError, U as TypeOptions, V as UserAgentMetadata, W as UserAgentOptions, X as ViewportOptions, Y as WaitForOptions } from './types-BflRmiDz.cjs';
+import { W as Page, $ as SnapshotNode, c as Condition, O as OutcomeStatus, M as MatchedCondition } from './types-Yuybzq53.cjs';
+export { m as ActionOptions, n as ActionResult, o as ConsoleHandler, p as ConsoleMessage, q as ConsoleMessageType, r as CustomSelectConfig, D as DeltaChange, t as DeltaResult, u as Dialog, v as DialogHandler, w as DialogType, x as Download, E as ElementInfo, y as ElementNotFoundError, z as EmulationState, F as ErrorHandler, av as FailureHint, I as FileInput, J as FillOptions, K as FormField, L as FormOption, N as GeolocationOptions, Q as InteractiveElement, T as KeyValuePair, U as NavigationError, V as NetworkIdleOptions, X as PageError, Y as PageSnapshot, Z as PageState, _ as ReviewResult, a0 as SnapshotOptions, a1 as SubmitOptions, a2 as SummaryCard, a3 as TableData, a4 as TimeoutError, a5 as TypeOptions, a6 as UserAgentMetadata, a7 as UserAgentOptions, a8 as ViewportOptions, a9 as WaitForOptions, s as computeDelta, G as extractPageState, H as extractReview } from './types-Yuybzq53.cjs';
 
 /**
  * Browser class - manages CDP connection and pages
@@ -68,7 +68,7 @@ declare class Browser {
     /**
      * List all page targets in the connected browser.
      */
-    listTargets(): Promise<TargetInfo[]>;
+    listTargets(): Promise<TargetInfo$1[]>;
     /**
      * Get the WebSocket URL for this browser connection
      */
@@ -104,4 +104,228 @@ declare class Browser {
  */
 declare function connect(options: BrowserOptions): Promise<Browser>;
 
-export { Browser, type BrowserOptions, Page, type PageOptions, connect };
+/**
+ * Custom combobox interaction — handles searchable dropdowns, listboxes
+ */
+
+interface ComboboxConfig {
+    /** Trigger element (the combobox button/input) */
+    trigger: string | string[];
+    /** Listbox/options container that appears after opening */
+    listbox?: string | string[];
+    /** Individual option selector pattern */
+    optionSelector?: string;
+    /** Text to search/filter by */
+    searchText?: string;
+    /** Value to select (matched against option text) */
+    value: string;
+    /** Match mode for option text */
+    match?: 'exact' | 'contains' | 'startsWith';
+    /** Timeout for each sub-step */
+    timeout?: number;
+}
+interface ComboboxResult {
+    /** Whether the selection succeeded */
+    success: boolean;
+    /** Which stage failed, if any */
+    failedAt?: 'open' | 'search' | 'select' | 'verify';
+    /** The option text that was selected */
+    selectedText?: string;
+    /** Error message */
+    error?: string;
+}
+/**
+ * Interact with a custom combobox: open -> optionally search -> select -> verify.
+ */
+declare function chooseOption(page: Page, config: ComboboxConfig): Promise<ComboboxResult>;
+
+/**
+ * Semantic fingerprints for stable element identity across rerenders.
+ *
+ * A fingerprint captures the logical identity of an interactive element
+ * (role, name, section context, stable attributes) so that a stale ref
+ * can be recovered cheaply after a lightweight DOM rerender.
+ */
+
+interface SemanticFingerprint {
+    /** Accessibility role */
+    role: string;
+    /** Accessible name */
+    name: string;
+    /** Control value shape (type, not actual value) */
+    valueShape: string;
+    /** Associated label text */
+    label: string;
+    /** Stable attributes (id, name, type) extracted from properties */
+    stableAttrs: Record<string, string>;
+    /** Nearest heading ancestor */
+    nearestHeading: string;
+    /** Position among same-role siblings */
+    siblingIndex: number;
+    /** Section path: heading trail from root */
+    sectionPath: string[];
+}
+/**
+ * Create a semantic fingerprint for a snapshot node.
+ */
+declare function createFingerprint(node: SnapshotNode, context: {
+    headingTrail: string[];
+    siblingIndex: number;
+    nearestHeading: string;
+}): SemanticFingerprint;
+/**
+ * Compute a string key from a fingerprint for fast map-based matching.
+ */
+declare function fingerprintKey(fp: SemanticFingerprint): string;
+/**
+ * Score how similar two fingerprints are (0–1, higher = more similar).
+ * Returns 0 immediately if the roles differ.
+ */
+declare function fingerprintSimilarity(a: SemanticFingerprint, b: SemanticFingerprint): number;
+/**
+ * Build a fingerprint map for all interactive nodes in a snapshot tree.
+ * Keys are the node refs (e.g. "e1").
+ */
+declare function buildFingerprintMap(nodes: SnapshotNode[]): Map<string, SemanticFingerprint>;
+/**
+ * Attempt to recover a stale ref by matching its fingerprint against
+ * the current snapshot's fingerprints.
+ *
+ * Returns the new ref and confidence score, or `null` when no
+ * unambiguous match above the threshold exists.
+ */
+declare function recoverStaleRef(staleFingerprint: SemanticFingerprint, currentFingerprints: Map<string, SemanticFingerprint>, threshold?: number): {
+    ref: string;
+    confidence: number;
+} | null;
+
+/**
+ * Overlay-aware targeting — detect and prioritize visible overlays
+ */
+
+interface OverlayInfo {
+    /** Whether an overlay/modal is currently visible */
+    hasOverlay: boolean;
+    /** Selector of the detected overlay */
+    overlaySelector?: string;
+    /** Text content of the overlay (truncated) */
+    overlayText?: string;
+}
+/**
+ * Detect if a modal/overlay is currently covering the page.
+ * Uses common overlay patterns: role="dialog", fixed/absolute positioning with backdrop.
+ */
+declare function detectOverlay(page: Page): Promise<OverlayInfo>;
+
+/**
+ * Safe submit — submit with verification and outcome classification
+ */
+
+interface SubmitAndVerifyOptions {
+    /** Form selector to submit */
+    selector: string | string[];
+    /** Submit method */
+    method?: 'enter' | 'click' | 'enter+click';
+    /** Conditions that indicate success (any match) */
+    expectAny?: Condition[];
+    /** Conditions that all must match for success */
+    expectAll?: Condition[];
+    /** Conditions that indicate failure */
+    failIf?: Condition[];
+    /** Whether this is a dangerous/irreversible action */
+    dangerous?: boolean;
+    /** Timeout for the entire operation */
+    timeout?: number;
+    /** Whether to wait for navigation after submit */
+    waitForNavigation?: boolean | 'auto';
+}
+interface SubmitAndVerifyResult {
+    /** Whether submit was mechanically successful */
+    submitted: boolean;
+    /** Outcome classification */
+    outcomeStatus: OutcomeStatus;
+    /** Condition evaluation details */
+    matchedConditions: MatchedCondition[];
+    /** Whether safe to retry */
+    retrySafe: boolean;
+    /** Total time taken */
+    durationMs: number;
+    /** Error if submit failed mechanically */
+    error?: string;
+}
+/**
+ * Submit a form and verify the outcome using conditions.
+ * Never auto-retries — returns the outcome for the caller to decide.
+ */
+declare function submitAndVerify(page: Page, options: SubmitAndVerifyOptions): Promise<SubmitAndVerifyResult>;
+
+/**
+ * Target pinning — fingerprint and recover browser targets
+ */
+interface TargetFingerprint {
+    /** URL at time of pinning */
+    url: string;
+    /** Page title at time of pinning */
+    title: string;
+    /** Original target ID */
+    originalTargetId: string;
+    /** Timestamp when pinned */
+    pinnedAt: number;
+}
+interface PinRecoveryResult {
+    /** Recovered target ID */
+    targetId: string;
+    /** How recovery was achieved */
+    method: 'exact' | 'url_match' | 'title_match' | 'best_guess';
+    /** Confidence 0-1 */
+    confidence: number;
+}
+interface TargetInfo {
+    targetId: string;
+    type: string;
+    url: string;
+    title: string;
+    attached: boolean;
+}
+/**
+ * Create a fingerprint for the current target
+ */
+declare function createTargetFingerprint(targetId: string, url: string, title: string): TargetFingerprint;
+/**
+ * Recover a pinned target from available targets.
+ * Returns null if no suitable candidate found.
+ */
+declare function recoverPinnedTarget(pin: TargetFingerprint, targets: TargetInfo[], threshold?: number): PinRecoveryResult | null;
+
+/**
+ * File upload helper — wraps CDP setInputFiles with verification
+ */
+
+interface UploadConfig {
+    /** File input selector */
+    selector: string | string[];
+    /** File paths to upload */
+    files: string[];
+    /** Timeout */
+    timeout?: number;
+}
+interface UploadResult {
+    /** Whether files were accepted by the input */
+    accepted: boolean;
+    /** Number of files set */
+    fileCount: number;
+    /** File names */
+    fileNames: string[];
+    /** Whether files appear in visible UI (best-effort check) */
+    visibleInUI?: boolean;
+    /** Validation error text if any */
+    validationError?: string;
+    /** Error if upload failed */
+    error?: string;
+}
+/**
+ * Upload files to a file input and verify acceptance.
+ */
+declare function uploadFiles(page: Page, config: UploadConfig): Promise<UploadResult>;
+
+export { Browser, type BrowserOptions, type ComboboxConfig, type ComboboxResult, type OverlayInfo, Page, type PageOptions, type PinRecoveryResult, type SemanticFingerprint, SnapshotNode, type SubmitAndVerifyOptions, type SubmitAndVerifyResult, type TargetFingerprint, type UploadConfig, type UploadResult, buildFingerprintMap, chooseOption, connect, createFingerprint, createTargetFingerprint, detectOverlay, fingerprintKey, fingerprintSimilarity, recoverPinnedTarget, recoverStaleRef, submitAndVerify, uploadFiles };

package/dist/browser.d.ts

@@ -1,8 +1,8 @@
 import { C as CDPClient } from './client-B5QBRgIy.js';
-import { TargetInfo } from './cdp.js';
+import { TargetInfo as TargetInfo$1 } from './cdp.js';
 import { b as ConnectOptions } from './types-DeVSWhXj.js';
-import { J as Page } from './types-BzM-IfsL.js';
-export { l as ActionOptions, m as ActionResult, n as ConsoleHandler, o as ConsoleMessage, p as ConsoleMessageType, q as CustomSelectConfig, D as Dialog, r as DialogHandler, s as DialogType, t as Download, E as ElementInfo, u as ElementNotFoundError, v as EmulationState, w as ErrorHandler, ai as FailureHint, F as FileInput, x as FillOptions, y as FormField, z as FormOption, G as GeolocationOptions, I as InteractiveElement, N as NavigationError, H as NetworkIdleOptions, K as PageError, L as PageSnapshot, M as SnapshotNode, O as SnapshotOptions, Q as SubmitOptions, T as TimeoutError, U as TypeOptions, V as UserAgentMetadata, W as UserAgentOptions, X as ViewportOptions, Y as WaitForOptions } from './types-BzM-IfsL.js';
+import { W as Page, $ as SnapshotNode, c as Condition, O as OutcomeStatus, M as MatchedCondition } from './types-B_v62K7C.js';
+export { m as ActionOptions, n as ActionResult, o as ConsoleHandler, p as ConsoleMessage, q as ConsoleMessageType, r as CustomSelectConfig, D as DeltaChange, t as DeltaResult, u as Dialog, v as DialogHandler, w as DialogType, x as Download, E as ElementInfo, y as ElementNotFoundError, z as EmulationState, F as ErrorHandler, av as FailureHint, I as FileInput, J as FillOptions, K as FormField, L as FormOption, N as GeolocationOptions, Q as InteractiveElement, T as KeyValuePair, U as NavigationError, V as NetworkIdleOptions, X as PageError, Y as PageSnapshot, Z as PageState, _ as ReviewResult, a0 as SnapshotOptions, a1 as SubmitOptions, a2 as SummaryCard, a3 as TableData, a4 as TimeoutError, a5 as TypeOptions, a6 as UserAgentMetadata, a7 as UserAgentOptions, a8 as ViewportOptions, a9 as WaitForOptions, s as computeDelta, G as extractPageState, H as extractReview } from './types-B_v62K7C.js';
 
 /**
  * Browser class - manages CDP connection and pages
@@ -68,7 +68,7 @@ declare class Browser {
     /**
      * List all page targets in the connected browser.
      */
-    listTargets(): Promise<TargetInfo[]>;
+    listTargets(): Promise<TargetInfo$1[]>;
     /**
      * Get the WebSocket URL for this browser connection
      */
@@ -104,4 +104,228 @@ declare class Browser {
  */
 declare function connect(options: BrowserOptions): Promise<Browser>;
 
-export { Browser, type BrowserOptions, Page, type PageOptions, connect };
+/**
+ * Custom combobox interaction — handles searchable dropdowns, listboxes
+ */
+
+interface ComboboxConfig {
+    /** Trigger element (the combobox button/input) */
+    trigger: string | string[];
+    /** Listbox/options container that appears after opening */
+    listbox?: string | string[];
+    /** Individual option selector pattern */
+    optionSelector?: string;
+    /** Text to search/filter by */
+    searchText?: string;
+    /** Value to select (matched against option text) */
+    value: string;
+    /** Match mode for option text */
+    match?: 'exact' | 'contains' | 'startsWith';
+    /** Timeout for each sub-step */
+    timeout?: number;
+}
+interface ComboboxResult {
+    /** Whether the selection succeeded */
+    success: boolean;
+    /** Which stage failed, if any */
+    failedAt?: 'open' | 'search' | 'select' | 'verify';
+    /** The option text that was selected */
+    selectedText?: string;
+    /** Error message */
+    error?: string;
+}
+/**
+ * Interact with a custom combobox: open -> optionally search -> select -> verify.
+ */
+declare function chooseOption(page: Page, config: ComboboxConfig): Promise<ComboboxResult>;
+
+/**
+ * Semantic fingerprints for stable element identity across rerenders.
+ *
+ * A fingerprint captures the logical identity of an interactive element
+ * (role, name, section context, stable attributes) so that a stale ref
+ * can be recovered cheaply after a lightweight DOM rerender.
+ */
+
+interface SemanticFingerprint {
+    /** Accessibility role */
+    role: string;
+    /** Accessible name */
+    name: string;
+    /** Control value shape (type, not actual value) */
+    valueShape: string;
+    /** Associated label text */
+    label: string;
+    /** Stable attributes (id, name, type) extracted from properties */
+    stableAttrs: Record<string, string>;
+    /** Nearest heading ancestor */
+    nearestHeading: string;
+    /** Position among same-role siblings */
+    siblingIndex: number;
+    /** Section path: heading trail from root */
+    sectionPath: string[];
+}
+/**
+ * Create a semantic fingerprint for a snapshot node.
+ */
+declare function createFingerprint(node: SnapshotNode, context: {
+    headingTrail: string[];
+    siblingIndex: number;
+    nearestHeading: string;
+}): SemanticFingerprint;
+/**
+ * Compute a string key from a fingerprint for fast map-based matching.
+ */
+declare function fingerprintKey(fp: SemanticFingerprint): string;
+/**
+ * Score how similar two fingerprints are (0–1, higher = more similar).
+ * Returns 0 immediately if the roles differ.
+ */
+declare function fingerprintSimilarity(a: SemanticFingerprint, b: SemanticFingerprint): number;
+/**
+ * Build a fingerprint map for all interactive nodes in a snapshot tree.
+ * Keys are the node refs (e.g. "e1").
+ */
+declare function buildFingerprintMap(nodes: SnapshotNode[]): Map<string, SemanticFingerprint>;
+/**
+ * Attempt to recover a stale ref by matching its fingerprint against
+ * the current snapshot's fingerprints.
+ *
+ * Returns the new ref and confidence score, or `null` when no
+ * unambiguous match above the threshold exists.
+ */
+declare function recoverStaleRef(staleFingerprint: SemanticFingerprint, currentFingerprints: Map<string, SemanticFingerprint>, threshold?: number): {
+    ref: string;
+    confidence: number;
+} | null;
+
+/**
+ * Overlay-aware targeting — detect and prioritize visible overlays
+ */
+
+interface OverlayInfo {
+    /** Whether an overlay/modal is currently visible */
+    hasOverlay: boolean;
+    /** Selector of the detected overlay */
+    overlaySelector?: string;
+    /** Text content of the overlay (truncated) */
+    overlayText?: string;
+}
+/**
+ * Detect if a modal/overlay is currently covering the page.
+ * Uses common overlay patterns: role="dialog", fixed/absolute positioning with backdrop.
+ */
+declare function detectOverlay(page: Page): Promise<OverlayInfo>;
+
+/**
+ * Safe submit — submit with verification and outcome classification
+ */
+
+interface SubmitAndVerifyOptions {
+    /** Form selector to submit */
+    selector: string | string[];
+    /** Submit method */
+    method?: 'enter' | 'click' | 'enter+click';
+    /** Conditions that indicate success (any match) */
+    expectAny?: Condition[];
+    /** Conditions that all must match for success */
+    expectAll?: Condition[];
+    /** Conditions that indicate failure */
+    failIf?: Condition[];
+    /** Whether this is a dangerous/irreversible action */
+    dangerous?: boolean;
+    /** Timeout for the entire operation */
+    timeout?: number;
+    /** Whether to wait for navigation after submit */
+    waitForNavigation?: boolean | 'auto';
+}
+interface SubmitAndVerifyResult {
+    /** Whether submit was mechanically successful */
+    submitted: boolean;
+    /** Outcome classification */
+    outcomeStatus: OutcomeStatus;
+    /** Condition evaluation details */
+    matchedConditions: MatchedCondition[];
+    /** Whether safe to retry */
+    retrySafe: boolean;
+    /** Total time taken */
+    durationMs: number;
+    /** Error if submit failed mechanically */
+    error?: string;
+}
+/**
+ * Submit a form and verify the outcome using conditions.
+ * Never auto-retries — returns the outcome for the caller to decide.
+ */
+declare function submitAndVerify(page: Page, options: SubmitAndVerifyOptions): Promise<SubmitAndVerifyResult>;
+
+/**
+ * Target pinning — fingerprint and recover browser targets
+ */
+interface TargetFingerprint {
+    /** URL at time of pinning */
+    url: string;
+    /** Page title at time of pinning */
+    title: string;
+    /** Original target ID */
+    originalTargetId: string;
+    /** Timestamp when pinned */
+    pinnedAt: number;
+}
+interface PinRecoveryResult {
+    /** Recovered target ID */
+    targetId: string;
+    /** How recovery was achieved */
+    method: 'exact' | 'url_match' | 'title_match' | 'best_guess';
+    /** Confidence 0-1 */
+    confidence: number;
+}
+interface TargetInfo {
+    targetId: string;
+    type: string;
+    url: string;
+    title: string;
+    attached: boolean;
+}
+/**
+ * Create a fingerprint for the current target
+ */
+declare function createTargetFingerprint(targetId: string, url: string, title: string): TargetFingerprint;
+/**
+ * Recover a pinned target from available targets.
+ * Returns null if no suitable candidate found.
+ */
+declare function recoverPinnedTarget(pin: TargetFingerprint, targets: TargetInfo[], threshold?: number): PinRecoveryResult | null;
+
+/**
+ * File upload helper — wraps CDP setInputFiles with verification
+ */
+
+interface UploadConfig {
+    /** File input selector */
+    selector: string | string[];
+    /** File paths to upload */
+    files: string[];
+    /** Timeout */
+    timeout?: number;
+}
+interface UploadResult {
+    /** Whether files were accepted by the input */
+    accepted: boolean;
+    /** Number of files set */
+    fileCount: number;
+    /** File names */
+    fileNames: string[];
+    /** Whether files appear in visible UI (best-effort check) */
+    visibleInUI?: boolean;
+    /** Validation error text if any */
+    validationError?: string;
+    /** Error if upload failed */
+    error?: string;
+}
+/**
+ * Upload files to a file input and verify acceptance.
+ */
+declare function uploadFiles(page: Page, config: UploadConfig): Promise<UploadResult>;
+
+export { Browser, type BrowserOptions, type ComboboxConfig, type ComboboxResult, type OverlayInfo, Page, type PageOptions, type PinRecoveryResult, type SemanticFingerprint, SnapshotNode, type SubmitAndVerifyOptions, type SubmitAndVerifyResult, type TargetFingerprint, type UploadConfig, type UploadResult, buildFingerprintMap, chooseOption, connect, createFingerprint, createTargetFingerprint, detectOverlay, fingerprintKey, fingerprintSimilarity, recoverPinnedTarget, recoverStaleRef, submitAndVerify, uploadFiles };

package/dist/browser.mjs

@@ -1,21 +1,53 @@
 import {
   Browser,
   Page,
-  connect
-} from "./chunk-NNEHWWHL.mjs";
+  buildFingerprintMap,
+  computeDelta,
+  connect,
+  createFingerprint,
+  createTargetFingerprint,
+  detectOverlay,
+  extractPageState,
+  extractReview,
+  fingerprintKey,
+  fingerprintSimilarity,
+  recoverPinnedTarget,
+  recoverStaleRef,
+  submitAndVerify
+} from "./chunk-FEEGNSHB.mjs";
 import "./chunk-EZNZ72VA.mjs";
 import "./chunk-BVZALQT4.mjs";
 import {
   ElementNotFoundError,
   NavigationError,
   TimeoutError
-} from "./chunk-V3VLBQAM.mjs";
+} from "./chunk-ZDODXEBD.mjs";
 import "./chunk-JXAUPHZM.mjs";
+import {
+  chooseOption
+} from "./chunk-MIJ7UIKB.mjs";
+import {
+  uploadFiles
+} from "./chunk-OIHU7OFY.mjs";
 export {
   Browser,
   ElementNotFoundError,
   NavigationError,
   Page,
   TimeoutError,
-  connect
+  buildFingerprintMap,
+  chooseOption,
+  computeDelta,
+  connect,
+  createFingerprint,
+  createTargetFingerprint,
+  detectOverlay,
+  extractPageState,
+  extractReview,
+  fingerprintKey,
+  fingerprintSimilarity,
+  recoverPinnedTarget,
+  recoverStaleRef,
+  submitAndVerify,
+  uploadFiles
 };