browser-debugger-cli 0.1.0 → 0.3.0

package/dist/utils/logger.d.ts

@@ -1,42 +1,98 @@
 /**
- * Logging utilities for consistent formatted output.
+ * Logging utilities for consistent formatted output with log level support.
  *
- * WHY: Centralizes log formatting to avoid repetitive `console.error('[component] message')` patterns.
+ * WHY: Centralizes log formatting and enables debug mode for verbose logging.
+ * By default, only 'info' level logs are shown. Set BDG_DEBUG=1 or use --debug
+ * flag to enable verbose 'debug' level logs.
  */
+/**
+ * Enable debug logging globally.
+ *
+ * This is typically called during CLI initialization when --debug flag is detected.
+ * Debug mode shows all logs including verbose internal state changes and tracing.
+ */
+export declare function enableDebugLogging(): void;
+/**
+ * Check if debug logging is currently enabled.
+ *
+ * @returns True if debug mode is active
+ */
+export declare function isDebugEnabled(): boolean;
+/**
+ * Log level determines visibility of log messages.
+ *
+ * - 'info': Always shown (important user-facing messages, errors, key milestones)
+ * - 'debug': Only shown in debug mode (verbose internal state, IPC traces, progress updates)
+ */
+export type LogLevel = 'info' | 'debug';
 /**
  * Log contexts for different components.
  * Used to prefix log messages with component name.
  */
 export type LogContext = 'bdg' | 'launcher' | 'daemon' | 'worker' | 'client' | 'cleanup' | 'session' | 'chrome' | 'cdp' | 'ipc';
 /**
- * Create a logger function for a specific context.
+ * Logger instance with support for different log levels.
+ */
+export interface Logger {
+    /**
+     * Log an info message (always shown).
+     * Use for important user-facing messages and key milestones.
+     */
+    info: (message: string) => void;
+    /**
+     * Log a debug message (only shown in debug mode).
+     * Use for verbose internal state, progress updates, and traces.
+     */
+    debug: (message: string) => void;
+    /**
+     * Log a message (defaults to info level).
+     * Provided for backward compatibility.
+     */
+    (message: string): void;
+}
+/**
+ * Create a logger instance for a specific context.
  *
- * WHY: Provides consistent log formatting with context prefix.
+ * WHY: Provides consistent log formatting with context prefix and level support.
+ * By default, ALL logs are hidden unless --debug flag or BDG_DEBUG=1 is set.
+ * This keeps normal output clean and only shows logs when debugging.
  *
  * @param context - Component context for log prefix
- * @returns Logger function that prefixes messages with context
+ * @returns Logger instance with info/debug methods
  *
  * @example
  * ```typescript
  * const log = createLogger('cleanup');
- * log('Removed stale daemon socket');
- * // Output: [cleanup] Removed stale daemon socket
+ *
+ * // Always shown (even without --debug)
+ * log.info('Cleaned up stale session files');
+ *
+ * // Only shown in debug mode (--debug or BDG_DEBUG=1)
+ * log.debug('Checking PID file at ~/.bdg/daemon.pid');
+ *
+ * // Backward compatible (treated as debug - only shown in debug mode)
+ * log('Daemon started successfully');
  * ```
  */
-export declare function createLogger(context: LogContext): (message: string) => void;
+export declare function createLogger(context: LogContext): Logger;
 /**
  * Log a message with a specific context (one-off usage).
  *
- * WHY: Convenient for single log statements without creating a logger function.
+ * WHY: Convenient for single log statements without creating a logger instance.
  *
  * @param context - Component context for log prefix
  * @param message - Log message
+ * @param level - Log level (defaults to 'debug' - only shown with --debug)
  *
  * @example
  * ```typescript
- * log('cleanup', 'Removed stale daemon socket');
- * // Output: [cleanup] Removed stale daemon socket
+ * // Always shown (even without --debug)
+ * log('cleanup', 'Removed stale daemon socket', 'info');
+ *
+ * // Only shown in debug mode (default behavior)
+ * log('cleanup', 'Found PID file');
+ * log('cleanup', 'Checking lock file', 'debug');
  * ```
  */
-export declare function log(context: LogContext, message: string): void;
+export declare function log(context: LogContext, message: string, level?: LogLevel): void;
 //# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,MAAM,UAAU,GAClB,KAAK,GACL,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,SAAS,GACT,QAAQ,GACR,KAAK,GACL,KAAK,CAAC;AAEV;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAI3E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE9D"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAMD;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAExC;;;GAGG;AACH,MAAM,MAAM,UAAU,GAClB,KAAK,GACL,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,SAAS,GACT,QAAQ,GACR,KAAK,GACL,KAAK,CAAC;AAMV;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;;OAGG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhC;;;OAGG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEjC;;;OAGG;IACH,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAaxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,QAAkB,GAAG,IAAI,CAKzF"}

package/dist/utils/logger.js

@@ -1,43 +1,93 @@
 /**
- * Logging utilities for consistent formatted output.
+ * Logging utilities for consistent formatted output with log level support.
  *
- * WHY: Centralizes log formatting to avoid repetitive `console.error('[component] message')` patterns.
+ * WHY: Centralizes log formatting and enables debug mode for verbose logging.
+ * By default, only 'info' level logs are shown. Set BDG_DEBUG=1 or use --debug
+ * flag to enable verbose 'debug' level logs.
  */
+// ============================================================================
+// Global Debug State
+// ============================================================================
+let debugEnabled = false;
 /**
- * Create a logger function for a specific context.
+ * Enable debug logging globally.
  *
- * WHY: Provides consistent log formatting with context prefix.
+ * This is typically called during CLI initialization when --debug flag is detected.
+ * Debug mode shows all logs including verbose internal state changes and tracing.
+ */
+export function enableDebugLogging() {
+    debugEnabled = true;
+}
+/**
+ * Check if debug logging is currently enabled.
+ *
+ * @returns True if debug mode is active
+ */
+export function isDebugEnabled() {
+    return debugEnabled || process.env['BDG_DEBUG'] === '1';
+}
+// ============================================================================
+// Logger Implementation
+// ============================================================================
+/**
+ * Create a logger instance for a specific context.
+ *
+ * WHY: Provides consistent log formatting with context prefix and level support.
+ * By default, ALL logs are hidden unless --debug flag or BDG_DEBUG=1 is set.
+ * This keeps normal output clean and only shows logs when debugging.
  *
  * @param context - Component context for log prefix
- * @returns Logger function that prefixes messages with context
+ * @returns Logger instance with info/debug methods
  *
  * @example
  * ```typescript
  * const log = createLogger('cleanup');
- * log('Removed stale daemon socket');
- * // Output: [cleanup] Removed stale daemon socket
+ *
+ * // Always shown (even without --debug)
+ * log.info('Cleaned up stale session files');
+ *
+ * // Only shown in debug mode (--debug or BDG_DEBUG=1)
+ * log.debug('Checking PID file at ~/.bdg/daemon.pid');
+ *
+ * // Backward compatible (treated as debug - only shown in debug mode)
+ * log('Daemon started successfully');
  * ```
  */
 export function createLogger(context) {
-    return (message) => {
+    const logMessage = (message, level = 'debug') => {
+        if (level === 'debug' && !isDebugEnabled()) {
+            return;
+        }
         console.error(`[${context}] ${message}`);
     };
+    const logger = ((message) => logMessage(message, 'debug'));
+    logger.info = (message) => logMessage(message, 'info');
+    logger.debug = (message) => logMessage(message, 'debug');
+    return logger;
 }
 /**
  * Log a message with a specific context (one-off usage).
  *
- * WHY: Convenient for single log statements without creating a logger function.
+ * WHY: Convenient for single log statements without creating a logger instance.
  *
  * @param context - Component context for log prefix
  * @param message - Log message
+ * @param level - Log level (defaults to 'debug' - only shown with --debug)
  *
  * @example
  * ```typescript
- * log('cleanup', 'Removed stale daemon socket');
- * // Output: [cleanup] Removed stale daemon socket
+ * // Always shown (even without --debug)
+ * log('cleanup', 'Removed stale daemon socket', 'info');
+ *
+ * // Only shown in debug mode (default behavior)
+ * log('cleanup', 'Found PID file');
+ * log('cleanup', 'Checking lock file', 'debug');
  * ```
  */
-export function log(context, message) {
+export function log(context, message, level = 'debug') {
+    if (level === 'debug' && !isDebugEnabled()) {
+        return;
+    }
     console.error(`[${context}] ${message}`);
 }
 //# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,OAAmB;IAC9C,OAAO,CAAC,OAAe,EAAE,EAAE;QACzB,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC,CAAC;IAC3C,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,GAAG,CAAC,OAAmB,EAAE,OAAe;IACtD,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC,CAAC;AAC3C,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E,IAAI,YAAY,GAAG,KAAK,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,GAAG,CAAC;AAC1D,CAAC;AAyDD,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAAC,OAAmB;IAC9C,MAAM,UAAU,GAAG,CAAC,OAAe,EAAE,QAAkB,OAAO,EAAQ,EAAE;QACtE,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;YAC3C,OAAO;QACT,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC,CAAC;IAC3C,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAW,CAAC;IAC7E,MAAM,CAAC,IAAI,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/D,MAAM,CAAC,KAAK,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAEjE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,GAAG,CAAC,OAAmB,EAAE,OAAe,EAAE,QAAkB,OAAO;IACjF,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QAC3C,OAAO;IACT,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC,CAAC;AAC3C,CAAC"}

package/dist/utils/pageReadiness.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Smart page readiness detection using self-tuning thresholds
+ *
+ * This module provides adaptive page load detection that works for any page type
+ * without configuration. It uses a three-phase approach:
+ * 1. Load event (baseline readiness)
+ * 2. Network stability (adapts to request patterns)
+ * 3. DOM stability (adapts to mutation rate)
+ */
+import type { CDPConnection } from '../connection/cdp.js';
+/**
+ * Options for page readiness detection
+ */
+export interface PageReadinessOptions {
+    /**
+     * Maximum wait time before proceeding anyway
+     * Default: 5000ms (5 seconds)
+     */
+    maxWaitMs?: number;
+}
+/**
+ * Wait for page to be ready using self-tuning detection
+ *
+ * Strategy (always applied):
+ * 1. Wait for load event (baseline readiness)
+ * 2. Wait for network to stabilize (adaptive 200ms idle)
+ * 3. Wait for DOM to stabilize (adaptive 300ms idle)
+ *
+ * All thresholds adapt to observed page behavior.
+ * No framework detection, no configuration needed.
+ * Works for static HTML, SPAs, and everything in between.
+ *
+ * @param cdp - CDP connection
+ * @param options - Optional configuration
+ *
+ * @example
+ * ```typescript
+ * // Default: Wait up to 5s for full stability
+ * await waitForPageReady(cdp);
+ *
+ * // Custom timeout for very slow apps
+ * await waitForPageReady(cdp, { maxWaitMs: 15000 });
+ * ```
+ */
+export declare function waitForPageReady(cdp: CDPConnection, options?: PageReadinessOptions): Promise<void>;
+//# sourceMappingURL=pageReadiness.d.ts.map

package/dist/utils/pageReadiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pageReadiness.d.ts","sourceRoot":"","sources":["../../src/utils/pageReadiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,aAAa,EAClB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/utils/pageReadiness.js

@@ -0,0 +1,271 @@
+/**
+ * Smart page readiness detection using self-tuning thresholds
+ *
+ * This module provides adaptive page load detection that works for any page type
+ * without configuration. It uses a three-phase approach:
+ * 1. Load event (baseline readiness)
+ * 2. Network stability (adapts to request patterns)
+ * 3. DOM stability (adapts to mutation rate)
+ */
+/**
+ * Wait for page to be ready using self-tuning detection
+ *
+ * Strategy (always applied):
+ * 1. Wait for load event (baseline readiness)
+ * 2. Wait for network to stabilize (adaptive 200ms idle)
+ * 3. Wait for DOM to stabilize (adaptive 300ms idle)
+ *
+ * All thresholds adapt to observed page behavior.
+ * No framework detection, no configuration needed.
+ * Works for static HTML, SPAs, and everything in between.
+ *
+ * @param cdp - CDP connection
+ * @param options - Optional configuration
+ *
+ * @example
+ * ```typescript
+ * // Default: Wait up to 5s for full stability
+ * await waitForPageReady(cdp);
+ *
+ * // Custom timeout for very slow apps
+ * await waitForPageReady(cdp, { maxWaitMs: 15000 });
+ * ```
+ */
+export async function waitForPageReady(cdp, options = {}) {
+    const maxWaitMs = options.maxWaitMs ?? 5000;
+    const deadline = Date.now() + maxWaitMs;
+    try {
+        // Phase 1: Wait for load event (baseline)
+        await waitForLoadEvent(cdp, deadline);
+        console.error('[readiness] ✓ Load event');
+        // Phase 2: Wait for network stability (always - modern web is async)
+        const networkIdleMs = await waitForNetworkStable(cdp, deadline);
+        console.error(`[readiness] ✓ Network stable (${networkIdleMs}ms idle)`);
+        // Phase 3: Wait for DOM stability (always - SPAs mutate after load)
+        const domIdleMs = await waitForDOMStable(cdp, deadline);
+        console.error(`[readiness] ✓ DOM stable (${domIdleMs}ms idle)`);
+        console.error('[readiness] ✓ Page ready');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[readiness] ${message}, proceeding anyway`);
+        // Don't rethrow - allow session to continue
+    }
+}
+/**
+ * Wait for Page.loadEventFired (window.onload equivalent)
+ *
+ * This is the browser's native load event - fires when:
+ * - Document is fully loaded
+ * - All synchronous scripts executed
+ * - DOMContentLoaded already fired
+ *
+ * Framework-agnostic baseline.
+ *
+ * Handles edge case where load event already fired (Chrome navigates during launch).
+ *
+ * @param cdp - CDP connection
+ * @param deadline - Timestamp when to timeout
+ * @throws Error if deadline exceeded
+ */
+async function waitForLoadEvent(cdp, deadline) {
+    await cdp.send('Page.enable');
+    // Check if page already loaded (handles Chrome pre-navigation)
+    try {
+        const result = await cdp.send('Runtime.evaluate', {
+            expression: 'document.readyState',
+            returnByValue: true,
+        });
+        if (result.result?.value === 'complete') {
+            // Load event already fired
+            return;
+        }
+    }
+    catch {
+        // Ignore evaluation errors, proceed to wait for event
+    }
+    return new Promise((resolve, reject) => {
+        let timeout;
+        let handlerId;
+        const cleanup = () => {
+            clearTimeout(timeout);
+            if (handlerId !== undefined) {
+                cdp.off('Page.loadEventFired', handlerId);
+            }
+        };
+        const checkDeadline = () => {
+            if (Date.now() >= deadline) {
+                cleanup();
+                reject(new Error('Load event timeout'));
+            }
+            else {
+                timeout = setTimeout(checkDeadline, 100);
+            }
+        };
+        const loadHandler = () => {
+            cleanup();
+            resolve();
+        };
+        handlerId = cdp.on('Page.loadEventFired', loadHandler);
+        checkDeadline();
+    });
+}
+/**
+ * Wait for network to stabilize using adaptive thresholds
+ *
+ * LEARNING PHASE (first 2s):
+ * - Track request intervals
+ * - Calculate average request frequency
+ *
+ * DETECTION PHASE:
+ * - Fast pattern (avg \< 100ms): 200ms idle = stable
+ * - Steady pattern (100-500ms): 500ms idle = stable
+ * - Slow pattern (\> 500ms): 1000ms idle = stable
+ *
+ * Why this works:
+ * - Fast sites: Quick bursts, fast stabilization
+ * - SSR apps: Steady hydration requests, medium wait
+ * - API-heavy: Slow requests, longer patience
+ *
+ * Framework-agnostic - adapts to actual behavior.
+ *
+ * @param cdp - CDP connection
+ * @param deadline - Timestamp when to timeout
+ * @returns Actual idle duration detected
+ * @throws Error if deadline exceeded
+ */
+async function waitForNetworkStable(cdp, deadline) {
+    await cdp.send('Network.enable');
+    let activeRequests = 0;
+    let lastActivity = Date.now();
+    const intervals = [];
+    let lastRequestTime = Date.now();
+    // Track request patterns
+    const requestHandler = () => {
+        const now = Date.now();
+        const interval = now - lastRequestTime;
+        if (interval < 5000)
+            intervals.push(interval);
+        lastRequestTime = now;
+        activeRequests++;
+        lastActivity = now;
+    };
+    const finishHandler = () => {
+        activeRequests--;
+        if (activeRequests === 0) {
+            lastActivity = Date.now();
+        }
+    };
+    const requestHandlerId = cdp.on('Network.requestWillBeSent', requestHandler);
+    const loadingFinishedId = cdp.on('Network.loadingFinished', finishHandler);
+    const loadingFailedId = cdp.on('Network.loadingFailed', finishHandler);
+    try {
+        // Use fixed threshold for immediate detection
+        const idleThreshold = 200; // 200ms idle = network stable
+        // Detection phase: wait for stability
+        while (Date.now() < deadline) {
+            if (activeRequests === 0) {
+                const idleTime = Date.now() - lastActivity;
+                if (idleTime >= idleThreshold) {
+                    return idleTime; // Success!
+                }
+            }
+            await delay(50); // Check every 50ms
+        }
+        throw new Error('Network stability timeout');
+    }
+    finally {
+        // Cleanup handlers
+        cdp.off('Network.requestWillBeSent', requestHandlerId);
+        cdp.off('Network.loadingFinished', loadingFinishedId);
+        cdp.off('Network.loadingFailed', loadingFailedId);
+    }
+}
+/**
+ * Wait for DOM to stabilize using adaptive thresholds
+ *
+ * HOW IT WORKS:
+ * 1. Inject MutationObserver into page
+ * 2. Track mutation rate for 1 second
+ * 3. Calculate adaptive stability threshold:
+ *    - High rate (\>50 mutations/sec): 1000ms no-change = stable
+ *    - Medium rate (10-50 mutations/sec): 500ms no-change = stable
+ *    - Low rate (\<10 mutations/sec): 300ms no-change = stable
+ * 4. Wait for DOM to remain unchanged for threshold duration
+ *
+ * Why this works:
+ * - SSR hydration causes DOM mutations
+ * - React/Vue/Svelte all mutate during hydration
+ * - When mutations stop, hydration is complete
+ *
+ * Framework-agnostic - detects actual mutations.
+ *
+ * @param cdp - CDP connection
+ * @param deadline - Timestamp when to timeout
+ * @returns Actual stable duration detected
+ * @throws Error if deadline exceeded
+ */
+async function waitForDOMStable(cdp, deadline) {
+    // Inject mutation observer
+    await cdp.send('Runtime.evaluate', {
+        expression: `
+      window.__bdg_mutations = 0;
+      window.__bdg_lastMutation = Date.now();
+
+      const observer = new MutationObserver(() => {
+        window.__bdg_mutations++;
+        window.__bdg_lastMutation = Date.now();
+      });
+
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        characterData: true
+      });
+
+      window.__bdg_observer = observer;
+    `,
+    });
+    try {
+        // Use fixed threshold for immediate detection
+        const stableThreshold = 300; // 300ms no mutations = DOM stable
+        // Detection phase: wait for stability
+        while (Date.now() < deadline) {
+            const checkResult = await cdp.send('Runtime.evaluate', {
+                expression: 'Date.now() - window.__bdg_lastMutation',
+                returnByValue: true,
+            });
+            const timeSinceLastMutation = checkResult.result?.value ?? 0;
+            if (timeSinceLastMutation >= stableThreshold) {
+                return timeSinceLastMutation; // Success!
+            }
+            await delay(100); // Check every 100ms
+        }
+        throw new Error('DOM stability timeout');
+    }
+    finally {
+        // Cleanup observer
+        await cdp
+            .send('Runtime.evaluate', {
+            expression: `
+        window.__bdg_observer?.disconnect();
+        delete window.__bdg_observer;
+        delete window.__bdg_mutations;
+        delete window.__bdg_lastMutation;
+      `,
+        })
+            .catch(() => {
+            // Ignore cleanup errors
+        });
+    }
+}
+/**
+ * Delay utility
+ *
+ * @param ms - Milliseconds to delay
+ */
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=pageReadiness.js.map

package/dist/utils/pageReadiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pageReadiness.js","sourceRoot":"","sources":["../../src/utils/pageReadiness.ts"],"names":[],"mappings":"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"}

package/dist/utils/ui.d.ts

@@ -0,0 +1,36 @@
+/**
+ * UI utilities for enhanced terminal output.
+ *
+ * WHY: Provides visual feedback and branding for CLI operations.
+ */
+/**
+ * Options for the landing page display.
+ */
+export interface LandingPageOptions {
+    /** Target URL being monitored */
+    url: string;
+    /** Worker process ID */
+    workerPid: number;
+    /** Chrome process ID */
+    chromePid: number;
+    /** Collectors enabled */
+    collectors: string[];
+}
+/**
+ * Generate the landing page display for session start.
+ *
+ * @param options - Landing page options
+ * @returns Formatted landing page string
+ *
+ * @example
+ * ```typescript
+ * landingPage({
+ *   url: 'http://localhost:3000',
+ *   workerPid: 12345,
+ *   chromePid: 12346,
+ *   collectors: ['network', 'console', 'dom']
+ * });
+ * ```
+ */
+export declare function landingPage(options: LandingPageOptions): string;
+//# sourceMappingURL=ui.d.ts.map

package/dist/utils/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/utils/ui.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CA2B/D"}

package/dist/utils/ui.js

@@ -0,0 +1,47 @@
+/**
+ * UI utilities for enhanced terminal output.
+ *
+ * WHY: Provides visual feedback and branding for CLI operations.
+ */
+/**
+ * Generate the landing page display for session start.
+ *
+ * @param options - Landing page options
+ * @returns Formatted landing page string
+ *
+ * @example
+ * ```typescript
+ * landingPage({
+ *   url: 'http://localhost:3000',
+ *   workerPid: 12345,
+ *   chromePid: 12346,
+ *   collectors: ['network', 'console', 'dom']
+ * });
+ * ```
+ */
+export function landingPage(options) {
+    const { url, workerPid, chromePid, collectors } = options;
+    const lines = [];
+    lines.push('');
+    lines.push('   bdg');
+    lines.push('');
+    lines.push('   ▲  Session Started');
+    lines.push('');
+    lines.push(`   ○  Target      ${url}`);
+    lines.push(`   ○  Chrome      PID ${chromePid}`);
+    lines.push(`   ○  Worker      PID ${workerPid}`);
+    lines.push(`   ○  Collecting  ${collectors.join(', ')}`);
+    lines.push('');
+    lines.push('   Ready — use these commands:');
+    lines.push('');
+    lines.push('     bdg status                   Session info');
+    lines.push('     bdg peek                     Preview data');
+    lines.push('     bdg cdp <method> [params]    Execute CDP commands');
+    lines.push('     bdg stop                     Stop & save');
+    lines.push('');
+    lines.push('   💡 Run any Chrome DevTools Protocol command:');
+    lines.push('      bdg cdp Runtime.evaluate \'{"expression": "document.title"}\'');
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=ui.js.map

package/dist/utils/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../../src/utils/ui.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAE1D,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,yBAAyB,SAAS,EAAE,CAAC,CAAC;IACjD,KAAK,CAAC,IAAI,CAAC,yBAAyB,SAAS,EAAE,CAAC,CAAC;IACjD,KAAK,CAAC,IAAI,CAAC,qBAAqB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;IAC7D,KAAK,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;IAC7D,KAAK,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IACrE,KAAK,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;IAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC;IAC9D,KAAK,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;IAClF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}