@xbrowser/cli 0.16.0 → 1.0.0

package/dist/index.d.ts

@@ -1,13 +1,414 @@
 import { EventEmitter } from 'events';
 import { Server } from 'http';
-import { Page, Browser, BrowserContext } from 'playwright';
 import { CommandContext, CommandScope, XCLIAPI, Core, PluginInstance, PluginStatus } from '@dyyz1993/xcli-core';
 export { PluginStatus } from '@dyyz1993/xcli-core';
 import { ZodType, ZodTypeDef, z } from 'zod';
-import * as playwright_core from 'playwright-core';
 
 declare const version: any;
 
+/**
+ * XBrowser CDP Driver — Abstract Interface Types
+ *
+ * Playwright-compatible interfaces backed by raw Chrome DevTools Protocol.
+ * All commands and plugins depend on these interfaces, NOT on Playwright.
+ *
+ * Naming convention: XB prefix (XBrowser) to avoid confusion with Playwright types.
+ */
+interface XBBrowser {
+    readonly disconnected: boolean;
+    close(): Promise<void>;
+    newContext(opts?: XBContextOptions): Promise<XBContext>;
+    contexts(): XBContext[];
+    on(event: string, handler: Function): void;
+    off(event: string, handler: Function): void;
+}
+interface XBContextOptions {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    userAgent?: string;
+    extraHTTPHeaders?: Record<string, string>;
+    ignoreHTTPSErrors?: boolean;
+}
+interface XBContext {
+    newPage(): Promise<XBPage>;
+    pages(): XBPage[];
+    close(): Promise<void>;
+    browser(): XBBrowser;
+    newCDPSession(page?: XBPage): Promise<XBCDPSession>;
+    addInitScript(script: string): Promise<void>;
+    cookies(urls?: string | string[]): Promise<XBCookie[]>;
+    addCookies(cookies: XBCookie[]): Promise<void>;
+    clearCookies(): Promise<void>;
+    on(event: string, handler: Function): void;
+    off(event: string, handler: Function): void;
+}
+interface XBCookie {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+type WaitUntilState = 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+interface XBPage {
+    goto(url: string, opts?: {
+        waitUntil?: WaitUntilState;
+        timeout?: number;
+        referer?: string;
+    }): Promise<XBNavigationResponse | null>;
+    goBack(opts?: {
+        timeout?: number;
+        waitUntil?: WaitUntilState;
+    }): Promise<void>;
+    goForward(opts?: {
+        timeout?: number;
+        waitUntil?: WaitUntilState;
+    }): Promise<void>;
+    reload(opts?: {
+        timeout?: number;
+        waitUntil?: WaitUntilState;
+    }): Promise<void>;
+    waitForLoadState(state?: WaitUntilState, timeout?: number): Promise<void>;
+    waitForTimeout(ms: number): Promise<void>;
+    waitForSelector(selector: string, opts?: {
+        state?: 'visible' | 'hidden' | 'attached' | 'detached';
+        timeout?: number;
+    }): Promise<void>;
+    waitForFunction<R>(fn: string | Function, opts?: {
+        timeout?: number;
+        polling?: number | 'raf';
+    }, ...args: unknown[]): Promise<R>;
+    waitForURL(url: string | RegExp | ((url: string) => boolean), opts?: {
+        timeout?: number;
+        waitUntil?: WaitUntilState;
+    }): Promise<void>;
+    waitForResponse(urlOrPredicate: string | RegExp | ((response: XBResponse) => boolean), opts?: {
+        timeout?: number;
+    }): Promise<XBResponse>;
+    waitForRequest(urlOrPredicate: string | RegExp | ((request: XBRequest) => boolean), opts?: {
+        timeout?: number;
+    }): Promise<XBRequest>;
+    url(): string;
+    title(): Promise<string>;
+    content(): Promise<string>;
+    evaluate<R = unknown>(fn: string | Function, ...args: unknown[]): Promise<R>;
+    $eval<R = unknown>(selector: string, fn: string | Function, ...args: unknown[]): Promise<R>;
+    $$eval<R = unknown>(selector: string, fn: string | Function, ...args: unknown[]): Promise<R>;
+    locator(selector: string): XBLocator;
+    getByText(text: string, opts?: {
+        exact?: boolean;
+    }): XBLocator;
+    getByRole(role: string, opts?: {
+        name?: string;
+        exact?: boolean;
+    }): XBLocator;
+    getByLabel(label: string, opts?: {
+        exact?: boolean;
+    }): XBLocator;
+    getByPlaceholder(text: string, opts?: {
+        exact?: boolean;
+    }): XBLocator;
+    getByTestId(id: string): XBLocator;
+    getByAltText(text: string, opts?: {
+        exact?: boolean;
+    }): XBLocator;
+    getByTitle(title: string, opts?: {
+        exact?: boolean;
+    }): XBLocator;
+    click(selector: string, opts?: XBClickOptions): Promise<void>;
+    dblclick(selector: string, opts?: XBClickOptions): Promise<void>;
+    fill(selector: string, value: string, opts?: XBFillOptions): Promise<void>;
+    press(selector: string, key: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    hover(selector: string, opts?: {
+        timeout?: number;
+        force?: boolean;
+    }): Promise<void>;
+    type(selector: string, text: string, opts?: {
+        delay?: number;
+        timeout?: number;
+    }): Promise<void>;
+    check(selector: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    uncheck(selector: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    selectOption(selector: string, value: string | string[] | {
+        label?: string;
+        value?: string;
+        index?: number;
+    }): Promise<string[]>;
+    textContent(selector: string): Promise<string | null>;
+    innerText(selector: string): Promise<string>;
+    innerHTML(selector: string): Promise<string>;
+    getAttribute(selector: string, name: string): Promise<string | null>;
+    readonly mouse: XBMouse;
+    readonly keyboard: XBKeyboard;
+    $(selector: string): Promise<XBElementHandle | null>;
+    $$(selector: string): Promise<XBElementHandle[]>;
+    screenshot(opts?: XBScreenshotOptions): Promise<Buffer>;
+    pdf(opts?: XBPdfOptions): Promise<Buffer>;
+    viewportSize(): {
+        width: number;
+        height: number;
+    } | null;
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    addInitScript(script: string): Promise<void>;
+    bringToFront(): Promise<void>;
+    setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
+    setOfflineMode(offline: boolean): Promise<void>;
+    route(url: string | RegExp, handler: (route: XBRoute) => Promise<void> | void): Promise<void>;
+    unroute(url: string | RegExp, handler?: (route: XBRoute) => Promise<void> | void): Promise<void>;
+    setInputFiles(selector: string, files: XBFilePayload | XBFilePayload[]): Promise<void>;
+    dragAndDrop(source: string, target: string): Promise<void>;
+    on(event: string, handler: Function): void;
+    off(event: string, handler: Function): void;
+    _cdpSend<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    _subscribe(event: string, handler: (params: unknown) => void): () => void;
+    close(): Promise<void>;
+    isClosed(): boolean;
+    context(): XBContext;
+    browser(): XBBrowser;
+    mainFrame(): XBFrame;
+    frames(): XBFrame[];
+}
+/** Response from navigation (goto). Playwright-compatible subset. */
+interface XBNavigationResponse {
+    status(): number;
+    ok(): boolean;
+    url(): string;
+    headers(): Record<string, string>;
+}
+interface XBLocator {
+    click(opts?: XBClickOptions): Promise<void>;
+    fill(value: string, opts?: XBFillOptions): Promise<void>;
+    press(key: string, opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    pressSequentially(text: string, opts?: {
+        delay?: number;
+        timeout?: number;
+    }): Promise<void>;
+    hover(opts?: {
+        timeout?: number;
+        force?: boolean;
+    }): Promise<void>;
+    type(text: string, opts?: {
+        delay?: number;
+        timeout?: number;
+    }): Promise<void>;
+    check(opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    uncheck(opts?: {
+        timeout?: number;
+    }): Promise<void>;
+    selectOption(value: string | string[] | {
+        label?: string;
+        value?: string;
+        index?: number;
+    }): Promise<string[]>;
+    screenshot(opts?: XBScreenshotOptions): Promise<Buffer>;
+    focus(): Promise<void>;
+    waitFor(opts?: {
+        state?: 'visible' | 'hidden' | 'attached' | 'detached';
+        timeout?: number;
+    }): Promise<void>;
+    count(): Promise<number>;
+    isVisible(): Promise<boolean>;
+    isHidden(): Promise<boolean>;
+    isEnabled(): Promise<boolean>;
+    isDisabled(): Promise<boolean>;
+    boundingBox(): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null>;
+    textContent(): Promise<string | null>;
+    innerText(): Promise<string>;
+    innerHTML(): Promise<string>;
+    getAttribute(name: string): Promise<string | null>;
+    evaluate<R = unknown>(fn: string | Function, ...args: unknown[]): Promise<R>;
+    ariaSnapshot(): Promise<string>;
+    first(): XBLocator;
+    last(): XBLocator;
+    nth(index: number): XBLocator;
+    filter(opts: {
+        visible?: boolean;
+    }): XBLocator;
+    all(): Promise<XBLocator[]>;
+}
+interface XBElementHandle {
+    click(opts?: XBClickOptions): Promise<void>;
+    fill(value: string, opts?: XBFillOptions): Promise<void>;
+    hover(): Promise<void>;
+    press(key: string): Promise<void>;
+    screenshot(opts?: XBScreenshotOptions): Promise<Buffer>;
+    boundingBox(): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null>;
+    isVisible(): Promise<boolean>;
+    isEnabled(): Promise<boolean>;
+    textContent(): Promise<string | null>;
+    innerText(): Promise<string>;
+    innerHTML(): Promise<string>;
+    getAttribute(name: string): Promise<string | null>;
+    scrollIntoViewIfNeeded(): Promise<void>;
+    dispose(): void;
+}
+interface XBMouse {
+    click(x: number, y: number, opts?: {
+        button?: 'left' | 'right' | 'middle';
+        clickCount?: number;
+        delay?: number;
+    }): Promise<void>;
+    dblclick(x: number, y: number, opts?: {
+        button?: 'left' | 'right' | 'middle';
+    }): Promise<void>;
+    down(opts?: {
+        button?: 'left' | 'right' | 'middle';
+    }): Promise<void>;
+    up(opts?: {
+        button?: 'left' | 'right' | 'middle';
+    }): Promise<void>;
+    move(x: number, y: number, opts?: {
+        steps?: number;
+    }): Promise<void>;
+    wheel(deltaX: number, deltaY: number): Promise<void>;
+}
+interface XBKeyboard {
+    press(key: string, opts?: {
+        delay?: number;
+    }): Promise<void>;
+    down(key: string): Promise<void>;
+    up(key: string): Promise<void>;
+    type(text: string, opts?: {
+        delay?: number;
+    }): Promise<void>;
+    insertText(text: string): Promise<void>;
+}
+interface XBFrame {
+    url(): string;
+    name(): string;
+    isDetached(): boolean;
+    page(): XBPage;
+    evaluate<R = unknown>(fn: string | Function, ...args: unknown[]): Promise<R>;
+    $(selector: string): Promise<XBElementHandle | null>;
+    $$(selector: string): Promise<XBElementHandle[]>;
+}
+interface XBCDPSession {
+    send<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    on(event: string, handler: Function): void;
+    off(event: string, handler: Function): void;
+    detach(): Promise<void>;
+}
+interface XBClickOptions {
+    button?: 'left' | 'right' | 'middle';
+    clickCount?: number;
+    delay?: number;
+    timeout?: number;
+    force?: boolean;
+    noWaitAfter?: boolean;
+    position?: {
+        x: number;
+        y: number;
+    };
+    trial?: boolean;
+}
+interface XBFillOptions {
+    timeout?: number;
+    force?: boolean;
+    noWaitAfter?: boolean;
+}
+interface XBScreenshotOptions {
+    type?: 'png' | 'jpeg';
+    quality?: number;
+    fullPage?: boolean;
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    omitBackground?: boolean;
+    timeout?: number;
+}
+interface XBPdfOptions {
+    format?: string;
+    landscape?: boolean;
+    printBackground?: boolean;
+    scale?: number;
+    margin?: {
+        top?: string;
+        bottom?: string;
+        left?: string;
+        right?: string;
+    };
+    preferCSSPageSize?: boolean;
+}
+interface XBResponse {
+    status(): number;
+    statusText(): string;
+    url(): string;
+    headers(): Record<string, string>;
+    ok(): boolean;
+    body(): Promise<Buffer>;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+    request(): XBRequest;
+}
+interface XBRoute {
+    request(): XBRequest;
+    abort(errorCode?: string): Promise<void>;
+    continue(opts?: {
+        url?: string;
+        method?: string;
+        headers?: Record<string, string>;
+        postData?: string;
+    }): Promise<void>;
+    fulfill(opts: {
+        status?: number;
+        headers?: Record<string, string>;
+        body?: string | Buffer;
+        contentType?: string;
+    }): Promise<void>;
+}
+interface XBFilePayload {
+    name: string;
+    mimeType: string;
+    buffer: Buffer;
+}
+interface XBRequest {
+    url(): string;
+    method(): string;
+    headers(): Record<string, string>;
+    postData(): string | null;
+    resourceType(): string;
+    response(): Promise<XBResponse | null>;
+}
+interface XBRequest {
+    url(): string;
+    method(): string;
+    headers(): Record<string, string>;
+    postData(): string | null;
+    resourceType(): string;
+    response(): Promise<XBResponse | null>;
+}
+
 /**
  * Configuration for the WebSocket server.
  */
@@ -208,7 +609,7 @@ declare class WSServer extends EventEmitter {
      * Call this when a session is created. The capturer will only start
      * when a WS client binds to this session.
      */
-    registerSession(sessionId: string, page: Page, options?: {
+    registerSession(sessionId: string, page: XBPage, options?: {
         interval?: number;
         quality?: number;
         type?: 'jpeg' | 'png';
@@ -530,7 +931,7 @@ declare class HumanInteractionManager {
     private capturer;
     private webhook;
     private autoOpen;
-    constructor(wsServer: WSServer, page: Page);
+    constructor(wsServer: WSServer, page: XBPage);
     private sendWebhook;
     private tryAutoOpen;
     /**
@@ -552,9 +953,9 @@ declare class HumanInteractionManager {
  * along with an optional `waitForHuman` function for CAPTCHA handling.
  */
 interface BrowserCommandContext extends CommandContext {
-    page: Page;
-    browser: Browser;
-    browserContext: BrowserContext;
+    page: XBPage;
+    browser: XBBrowser;
+    browserContext: XBContext;
     sessionId?: string;
     cdpEndpoint?: string;
     waitForHuman?: (options?: WaitForHumanOptions) => Promise<WaitForHumanResult>;
@@ -574,7 +975,7 @@ declare function checkBrowserScope(scope: CommandScope, ctx: BrowserCommandConte
  * @throws If no active page is available in the context.
  */
 declare function assertPageScope(ctx: BrowserCommandContext): asserts ctx is BrowserCommandContext & {
-    page: Page;
+    page: XBPage;
 };
 /**
  * Attach a `waitForHuman` function to the browser command context.
@@ -585,21 +986,21 @@ declare function assertPageScope(ctx: BrowserCommandContext): asserts ctx is Bro
  * @param ctx - The browser command context to augment.
  * @param getOrCreateWSServer - Factory that returns a WSServer for the given BrowserContext.
  */
-declare function attachWaitForHuman(ctx: BrowserCommandContext, getOrCreateWSServer: (browserContext: BrowserContext) => Promise<WSServer>): void;
+declare function attachWaitForHuman(ctx: BrowserCommandContext, getOrCreateWSServer: (browserContext: XBContext) => Promise<WSServer>): void;
 /**
  * Retrieve a cached WSServer instance for the given BrowserContext.
  *
  * @param browserContext - The Playwright BrowserContext.
  * @returns The cached WSServer, or `undefined` if none is cached.
  */
-declare function getWSServerFromCache(browserContext: BrowserContext): WSServer | undefined;
+declare function getWSServerFromCache(browserContext: XBContext): WSServer | undefined;
 /**
  * Cache a WSServer instance for the given BrowserContext.
  *
  * @param browserContext - The Playwright BrowserContext.
  * @param server - The WSServer to associate with this context.
  */
-declare function setWSServerCache(browserContext: BrowserContext, server: WSServer): void;
+declare function setWSServerCache(browserContext: XBContext, server: WSServer): void;
 
 /**
  * Represents a managed browser session with its Playwright context, page,
@@ -608,9 +1009,9 @@ declare function setWSServerCache(browserContext: BrowserContext, server: WSServ
 interface ManagedSession {
     id: string;
     name: string;
-    context: BrowserContext;
-    page: Page;
-    browser: Browser;
+    context: XBContext;
+    page: XBPage;
+    browser: XBBrowser;
     createdAt: string;
     lastActivityAt: number;
     isCDP?: boolean;
@@ -640,7 +1041,7 @@ interface BrowserLaunchOptions {
  * const browser = await getBrowser({ headless: true });
  * ```
  */
-declare function getBrowser(options?: BrowserLaunchOptions): Promise<Browser>;
+declare function getBrowser(options?: BrowserLaunchOptions): Promise<XBBrowser>;
 /**
  * Find a managed session by its name.
  *
@@ -915,7 +1316,7 @@ declare function listSessions(): Promise<Array<{
  * @param name - The session name. Defaults to "default".
  * @returns The page instance, or `null` if the session does not exist.
  */
-declare function getSessionPage(name?: string, cdpEndpoint?: string): Promise<playwright_core.Page | null>;
+declare function getSessionPage(name?: string, cdpEndpoint?: string): Promise<XBPage | null>;
 
 /**
  * A built-in CLI command with help text and an execute function.
@@ -957,6 +1358,80 @@ declare const allBuiltins: BuiltinCommand[];
  */
 declare function getBuiltin(name: string): BuiltinCommand | undefined;
 
+interface XBrowserPluginMetadata {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    homepage?: string;
+    commands?: string[];
+    sites?: string[];
+    tags?: string[];
+    screenshot?: string;
+    license?: string;
+}
+type PluginFormWidget = 'text' | 'textarea' | 'number' | 'checkbox' | 'select' | 'multi-select' | 'json' | 'file' | 'url' | 'password';
+type PluginCapability = 'browser.page' | 'browser.context' | 'browser.cdp' | 'network' | 'storage' | 'filesystem' | 'external-api' | 'auth.login' | (string & {});
+interface PluginFormField {
+    name: string;
+    label: string;
+    type: string;
+    widget: PluginFormWidget;
+    required: boolean;
+    description?: string;
+    default?: unknown;
+    enum?: string[];
+    positional?: boolean;
+    placeholder?: string;
+    secret?: boolean;
+    multiple?: boolean;
+}
+interface PluginCommandContractExtension {
+    category?: string;
+    capabilities?: PluginCapability[];
+    positional?: string[];
+    form?: {
+        title?: string;
+        description?: string;
+        submitLabel?: string;
+        fields?: Partial<PluginFormField>[];
+    };
+    output?: {
+        schema?: unknown;
+        examples?: unknown[];
+    };
+}
+interface PluginCommandContract {
+    name: string;
+    description: string;
+    scope: string;
+    requiresLogin: boolean;
+    category?: string;
+    capabilities: PluginCapability[];
+    positional: string[];
+    form: {
+        title: string;
+        description?: string;
+        submitLabel: string;
+        fields: PluginFormField[];
+    };
+    output?: PluginCommandContractExtension['output'];
+}
+interface PluginContract {
+    version: 2;
+    plugin: {
+        name: string;
+        url?: string;
+        description?: string;
+        requiresLogin?: boolean;
+    };
+    commands: PluginCommandContract[];
+}
+interface PluginListOptions {
+    json?: boolean;
+}
+
 /**
  * Options for configuring the plugin loader's search directories.
  */
@@ -985,6 +1460,7 @@ declare class XBrowserPluginLoader {
     getPlugin(id: string): PluginInstance | undefined;
     getPluginStatus(id: string): PluginStatus;
     getLoadedPlugins(): PluginInstance[];
+    getPluginContract(siteName: string, commandName?: string): PluginContract | PluginCommandContract | undefined;
     loadPlugin(pluginPath: string, id?: string): Promise<PluginInstance>;
     unloadPlugin(id: string): Promise<void>;
     reloadPlugin(id: string): Promise<PluginInstance>;
@@ -993,23 +1469,6 @@ declare class XBrowserPluginLoader {
     unload(): Promise<void>;
 }
 
-interface XBrowserPluginMetadata {
-    id: string;
-    name: string;
-    description: string;
-    version: string;
-    author: string;
-    homepage?: string;
-    commands?: string[];
-    sites?: string[];
-    tags?: string[];
-    screenshot?: string;
-    license?: string;
-}
-interface PluginListOptions {
-    json?: boolean;
-}
-
 interface InstalledPlugin {
     id: string;
     name: string;
@@ -1104,7 +1563,7 @@ declare class RecorderController {
     private startTime;
     private startUrl;
     private name;
-    constructor(page: Page);
+    constructor(page: XBPage);
     /**
      * Start recording browser interactions.
      *
@@ -1300,7 +1759,7 @@ declare class SessionRecorder {
     private lastActionTs;
     private activePages;
     private _isRecording;
-    constructor(context: BrowserContext, page: Page, sessionName: string);
+    constructor(context: XBContext, page: XBPage, sessionName: string);
     get isRecording(): boolean;
     get actionCount(): number;
     get networkCount(): number;
@@ -1386,7 +1845,7 @@ declare class PlaybackEngine {
     private page;
     private recording;
     private checkpoints;
-    constructor(page: Page, recording: RecordingSession);
+    constructor(page: XBPage, recording: RecordingSession);
     /**
      * Create a PlaybackEngine from a YAML recording file.
      *
@@ -1394,7 +1853,7 @@ declare class PlaybackEngine {
      * @param filePath - Path to the YAML recording file.
      * @returns A new PlaybackEngine instance.
      */
-    static fromFile(page: Page, filePath: string): PlaybackEngine;
+    static fromFile(page: XBPage, filePath: string): PlaybackEngine;
     withCheckpoints(checkpoints: CheckpointEntry[]): PlaybackEngine;
     play(options?: PlaybackOptions): Promise<PlaybackResult>;
     private executeEvent;
@@ -1452,7 +1911,7 @@ declare class CaptchaDetector {
      * @param page - The Playwright page to scan.
      * @returns Detection result with type, selector, and confidence level.
      */
-    static detect(page: Page): Promise<CaptchaDetectionResult>;
+    static detect(page: XBPage): Promise<CaptchaDetectionResult>;
     /**
      * Check whether a previously detected CAPTCHA has been solved.
      *
@@ -1460,7 +1919,7 @@ declare class CaptchaDetector {
      * @param previousSelector - The selector from a previous detection result.
      * @returns `true` if the CAPTCHA is no longer visible.
      */
-    static isSolved(page: Page, previousSelector?: string): Promise<boolean>;
+    static isSolved(page: XBPage, previousSelector?: string): Promise<boolean>;
 }
 
 /**
@@ -1520,7 +1979,7 @@ declare class ScreencastCapturer {
      * If CDP session creation fails (non-Chromium, restricted access),
      * automatically falls back to `page.screenshot()` polling.
      */
-    startCapture(page: Page, sessionId: string, onFrame: (frame: ScreencastFrame) => void): Promise<void>;
+    startCapture(page: XBPage, sessionId: string, onFrame: (frame: ScreencastFrame) => void): Promise<void>;
     /**
      * Fallback: periodic page.screenshot() polling when CDP Cast is unavailable.
      */
@@ -1817,6 +2276,87 @@ declare function registerCommandDefinition(name: string, positional: string[]):
 
 declare function normalizeSelector(input: string): string;
 
+type AgentTargetAction = 'click' | 'fill' | 'type' | 'press' | 'select' | 'check' | 'hover';
+interface AgentTarget {
+    ref: string;
+    selector: string;
+    role: string;
+    name: string;
+    tag: string;
+    visible: boolean;
+    enabled: boolean;
+    editable: boolean;
+    checked?: boolean;
+    value?: string;
+    box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    actions: AgentTargetAction[];
+}
+interface AgentObservation {
+    url: string;
+    title: string;
+    screenHash: string;
+    timestamp: string;
+    targets: AgentTarget[];
+    compact?: string;
+    selectors?: Record<string, string>;
+}
+type AgentActionType = 'click' | 'fill' | 'type' | 'press' | 'select' | 'check' | 'hover';
+interface AgentActionInput {
+    action: AgentActionType;
+    ref?: string;
+    selector?: string;
+    value?: string;
+    key?: string;
+    force?: boolean;
+    timeout?: number;
+}
+interface AgentActionResult {
+    action: AgentActionType;
+    selector: string;
+    ref?: string;
+    success: boolean;
+    reason?: string;
+    message?: string;
+    stale?: boolean;
+    screenHash?: string;
+    target?: AgentTarget;
+}
+type AgentWaitState = 'attached' | 'detached' | 'visible' | 'hidden';
+type AgentLoadState = 'load' | 'domcontentloaded' | 'networkidle';
+interface AgentWaitInput {
+    selector?: string;
+    state?: AgentWaitState;
+    text?: string;
+    url?: string;
+    load?: AgentLoadState;
+    fn?: string;
+    screenHashChanged?: string;
+    timeout?: number;
+    pollInterval?: number;
+}
+interface AgentWaitResult {
+    success: boolean;
+    matched: 'selector' | 'text' | 'url' | 'load' | 'fn' | 'screenHashChanged';
+    timeout: number;
+    elapsed: number;
+    screenHash?: string;
+    message?: string;
+}
+
+interface ObserveOptions {
+    includeHidden?: boolean;
+    limit?: number;
+}
+declare function observePage(page: XBPage, sessionId: string | undefined, options?: ObserveOptions): Promise<AgentObservation>;
+declare function getPageScreenHash(page: XBPage): Promise<string>;
+declare function actOnPage(page: XBPage, sessionId: string | undefined, input: AgentActionInput): Promise<AgentActionResult>;
+declare function waitForPage(page: XBPage, input: AgentWaitInput): Promise<AgentWaitResult>;
+
 /**
  * A single event in a browser recording.
  */
@@ -2249,4 +2789,4 @@ declare function advise(decision: DecisionResult, originalMethod: string): Advis
 /** Convenience factory: create and start a CDP interceptor proxy with defaults. */
 declare function createCDPInterceptor(config: CDPInterceptorConfig): Promise<CDPInterceptorProxy>;
 
-export { type APIRequest, type APIResponse, type AdvisoryResult, type AnalysisResult, BROWSER_SCOPE, type BatchCollectResult, type BrowserCommandContext, type BrowserCommandDefinition, type BrowserLaunchOptions, type BuiltinCommand, type BuiltinContext, type CDPError, type CDPInterceptorConfig, CDPInterceptorProxy, type CDPInterceptorRule, type CDPInterceptorStats, type CDPLogEntry, type CDPMessage, type CDPRequest, type CDPResponse, type CaptchaDetectionResult, CaptchaDetector, type ChainExecutionResult, type ChainRequest, type ChainStepResult, type CollectResult, type CollectorConfig, type CommandMessage, type CompanyInfo, type ContextChange, type DaemonInfo, DataCollector, DataStorage, type DecisionAction, type DecisionResult, type DomainStat, type ElementRef, type ExecRequest, type ExecutionResult, HTTPServer, type HTTPServerConfig, type HTTPServerError, HumanInteractionManager, type InstallOptions, type InstalledPlugin, type ManagedSession, type MessageDirection, type NetworkEntry, type ParsedPipeline, PlaybackEngine, type PlaybackOptions, type PlaybackResult, PluginInstaller, type PluginLoaderOptions, type RecordedEvent, RecorderController, type RecorderStatus, type Recording, type RecordingControlFile, type RecordingData, type RecordingEvent, type RecordingSession, type RecordingStep, type RecordingSummary, type RegisteredCommand, ResultAnalyzer, type RuleContext, type RuleEngine, type ScopeDefinition, type ScopeLevel, ScreencastCapturer, type ScreencastFrame, type ScreencastMessage, type ScreencastOptions, type SearchResult, type ManagedSession as SessionInfo, SessionRecorder, type StatusMessage, type StorageConfig, type UserAction, type ViolationSeverity, type WSInboundMessage, type WSMessage, WSServer, type WSServerConfig, type WaitForHumanOptions, type WaitForHumanResult, WebhookNotifier, type WebhookPayload, XBrowserPluginLoader, advise, allBuiltins, assertPageScope, attachWaitForHuman, automationSignalsRule, checkBrowserScope, routeCommand as cliRoute, closeAllSessions as closeAllBrowserSessions, closeAllSessions, closeSession, closeSessionByName, createCDPInterceptor, createRuleEngine, createSession, destroyBrowser, destroyBrowser as destroySessionManager, domMutationRule, emulationOverrideRule, eventSimulationRule, executeChain, executeCommand, extractAndSave, extractRecording, filterRecording, findSession, findSession as findSessionInfo, fingerprintingRule, generateBashScript, generateJSScript, generatePythonScript, getAllSessions as getAllBrowserSessions, getAllCommands, getBrowser, getBuiltin, getCaptchaConfig, getCommand, getCommandNames, getCompanyType, getDaemonProcessStatus, getPlatformName, getSessionPage, getWSServerFromCache, inputKeystrokeRule, isChainInput, getAllSessions as listAllBrowserSessions, listSessions, mouseTrajectoryRule, networkAnomalyRule, normalizeSelector, openSession, pageLifecycleRule, parseCommandArgs, parseCommandChain, parseExcludeTypes, printExtractSummary, readCommandFile, readStdin, registerCommand, registerCommandDefinition, resetForTesting, setWSServer, setWSServerCache, splitCommand, startDaemonProcess, stopDaemonProcess, version };
+export { type APIRequest, type APIResponse, type AdvisoryResult, type AgentActionInput, type AgentActionResult, type AgentObservation, type AgentTarget, type AgentWaitInput, type AgentWaitResult, type AnalysisResult, BROWSER_SCOPE, type BatchCollectResult, type BrowserCommandContext, type BrowserCommandDefinition, type BrowserLaunchOptions, type BuiltinCommand, type BuiltinContext, type CDPError, type CDPInterceptorConfig, CDPInterceptorProxy, type CDPInterceptorRule, type CDPInterceptorStats, type CDPLogEntry, type CDPMessage, type CDPRequest, type CDPResponse, type CaptchaDetectionResult, CaptchaDetector, type ChainExecutionResult, type ChainRequest, type ChainStepResult, type CollectResult, type CollectorConfig, type CommandMessage, type CompanyInfo, type ContextChange, type DaemonInfo, DataCollector, DataStorage, type DecisionAction, type DecisionResult, type DomainStat, type ElementRef, type ExecRequest, type ExecutionResult, HTTPServer, type HTTPServerConfig, type HTTPServerError, HumanInteractionManager, type InstallOptions, type InstalledPlugin, type ManagedSession, type MessageDirection, type NetworkEntry, type ParsedPipeline, PlaybackEngine, type PlaybackOptions, type PlaybackResult, PluginInstaller, type PluginLoaderOptions, type RecordedEvent, RecorderController, type RecorderStatus, type Recording, type RecordingControlFile, type RecordingData, type RecordingEvent, type RecordingSession, type RecordingStep, type RecordingSummary, type RegisteredCommand, ResultAnalyzer, type RuleContext, type RuleEngine, type ScopeDefinition, type ScopeLevel, ScreencastCapturer, type ScreencastFrame, type ScreencastMessage, type ScreencastOptions, type SearchResult, type ManagedSession as SessionInfo, SessionRecorder, type StatusMessage, type StorageConfig, type UserAction, type ViolationSeverity, type WSInboundMessage, type WSMessage, WSServer, type WSServerConfig, type WaitForHumanOptions, type WaitForHumanResult, WebhookNotifier, type WebhookPayload, XBrowserPluginLoader, actOnPage, advise, allBuiltins, assertPageScope, attachWaitForHuman, automationSignalsRule, checkBrowserScope, routeCommand as cliRoute, closeAllSessions as closeAllBrowserSessions, closeAllSessions, closeSession, closeSessionByName, createCDPInterceptor, createRuleEngine, createSession, destroyBrowser, destroyBrowser as destroySessionManager, domMutationRule, emulationOverrideRule, eventSimulationRule, executeChain, executeCommand, extractAndSave, extractRecording, filterRecording, findSession, findSession as findSessionInfo, fingerprintingRule, generateBashScript, generateJSScript, generatePythonScript, getAllSessions as getAllBrowserSessions, getAllCommands, getBrowser, getBuiltin, getCaptchaConfig, getCommand, getCommandNames, getCompanyType, getDaemonProcessStatus, getPageScreenHash, getPlatformName, getSessionPage, getWSServerFromCache, inputKeystrokeRule, isChainInput, getAllSessions as listAllBrowserSessions, listSessions, mouseTrajectoryRule, networkAnomalyRule, normalizeSelector, observePage, openSession, pageLifecycleRule, parseCommandArgs, parseCommandChain, parseExcludeTypes, printExtractSummary, readCommandFile, readStdin, registerCommand, registerCommandDefinition, resetForTesting, setWSServer, setWSServerCache, splitCommand, startDaemonProcess, stopDaemonProcess, version, waitForPage };