1  /**
  2   * Page interface: type-safe abstraction over browser page.
  3   *
  4   * All pipeline steps and CLI adapters should use this interface
  5   * instead of `any` for browser interactions.
  6   */
  7  
  8  export interface BrowserCookie {
  9    name: string;
 10    value: string;
 11    domain: string;
 12    path?: string;
 13    secure?: boolean;
 14    httpOnly?: boolean;
 15    expirationDate?: number;
 16  }
 17  
 18  export interface SnapshotOptions {
 19    interactive?: boolean;
 20    compact?: boolean;
 21    maxDepth?: number;
 22    raw?: boolean;
 23    viewportExpand?: number;
 24    maxTextLength?: number;
 25  }
 26  
 27  export interface WaitOptions {
 28    text?: string;
 29    selector?: string;   // wait until document.querySelector(selector) matches
 30    time?: number;
 31    timeout?: number;
 32  }
 33  
 34  export interface ScreenshotOptions {
 35    format?: 'png' | 'jpeg';
 36    quality?: number;
 37    fullPage?: boolean;
 38    path?: string;
 39  }
 40  
 41  export interface BrowserSessionInfo {
 42    workspace?: string;
 43    connected?: boolean;
 44    [key: string]: unknown;
 45  }
 46  
 47  export interface IPage {
 48    goto(url: string, options?: { waitUntil?: 'load' | 'none'; settleMs?: number }): Promise<void>;
 49    evaluate(js: string): Promise<any>;
 50    /** Safely evaluate JS with pre-serialized arguments — prevents injection. */
 51    evaluateWithArgs?(js: string, args: Record<string, unknown>): Promise<any>;
 52    getCookies(opts?: { domain?: string; url?: string }): Promise<BrowserCookie[]>;
 53    snapshot(opts?: SnapshotOptions): Promise<any>;
 54    click(ref: string, opts?: { nth?: number; firstOnMulti?: boolean }): Promise<{ matches_n: number; match_level: 'exact' | 'stable' | 'reidentified' }>;
 55    typeText(ref: string, text: string, opts?: { nth?: number; firstOnMulti?: boolean }): Promise<{ matches_n: number; match_level: 'exact' | 'stable' | 'reidentified' }>;
 56    pressKey(key: string): Promise<void>;
 57    scrollTo(ref: string, opts?: { nth?: number; firstOnMulti?: boolean }): Promise<any>;
 58    getFormState(): Promise<any>;
 59    wait(options: number | WaitOptions): Promise<void>;
 60    tabs(): Promise<any>;
 61    closeTab?(target?: number | string): Promise<void>;
 62    newTab?(url?: string): Promise<string | undefined>;
 63    selectTab(target: number | string): Promise<void>;
 64    networkRequests(includeStatic?: boolean): Promise<any>;
 65    consoleMessages(level?: string): Promise<any>;
 66    scroll(direction?: string, amount?: number): Promise<void>;
 67    autoScroll(options?: { times?: number; delayMs?: number }): Promise<void>;
 68    installInterceptor(pattern: string): Promise<void>;
 69    getInterceptedRequests(): Promise<any[]>;
 70    waitForCapture(timeout?: number): Promise<void>;
 71    screenshot(options?: ScreenshotOptions): Promise<string>;
 72    startNetworkCapture?(pattern?: string): Promise<boolean>;
 73    readNetworkCapture?(): Promise<unknown[]>;
 74    /**
 75     * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
 76     * Chrome reads the files directly — no base64 encoding or payload size limits.
 77     */
 78    setFileInput?(files: string[], selector?: string): Promise<void>;
 79    /**
 80     * Insert text via native CDP Input.insertText into the currently focused element.
 81     * Useful for rich editors that ignore synthetic DOM value/text mutations.
 82     */
 83    insertText?(text: string): Promise<void>;
 84    closeWindow?(): Promise<void>;
 85    /** Returns the current page URL, or null if unavailable. */
 86    getCurrentUrl?(): Promise<string | null>;
 87    /** Returns the active page identity (targetId), or undefined if not yet resolved. */
 88    getActivePage?(): string | undefined;
 89    /** Bind the page object to a specific page identity (targetId). */
 90    setActivePage?(page?: string): void;
 91    /** Send a raw CDP command via chrome.debugger passthrough. */
 92    cdp?(method: string, params?: Record<string, unknown>): Promise<unknown>;
 93    /** List cross-origin iframe targets in snapshot order. */
 94    frames?(): Promise<Array<{ index: number; frameId: string; url: string; name: string }>>;
 95    /** Evaluate JavaScript inside a cross-origin iframe identified by its frame index. */
 96    evaluateInFrame?(js: string, frameIndex: number): Promise<unknown>;
 97    /** Click at native coordinates via CDP Input.dispatchMouseEvent. */
 98    nativeClick?(x: number, y: number): Promise<void>;
 99    /** Type text via CDP Input.insertText. */
100    nativeType?(text: string): Promise<void>;
101    /** Press a key via CDP Input.dispatchKeyEvent. */
102    nativeKeyPress?(key: string, modifiers?: string[]): Promise<void>;
103  }