@xbrowser/cli 1.0.0 → 1.0.3

package/dist/{extract-JUOQQX4V.js → extract-2ZFW2MX7.js}

@@ -3,7 +3,7 @@ import {
   extractRecording,
   printExtractSummary
 } from "./chunk-L53IDAWK.js";
-import "./chunk-3RG5ZIWI.js";
+import "./chunk-KFQGP6VL.js";
 export {
   extractAndSave,
   extractRecording,

package/dist/{extract-L2IW3IUB.js → extract-BSYBM4MR.js}

@@ -1,4 +1,4 @@
-import "./chunk-3RG5ZIWI.js";
+import "./chunk-KFQGP6VL.js";
 
 // src/commands/extract.ts
 import * as fs from "fs";

package/dist/{filter-HC4RA7JY.js → filter-KCFO4RSV.js}

@@ -1,4 +1,4 @@
-import "./chunk-3RG5ZIWI.js";
+import "./chunk-KFQGP6VL.js";
 
 // src/commands/filter.ts
 import * as fs from "fs";

package/dist/{filter-VID2GGZ7.js → filter-T7DSZ2X7.js}

@@ -2,7 +2,7 @@ import {
   filterRecording,
   parseExcludeTypes
 } from "./chunk-OPRXFZVE.js";
-import "./chunk-3RG5ZIWI.js";
+import "./chunk-KFQGP6VL.js";
 export {
   filterRecording,
   parseExcludeTypes

package/dist/{human-interaction-W753RVJB.js → human-interaction-UKAS5ZXV.js}

@@ -1,7 +1,7 @@
 import {
   HumanInteractionManager
-} from "./chunk-ITKPSIP7.js";
-import "./chunk-3RG5ZIWI.js";
+} from "./chunk-MDAPTB7C.js";
+import "./chunk-KFQGP6VL.js";
 export {
   HumanInteractionManager
 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
+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 { CommandContext, CommandScope, XCLIAPI, Core, PluginInstance, PluginStatus } from '@dyyz1993/xcli-core';
-export { PluginStatus } from '@dyyz1993/xcli-core';
 import { ZodType, ZodTypeDef, z } from 'zod';
 
 declare const version: any;
@@ -19,6 +19,14 @@ interface XBBrowser {
     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;
 }
@@ -173,6 +181,10 @@ interface XBPage {
     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>;
@@ -455,6 +467,9 @@ type WSMessage = {
     success: boolean;
     fileName: string;
     error?: string;
+} | {
+    type: 'file_input_clicked';
+    selector: string;
 } | {
     type: 'file_list_result';
     path: string;
@@ -471,6 +486,9 @@ type WSMessage = {
     mimeType: string;
     data: string;
     error?: string;
+} | {
+    type: 'views_update';
+    views: ViewInfo[];
 } | {
     type: 'error';
     data: {
@@ -479,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.
  */
@@ -537,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.
@@ -587,28 +625,22 @@ 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.
-     */
+    private setupSessionManagerEvents;
     registerSession(sessionId: string, page: XBPage, options?: {
         interval?: number;
         quality?: number;
@@ -616,42 +648,23 @@ declare class WSServer extends EventEmitter {
         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;
@@ -670,7 +683,7 @@ interface ExecutionResult {
     data: unknown;
     message?: string;
     duration: number;
-    tips?: string[];
+    tips?: Tip[];
     hookOutputs?: HookOutput[];
 }
 /**
@@ -683,7 +696,7 @@ interface ChainStepResult {
     data: unknown;
     message?: string;
     duration: number;
-    tips?: string[];
+    tips?: Tip[];
     hookOutputs?: HookOutput[];
 }
 /**
@@ -1256,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.
  *
@@ -1636,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;
@@ -1644,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;
@@ -1658,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;
@@ -1758,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: 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;
@@ -1788,6 +1884,7 @@ declare class SessionRecorder {
     private handleNewPage;
     private handleFrameNavigated;
     private handleDialog;
+    private handleFileChooser;
     private pollActions;
     private flushPendingActions;
     /**
@@ -1831,7 +1928,7 @@ interface PlaybackResult {
     totalEvents: number;
     errors: Array<{
         eventIndex: number;
-        event: RecordedEvent;
+        event?: RecordedEvent;
         error: string;
     }>;
 }
@@ -2230,49 +2327,8 @@ 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;
 
@@ -2399,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;
 /**
@@ -2789,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 AgentActionInput, type AgentActionResult, type AgentObservation, type AgentTarget, type AgentWaitInput, type AgentWaitResult, type AnalysisResult, BROWSER_SCOPE, type BatchCollectResult, type BrowserCommandContext, type BrowserCommandDefinition, type BrowserLaunchOptions, type BuiltinCommand, type BuiltinContext, type CDPError, type CDPInterceptorConfig, CDPInterceptorProxy, type CDPInterceptorRule, type CDPInterceptorStats, type CDPLogEntry, type CDPMessage, type CDPRequest, type CDPResponse, type CaptchaDetectionResult, CaptchaDetector, type ChainExecutionResult, type ChainRequest, type ChainStepResult, type CollectResult, type CollectorConfig, type CommandMessage, type CompanyInfo, type ContextChange, type DaemonInfo, DataCollector, DataStorage, type DecisionAction, type DecisionResult, type DomainStat, type ElementRef, type ExecRequest, type ExecutionResult, HTTPServer, type HTTPServerConfig, type HTTPServerError, HumanInteractionManager, type InstallOptions, type InstalledPlugin, type ManagedSession, type MessageDirection, type NetworkEntry, type ParsedPipeline, PlaybackEngine, type PlaybackOptions, type PlaybackResult, PluginInstaller, type PluginLoaderOptions, type RecordedEvent, RecorderController, type RecorderStatus, type Recording, type RecordingControlFile, type RecordingData, type RecordingEvent, type RecordingSession, type RecordingStep, type RecordingSummary, type RegisteredCommand, ResultAnalyzer, type RuleContext, type RuleEngine, type ScopeDefinition, type ScopeLevel, ScreencastCapturer, type ScreencastFrame, type ScreencastMessage, type ScreencastOptions, type SearchResult, type ManagedSession as SessionInfo, SessionRecorder, type StatusMessage, type StorageConfig, type UserAction, type ViolationSeverity, type WSInboundMessage, type WSMessage, WSServer, type WSServerConfig, type WaitForHumanOptions, type WaitForHumanResult, WebhookNotifier, type WebhookPayload, XBrowserPluginLoader, actOnPage, advise, allBuiltins, assertPageScope, attachWaitForHuman, automationSignalsRule, checkBrowserScope, routeCommand as cliRoute, closeAllSessions as closeAllBrowserSessions, closeAllSessions, closeSession, closeSessionByName, createCDPInterceptor, createRuleEngine, createSession, destroyBrowser, destroyBrowser as destroySessionManager, domMutationRule, emulationOverrideRule, eventSimulationRule, executeChain, executeCommand, extractAndSave, extractRecording, filterRecording, findSession, findSession as findSessionInfo, fingerprintingRule, generateBashScript, generateJSScript, generatePythonScript, getAllSessions as getAllBrowserSessions, getAllCommands, getBrowser, getBuiltin, getCaptchaConfig, getCommand, getCommandNames, getCompanyType, getDaemonProcessStatus, getPageScreenHash, getPlatformName, getSessionPage, getWSServerFromCache, inputKeystrokeRule, isChainInput, getAllSessions as listAllBrowserSessions, listSessions, mouseTrajectoryRule, networkAnomalyRule, normalizeSelector, observePage, openSession, pageLifecycleRule, parseCommandArgs, parseCommandChain, parseExcludeTypes, printExtractSummary, readCommandFile, readStdin, registerCommand, registerCommandDefinition, resetForTesting, setWSServer, setWSServerCache, splitCommand, startDaemonProcess, stopDaemonProcess, version, waitForPage };
+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 };