@xbrowser/cli 0.14.3 → 0.15.0

package/dist/index.d.ts

@@ -1,3 +1,797 @@
+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;
+
+/**
+ * Configuration for the WebSocket server.
+ */
+interface WSServerConfig {
+    port?: number;
+    host?: string;
+}
+/**
+ * Outbound WebSocket message types sent to connected clients.
+ */
+type WSMessage = {
+    type: 'screenshot';
+    data: ScreencastMessage;
+} | {
+    type: 'command';
+    data: CommandMessage;
+} | {
+    type: 'status';
+    data: StatusMessage;
+} | {
+    type: 'captcha-detected';
+    sessionId: string;
+    url: string;
+    reason: string;
+    timeout: number;
+} | {
+    type: 'resolved';
+    sessionId: string;
+} | {
+    type: 'navigation';
+    url: string;
+    title: string;
+} | {
+    type: 'input_focused';
+    selector: string;
+    value: string;
+    tag: string;
+    placeholder?: string;
+} | {
+    type: 'input_blur';
+    selector: string;
+} | {
+    type: 'file_upload_result';
+    success: boolean;
+    fileName: string;
+    error?: string;
+} | {
+    type: 'file_list_result';
+    path: string;
+    files: Array<{
+        name: string;
+        isDir: boolean;
+        size: number;
+        modified: string;
+    }>;
+    error?: string;
+} | {
+    type: 'file_download_result';
+    fileName: string;
+    mimeType: string;
+    data: string;
+    error?: string;
+} | {
+    type: 'error';
+    data: {
+        code: string;
+        message: string;
+        availableSessions?: string[];
+    };
+};
+/**
+ * Inbound WebSocket message types received from clients.
+ */
+type WSInboundMessage = {
+    type: 'click';
+    x: number;
+    y: number;
+    button?: 'left' | 'right';
+} | {
+    type: 'type';
+    text: string;
+} | {
+    type: 'keypress';
+    key: string;
+} | {
+    type: 'scroll';
+    deltaX: number;
+    deltaY: number;
+} | {
+    type: 'solved';
+} | {
+    type: 'bind';
+    sessionId: string;
+} | {
+    type: 'input_mouse';
+    action: 'move' | 'down' | 'up' | 'click';
+    x: number;
+    y: number;
+    button?: 'left' | 'middle' | 'right';
+} | {
+    type: 'input_keyboard';
+    action: 'down' | 'up';
+    key: string;
+    modifiers?: number;
+} | {
+    type: 'input_fill';
+    text: string;
+    selector: string;
+} | {
+    type: 'input_insert_text';
+    text: string;
+} | {
+    type: 'file_upload';
+    fileName: string;
+    mimeType: string;
+    data: string;
+    selector?: string;
+} | {
+    type: 'file_list';
+    path: string;
+} | {
+    type: 'file_download';
+    path: string;
+} | {
+    type: 'focus_element';
+    selector: string;
+} | {
+    type: 'focus_clear';
+};
+/**
+ * A screencast frame message with binary image data.
+ */
+interface ScreencastMessage {
+    sessionId: string;
+    id: string;
+    timestamp: number;
+    data: Buffer;
+    url: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * A command execution event message streamed during command lifecycle.
+ */
+interface CommandMessage {
+    sessionId: string;
+    command: string;
+    args: unknown[];
+    phase: 'before' | 'after';
+    result?: unknown;
+    error?: string;
+    timestamp: number;
+    duration?: number;
+}
+/**
+ * A server status change notification.
+ */
+interface StatusMessage {
+    status: 'connected' | 'disconnected' | 'error';
+    sessionId?: string;
+    message?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * WebSocket server for streaming browser screenshots and handling remote input.
+ *
+ * Two modes:
+ * 1. **Standalone**: `start()` creates its own WS server on a port.
+ * 2. **Attached**: `attachToServer(httpServer)` shares an existing HTTP server
+ *    via the WS upgrade mechanism (same port as HTTP, e.g., daemon port 9224).
+ *
+ * **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.
+ */
+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;
+    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?: {
+        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.
+     */
+    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).
+     */
+    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;
+    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;
+    getPort(): number;
+}
+
+/**
+ * Result of a single command execution.
+ */
+interface HookOutput {
+    _hook: string;
+    [key: string]: unknown;
+}
+interface ExecutionResult {
+    success: boolean;
+    data: unknown;
+    message?: string;
+    duration: number;
+    tips?: string[];
+    hookOutputs?: HookOutput[];
+}
+/**
+ * Result of a single step within a command chain execution.
+ */
+interface ChainStepResult {
+    command: string;
+    raw: string;
+    success: boolean;
+    data: unknown;
+    message?: string;
+    duration: number;
+    tips?: string[];
+    hookOutputs?: HookOutput[];
+}
+/**
+ * Result of executing a command chain (multiple commands linked with &&, ||, etc.).
+ */
+interface ChainExecutionResult {
+    success: boolean;
+    steps: ChainStepResult[];
+    totalDuration: number;
+    stoppedAt?: number;
+    stoppedReason?: string;
+}
+/**
+ * Set or clear the WebSocket server used for streaming command events.
+ *
+ * @param server - A WSServer instance to stream events to, or null to disable.
+ */
+declare function setWSServer(server: WSServer | null): void;
+/**
+ * Execute a single browser command against an existing session.
+ *
+ * Looks up the command by name, validates parameters via Zod schema,
+ * resolves the target session, and runs the command handler.
+ * Streams before/after events to the configured WebSocket server.
+ *
+ * @param commandName - Registered command name (e.g. "goto", "click", "fill").
+ * @param params - Key-value parameters forwarded to the command handler.
+ * @param sessionName - Name of the target session. Defaults to "default".
+ * @returns An {@link ExecutionResult} with success status, data, and duration.
+ *
+ * @example
+ * ```ts
+ * const result = await executeCommand('click', { selector: '#submit' }, 'default');
+ * if (result.success) console.log('Clicked!', result.data);
+ * ```
+ */
+declare function executeCommand(commandName: string, params: Record<string, unknown>, sessionName?: string, extraOpts?: {
+    cdpEndpoint?: string;
+    skipCleanup?: boolean;
+}): Promise<ExecutionResult>;
+/**
+ * Execute a chain of browser commands parsed from a string expression.
+ *
+ * Supports `&&` (and-chain, stops on first failure), `||` (or-chain, stops on
+ * first success), `;` (sequence separator), `->`, `,`, and `+` operators.
+ * Automatically creates a browser session if none exists and destroys it
+ * afterwards.
+ *
+ * @param input - Raw chain expression (e.g. `"goto https://example.com && click #btn"`).
+ * @param options - Optional configuration for CDP endpoint, session name, and file mode.
+ * @returns A {@link ChainExecutionResult} with per-step results and total duration.
+ *
+ * @example
+ * ```ts
+ * const result = await executeChain('goto https://example.com && click #btn');
+ * console.log(result.success, result.steps.length);
+ * ```
+ */
+declare function executeChain(input: string, options?: {
+    cdpEndpoint?: string;
+    sessionName?: string;
+    fileMode?: boolean;
+}): Promise<ChainExecutionResult>;
+/**
+ * Check whether the given input string contains chain operators.
+ *
+ * Detects `&&`, `;`, `,`, `+`, and `->` surrounded by whitespace.
+ *
+ * @param input - The raw input string to test.
+ * @returns `true` if chain operators are present.
+ */
+declare function isChainInput(input: string): boolean;
+
+/**
+ * CDP Interceptor — Core Types
+ *
+ * Models the JSON-RPC 2.0 messages flowing over the CDP WebSocket and
+ * defines the rule/decision system for intercepting, blocking, or
+ * transforming automation traffic to avoid anti-crawler detection.
+ */
+/** Raw JSON-RPC 2.0 request as it appears on the wire */
+interface CDPRequest {
+    id: number;
+    method: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+}
+/** Raw JSON-RPC 2.0 response (success) */
+interface CDPResponse {
+    id: number;
+    result?: Record<string, unknown>;
+    sessionId?: string;
+}
+/** Raw JSON-RPC 2.0 error response */
+interface CDPError {
+    id: number;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    sessionId?: string;
+}
+/** Union of all possible CDP messages */
+type CDPMessage = CDPRequest | CDPResponse | CDPError;
+/** Direction: from client → browser or browser → client */
+type MessageDirection = 'client→browser' | 'browser→client';
+/** Structured log entry for a single CDP message */
+interface CDPLogEntry {
+    /** Unix timestamp in ms */
+    timestamp: number;
+    /** Message direction */
+    direction: MessageDirection;
+    /** Session identifier (for grouping messages) */
+    sessionId: string;
+    /** CDP method (e.g. "Runtime.evaluate"), undefined for responses */
+    method?: string;
+    /** Sanitized payload summary */
+    payload: Record<string, unknown>;
+    /** Rule decision that was applied, if any */
+    decision?: DecisionResult;
+}
+/**
+ * Severity of a rule violation
+ *
+ * - **danger**: definitely triggers anti-crawler detection — block immediately
+ * - **warn**:   likely problematic — log and warn, but don't block yet
+ * - **info**:   informational only — could be a future concern
+ */
+type ViolationSeverity = 'danger' | 'warn' | 'info';
+/**
+ * Action the interceptor should take for a matched message
+ *
+ * - **block**:     reject the message, return CDP error, never reach browser
+ * - **transform**: modify the message before forwarding
+ * - **pass**:      forward unchanged (log only)
+ */
+type DecisionAction = 'block' | 'transform' | 'pass';
+/** Result of a rule evaluation */
+interface DecisionResult {
+    /** Matched rule id */
+    ruleId: string;
+    action: DecisionAction;
+    severity: ViolationSeverity;
+    /** Human-readable explanation of why this was flagged */
+    reason: string;
+    /** Suggested fix / alternative approach */
+    suggestion?: string;
+    /** Transformed params (only for 'transform' action) */
+    transformedParams?: Record<string, unknown>;
+    /** Custom CDP error code (only for 'block' action) */
+    errorCode?: number;
+    /** Custom CDP error message (only for 'block' action) */
+    errorMessage?: string;
+}
+/** Handler context passed to each rule */
+interface RuleContext {
+    method: string;
+    params: Record<string, unknown>;
+    sessionId: string;
+    /** Direction: the message is being sent TO the browser */
+    direction: MessageDirection;
+    /** Per-session state store (rules can stash data here) */
+    sessionState: Map<string, unknown>;
+}
+/**
+ * A CDP interception rule
+ *
+ * Rules are evaluated **in priority order** (lower number = earlier).
+ * The first rule that returns a decision wins.
+ */
+interface CDPInterceptorRule {
+    /** Unique rule identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Priority: lower numbers are evaluated first */
+    priority: number;
+    /**
+     * Quick pre-filter — skip expensive checks for messages that can't match.
+     * Return false to skip this rule.
+     */
+    canHandle?(ctx: RuleContext): boolean;
+    /**
+     * Evaluate the message and return a decision.
+     * Return null to pass (no match).
+     */
+    evaluate(ctx: RuleContext): DecisionResult | null;
+}
+/** Configuration for the CDP interceptor proxy */
+interface CDPInterceptorConfig {
+    /** Chromium CDP WebSocket endpoint (e.g. ws://localhost:9222/...) */
+    cdpEndpoint: string;
+    /** Port to listen on for incoming client connections */
+    listenPort?: number;
+    /** Rules to apply, defaults to built-in rules */
+    rules?: CDPInterceptorRule[];
+    /** Enable logging (default: true) */
+    enableLogging?: boolean;
+    /** Log output directory (default: no file logging) */
+    logDir?: string;
+    /** Block mode: 'strict' blocks danger only, 'paranoid' blocks warn+ */
+    blockMode?: 'strict' | 'paranoid';
+}
+/** Statistics collected during a proxy session */
+interface CDPInterceptorStats {
+    totalMessages: number;
+    blockedMessages: number;
+    transformedMessages: number;
+    passedMessages: number;
+    /** Breakdown by rule id */
+    byRule: Record<string, {
+        matched: number;
+        blocked: number;
+        transformed: number;
+    }>;
+}
+
+/**
+ * Options for the wait-for-human interaction flow.
+ */
+interface WaitForHumanOptions {
+    reason?: string;
+    timeout?: number;
+    autoDetect?: boolean;
+    detectInterval?: number;
+}
+/**
+ * Result of a wait-for-human interaction attempt.
+ */
+interface WaitForHumanResult {
+    solved: boolean;
+    method: 'preview' | 'auto-detected' | 'timeout' | 'manual';
+}
+/**
+ * Manages human-in-the-loop interactions for CAPTCHA solving and manual intervention.
+ *
+ * Streams the page via screencast, sends webhook notifications, and waits
+ * for either auto-detection of CAPTCHA resolution, manual solving via
+ * the preview UI, or timeout.
+ */
+declare class HumanInteractionManager {
+    private wsServer;
+    private page;
+    private capturer;
+    private webhook;
+    private autoOpen;
+    constructor(wsServer: WSServer, page: Page);
+    private sendWebhook;
+    private tryAutoOpen;
+    /**
+     * Wait for a human to solve a CAPTCHA or complete an interaction.
+     *
+     * Starts screencast streaming, sends webhook and broadcast notifications,
+     * then polls for CAPTCHA resolution or waits for a manual solve signal.
+     *
+     * @param options - Configuration for timeout, auto-detection, and reason text.
+     * @returns Result indicating whether the CAPTCHA was solved and by what method.
+     */
+    waitForHuman(options?: WaitForHumanOptions): Promise<WaitForHumanResult>;
+}
+
+/**
+ * Extended command context for browser automation commands.
+ *
+ * Provides Playwright Page, Browser, and BrowserContext instances,
+ * along with an optional `waitForHuman` function for CAPTCHA handling.
+ */
+interface BrowserCommandContext extends CommandContext {
+    page: Page;
+    browser: Browser;
+    browserContext: BrowserContext;
+    sessionId?: string;
+    cdpEndpoint?: string;
+    waitForHuman?: (options?: WaitForHumanOptions) => Promise<WaitForHumanResult>;
+}
+/**
+ * Validate that the required browser scope is available in the context.
+ *
+ * @param scope - The required command scope level.
+ * @param ctx - The current browser command context.
+ * @returns An error message string if the scope is not satisfied, or `null` if valid.
+ */
+declare function checkBrowserScope(scope: CommandScope, ctx: BrowserCommandContext): string | null;
+/**
+ * Assert that the context has an active page, narrowing the type.
+ *
+ * @param ctx - The browser command context to validate.
+ * @throws If no active page is available in the context.
+ */
+declare function assertPageScope(ctx: BrowserCommandContext): asserts ctx is BrowserCommandContext & {
+    page: Page;
+};
+/**
+ * Attach a `waitForHuman` function to the browser command context.
+ *
+ * Lazily imports the human interaction manager and binds it to the
+ * context's page via the provided WebSocket server factory.
+ *
+ * @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;
+/**
+ * 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;
+/**
+ * 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;
+
+/**
+ * Represents a managed browser session with its Playwright context, page,
+ * and its own dedicated Browser connection.
+ */
+interface ManagedSession {
+    id: string;
+    name: string;
+    context: BrowserContext;
+    page: Page;
+    browser: Browser;
+    createdAt: string;
+    lastActivityAt: number;
+    isCDP?: boolean;
+    cdpEndpoint?: string;
+}
+/**
+ * Options for launching or connecting to a browser instance.
+ */
+interface BrowserLaunchOptions {
+    headless?: boolean;
+    executablePath?: string;
+    cdpEndpoint?: string;
+    /** Enable CDP-level interception for anti-crawler protection */
+    intercept?: boolean | CDPInterceptorConfig;
+}
+/**
+ * Get or create the shared browser instance (lazy singleton).
+ *
+ * Used by non-session callers such as {@link createEphemeralContext} and
+ * project-scope commands that don't need per-session isolation.
+ *
+ * @param options - Launch options including headless mode, executable path, or CDP endpoint.
+ * @returns The shared Playwright Browser instance.
+ *
+ * @example
+ * ```ts
+ * const browser = await getBrowser({ headless: true });
+ * ```
+ */
+declare function getBrowser(options?: BrowserLaunchOptions): Promise<Browser>;
+/**
+ * Find a managed session by its name.
+ *
+ * @param name - The session name to search for.
+ * @returns The matching session, or `undefined` if not found.
+ */
+declare function findSession(name: string): ManagedSession | undefined;
+/**
+ * Get all active managed sessions.
+ *
+ * @returns Array of all active sessions.
+ */
+declare function getAllSessions(): ManagedSession[];
+/**
+ * Create a new browser session with a page and optional initial URL.
+ *
+ * Each session gets its own dedicated Browser connection. If connecting via
+ * CDP, reuses existing pages when possible instead of creating a new
+ * context/page pair.
+ *
+ * @param name - Unique name for the session.
+ * @param url - Optional URL to navigate to after creation.
+ * @param options - Browser launch or CDP connection options.
+ * @returns The newly created managed session.
+ *
+ * @example
+ * ```ts
+ * const session = await createSession('default', 'https://example.com');
+ * ```
+ */
+declare function createSession(name: string, url?: string, options?: BrowserLaunchOptions): Promise<ManagedSession>;
+/**
+ * Close a session by its name or ID.
+ *
+ * @param name - Session name or UUID to close.
+ * @returns `true` if a session was found and closed, `false` otherwise.
+ */
+declare function closeSessionByName(name: string): Promise<boolean>;
+/**
+ * Close all active browser sessions.
+ *
+ * Closes every managed context and its dedicated browser connection,
+ * ignoring individual close errors.
+ */
+declare function closeAllSessions(): Promise<void>;
+/**
+ * Close all sessions and destroy all browser instances.
+ *
+ * After calling this, the module returns to a clean state and
+ * {@link getBrowser} will create a new instance on next call.
+ */
+declare function destroyBrowser(): Promise<void>;
+/**
+ * Reset all internal state for testing purposes.
+ *
+ * Clears the session map and drops the browser reference without
+ * closing anything. Intended for use in test teardown.
+ */
+declare function resetForTesting(): void;
+
+/**
+ * Describes a single scope level in the browser automation hierarchy.
+ */
+interface ScopeLevel {
+    name: CommandScope;
+    description: string;
+    order: number;
+}
+/**
+ * A named scope definition with a description and ordered levels.
+ */
+interface ScopeDefinition {
+    name: string;
+    description: string;
+    levels: ScopeLevel[];
+}
+/**
+ * Built-in browser automation scope hierarchy.
+ *
+ * Defines four levels: project, browser, page, and element,
+ * ordered from coarsest to finest granularity.
+ */
+declare const BROWSER_SCOPE: ScopeDefinition;
+
+/**
+ * Definition of a browser command, including its Zod-validated parameters,
+ * scope, and handler function.
+ */
+interface BrowserCommandDefinition<P extends ZodType<unknown, ZodTypeDef, unknown> = ZodType<unknown, ZodTypeDef, unknown>> {
+    name: string;
+    description: string;
+    scope: CommandScope;
+    parameters?: P;
+    result?: ZodType<unknown>;
+    /**
+     * Declare which parameter keys contain CSS selectors.
+     * The executor will resolve `eN` ref values to real selectors before calling the handler.
+     */
+    selectorParams?: string[];
+    handler: (params: z.infer<P>, ctx: BrowserCommandContext) => Promise<unknown>;
+}
+/**
+ * A command that has been registered and is available for execution.
+ */
+interface RegisteredCommand {
+    readonly name: string;
+    readonly description: string;
+    readonly scope: CommandScope;
+    readonly parameters?: ZodType<unknown>;
+    readonly result?: ZodType<unknown>;
+    readonly selectorParams?: string[];
+    readonly handler: (params: Record<string, unknown>, ctx: BrowserCommandContext) => Promise<unknown>;
+}
+/**
+ * Register a browser command in the global registry.
+ *
+ * @param def - The command definition including name, description, scope, parameters, and handler.
+ * @returns The registered command instance.
+ *
+ * @example
+ * ```ts
+ * registerCommand({
+ *   name: 'click',
+ *   description: 'Click an element',
+ *   scope: 'element',
+ *   result: z.object({ success: z.boolean() }),
+ *   handler: async (params, ctx) => { await ctx.page.click(params.selector); return ok({ success: true }); },
+ * });
+ * ```
+ */
+declare function registerCommand<P extends ZodType<unknown, ZodTypeDef, unknown>>(def: BrowserCommandDefinition<P>): RegisteredCommand;
+/**
+ * Retrieve a registered command by name.
+ *
+ * @param name - The command name.
+ * @returns The registered command, or `undefined` if not found.
+ */
+declare function getCommand(name: string): RegisteredCommand | undefined;
+/**
+ * Get all registered commands.
+ *
+ * @returns Array of all registered commands.
+ */
+declare function getAllCommands(): RegisteredCommand[];
+/**
+ * Get the names of all registered commands.
+ *
+ * @returns Array of command name strings.
+ */
+declare function getCommandNames(): string[];
+
 interface AISearchResultItem {
     title: string;
     url: string;
@@ -49,6 +843,740 @@ interface AISearchResult {
     duration?: string;
 }
 
+/**
+ * Route CLI arguments to the appropriate handler.
+ *
+ * Dispatches stdin commands, eval flags, chain input, and sub-commands
+ * (session, plugin, daemon, record, replay, etc.) to their respective
+ * handler functions.
+ *
+ * @param argv - Raw CLI argument array (typically `process.argv.slice(2)`).
+ * @param stdinCommands - Optional array of commands read from stdin.
+ */
+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.
+ *
+ * @param name - Unique name for the session.
+ * @param url - The initial URL to navigate to.
+ * @param options - Optional CDP endpoint configuration.
+ * @returns Session info including id, name, url, and creation timestamp.
+ *
+ * @example
+ * ```ts
+ * const info = await openSession('default', 'https://example.com');
+ * ```
+ */
+declare function openSession(name: string, url: string, options?: {
+    cdpEndpoint?: string;
+}): Promise<{
+    id: string;
+    name: string;
+    url: string;
+    createdAt: string;
+}>;
+/**
+ * Close a browser session by name.
+ *
+ * @param name - The session name to close.
+ */
+declare function closeSession(name: string): Promise<void>;
+
+/**
+ * List all active sessions with their IDs and names.
+ *
+ * @returns Array of objects with `id` and `name` fields.
+ */
+declare function listSessions(): Promise<Array<{
+    id: string;
+    name: string;
+}>>;
+/**
+ * Get the Playwright Page for a named session.
+ *
+ * @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>;
+
+/**
+ * A built-in CLI command with help text and an execute function.
+ */
+interface BuiltinCommand {
+    name: string;
+    description: string;
+    aliases?: string[];
+    help: {
+        usage: string;
+        description: string;
+        options: {
+            name: string;
+            description: string;
+        }[];
+        examples?: {
+            cmd: string;
+            description: string;
+        }[];
+    };
+    execute: (args: string[], options: Record<string, unknown>, ctx: BuiltinContext) => Promise<void>;
+}
+/**
+ * Minimal execution context for built-in commands.
+ */
+interface BuiltinContext {
+    cwd: string;
+}
+
+/**
+ * All built-in CLI commands (session, config, plugin, create, preview).
+ */
+declare const allBuiltins: BuiltinCommand[];
+/**
+ * Find a built-in command by name or alias.
+ *
+ * @param name - The command name or alias to look up.
+ * @returns The matching built-in command, or `undefined` if not found.
+ */
+declare function getBuiltin(name: string): BuiltinCommand | undefined;
+
+/**
+ * Options for configuring the plugin loader's search directories.
+ */
+interface PluginLoaderOptions {
+    cwd?: string;
+    userDir?: string;
+    globalDir?: string;
+}
+/**
+ * Plugin loader for discovering and managing xbrowser plugins.
+ *
+ * Wraps the xcli-core PluginLoader and provides xbrowser-specific
+ * directory conventions for plugin discovery.
+ */
+declare class XBrowserPluginLoader {
+    private core;
+    private loader;
+    private options;
+    constructor(options?: PluginLoaderOptions);
+    getAPI(): XCLIAPI;
+    /**
+     * Get the core instance for external use.
+     * @returns The xcli-core Core instance.
+     */
+    getCore(): Core;
+    getPlugin(id: string): PluginInstance | undefined;
+    getPluginStatus(id: string): PluginStatus;
+    getLoadedPlugins(): PluginInstance[];
+    loadPlugin(pluginPath: string, id?: string): Promise<PluginInstance>;
+    unloadPlugin(id: string): Promise<void>;
+    reloadPlugin(id: string): Promise<PluginInstance>;
+    loadFromFunction(setup: (api: XCLIAPI) => void): Promise<void>;
+    scanAndLoad(): Promise<PluginInstance[]>;
+    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;
+    path: string;
+    source: 'local' | 'npm' | 'git' | 'url' | 'builtin' | 'marketplace';
+    installedAt: string;
+    metadata?: XBrowserPluginMetadata;
+    warnings?: string[];
+}
+interface InstallOptions {
+    name?: string;
+    force?: boolean;
+}
+
+/**
+ * Manages installation, uninstallation, and listing of plugins.
+ *
+ * Supports local paths, npm packages, git repositories, and URL sources.
+ */
+declare class PluginInstaller {
+    private pluginsDir;
+    constructor(pluginsDir?: string);
+    getPluginsDir(): string;
+    /**
+     * Install a plugin from a local path, npm package, git repository, or URL.
+     *
+     * @param source - The plugin source (local path, npm name, git URL, or HTTP URL).
+     * @param options - Install options including name override and force flag.
+     * @returns Information about the installed plugin.
+     * @throws If the plugin already exists without `force`, or if installation fails.
+     */
+    install(source: string, options?: InstallOptions): Promise<InstalledPlugin>;
+    installFromMarketplace(slug: string, options?: InstallOptions): Promise<InstalledPlugin>;
+    installWithMarketplaceFallback(source: string, options?: InstallOptions): Promise<InstalledPlugin>;
+    /**
+     * Uninstall a plugin by name.
+     *
+     * @param name - The plugin directory name to remove.
+     * @throws If the plugin is not installed.
+     */
+    uninstall(name: string): Promise<void>;
+    /**
+     * List all installed plugins with metadata.
+     *
+     * @returns Array of installed plugin information.
+     */
+    list(_options?: PluginListOptions): Promise<InstalledPlugin[]>;
+    private detectSourceType;
+    private deriveName;
+}
+
+/**
+ * A single recorded browser event (click, type, scroll, navigate, etc.).
+ */
+interface RecordedEvent {
+    id: string;
+    type: 'click' | 'type' | 'scroll' | 'navigate' | 'keypress' | 'page_load';
+    timestamp: number;
+    selector?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * A complete recording session with metadata and captured events.
+ */
+interface RecordingSession {
+    id: string;
+    name: string;
+    startUrl: string;
+    startTime: string;
+    duration: number;
+    events: RecordedEvent[];
+}
+/**
+ * Current status of an active recording.
+ */
+interface RecorderStatus {
+    isRecording: boolean;
+    eventCount: number;
+    duration: number;
+}
+/**
+ * Controller for recording browser interactions on a page.
+ *
+ * Injects a client-side recorder script that captures click, input,
+ * scroll, and keyboard events. The recording can be stopped and saved
+ * to a YAML file.
+ */
+declare class RecorderController {
+    private page;
+    private isRecordingFlag;
+    private events;
+    private startTime;
+    private startUrl;
+    private name;
+    constructor(page: Page);
+    /**
+     * Start recording browser interactions.
+     *
+     * Injects the recorder script into the page and optionally navigates
+     * to a starting URL.
+     *
+     * @param options - Recording options with optional starting URL and session name.
+     * @throws If a recording is already in progress.
+     */
+    start(options?: {
+        url?: string;
+        name?: string;
+    }): Promise<void>;
+    /**
+     * Stop the current recording and save it to a YAML file.
+     *
+     * Collects all captured events from the page, stops the recorder,
+     * and writes the session to disk.
+     *
+     * @param outputPath - Optional file path to save the recording. Defaults to `recordings/` directory.
+     * @returns An object with the output file path and the recording session data.
+     * @throws If no recording is in progress.
+     */
+    stop(outputPath?: string): Promise<{
+        path: string;
+        session: RecordingSession;
+    }>;
+    /**
+     * Get the current recording status.
+     *
+     * @returns The recorder status, or `null` if not recording.
+     */
+    getStatus(): RecorderStatus | null;
+    private getDefaultOutputPath;
+}
+
+interface ClickContextItem {
+    text: string;
+    tag?: string;
+    disabled?: boolean;
+    href?: string;
+}
+interface ClickContextElement {
+    tag: string;
+    selector?: string;
+    role?: string;
+    text: string;
+    rect?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    items: ClickContextItem[];
+}
+interface ClickContextStateChange {
+    tag: string;
+    text: string;
+    id?: string;
+    ariaExpanded?: string;
+    ariaSelected?: string;
+    disabled?: boolean;
+    dataState?: string;
+    changed?: boolean;
+}
+interface ClickContext {
+    appeared: ClickContextElement[];
+    disappeared: unknown[];
+    stateChanges: ClickContextStateChange[];
+}
+interface UserAction {
+    id: number;
+    type: 'click' | 'input' | 'change' | 'keydown' | 'submit' | 'scroll';
+    timestamp: number;
+    url: string;
+    pageTitle: string;
+    element?: {
+        tag: string;
+        selector?: string;
+        text: string;
+        role?: string;
+        type?: string;
+        placeholder?: string;
+        ariaLabel?: string;
+        href?: string;
+    };
+    value?: string;
+    key?: string;
+    x?: number;
+    y?: number;
+    scrollX?: number;
+    scrollY?: number;
+    /** Click context: popover/dropdown/menu items captured 200ms after click */
+    clickContext?: ClickContext;
+}
+interface NetworkEntry {
+    id: number;
+    timestamp: number;
+    method: string;
+    url: string;
+    path: string;
+    status: number;
+    resourceType: string;
+    contentType: string;
+    requestBody?: unknown;
+    responseBody?: unknown;
+    responseSize: number;
+}
+interface ContextChange {
+    id: number;
+    timestamp: number;
+    type: 'navigate' | 'new_tab' | 'tab_closed';
+    url?: string;
+    detail?: string;
+}
+interface ElementRef {
+    selector: string;
+    tag: string;
+    text: string;
+    role?: string;
+    type?: string;
+    placeholder?: string;
+    ariaLabel?: string;
+    href?: string;
+}
+interface RecordingStep {
+    step: number;
+    ref: string;
+    action: UserAction;
+    network: NetworkEntry[];
+    contextChanges: ContextChange[];
+    matchedInputs: Array<{
+        inputValue: string;
+        networkId: number;
+        paramName: string;
+    }>;
+}
+interface RecordingSummary {
+    startUrl: string;
+    recordedAt: string;
+    durationMs: number;
+    totalActions: number;
+    totalNetworkRequests: number;
+    steps: RecordingStep[];
+    elements: Record<string, ElementRef>;
+    checkpoints: CheckpointEntry[];
+}
+type CheckpointType = 'dialog' | 'captcha' | 'login' | 'iframe' | 'slider' | 'custom';
+interface CheckpointEntry {
+    id: number;
+    type: CheckpointType;
+    timestamp: number;
+    url: string;
+    pageTitle: string;
+    hint: string;
+    selector?: string;
+    source: 'auto' | 'manual';
+    relatedActionId?: number;
+    context?: Record<string, unknown>;
+}
+interface RecordingData {
+    startUrl: string;
+    sessionName: string;
+    startedAt: string;
+    actions: UserAction[];
+    network: NetworkEntry[];
+    contextChanges: ContextChange[];
+    checkpoints: CheckpointEntry[];
+}
+/** Written to disk so `record stop` (separate process) can signal the recorder. */
+interface RecordingControlFile {
+    pid: number;
+    startedAt: string;
+    startUrl: string;
+    sessionName: string;
+}
+declare class SessionRecorder {
+    private context;
+    private page;
+    private sessionName;
+    private startUrl;
+    private startedAt;
+    private actions;
+    private network;
+    private contextChanges;
+    private checkpoints;
+    private actionCounter;
+    private networkCounter;
+    private contextCounter;
+    private checkpointCounter;
+    private pollTimer;
+    private flushTimer;
+    private lastActionTs;
+    private activePages;
+    private _isRecording;
+    constructor(context: BrowserContext, page: Page, sessionName: string);
+    get isRecording(): boolean;
+    get actionCount(): number;
+    get networkCount(): number;
+    getLiveData(): RecordingData;
+    addManualCheckpoint(type: string, hint: string, selector?: string): CheckpointEntry;
+    /** Directory for this session's recordings. */
+    get recordingsDir(): string;
+    static getRecordingsDir(sessionName: string): string;
+    /** Path to the control file (used by record stop to signal this process). */
+    get controlFilePath(): string;
+    /** Path to the stop signal file (written by `record stop`). */
+    get stopSignalPath(): string;
+    start(url?: string): Promise<void>;
+    stop(): Promise<{
+        data: RecordingData;
+        summary: RecordingSummary;
+    }>;
+    static cleanup(sessionName: string): void;
+    waitForStopSignal(): Promise<void>;
+    static sendStopSignal(sessionName: string): Promise<RecordingControlFile | null>;
+    static readSummary(sessionName: string): RecordingSummary | null;
+    static readData(sessionName: string): RecordingData | null;
+    private injectActionScript;
+    private handleRequest;
+    private handleResponse;
+    private handleNewPage;
+    private handleFrameNavigated;
+    private handleDialog;
+    private pollActions;
+    private flushPendingActions;
+    /**
+     * After a click, wait 300ms then scan for popover/dropdown/menu elements
+     * near the click position. This runs server-side to avoid race conditions
+     * with the client-side poll interval.
+     */
+    private captureClickContext;
+    private detectCheckpoints;
+    private flushToDisk;
+    private writeFinalOutput;
+    private buildData;
+    private buildSummary;
+    private matchActionToNetwork;
+    private searchObjectForValue;
+    private buildMarkdownSummary;
+    static readMarkdownSummary(sessionName: string): string | null;
+}
+
+interface PlaybackOptions {
+    slowMo?: number;
+    stopOnError?: boolean;
+    onProgress?: (info: {
+        current: number;
+        total: number;
+        event: RecordedEvent;
+    }) => void;
+    onCheckpoint?: (checkpoint: {
+        type: string;
+        hint: string;
+        selector?: string;
+    }) => Promise<boolean>;
+}
+/**
+ * Result of playing back a recording session.
+ */
+interface PlaybackResult {
+    success: boolean;
+    duration: number;
+    eventsPlayed: number;
+    totalEvents: number;
+    errors: Array<{
+        eventIndex: number;
+        event: RecordedEvent;
+        error: string;
+    }>;
+}
+/**
+ * Engine for playing back a recorded browser session.
+ *
+ * Replays events (click, type, scroll, navigate, keypress) on a live
+ * Playwright page, respecting original timing with an optional slow-motion factor.
+ */
+declare class PlaybackEngine {
+    private page;
+    private recording;
+    private checkpoints;
+    constructor(page: Page, recording: RecordingSession);
+    /**
+     * Create a PlaybackEngine from a YAML recording file.
+     *
+     * @param page - The Playwright page to replay events on.
+     * @param filePath - Path to the YAML recording file.
+     * @returns A new PlaybackEngine instance.
+     */
+    static fromFile(page: Page, filePath: string): PlaybackEngine;
+    withCheckpoints(checkpoints: CheckpointEntry[]): PlaybackEngine;
+    play(options?: PlaybackOptions): Promise<PlaybackResult>;
+    private executeEvent;
+}
+
+interface DaemonInfo {
+    pid: number;
+    port: number;
+    startedAt: string;
+    cdpEndpoint?: string;
+}
+/**
+ * Start the daemon process. Spawns daemon-main.js as a detached child.
+ *
+ * Uses xcli-core's isDaemonRunning() for quick check, then getDaemonStatus()
+ * for detailed health polling after spawn.
+ *
+ * Does NOT use xcli-core's startDaemon() because that spawns with
+ * --import tsx, which requires tsx to be installed. xbrowser's
+ * daemon-main.js is compiled JS and loads without tsx.
+ */
+declare function startDaemonProcess(port?: number): Promise<DaemonInfo>;
+/**
+ * Stop the daemon process using xcli-core's stopDaemon().
+ */
+declare function stopDaemonProcess(): Promise<void>;
+/**
+ * Get daemon process status using xcli-core's isDaemonRunning() + getDaemonStatus().
+ */
+declare function getDaemonProcessStatus(): {
+    running: boolean;
+    pid: number;
+    port: number;
+    info: DaemonInfo | null;
+};
+
+/**
+ * Result of a CAPTCHA detection scan.
+ */
+interface CaptchaDetectionResult {
+    detected: boolean;
+    type?: string;
+    selector?: string;
+    confidence: 'high' | 'medium' | 'low';
+}
+/**
+ * Detect CAPTCHAs on the current page using selector-based rules and text patterns.
+ *
+ * Supports reCAPTCHA, hCaptcha, Cloudflare Turnstile, and generic CAPTCHAs.
+ */
+declare class CaptchaDetector {
+    /**
+     * Scan the page for visible CAPTCHA elements or challenge text.
+     *
+     * @param page - The Playwright page to scan.
+     * @returns Detection result with type, selector, and confidence level.
+     */
+    static detect(page: Page): Promise<CaptchaDetectionResult>;
+    /**
+     * Check whether a previously detected CAPTCHA has been solved.
+     *
+     * @param page - The Playwright page to check.
+     * @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>;
+}
+
+/**
+ * A single screencast frame with binary image data.
+ */
+interface ScreencastFrame {
+    id: string;
+    sessionId: string;
+    timestamp: number;
+    data: Buffer;
+    url: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Options for configuring screencast capture behavior.
+ */
+interface ScreencastOptions {
+    /** Target frame interval in ms (used as hint; CDP Cast delivers frames as fast as the page updates). Default: 100 (~10fps target) */
+    interval?: number;
+    /** JPEG quality 0-100. Default: 80 */
+    quality?: number;
+    /** Image format. Default: 'jpeg' */
+    type?: 'jpeg' | 'png';
+    /** Max capture width. Default: 1920 */
+    width?: number;
+    /** Max capture height. Default: 1080 */
+    height?: number;
+}
+/**
+ * Captures screenshots from a Playwright page using CDP `Page.startScreencast`.
+ *
+ * CDP Cast delivers frames as the page repaints — no polling needed.
+ * This gives 10-30+ fps depending on page activity, vs ~2 fps with the old
+ * `page.screenshot()` polling approach.
+ *
+ * Falls back to `page.screenshot()` polling if CDP session creation fails
+ * (e.g., non-Chromium browser or restricted CDP access).
+ */
+declare class ScreencastCapturer {
+    private interval;
+    private quality;
+    private type;
+    private maxWidth;
+    private maxHeight;
+    private isCapturing;
+    private frameCallback;
+    private cdpSession;
+    private sessionId;
+    private fallbackTimer;
+    constructor(options?: ScreencastOptions);
+    /**
+     * Start screencast capture using CDP Page.startScreencast.
+     *
+     * 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>;
+    /**
+     * Fallback: periodic page.screenshot() polling when CDP Cast is unavailable.
+     */
+    private startFallbackPolling;
+    /**
+     * Capture a single screenshot frame from the page (fallback mode).
+     */
+    private captureFrame;
+    /**
+     * Stop the current screencast capture.
+     */
+    stopCapture(): Promise<void>;
+    isActive(): boolean;
+    setInterval(interval: number): void;
+    setQuality(quality: number): void;
+}
+
+/**
+ * Payload sent to a webhook endpoint for lifecycle events.
+ */
+interface WebhookPayload {
+    event: 'captcha-detected' | 'captcha-resolved' | 'session-started' | 'session-ended';
+    timestamp: string;
+    sessionId?: string;
+    url?: string;
+    reason?: string;
+    previewUrl?: string;
+    targetUrl?: string;
+    timeout?: number;
+}
+/**
+ * Sends webhook notifications for browser automation lifecycle events.
+ *
+ * Reads the webhook URL from the constructor argument or the
+ * `XBROWSER_NOTIFY_URL` environment variable.
+ */
+declare class WebhookNotifier {
+    private url;
+    constructor(url?: string);
+    /**
+     * Send a webhook notification payload.
+     *
+     * @param payload - The event payload to send.
+     * @returns `true` if the request succeeded (HTTP 2xx), `false` otherwise.
+     */
+    notify(payload: WebhookPayload): Promise<boolean>;
+}
+
+interface CaptchaConfig {
+    notifyUrl: string | undefined;
+    autoOpen: boolean;
+    timeout: number;
+    previewPort: number;
+}
+declare function getCaptchaConfig(): CaptchaConfig;
+
 interface SearchResult extends AISearchResult {
     id: string;
     collectedAt: number;
@@ -132,10 +1660,6 @@ interface BatchCollectResult {
     duration: number;
 }
 
-declare const DEFAULT_STORAGE_CONFIG: StorageConfig;
-declare const DEFAULT_COLLECTOR_CONFIG: CollectorConfig;
-declare const PLATFORM_MAPPING: Record<string, string>;
-declare const EXCLUDED_DOMAINS: Set<string>;
 declare function getPlatformName(domain: string): string | undefined;
 declare function getCompanyType(domain: string): 'job-platform' | 'media' | 'gov' | 'ai-platform' | 'enterprise' | 'other';
 
@@ -228,4 +1752,501 @@ declare class DataCollector {
     getConfig(): CollectorConfig;
 }
 
-export { type AnalysisResult, type BatchCollectResult, type CollectResult, type CollectorConfig, type CompanyInfo, DEFAULT_COLLECTOR_CONFIG, DEFAULT_STORAGE_CONFIG, DataCollector, DataStorage, type DomainStat, EXCLUDED_DOMAINS, PLATFORM_MAPPING, ResultAnalyzer, type SearchResult, type StorageConfig, getCompanyType, getPlatformName };
+/**
+ * A parsed pipeline of commands with its chain type.
+ */
+interface ParsedPipeline {
+    pipeline: string[];
+    type: 'sequence' | 'and' | 'or';
+}
+interface ParseOptions {
+    fileMode?: boolean;
+}
+/**
+ * Parse a command chain string into ordered pipelines.
+ *
+ * Supports `&&` (and), `||` (or), `;` (sequence), `->`, `,`, and `+` operators.
+ * Respects quoted strings and parenthesized groups.
+ *
+ * @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;
+
+/**
+ * A single event in a browser recording.
+ */
+interface RecordingEvent {
+    type: string;
+    selector?: string;
+    tagName?: string;
+    data?: {
+        value?: string;
+        key?: string;
+        x?: number;
+        y?: number;
+    };
+    timestamp?: number;
+    pageState?: {
+        url?: string;
+        title?: string;
+    };
+}
+/**
+ * A browser recording session with a start URL and captured events.
+ */
+interface Recording {
+    startUrl: string;
+    events?: RecordingEvent[];
+    id?: string;
+    name?: string;
+    startTime?: string;
+    duration?: number;
+}
+
+/**
+ * Generate a Node.js replay script from a recording.
+ *
+ * @param recording - The recording session to convert.
+ * @returns A self-contained JavaScript script string.
+ */
+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.
+ */
+declare function generatePythonScript(recording: Recording): string;
+/**
+ * Generate a Bash replay script from a recording using CDP HTTP endpoints.
+ *
+ * @param recording - The recording session to convert.
+ * @returns A self-contained Bash script string.
+ */
+declare function generateBashScript(recording: Recording): string;
+
+interface ExtractSummary {
+    startUrl: string;
+    totalEvents: number;
+    keyEventsCount: number;
+    eventTypes: Record<string, number>;
+    operations: Array<{
+        step: number;
+        type: string;
+        selector?: string;
+        tagName?: string;
+        data?: RecordingEvent['data'];
+        url?: string;
+    }>;
+}
+/**
+ * Extract and summarize key events from a YAML recording file.
+ *
+ * @param filePath - Path to the YAML recording file.
+ * @returns A summary with start URL, event counts, type statistics, and key operations.
+ */
+declare function extractRecording(filePath: string): ExtractSummary;
+/**
+ * Extract a recording summary and save it as a JSON file alongside the original.
+ *
+ * @param filePath - Path to the YAML recording file.
+ * @returns An object with the summary and the output file path.
+ */
+declare function extractAndSave(filePath: string): {
+    summary: ExtractSummary;
+    outputPath: string;
+};
+/**
+ * Print a human-readable recording summary to stdout.
+ *
+ * @param summary - The extracted recording summary to display.
+ */
+declare function printExtractSummary(summary: ExtractSummary): void;
+
+/**
+ * Filter a recording file by removing events of specified types.
+ *
+ * Reads the YAML recording, removes events matching the exclude list,
+ * and writes the filtered result to the output path.
+ *
+ * @param inputPath - Path to the input YAML recording file.
+ * @param outputPath - Path to write the filtered recording.
+ * @param excludeTypes - Event types to remove. Defaults to a built-in list of noise events.
+ * @returns Statistics about original count, filtered count, and removal percentage.
+ */
+declare function filterRecording(inputPath: string, outputPath: string, excludeTypes?: string[]): {
+    originalCount: number;
+    filteredCount: number;
+    removed: number;
+    percentage: number;
+};
+/**
+ * Parse the `--exclude-types` flag from CLI arguments.
+ *
+ * @param args - CLI argument array.
+ * @returns Array of event type strings, or `undefined` if not specified.
+ */
+declare function parseExcludeTypes(args: string[]): string[] | undefined;
+
+interface APIRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string | undefined>;
+    body: unknown;
+    params: Record<string, string>;
+    query: Record<string, string>;
+}
+interface APIResponse {
+    statusCode: number;
+    body: unknown;
+    headers?: Record<string, string>;
+}
+interface ExecRequest {
+    command: string;
+    params?: Record<string, unknown>;
+    session?: string;
+}
+interface ChainRequest {
+    chain: string;
+    session?: string;
+    cdpEndpoint?: string;
+}
+interface HTTPServerError {
+    error: string;
+    message: string;
+    statusCode: number;
+}
+interface HTTPServerConfig {
+    port?: number;
+    host?: string;
+    tokens?: string[];
+}
+
+/**
+ * HTTP server exposing the xbrowser REST API for remote command execution.
+ *
+ * Provides endpoints for health checks, session management, single command
+ * execution, and command chain execution. Supports optional Bearer token
+ * authentication via config or environment variable.
+ */
+declare class HTTPServer {
+    private port;
+    private host;
+    private server;
+    private validTokens;
+    constructor(config?: HTTPServerConfig);
+    /**
+     * Start the HTTP server and begin listening for requests.
+     *
+     * @returns The actual port and host the server bound to.
+     * @throws If the server is already running or fails to start.
+     */
+    start(): Promise<{
+        port: number;
+        host: string;
+    }>;
+    /**
+     * Stop the HTTP server gracefully.
+     *
+     * Closes all active connections and stops accepting new ones.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the address the server is bound to.
+     *
+     * @returns The port and host, or `null` if the server is not running.
+     */
+    getAddress(): {
+        port: number;
+        host: string;
+    } | null;
+}
+
+/**
+ * CDP Interceptor Proxy
+ *
+ * A thin WebSocket proxy that sits between any automation tool (Playwright,
+ * Puppeteer, etc.) and Chromium's CDP endpoint. Every JSON-RPC message is
+ * intercepted, analyzed against a rule engine, and either passed through,
+ * blocked (with error response), or transformed before reaching the browser.
+ *
+ * Usage:
+ * ```
+ * const proxy = new CDPInterceptorProxy({ cdpEndpoint: 'ws://localhost:9222/...' });
+ * await proxy.start(); // starts listening on a random port
+ * // Now connect your automation tool to: ws://localhost:{proxy.port}
+ * ```
+ */
+
+declare class CDPInterceptorProxy {
+    private wss;
+    private engine;
+    private config;
+    private logger;
+    private started;
+    stats: CDPInterceptorStats;
+    constructor(config: CDPInterceptorConfig);
+    /** The port the proxy is listening on (only valid after start()) */
+    get port(): number;
+    /** Start the proxy server */
+    start(): Promise<number>;
+    /** Stop the proxy server */
+    stop(): Promise<void>;
+    /** Get accumulated statistics */
+    getStats(): CDPInterceptorStats;
+    /** Get recent log entries (for inspection) */
+    getRecentLogs(count?: number): CDPLogEntry[];
+    private handleConnection;
+    private handleClientMessage;
+    private handleBrowserMessage;
+    private parseMessage;
+    private recordDecision;
+}
+
+/**
+ * CDP Interceptor — Rule Engine
+ *
+ * Evaluates messages against a prioritized list of interception rules.
+ * Rules that need per-session state can store data in sessionState.
+ *
+ * Total built-in patterns: ~200+ across 9 rule modules.
+ */
+
+interface RuleEngine {
+    start(): void;
+    stop(): void;
+    evaluate(ctx: Omit<RuleContext, 'sessionState'>): DecisionResult | null;
+}
+declare function createRuleEngine(customRules?: CDPInterceptorRule[]): RuleEngine;
+
+/**
+ * Rule: DOM Property Mutation — Comprehensive Edition
+ *
+ * Detects ALL direct DOM property setters via Runtime.evaluate / Runtime.callFunctionOn.
+ * Each pattern bypasses framework reactivity (React setter, Vue proxy, Angular zone.js).
+ *
+ * Severity tiers:
+ *   danger  → hard block (100% automation signal)
+ *   warn    → soft block (likely automation, some legitimate uses)
+ *   info    → log only (could be context-dependent)
+ */
+
+declare const domMutationRule: CDPInterceptorRule;
+
+/**
+ * Rule: Mouse Trajectory Analysis
+ *
+ * Detects automated mouse interactions by analyzing mouse movement patterns.
+ * Natural human mouse movements exhibit acceleration curves, jitter, and
+ * non-linear paths. Automated movements are often perfect straight lines
+ * with constant speed.
+ *
+ * Detection heuristics:
+ *   1. **Collinearity**: Path from A→B lies on a near-perfect straight line
+ *      (very low residuals from linear regression)
+ *   2. **Constant velocity**: Speed between consecutive move events is too uniform
+ *   3. **No jitter**: Human hands have micro-tremors (1-3px variation)
+ *
+ * Stateful: tracks mouse positions per CDP session to analyze trajectories.
+ */
+
+declare const mouseTrajectoryRule: CDPInterceptorRule;
+
+/**
+ * Rule: Input Keystroke Timing Analysis
+ *
+ * Analyzes `Input.dispatchKeyEvent` sequences for patterns that betray
+ * automation:
+ *
+ * 1. **Constant inter-key timing**: natural typing has 30-200ms variation;
+ *    automation tools like `page.type(..., {delay: 50})` produce exact 50ms
+ *    intervals with zero variance.
+ *
+ * 2. **Input.insertText**: bypasses native keyboard events entirely.
+ *    Real users always dispatch keyDown → keyPress → input → keyUp.
+ *    `Input.insertText` skips all of these and is a strong automation signal.
+ *
+ * 3. **Unnatural key order**: typing characters one-by-one without variation
+ *    in hold time (keyDown → keyUp interval).
+ */
+
+declare const inputKeystrokeRule: CDPInterceptorRule;
+
+/**
+ * Rule: Browser Automation Signals
+ *
+ * Detects telltale markers left in the page context by browser automation
+ * tools (Playwright, Puppeteer, Selenium, WebDriver). These markers are
+ * the #1 thing anti-crawler systems check for.
+ *
+ * Detection categories:
+ *   1. Tool-specific global objects (window.__playwright, etc.)
+ *   2. navigator.webdriver flag checks
+ *   3. Chrome headless API surface detection
+ *   4. Anti-detection script injection attempts (already too late)
+ *
+ * Both Runtime.evaluate and Page.addScriptToEvaluateOnNewDocument are checked.
+ */
+
+declare const automationSignalsRule: CDPInterceptorRule;
+
+/**
+ * Rule: Browser Fingerprinting Access Detection
+ *
+ * Blocks access to known browser fingerprinting APIs via Runtime.evaluate.
+ * Anti-crawler systems use these APIs to build a unique device fingerprint
+ * and detect headless/automated browsers.
+ *
+ * Instead of blocking these calls (which would break the page), we:
+ *   - Log the access (info)
+ *   - Warn the developer (warn)
+ *   - Suggest alternatives
+ *
+ * The goal is to make the developer aware that their code is triggering
+ * fingerprinting APIs, which means the target site can identify them.
+ *
+ * Severity reflects how diagnostic the API is (not how dangerous the call is):
+ *   - canvas.toDataURL() → danger (fingerprint hash, highly diagnostic)
+ *   - AudioContext → warn (common fingerprint method)
+ *   - platform info → info (less diagnostic alone)
+ */
+
+declare const fingerprintingRule: CDPInterceptorRule;
+
+/**
+ * Rule: Event Simulation Detection
+ *
+ * Detects CDP calls that simulate user interaction events via
+ * evaluate/callFunctionOn, bypassing the browser's trusted event system.
+ *
+ * Key distinction:
+ *   - Input.dispatchMouseEvent / Input.dispatchKeyEvent → isTrusted=true ✓
+ *   - element.click() / element.dispatchEvent(new Event(...)) → isTrusted=false ✗
+ *
+ * Any event with isTrusted=false is immediately detectable by anti-crawler
+ * systems that check the event's isTrusted property.
+ *
+ * This rule covers:
+ *   1. Direct method calls (el.click(), el.focus(), el.submit(), etc.)
+ *   2. dispatchEvent with synthetic event objects
+ *   3. Dialog/modal/fullscreen programmatic triggers
+ */
+
+declare const eventSimulationRule: CDPInterceptorRule;
+
+/**
+ * Rule: CDP Emulation / Override Detection
+ *
+ * Detects calls to CDP methods that override browser behavior in ways that
+ * can be detected by anti-crawler systems. Each override creates an
+ * inconsistency between the JS environment and the real browser state.
+ *
+ * Examples:
+ *   - Emulation.setUserAgentOverride → navigator.userAgent vs HTTP headers mismatch
+ *   - Emulation.setDeviceMetricsOverride → matchMedia vs actual viewport mismatch
+ *   - Emulation.setGeolocationOverride → geo suddenly changes mid-session
+ *   - Network.setExtraHTTPHeaders → header conflicts with JS environment
+ */
+
+declare const emulationOverrideRule: CDPInterceptorRule;
+
+/**
+ * Rule: Network Request Anomaly Detection
+ *
+ * Detects network request patterns that betray automation at the
+ * CDP protocol level. While most network analysis requires a proxy,
+ * certain CDP methods and timing patterns are visible at the CDP layer.
+ *
+ * Detection patterns:
+ *   1. Network.setExtraHTTPHeaders with suspicious headers
+ *   2. Network.setUserAgentOverride (also caught by emulation-override)
+ *   3. Requests too fast after navigation (via PageLifecycle state)
+ *   4. Network.clearBrowserCache (automation optimization giveaway)
+ *   5. Network.enable called at suspicious times
+ */
+
+declare const networkAnomalyRule: CDPInterceptorRule;
+
+/**
+ * Rule: Page Lifecycle Anomaly Detection
+ *
+ * Detects unnatural page interaction sequences that betray automation:
+ *   1. Rapid navigation → screenshot → close (content extraction pattern)
+ *   2. Page.printToPDF (scraper intent giveaway)
+ *   3. Zero mouse/scroll events across full session
+ *   4. Multiple navigations without waiting for load
+ *   5. Tab/window operations without user action
+ *
+ * Stateful: tracks page-level metrics per CDP session.
+ */
+
+declare const pageLifecycleRule: CDPInterceptorRule;
+
+/**
+ * CDP Interceptor — Advisor
+ *
+ * Generates actionable suggestions when rules flag a message.
+ * Designed to be LLM-friendly: any AI agent reading the error
+ * should know exactly what to do instead.
+ */
+
+interface AdvisoryResult {
+    ruleId: string;
+    title: string;
+    detail: string;
+    codeExample?: string;
+}
+/**
+ * Generate an advisory message from a rule decision.
+ */
+declare function advise(decision: DecisionResult, originalMethod: string): AdvisoryResult;
+
+/** 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 };