@xbrowser/cli 0.16.0 → 1.0.2

package/dist/index.d.ts

@@ -1,13 +1,426 @@
+import { Tip, CommandContext, CommandScope, XCLIAPI, Core, PluginInstance, PluginStatus } from '@dyyz1993/xcli-core';
+export { PluginStatus, parseCommandArgs, readCommandFile, readStdin, registerCommandDefinition, splitCommand } from '@dyyz1993/xcli-core';
 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[];
+    /**
+     * Discover existing browser contexts and pages from the CDP browser.
+     * Required when connecting via CDP tunnel (cdp-tunnel) where
+     * auto-attach events are unreliable. After this call, `contexts()`
+     * returns the user's actual browser contexts (with their existing
+     * cookies and login state) instead of an empty list.
+     */
+    discoverContexts(): Promise<void>;
+    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;
+    waitForEvent(event: string, opts?: {
+        timeout?: number;
+        predicate?: (...args: unknown[]) => boolean;
+    }): Promise<unknown>;
+    _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.
  */
@@ -54,6 +467,9 @@ type WSMessage = {
     success: boolean;
     fileName: string;
     error?: string;
+} | {
+    type: 'file_input_clicked';
+    selector: string;
 } | {
     type: 'file_list_result';
     path: string;
@@ -70,6 +486,9 @@ type WSMessage = {
     mimeType: string;
     data: string;
     error?: string;
+} | {
+    type: 'views_update';
+    views: ViewInfo[];
 } | {
     type: 'error';
     data: {
@@ -78,6 +497,16 @@ type WSMessage = {
         availableSessions?: string[];
     };
 };
+interface ViewInfo {
+    id: string;
+    label: string;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
 /**
  * Inbound WebSocket message types received from clients.
  */
@@ -136,6 +565,16 @@ type WSInboundMessage = {
     selector: string;
 } | {
     type: 'focus_clear';
+} | {
+    type: 'input_blur';
+} | {
+    type: 'select_view';
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
 };
 /**
  * A screencast frame message with binary image data.
@@ -186,71 +625,46 @@ interface StatusMessage {
  *
  * **Lazy screencast**: Screencast capture only starts when the first WS client
  * binds to a session, and stops when the last client for that session disconnects.
+ *
+ * Responsibilities are delegated to:
+ * - **SessionManager**: client/session lifecycle, capturer start/stop, element monitors
+ * - **StreamCoordinator**: frame processing, stream state, crop management
+ * - **MessageDispatcher**: inbound message routing to typed handlers
  */
 declare class WSServer extends EventEmitter {
     private port;
     private host;
-    private clients;
-    private sessionClients;
-    private screencasts;
     private wsServer;
     private isRunning;
-    private stateManager;
-    private frameRateController;
-    private frameProcessor;
-    private lastFrameData;
-    private lastFrameViewport;
-    private sessionCrops;
+    private readonly streamCoordinator;
+    private readonly sessionManager;
+    private readonly messageDispatcher;
     constructor(config?: WSServerConfig);
-    private processAndBroadcast;
-    /**
-     * Register a session page for screencast streaming.
-     * 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?: {
+    private setupSessionManagerEvents;
+    registerSession(sessionId: string, page: XBPage, options?: {
         interval?: number;
         quality?: number;
         type?: 'jpeg' | 'png';
         width?: number;
         height?: number;
     }): void;
-    /**
-     * Unregister a session. Stops screencast if running.
-     */
     unregisterSession(sessionId: string): void;
-    /**
-     * Start standalone WS server on its own port.
-     */
+    pauseScreencast(sessionId: string): Promise<void>;
+    resumeScreencast(sessionId: string): Promise<void>;
+    private startScreencastIfNeeded;
+    private stopScreencastIfNeeded;
+    bindClientToSession(clientId: string, sessionId: string): void;
+    private sendBoundStatus;
     start(): Promise<void>;
-    /**
-     * Attach to an existing HTTP server via WS upgrade.
-     * Shares the same port as the HTTP server (e.g., daemon port 9224).
-     * The WS path defaults to `/preview`.
-     */
     attachToServer(httpServer: Server, path?: string): Promise<void>;
-    /**
-     * Set up the connection handler for incoming WS connections.
-     * When attached to an HTTP server, the third argument carries the sessionId
-     * extracted from the URL path (e.g., /preview/default).
-     */
+    stop(): Promise<void>;
     private setupConnectionHandler;
-    /**
-     * Lazy screencast: start when first client binds, stop when last unbinds.
-     */
-    private startScreencastIfNeeded;
-    private stopScreencastIfNeeded;
-    pauseScreencast(sessionId: string): Promise<void>;
-    resumeScreencast(sessionId: string): Promise<void>;
-    private sendToClient;
-    private getClientPage;
     private handleInboundMessage;
-    stop(): Promise<void>;
-    bindClientToSession(clientId: string, sessionId: string): void;
+    private handleClientDisconnect;
+    private sendToClient;
     broadcastToSession(sessionId: string, message: WSMessage): void;
     broadcast(message: WSMessage): void;
     broadcastBinaryToSession(sessionId: string, payload: Buffer): void;
-    private handleClientDisconnect;
     getClientCount(): number;
     getSessionClientCount(sessionId: string): number;
     getRunning(): boolean;
@@ -269,7 +683,7 @@ interface ExecutionResult {
     data: unknown;
     message?: string;
     duration: number;
-    tips?: string[];
+    tips?: Tip[];
     hookOutputs?: HookOutput[];
 }
 /**
@@ -282,7 +696,7 @@ interface ChainStepResult {
     data: unknown;
     message?: string;
     duration: number;
-    tips?: string[];
+    tips?: Tip[];
     hookOutputs?: HookOutput[];
 }
 /**
@@ -530,7 +944,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 +966,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 +988,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 +999,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 +1022,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 +1054,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.
  *
@@ -855,23 +1269,6 @@ interface AISearchResult {
  */
 declare function routeCommand(argv: string[], stdinCommands?: string[]): Promise<void>;
 
-/**
- * Read non-empty, non-comment lines from stdin.
- *
- * Returns an empty array when stdin is a TTY. Lines starting with `#` are
- * treated as comments and skipped.
- *
- * @returns Array of trimmed, non-comment lines.
- */
-declare function readStdin(): Promise<string[]>;
-/**
- * Read a command file and return non-empty, non-comment lines.
- *
- * @param filePath - Path to the file to read.
- * @returns Array of trimmed, non-comment lines.
- */
-declare function readCommandFile(filePath: string): string[];
-
 /**
  * Open a new browser session, navigate to the given URL, and persist session metadata.
  *
@@ -915,7 +1312,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 +1354,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 +1456,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 +1465,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 +1559,7 @@ declare class RecorderController {
     private startTime;
     private startUrl;
     private name;
-    constructor(page: Page);
+    constructor(page: XBPage);
     /**
      * Start recording browser interactions.
      *
@@ -1177,7 +1632,7 @@ interface ClickContext {
 }
 interface UserAction {
     id: number;
-    type: 'click' | 'input' | 'change' | 'keydown' | 'submit' | 'scroll';
+    type: 'click' | 'input' | 'change' | 'keydown' | 'submit' | 'scroll' | 'navigation' | 'goto' | 'cdp-fill' | 'cdp-click' | 'cdp-eval' | 'filechooser' | 'dblclick' | 'contextmenu' | 'hover' | 'drag' | 'resize' | 'clipboard' | 'touch' | 'focus' | 'visibility';
     timestamp: number;
     url: string;
     pageTitle: string;
@@ -1185,6 +1640,21 @@ interface UserAction {
         tag: string;
         selector?: string;
         text: string;
+        /** Which strategy from generateUniqueSelector produced this selector */
+        strategy?: string;
+        /** Reliability rating from generateUniqueSelector: high / medium / low */
+        confidence?: 'high' | 'medium' | 'low';
+        /** Text-based fallback for low-confidence selectors (e.g. menu items) */
+        textFallback?: {
+            type: 'text';
+            value: string;
+            selector: string;
+        };
+        /** Popup/menu context when element is inside a dropdown */
+        popup?: {
+            containerSelector: string;
+            containerText: string;
+        };
         role?: string;
         type?: string;
         placeholder?: string;
@@ -1199,6 +1669,77 @@ interface UserAction {
     scrollY?: number;
     /** Click context: popover/dropdown/menu items captured 200ms after click */
     clickContext?: ClickContext;
+    /** File upload info (type=filechooser only) */
+    files?: {
+        names: string[];
+        count: number;
+        isMultiple: boolean;
+        fileData?: Array<{
+            name: string;
+            type: string;
+            size: number;
+            dataUrl: string | null;
+        }>;
+    };
+    /** Drag & drop info (type=drag only) */
+    drag?: {
+        fromX: number;
+        fromY: number;
+        toX: number;
+        toY: number;
+        /** Source element description */
+        source?: {
+            tag: string;
+            selector?: string;
+            text: string;
+        };
+        /** Target (drop zone) element description */
+        target?: {
+            tag: string;
+            selector?: string;
+            text: string;
+        };
+    };
+    /** Resize info (type=resize only) */
+    resize?: {
+        width: number;
+        height: number;
+    };
+    /** Clipboard info (type=clipboard only) */
+    clipboard?: {
+        operation: 'copy' | 'paste' | 'cut';
+        textPreview?: string;
+    };
+    /** Touch info (type=touch only) */
+    touch?: {
+        touchType: 'start' | 'move' | 'end';
+        touches: Array<{
+            x: number;
+            y: number;
+        }>;
+    };
+    /** Focus info (type=focus only) */
+    focus?: {
+        focusType: 'focus' | 'blur';
+    };
+    /** Visibility info (type=visibility only) */
+    visibility?: {
+        state: 'visible' | 'hidden';
+    };
+    /** Mouse trajectory from previous action's position to this action's position.
+     *  Captured as simplified waypoints with relative timestamps for realistic replay. */
+    trajectory?: {
+        /** Waypoints: [x, y, deltaMs from previous point] */
+        points: Array<{
+            x: number;
+            y: number;
+            dt: number;
+        }>;
+        /** Total distance in pixels (approximate) */
+        distance: number;
+        /** Total duration in ms */
+        duration: number;
+    };
 }
 interface NetworkEntry {
     id: number;
@@ -1299,10 +1840,24 @@ declare class SessionRecorder {
     private flushTimer;
     private lastActionTs;
     private activePages;
+    private lastKnownUrl;
+    /** Dedup window: after a CDP command action, ignore matching action signals within this window */
+    private cdpActionDedup;
+    /** Network dedup: last request key for short-window dedup */
+    private _lastRequestKey;
+    private _lastRequestTs;
     private _isRecording;
-    constructor(context: BrowserContext, page: Page, sessionName: string);
+    constructor(context: XBContext, page: XBPage, sessionName: string);
     get isRecording(): boolean;
     get actionCount(): number;
+    /** Record an action triggered by a CDP command (e.g. xbrowser fill/click/goto) */
+    recordCommandAction(action: {
+        type: string;
+        selector?: string;
+        value?: string;
+        url?: string;
+        element?: UserAction['element'];
+    }): void;
     get networkCount(): number;
     getLiveData(): RecordingData;
     addManualCheckpoint(type: string, hint: string, selector?: string): CheckpointEntry;
@@ -1329,6 +1884,7 @@ declare class SessionRecorder {
     private handleNewPage;
     private handleFrameNavigated;
     private handleDialog;
+    private handleFileChooser;
     private pollActions;
     private flushPendingActions;
     /**
@@ -1386,7 +1942,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 +1950,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 +2008,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 +2016,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 +2076,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.
      */
@@ -1771,52 +2327,92 @@ interface ParseOptions {
  * @param input - The raw command chain string.
  * @param options - Parse options; `fileMode` treats single `|` as a pipeline separator.
  * @returns Array of parsed pipelines, each with commands and a chain type.
- *
- * @example
- * ```ts
- * const pipelines = parseCommandChain('goto https://example.com && click #btn');
- * // [{ pipeline: ['goto https://example.com', 'click #btn'], type: 'and' }]
- * ```
  */
 declare function parseCommandChain(input: string, options?: ParseOptions): ParsedPipeline[];
-/**
- * Split a command string into whitespace-separated tokens, respecting quotes.
- *
- * @param cmdStr - The raw command string (e.g. `"click '#my-btn'"`).
- * @returns Array of string tokens.
- */
-declare function splitCommand(cmdStr: string): string[];
-/**
- * Parse positional and flagged arguments into a parameter object.
- *
- * Supports `--key value`, `-s value` (short flags), and positional arguments
- * mapped via registered command definitions. Values are automatically coerced
- * to boolean, number, or string.
- *
- * @param name - The command name (used to look up positional parameter names).
- * @param args - Array of argument strings.
- * @returns An object with the command name and parsed params.
- *
- * @example
- * ```ts
- * const { params } = parseCommandArgs('fill', ['#email', 'hello']);
- * // { command: 'fill', params: { selector: '#email', value: 'hello' } }
- * ```
- */
-declare function parseCommandArgs(name: string, args: string[]): {
-    command: string;
-    params: Record<string, unknown>;
-};
-/**
- * Register positional parameter names for a command used by {@link parseCommandArgs}.
- *
- * @param name - The command name.
- * @param positional - Ordered array of positional parameter names.
- */
-declare function registerCommandDefinition(name: string, positional: string[]): void;
 
 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.
  */
@@ -1859,7 +2455,8 @@ declare function generateJSScript(recording: Recording): string;
  * Generate a Python replay script from a recording.
  *
  * @param recording - The recording session to convert.
- * @returns A self-contained Python script string using Playwright async API.
+ * @returns A self-contained Python script string using Playwright async API
+ *          (requires: pip install playwright && playwright install chromium).
  */
 declare function generatePythonScript(recording: Recording): string;
 /**
@@ -2249,4 +2846,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, parseCommandChain, parseExcludeTypes, printExtractSummary, registerCommand, resetForTesting, setWSServer, setWSServerCache, startDaemonProcess, stopDaemonProcess, version, waitForPage };