sessioncast-cli 2.3.0 → 2.3.1

package/dist/agent/browser-handler.d.ts

@@ -0,0 +1,100 @@
+export interface BrowserStartOptions {
+    url?: string;
+    width?: number;
+    height?: number;
+    chromePath?: string;
+}
+export interface DomEvent {
+    type: number;
+    data: any;
+    timestamp: number;
+}
+type DomEventCallback = (event: DomEvent) => void;
+/**
+ * Manages a headless Chrome instance with rrweb-based DOM recording.
+ * Spawns Chrome with --headless=new, connects via CDP, injects rrweb,
+ * and streams DOM mutation events through a callback.
+ */
+export declare class BrowserHandler {
+    private chrome;
+    private cdp;
+    private domCallback;
+    private eventBuffer;
+    private running;
+    /**
+     * Launch headless Chrome and connect CDP.
+     * @param port  Remote debugging port for Chrome
+     * @param opts  Optional browser configuration
+     */
+    start(port: number, opts?: BrowserStartOptions): Promise<void>;
+    /**
+     * Register a callback for rrweb DOM events.
+     * Flushes any events buffered before the callback was registered.
+     */
+    onDomEvent(cb: DomEventCallback): void;
+    /**
+     * Dispatch an input event to the page via CDP.
+     * Accepts WebInputEvent from the web client (inputType field).
+     */
+    dispatchInput(event: {
+        inputType?: string;
+        type?: string;
+        x?: number;
+        y?: number;
+        button?: string;
+        clickCount?: number;
+        key?: string;
+        code?: string;
+        text?: string;
+        modifiers?: number;
+        deltaX?: number;
+        deltaY?: number;
+    }): Promise<void>;
+    /**
+     * Trigger rrweb to emit a fresh FullSnapshot by restarting the recording.
+     * Stops the current recording and starts a new one, which immediately
+     * produces a FullSnapshot of the current DOM state.
+     */
+    takeFullSnapshot(): Promise<void>;
+    /**
+     * Navigate the browser to a new URL.
+     * Only localhost/127.0.0.1 URLs are allowed for security.
+     */
+    navigate(url: string): Promise<void>;
+    /**
+     * Stop Chrome and close the CDP connection.
+     */
+    stop(): void;
+    /**
+     * Check whether the browser is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Wait for Chrome to output the DevTools WebSocket URL on stderr.
+     * Falls back to querying the /json/version endpoint.
+     */
+    private waitForDebugUrl;
+    /**
+     * Fetch the DevTools WebSocket URL via the /json/version HTTP endpoint.
+     * Returns the browser-level WebSocket URL.
+     */
+    private fetchDebugUrl;
+    /**
+     * Find the page-level WebSocket target via /json endpoint.
+     * Page targets support Page.enable, Runtime.evaluate, etc.
+     * The browser-level target only supports browser-wide commands.
+     */
+    private findPageTarget;
+    /**
+     * Build the rrweb injection script source.
+     * Used by both addScriptToEvaluateOnNewDocument and Runtime.evaluate.
+     */
+    private getRrwebInjectionScript;
+    /**
+     * Inject rrweb recording script into the current page.
+     * The script loads rrweb from CDN, then starts recording,
+     * emitting events through the __sessioncast_emit CDP binding.
+     */
+    private injectRrweb;
+}
+export {};

package/dist/agent/browser-handler.js

@@ -0,0 +1,485 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserHandler = void 0;
+const child_process_1 = require("child_process");
+const chrome_finder_1 = require("./chrome-finder");
+const cdp_client_1 = require("./cdp-client");
+const debug_1 = require("./debug");
+// rrweb CDN — v1.x reliably exposes global `rrweb.record` via <script> tag.
+// The v2 Replayer (used in the web client) is backward-compatible with v1 events.
+const RRWEB_CDN = 'https://cdn.jsdelivr.net/npm/rrweb@1.1.3/dist/rrweb.min.js';
+/**
+ * Manages a headless Chrome instance with rrweb-based DOM recording.
+ * Spawns Chrome with --headless=new, connects via CDP, injects rrweb,
+ * and streams DOM mutation events through a callback.
+ */
+class BrowserHandler {
+    constructor() {
+        this.chrome = null;
+        this.cdp = null;
+        this.domCallback = null;
+        this.eventBuffer = [];
+        this.running = false;
+    }
+    /**
+     * Launch headless Chrome and connect CDP.
+     * @param port  Remote debugging port for Chrome
+     * @param opts  Optional browser configuration
+     */
+    async start(port, opts = {}) {
+        const chromePath = opts.chromePath || (0, chrome_finder_1.findChromePath)();
+        if (!chromePath) {
+            throw new Error('Chrome/Chromium not found. Install Chrome or pass chromePath in options.');
+        }
+        const width = opts.width || 1280;
+        const height = opts.height || 720;
+        const url = opts.url || 'about:blank';
+        const args = [
+            '--headless=new',
+            `--remote-debugging-port=${port}`,
+            `--window-size=${width},${height}`,
+            '--disable-gpu',
+            '--no-first-run',
+            '--no-default-browser-check',
+            '--disable-extensions',
+            '--disable-background-networking',
+            '--disable-sync',
+            '--disable-translate',
+            '--mute-audio',
+            url,
+        ];
+        (0, debug_1.debugLog)('Browser', 'Launching', chromePath, args.join(' '));
+        this.chrome = (0, child_process_1.spawn)(chromePath, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        // Wait for Chrome to be ready, then find the page-level WebSocket target.
+        // We must connect to a page target (not the browser target) for Page.enable to work.
+        await this.waitForDebugUrl(port);
+        const pageUrl = await this.findPageTarget(port);
+        (0, debug_1.debugLog)('Browser', 'Page DevTools URL:', pageUrl);
+        // Connect CDP to the page target
+        this.cdp = new cdp_client_1.CdpClient();
+        await this.cdp.connect(pageUrl);
+        this.running = true;
+        // Enable required CDP domains
+        await this.cdp.send('Page.enable');
+        await this.cdp.send('Runtime.enable');
+        // Set up the binding that rrweb will call to emit events
+        await this.cdp.send('Runtime.addBinding', {
+            name: '__sessioncast_emit',
+        });
+        // Listen for the binding call — buffer events if callback isn't registered yet
+        this.cdp.on('Runtime.bindingCalled', (params) => {
+            if (params.name === '__sessioncast_emit') {
+                try {
+                    const event = JSON.parse(params.payload);
+                    if (this.domCallback) {
+                        this.domCallback(event);
+                    }
+                    else {
+                        this.eventBuffer.push(event);
+                    }
+                }
+                catch (e) {
+                    (0, debug_1.debugLog)('Browser', 'Failed to parse DOM event:', e.message);
+                }
+            }
+        });
+        // Detect page navigation → take fresh FullSnapshot for viewers.
+        // addScriptToEvaluateOnNewDocument handles rrweb re-injection,
+        // but binding-based event delivery is unreliable after navigation.
+        // This handler uses the direct-capture approach instead.
+        let navTimer = null;
+        this.cdp.on('Page.frameNavigated', (params) => {
+            if (params.frame?.parentId)
+                return; // skip iframes
+            (0, debug_1.debugLog)('Browser', 'Navigation detected:', params.frame?.url);
+            if (navTimer)
+                clearTimeout(navTimer);
+            navTimer = setTimeout(async () => {
+                if (!this.cdp || !this.running)
+                    return;
+                try {
+                    // Re-add binding for the new execution context
+                    try {
+                        await this.cdp.send('Runtime.addBinding', { name: '__sessioncast_emit' });
+                    }
+                    catch { /* binding may already exist */ }
+                    // Wait for document to be ready
+                    await this.cdp.send('Runtime.evaluate', {
+                        expression: `new Promise(function(resolve) {
+              if (document.readyState !== 'loading') resolve();
+              else document.addEventListener('DOMContentLoaded', resolve);
+            })`,
+                        awaitPromise: true,
+                    });
+                    // addScriptToEvaluateOnNewDocument may have set the flag but failed
+                    // to load rrweb CDN. Reset and manually inject.
+                    await this.cdp.send('Runtime.evaluate', {
+                        expression: 'window.__sessioncast_recording = false;',
+                    });
+                    await this.injectRrweb();
+                    if (!this.running)
+                        return;
+                    await this.takeFullSnapshot();
+                }
+                catch (e) {
+                    (0, debug_1.debugLog)('Browser', 'Post-navigation handler failed:', e.message);
+                }
+            }, 500);
+        });
+        // Use addScriptToEvaluateOnNewDocument so rrweb is injected
+        // on every navigation (including the initial load) automatically.
+        // This is more reliable than listening for frameNavigated.
+        await this.cdp.send('Page.addScriptToEvaluateOnNewDocument', {
+            source: this.getRrwebInjectionScript(),
+        });
+        // Also inject into the current page immediately (for already-loaded pages)
+        await this.injectRrweb();
+        // Handle Chrome exit
+        this.chrome.on('exit', (code) => {
+            (0, debug_1.debugLog)('Browser', 'Chrome exited with code', code);
+            this.running = false;
+        });
+    }
+    /**
+     * Register a callback for rrweb DOM events.
+     * Flushes any events buffered before the callback was registered.
+     */
+    onDomEvent(cb) {
+        this.domCallback = cb;
+        // Flush buffered events (e.g. FullSnapshot emitted during start())
+        if (this.eventBuffer.length > 0) {
+            const buffered = this.eventBuffer;
+            this.eventBuffer = [];
+            for (const event of buffered) {
+                cb(event);
+            }
+        }
+    }
+    /**
+     * Dispatch an input event to the page via CDP.
+     * Accepts WebInputEvent from the web client (inputType field).
+     */
+    async dispatchInput(event) {
+        if (!this.cdp || !this.running)
+            return;
+        // Support both 'inputType' (from web client) and 'type' (legacy)
+        const inputType = event.inputType || event.type || '';
+        if (inputType === 'mousePressed' || inputType === 'mouseReleased' || inputType === 'mouseMoved') {
+            // CDP expects button: 'none' for mouseMoved, 'left'/'right'/'middle' for press/release
+            const button = inputType === 'mouseMoved' ? 'none' : (event.button || 'left');
+            await this.cdp.send('Input.dispatchMouseEvent', {
+                type: inputType,
+                x: event.x || 0,
+                y: event.y || 0,
+                button,
+                clickCount: event.clickCount || (inputType === 'mousePressed' ? 1 : 0),
+                modifiers: event.modifiers || 0,
+            });
+        }
+        else if (inputType === 'mouseWheel') {
+            await this.cdp.send('Input.dispatchMouseEvent', {
+                type: 'mouseWheel',
+                x: event.x || 0,
+                y: event.y || 0,
+                deltaX: event.deltaX || 0,
+                deltaY: event.deltaY || 0,
+                modifiers: event.modifiers || 0,
+            });
+        }
+        else if (inputType === 'keyDown' || inputType === 'keyUp') {
+            await this.cdp.send('Input.dispatchKeyEvent', {
+                type: inputType,
+                key: event.key || '',
+                code: event.code || '',
+                text: event.text || (inputType === 'keyDown' && event.key?.length === 1 ? event.key : ''),
+                modifiers: event.modifiers || 0,
+            });
+        }
+    }
+    /**
+     * Trigger rrweb to emit a fresh FullSnapshot by restarting the recording.
+     * Stops the current recording and starts a new one, which immediately
+     * produces a FullSnapshot of the current DOM state.
+     */
+    async takeFullSnapshot() {
+        if (!this.cdp || !this.running)
+            return;
+        try {
+            // Stop existing recording, restart, and collect the FullSnapshot
+            // all within Chrome's JS context, then return the snapshot data.
+            const result = await this.cdp.send('Runtime.evaluate', {
+                expression: `
+          (function() {
+            // Stop existing recording
+            if (window.__sessioncast_stopFn) {
+              window.__sessioncast_stopFn();
+              window.__sessioncast_stopFn = null;
+            }
+            // Capture the FullSnapshot synchronously
+            var captured = null;
+            if (typeof rrweb !== 'undefined' && rrweb.record) {
+              window.__sessioncast_stopFn = rrweb.record({
+                emit: function(event) {
+                  if (event.type === 2 && !captured) {
+                    captured = JSON.stringify(event);
+                  }
+                  try { __sessioncast_emit(JSON.stringify(event)); } catch(e) {}
+                },
+                sampling: {
+                  mousemove: 50,
+                  mouseInteraction: true,
+                  scroll: 150,
+                  input: 'last',
+                },
+              });
+            }
+            return captured || '';
+          })();
+        `,
+                returnByValue: true,
+            });
+            const snapshotJson = result?.result?.value;
+            if (snapshotJson && snapshotJson.length > 0) {
+                (0, debug_1.debugLog)('Browser', 'takeFullSnapshot: captured', snapshotJson.length, 'bytes, emitting via binding');
+                // The binding call inside evaluate might be queued —
+                // also emit directly from Node.js side as fallback
+                if (this.domCallback) {
+                    try {
+                        const event = JSON.parse(snapshotJson);
+                        this.domCallback(event);
+                    }
+                    catch (e) {
+                        (0, debug_1.debugLog)('Browser', 'takeFullSnapshot: parse error', e.message);
+                    }
+                }
+            }
+            else {
+                (0, debug_1.debugLog)('Browser', 'takeFullSnapshot: no snapshot captured (rrweb may not be loaded)');
+            }
+        }
+        catch (e) {
+            (0, debug_1.debugLog)('Browser', 'takeFullSnapshot failed:', e.message);
+        }
+    }
+    /**
+     * Navigate the browser to a new URL.
+     * Only localhost/127.0.0.1 URLs are allowed for security.
+     */
+    async navigate(url) {
+        if (!this.cdp || !this.running) {
+            throw new Error('Browser is not running');
+        }
+        // Security: only allow localhost navigation
+        try {
+            const parsed = new URL(url);
+            if (parsed.hostname !== 'localhost' && parsed.hostname !== '127.0.0.1') {
+                throw new Error(`Navigation blocked: only localhost URLs are allowed (got ${parsed.hostname})`);
+            }
+        }
+        catch (e) {
+            if (e.message.includes('Navigation blocked'))
+                throw e;
+            throw new Error(`Invalid URL: ${url}`);
+        }
+        (0, debug_1.debugLog)('Browser', 'Navigating to', url);
+        await this.cdp.send('Page.navigate', { url });
+    }
+    /**
+     * Stop Chrome and close the CDP connection.
+     */
+    stop() {
+        this.running = false;
+        if (this.cdp) {
+            this.cdp.close();
+            this.cdp = null;
+        }
+        if (this.chrome) {
+            this.chrome.kill('SIGTERM');
+            this.chrome = null;
+        }
+        this.domCallback = null;
+        (0, debug_1.debugLog)('Browser', 'Stopped');
+    }
+    /**
+     * Check whether the browser is currently running.
+     */
+    isRunning() {
+        return this.running;
+    }
+    // -- Private methods --
+    /**
+     * Wait for Chrome to output the DevTools WebSocket URL on stderr.
+     * Falls back to querying the /json/version endpoint.
+     */
+    waitForDebugUrl(port) {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                // Fallback: query the HTTP endpoint
+                this.fetchDebugUrl(port).then(resolve).catch(reject);
+            }, 5000);
+            if (!this.chrome?.stderr) {
+                clearTimeout(timeout);
+                // No stderr available, try HTTP fallback directly
+                setTimeout(() => {
+                    this.fetchDebugUrl(port).then(resolve).catch(reject);
+                }, 1000);
+                return;
+            }
+            let buffer = '';
+            const onData = (data) => {
+                buffer += data.toString();
+                // Chrome outputs: DevTools listening on ws://127.0.0.1:PORT/devtools/browser/UUID
+                const match = buffer.match(/DevTools listening on (ws:\/\/[^\s]+)/);
+                if (match) {
+                    clearTimeout(timeout);
+                    this.chrome?.stderr?.removeListener('data', onData);
+                    resolve(match[1]);
+                }
+            };
+            this.chrome.stderr.on('data', onData);
+            this.chrome.on('exit', (code) => {
+                clearTimeout(timeout);
+                reject(new Error(`Chrome exited unexpectedly with code ${code}`));
+            });
+        });
+    }
+    /**
+     * Fetch the DevTools WebSocket URL via the /json/version HTTP endpoint.
+     * Returns the browser-level WebSocket URL.
+     */
+    async fetchDebugUrl(port) {
+        const fetch = (await Promise.resolve().then(() => __importStar(require('node-fetch')))).default;
+        const maxRetries = 5;
+        for (let i = 0; i < maxRetries; i++) {
+            try {
+                const res = await fetch(`http://127.0.0.1:${port}/json/version`);
+                const json = (await res.json());
+                if (json.webSocketDebuggerUrl) {
+                    return json.webSocketDebuggerUrl;
+                }
+            }
+            catch {
+                // Chrome may not be ready yet
+            }
+            await new Promise((r) => setTimeout(r, 500));
+        }
+        throw new Error(`Could not get DevTools URL from Chrome on port ${port}`);
+    }
+    /**
+     * Find the page-level WebSocket target via /json endpoint.
+     * Page targets support Page.enable, Runtime.evaluate, etc.
+     * The browser-level target only supports browser-wide commands.
+     */
+    async findPageTarget(port) {
+        const fetch = (await Promise.resolve().then(() => __importStar(require('node-fetch')))).default;
+        const maxRetries = 10;
+        for (let i = 0; i < maxRetries; i++) {
+            try {
+                const res = await fetch(`http://127.0.0.1:${port}/json`);
+                const targets = (await res.json());
+                const page = targets.find(t => t.type === 'page');
+                if (page?.webSocketDebuggerUrl) {
+                    return page.webSocketDebuggerUrl;
+                }
+            }
+            catch {
+                // Chrome may not be ready yet
+            }
+            await new Promise((r) => setTimeout(r, 500));
+        }
+        throw new Error(`Could not find page target on Chrome port ${port}`);
+    }
+    /**
+     * Build the rrweb injection script source.
+     * Used by both addScriptToEvaluateOnNewDocument and Runtime.evaluate.
+     */
+    getRrwebInjectionScript() {
+        return `
+      (async function() {
+        if (window.__sessioncast_recording) return;
+        window.__sessioncast_recording = true;
+
+        // Load rrweb from CDN
+        await new Promise((resolve, reject) => {
+          const s = document.createElement('script');
+          s.src = '${RRWEB_CDN}';
+          s.onload = resolve;
+          s.onerror = reject;
+          (document.head || document.documentElement).appendChild(s);
+        });
+
+        // Start recording (save stop function for later restart)
+        if (typeof rrweb !== 'undefined' && rrweb.record) {
+          window.__sessioncast_stopFn = rrweb.record({
+            emit(event) {
+              try {
+                __sessioncast_emit(JSON.stringify(event));
+              } catch(e) { /* binding may be gone */ }
+            },
+            sampling: {
+              mousemove: 50,
+              mouseInteraction: true,
+              scroll: 150,
+              input: 'last',
+            },
+          });
+        }
+      })();
+    `;
+    }
+    /**
+     * Inject rrweb recording script into the current page.
+     * The script loads rrweb from CDN, then starts recording,
+     * emitting events through the __sessioncast_emit CDP binding.
+     */
+    async injectRrweb() {
+        if (!this.cdp || !this.running)
+            return;
+        try {
+            await this.cdp.send('Runtime.evaluate', {
+                expression: this.getRrwebInjectionScript(),
+                awaitPromise: true,
+            });
+            (0, debug_1.debugLog)('Browser', 'rrweb injected successfully');
+        }
+        catch (e) {
+            (0, debug_1.debugLog)('Browser', 'rrweb injection failed:', e.message);
+        }
+    }
+}
+exports.BrowserHandler = BrowserHandler;

package/dist/agent/cdp-client.d.ts

@@ -0,0 +1,28 @@
+import { EventEmitter } from 'events';
+/**
+ * Lightweight Chrome DevTools Protocol client.
+ * Uses the existing `ws` package — no additional dependencies.
+ */
+export declare class CdpClient extends EventEmitter {
+    private ws;
+    private nextId;
+    private callbacks;
+    private connected;
+    /**
+     * Connect to a Chrome DevTools WebSocket URL.
+     * URL is obtained from Chrome's --remote-debugging-port output.
+     */
+    connect(browserDebugUrl: string): Promise<void>;
+    /**
+     * Send a CDP command and wait for the response.
+     */
+    send(method: string, params?: Record<string, any>): Promise<any>;
+    /**
+     * Check if connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Close the CDP connection.
+     */
+    close(): void;
+}