devharness 0.8.0

package/build/cdp-manager.js

@@ -0,0 +1,1828 @@
+/**
+ * CDP Connection Manager
+ * Handles connection to Chrome DevTools Protocol (Chrome or Node.js)
+ */
+import CDP from 'chrome-remote-interface';
+import { debugLog } from './debug-logger.js';
+/**
+ * Thrown by evaluateExpression() when the evaluated code itself threw
+ * (CDP reports this via `exceptionDetails` on an otherwise-successful
+ * Runtime.evaluate/Debugger.evaluateOnCallFrame response, NOT as a rejected
+ * promise) - e.g. `Math.max(...bigArray)` throwing a stack-exhaustion
+ * RangeError. This is an ordinary outcome of evaluating arbitrary user code
+ * and must be surfaced as a normal tool error rather than silently ignored.
+ */
+export class EvaluateExpressionExceptionError extends Error {
+    expression;
+    exceptionType;
+    exceptionMessage;
+    exceptionStack;
+    constructor(expression, exceptionType, exceptionMessage, exceptionStack) {
+        super(`${exceptionType}: ${exceptionMessage}`);
+        this.expression = expression;
+        this.exceptionType = exceptionType;
+        this.exceptionMessage = exceptionMessage;
+        this.exceptionStack = exceptionStack;
+        this.name = 'EvaluateExpressionExceptionError';
+    }
+}
+/**
+ * Thrown by evaluateExpression() when the underlying CDP call does not
+ * return within the bounded client-side timeout. This is the backstop for
+ * cases where the renderer/execution context stops responding entirely (no
+ * result, no exception, no CDP-level timeout) - see the RangeError
+ * stack-exhaustion hang this was written to fix.
+ */
+export class EvaluateExpressionTimeoutError extends Error {
+    expression;
+    timeoutMs;
+    constructor(expression, timeoutMs) {
+        super(`Evaluation timed out after ${timeoutMs}ms - the execution context may be unresponsive`);
+        this.expression = expression;
+        this.timeoutMs = timeoutMs;
+        this.name = 'EvaluateExpressionTimeoutError';
+    }
+}
+/**
+ * Thrown by evaluateExpression() when the expression returned a Promise that
+ * is still pending while the debugger is paused. The paused event loop can
+ * never run the microtask queue, so the promise can never settle - awaiting
+ * it would only burn the full client-side timeout. Failing fast with an
+ * explanation is strictly better. (Promises that already settled - e.g.
+ * `Promise.resolve(x)` or an async IIFE with no real await - ARE recovered
+ * via their [[PromiseState]]/[[PromiseResult]] internal properties and never
+ * reach this error.)
+ */
+export class EvaluateExpressionPendingPromiseError extends Error {
+    expression;
+    constructor(expression) {
+        super('Expression returned a pending Promise while the debugger is paused - the event loop is stopped, so it can never settle');
+        this.expression = expression;
+        this.name = 'EvaluateExpressionPendingPromiseError';
+    }
+}
+/** Truncate a long expression for inclusion in error messages/telemetry. */
+function truncateExpression(expression, maxLength = 200) {
+    return expression.length > maxLength ? `${expression.slice(0, maxLength)}...` : expression;
+}
+export class CDPManager {
+    client = null;
+    state = {
+        connected: false,
+        paused: false,
+        breakpoints: new Map(),
+    };
+    scriptIdToUrl = new Map();
+    urlToScriptId = new Map(); // Support multiple scripts per URL (inline HTML scripts)
+    pauseResolvers = [];
+    scriptWaitResolvers = [];
+    sourceMapHandler = null;
+    logpointLimitExceeded = null;
+    consoleMessageCallback = null;
+    pauseCallback = null;
+    resumeCallback = null;
+    // DOMDebugger state for advanced breakpoints
+    domBreakpoints = new Map();
+    eventBreakpoints = new Map();
+    xhrBreakpoints = new Map();
+    advancedBpCounter = 0;
+    constructor(sourceMapHandler) {
+        this.sourceMapHandler = sourceMapHandler || null;
+    }
+    /**
+     * Set a callback to receive console messages from Runtime.consoleAPICalled
+     * This is used for Node.js debugging where Puppeteer's page.on('console') isn't available
+     */
+    setConsoleMessageCallback(callback) {
+        this.consoleMessageCallback = callback;
+    }
+    /**
+     * Set a callback to be called when debugger pauses at a breakpoint
+     */
+    setPauseCallback(callback) {
+        this.pauseCallback = callback;
+    }
+    /**
+     * Set a callback to be called when debugger resumes from a breakpoint
+     */
+    setResumeCallback(callback) {
+        this.resumeCallback = callback;
+    }
+    /**
+     * Find script IDs by URL, with fallback matching strategies:
+     * 1. Exact match
+     * 2. Base URL match (strips query params)
+     * 3. Filename/path suffix match (e.g., "click.js" matches "/controls/click.js")
+     *
+     * This allows breakpoints to work with partial URLs and across page reloads
+     * Returns the most recently loaded script (highest scriptId) when multiple matches exist
+     */
+    findScriptIds(url) {
+        // First, try exact match
+        const exactMatch = this.urlToScriptId.get(url);
+        if (exactMatch && exactMatch.length > 0) {
+            return { scriptIds: exactMatch, matchedUrl: url };
+        }
+        // Second, try matching by base URL (strip query params)
+        // If multiple matches, prefer the one with the highest scriptId (most recent)
+        const baseUrl = url.split('?')[0];
+        let bestMatch = null;
+        let highestScriptId = -1;
+        for (const [loadedUrl, scriptIds] of this.urlToScriptId.entries()) {
+            const loadedBaseUrl = loadedUrl.split('?')[0];
+            if (loadedBaseUrl === baseUrl && scriptIds.length > 0) {
+                // Get the highest numeric scriptId from this entry
+                const maxId = Math.max(...scriptIds.map(id => parseInt(id, 10) || 0));
+                if (maxId > highestScriptId) {
+                    highestScriptId = maxId;
+                    bestMatch = { scriptIds, matchedUrl: loadedUrl };
+                }
+            }
+        }
+        if (bestMatch) {
+            return bestMatch;
+        }
+        // Third, try filename/path suffix match
+        // This handles cases like "click.js" matching "http://localhost/controls/click.js"
+        // or "controls/click.js" matching "http://localhost/controls/click.js"
+        for (const [loadedUrl, scriptIds] of this.urlToScriptId.entries()) {
+            const loadedBaseUrl = loadedUrl.split('?')[0];
+            // Check if the loaded URL ends with the provided URL (after stripping protocol/host)
+            if (loadedBaseUrl.endsWith('/' + baseUrl) || loadedBaseUrl.endsWith(baseUrl)) {
+                if (scriptIds.length > 0) {
+                    const maxId = Math.max(...scriptIds.map(id => parseInt(id, 10) || 0));
+                    if (maxId > highestScriptId) {
+                        highestScriptId = maxId;
+                        bestMatch = { scriptIds, matchedUrl: loadedUrl };
+                    }
+                }
+            }
+        }
+        return bestMatch;
+    }
+    /**
+     * Check if a script with the given URL (or matching suffix) is loaded
+     * This is useful to detect Vite-style serving where .ts files are loaded directly
+     */
+    isScriptLoaded(url) {
+        return this.findScriptIds(url) !== null;
+    }
+    /**
+     * Get the URL for a script by its ID
+     */
+    getScriptUrl(scriptId) {
+        return this.scriptIdToUrl.get(scriptId);
+    }
+    /**
+     * Connect to a Chrome or Node.js debugger instance
+     * @param host - The debugger host (default: localhost)
+     * @param port - The debugger port (default: 9222)
+     * @param targetId - Optional target ID to connect to a specific page/tab
+     */
+    async connect(host = 'localhost', port = 9222, targetId) {
+        try {
+            // If targetId is provided, connect to that specific target
+            // Otherwise, connect to the default target
+            const cdpOptions = { host, port };
+            if (targetId) {
+                cdpOptions.target = targetId;
+            }
+            this.client = await CDP(cdpOptions);
+            const { Debugger, Runtime, DOM } = this.client;
+            // Set up event listeners BEFORE enabling domains
+            // This ensures we capture scriptParsed events for already-loaded scripts
+            // (which are emitted immediately when Debugger.enable() is called)
+            Debugger.scriptParsed((params) => {
+                this.scriptIdToUrl.set(params.scriptId, params.url);
+                // Support multiple scripts per URL (inline HTML script blocks)
+                const existingScripts = this.urlToScriptId.get(params.url) || [];
+                this.urlToScriptId.set(params.url, [...existingScripts, params.scriptId]);
+                // Register source map for lazy loading (loaded on-demand when needed)
+                if (params.sourceMapURL && this.sourceMapHandler) {
+                    this.sourceMapHandler.registerSourceMap(params.url, params.sourceMapURL);
+                }
+                // Check if any waitForScript calls are waiting for this script
+                const matchingResolvers = [];
+                this.scriptWaitResolvers.forEach((waiter, index) => {
+                    const matches = typeof waiter.pattern === 'string'
+                        ? params.url.includes(waiter.pattern)
+                        : waiter.pattern.test(params.url);
+                    if (matches) {
+                        waiter.resolve(params.url);
+                        matchingResolvers.push(index);
+                    }
+                });
+                // Remove matched resolvers (in reverse order to maintain indices)
+                matchingResolvers.reverse().forEach(index => {
+                    this.scriptWaitResolvers.splice(index, 1);
+                });
+            });
+            Debugger.paused((params) => {
+                debugLog('cdp-manager', `Debugger.paused event received, resolvers count: ${this.pauseResolvers.length}`);
+                this.state.paused = true;
+                this.state.currentCallFrames = params.callFrames;
+                // Resolve all pending pause promises
+                const resolvers = this.pauseResolvers.splice(0);
+                debugLog('cdp-manager', `Resolving ${resolvers.length} pause resolvers`);
+                resolvers.forEach(resolve => resolve());
+                // Inject clickable console link when paused at breakpoint
+                if (params.callFrames && params.callFrames.length > 0) {
+                    const location = params.callFrames[0].location;
+                    const url = this.scriptIdToUrl.get(location.scriptId) || 'unknown';
+                    this.injectConsoleLink(url, location.lineNumber, '⏸️ Paused at');
+                }
+                // Notify pause callback (e.g., to pause port monitoring)
+                if (this.pauseCallback) {
+                    this.pauseCallback();
+                }
+            });
+            Debugger.resumed(() => {
+                this.state.paused = false;
+                this.state.currentCallFrames = undefined;
+                // Notify resume callback (e.g., to resume port monitoring)
+                if (this.resumeCallback) {
+                    this.resumeCallback();
+                }
+            });
+            // Listen for breakpoint resolution - updates pending breakpoints when script loads
+            Debugger.breakpointResolved((params) => {
+                const { breakpointId, location } = params;
+                const existingBp = this.state.breakpoints.get(breakpointId);
+                if (existingBp && existingBp.status === 'pending') {
+                    // Update the breakpoint from pending to resolved
+                    existingBp.status = 'resolved';
+                    existingBp.location = location;
+                    this.state.breakpoints.set(breakpointId, existingBp);
+                }
+            });
+            // Listen for console messages via CDP (works for both Chrome and Node.js)
+            // This enables console capture for Node.js where Puppeteer isn't available
+            Runtime.consoleAPICalled((params) => {
+                if (this.consoleMessageCallback) {
+                    this.consoleMessageCallback(params);
+                }
+            });
+            // Enable domains AFTER setting up event listeners
+            // This ensures we capture all events including scriptParsed for already-loaded scripts
+            await Debugger.enable();
+            await Runtime.enable();
+            // Enable DOM domain (required for DOMDebugger breakpoints to work)
+            // Note: DOM domain is not available in Node.js, only in browsers
+            try {
+                await DOM.enable();
+            }
+            catch {
+                // DOM domain not available (e.g., Node.js runtime)
+            }
+            // Detect runtime type
+            this.state.runtimeType = await this.detectRuntimeType();
+            this.state.connected = true;
+        }
+        catch (error) {
+            throw new Error(`Failed to connect to debugger: ${error}`);
+        }
+    }
+    /**
+     * Disconnect from the debugger
+     */
+    async disconnect() {
+        if (this.client) {
+            const wasPaused = this.state.paused;
+            try {
+                await this.client.close();
+            }
+            finally {
+                this.client = null;
+                this.state.connected = false;
+                this.state.paused = false;
+                this.state.currentCallFrames = undefined;
+                this.state.runtimeType = undefined;
+                this.state.breakpoints.clear();
+                this.scriptIdToUrl.clear();
+                this.urlToScriptId.clear();
+                // Clear DOMDebugger state
+                this.domBreakpoints.clear();
+                this.eventBreakpoints.clear();
+                this.xhrBreakpoints.clear();
+                // A connection torn down while paused would otherwise never fire
+                // Debugger.resumed, leaving anything gated on it (e.g. port monitoring)
+                // stuck paused forever.
+                if (wasPaused && this.resumeCallback) {
+                    this.resumeCallback();
+                }
+            }
+        }
+    }
+    /**
+     * Check if connected
+     */
+    isConnected() {
+        return this.state.connected;
+    }
+    /**
+     * Check if currently paused at a breakpoint
+     */
+    isPaused() {
+        return this.state.paused;
+    }
+    /**
+     * Get the runtime type (chrome, node, or unknown)
+     */
+    getRuntimeType() {
+        return this.state.runtimeType || 'unknown';
+    }
+    /**
+     * Detect whether we're connected to Chrome/browser or Node.js
+     * This detection happens by checking for browser-specific global objects
+     */
+    async detectRuntimeType() {
+        if (!this.client) {
+            return 'unknown';
+        }
+        try {
+            const { Runtime } = this.client;
+            // Try to evaluate 'typeof window' - exists in browsers, not in Node.js
+            const windowCheck = await Runtime.evaluate({
+                expression: 'typeof window',
+                silent: true,
+            });
+            // If 'window' is defined, we're in a browser (Chrome)
+            if (windowCheck.result.type === 'object' ||
+                windowCheck.result.value === 'object') {
+                return 'chrome';
+            }
+            // Try to evaluate 'typeof process' - exists in Node.js, not in browsers
+            const processCheck = await Runtime.evaluate({
+                expression: 'typeof process',
+                silent: true,
+            });
+            // If 'process' is an object, we're in Node.js
+            if (processCheck.result.type === 'object' ||
+                processCheck.result.value === 'object') {
+                return 'node';
+            }
+            return 'unknown';
+        }
+        catch (error) {
+            console.error('Failed to detect runtime type:', error);
+            return 'unknown';
+        }
+    }
+    /**
+     * Set a breakpoint at a specific file and line
+     */
+    async setBreakpoint(url, lineNumber, columnNumber, condition) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { Debugger } = this.client;
+        // IMPORTANT: CDP uses 0-based line and column numbers internally
+        // User provides 1-based numbers (line 1 = first line, column 1 = first column)
+        // We must convert before calling CDP API
+        const cdpLineNumber = lineNumber - 1; // Convert 1-based → 0-based
+        const cdpColumnNumber = columnNumber !== undefined ? columnNumber - 1 : undefined; // Convert 1-based → 0-based
+        // Try to find actual URL if the provided one has query params that may differ
+        // This handles cache-busting params like ?v=123 that change on rebuild
+        let actualUrl = url;
+        const match = this.findScriptIds(url);
+        if (match && match.matchedUrl !== url) {
+            actualUrl = match.matchedUrl;
+        }
+        // Set breakpoint using 0-based CDP numbers
+        let result;
+        try {
+            result = await Debugger.setBreakpointByUrl({
+                url: actualUrl,
+                lineNumber: cdpLineNumber,
+                columnNumber: cdpColumnNumber,
+                condition,
+            });
+        }
+        catch (error) {
+            // Handle "Breakpoint at specified location already exists" error
+            if (error?.message?.includes('already exists')) {
+                // Find and remove the existing breakpoint at this location
+                for (const [bpId, bp] of this.state.breakpoints.entries()) {
+                    if (bp.originalLocation?.url === url &&
+                        bp.originalLocation?.lineNumber === lineNumber &&
+                        (columnNumber === undefined || bp.originalLocation?.columnNumber === columnNumber)) {
+                        await this.removeBreakpoint(bpId);
+                        break;
+                    }
+                }
+                // Retry setting the breakpoint
+                result = await Debugger.setBreakpointByUrl({
+                    url: actualUrl,
+                    lineNumber: cdpLineNumber,
+                    columnNumber: cdpColumnNumber,
+                    condition,
+                });
+            }
+            else {
+                throw error;
+            }
+        }
+        // Check if breakpoint was resolved to any location
+        // Per CDP spec, setBreakpointByUrl can return empty locations if script isn't loaded yet
+        // The breakpoint is still valid and will activate when the script loads
+        if (!result.locations || result.locations.length === 0) {
+            // Breakpoint is pending - script not loaded yet but breakpoint is queued
+            const breakpointInfo = {
+                breakpointId: result.breakpointId,
+                // For pending breakpoints, we don't have a resolved location yet
+                // Use a placeholder that indicates pending state
+                location: {
+                    scriptId: '',
+                    lineNumber: cdpLineNumber, // Store the requested 0-based line
+                    columnNumber: cdpColumnNumber,
+                },
+                originalLocation: { url, lineNumber, columnNumber },
+                status: 'pending',
+            };
+            this.state.breakpoints.set(result.breakpointId, breakpointInfo);
+            return breakpointInfo;
+        }
+        // Warn if multiple locations (rare but possible)
+        if (result.locations.length > 1) {
+            console.error(`[cdp-tools] Warning: Breakpoint matched ${result.locations.length} locations. Using first match.`);
+        }
+        // Store breakpoint info
+        // - location: Actual location from CDP (0-based)
+        // - originalLocation: User-requested location (1-based, what user asked for)
+        const breakpointInfo = {
+            breakpointId: result.breakpointId,
+            location: result.locations[0],
+            originalLocation: { url, lineNumber, columnNumber },
+            status: 'resolved',
+        };
+        this.state.breakpoints.set(result.breakpointId, breakpointInfo);
+        return breakpointInfo;
+    }
+    /**
+     * Remove a breakpoint
+     */
+    async removeBreakpoint(breakpointId) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { Debugger } = this.client;
+        await Debugger.removeBreakpoint({ breakpointId });
+        this.state.breakpoints.delete(breakpointId);
+    }
+    /**
+     * Get all active breakpoints
+     */
+    getBreakpoints() {
+        return Array.from(this.state.breakpoints.values());
+    }
+    /**
+     * Get breakpoint counts (total, regular, logpoints)
+     */
+    getBreakpointCounts() {
+        const all = this.getBreakpoints();
+        const logpoints = all.filter(bp => bp.isLogpoint).length;
+        const regularBreakpoints = all.length - logpoints;
+        return {
+            total: all.length,
+            breakpoints: regularBreakpoints,
+            logpoints,
+        };
+    }
+    /**
+     * Wait for a script matching the given URL pattern to load
+     * @param urlPattern - String (substring match) or RegExp to match against script URLs
+     * @param timeout - Maximum time to wait in milliseconds (default: 10000)
+     * @returns The URL of the matched script
+     * @throws Error if timeout expires before script loads
+     */
+    async waitForScript(urlPattern, timeout = 10000) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        // First, check if script is already loaded
+        for (const url of this.urlToScriptId.keys()) {
+            const matches = typeof urlPattern === 'string'
+                ? url.includes(urlPattern)
+                : urlPattern.test(url);
+            if (matches) {
+                return url; // Script already loaded
+            }
+        }
+        // Script not loaded yet, wait for it
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                // Remove this waiter from the list
+                const index = this.scriptWaitResolvers.findIndex(w => w.resolve === resolveWrapper);
+                if (index >= 0) {
+                    this.scriptWaitResolvers.splice(index, 1);
+                }
+                reject(new Error(`Timeout: Script matching "${urlPattern}" did not load within ${timeout}ms`));
+            }, timeout);
+            const resolveWrapper = (url) => {
+                clearTimeout(timeoutId);
+                resolve(url);
+            };
+            this.scriptWaitResolvers.push({
+                pattern: urlPattern,
+                resolve: resolveWrapper,
+            });
+        });
+    }
+    /**
+     * Get list of all loaded scripts
+     * @returns Array of script URLs
+     */
+    getLoadedScripts() {
+        return Array.from(this.urlToScriptId.keys());
+    }
+    /**
+     * Check if a script matching the pattern is loaded
+     * @param urlPattern - String (substring match) or RegExp
+     * @returns The matched URL or null
+     */
+    findLoadedScript(urlPattern) {
+        for (const url of this.urlToScriptId.keys()) {
+            const matches = typeof urlPattern === 'string'
+                ? url.includes(urlPattern)
+                : urlPattern.test(url);
+            if (matches) {
+                return url;
+            }
+        }
+        return null;
+    }
+    /**
+     * Synchronize breakpoint state with CDP's actual breakpoints
+     * Use this to recover from state desynchronization
+     */
+    async syncBreakpoints() {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        // This is a future enhancement - for now, just return current counts
+        // Full implementation would query CDP for all active breakpoints
+        // and reconcile with state.breakpoints Map
+        return {
+            synced: this.state.breakpoints.size,
+            removed: 0,
+        };
+    }
+    /**
+     * Diagnose why a breakpoint failed to set (empty locations array)
+     * Performs lazy validation to determine exact cause
+     */
+    async diagnoseBreakpointFailure(url, lineNumber) {
+        // Check if we have this script loaded (with fallback to base URL matching)
+        const match = this.findScriptIds(url);
+        if (!match) {
+            return {
+                cause: 'script_not_found',
+                message: `Script not loaded: ${url}`,
+                scriptUrl: url,
+                requestedLine: lineNumber,
+                suggestion: 'The script has not been loaded by Chrome yet. Use reloadPage() or navigateTo() to ensure the script loads.'
+            };
+        }
+        const { scriptIds } = match;
+        // Script exists - check each scriptId to find which contains the requested line
+        try {
+            const { Debugger } = this.client;
+            // Try each script to find one that contains the requested line
+            for (const scriptId of scriptIds) {
+                const source = await Debugger.getScriptSource({ scriptId });
+                const totalLines = source.scriptSource.split('\n').length;
+                // Check if this script contains the requested line
+                if (lineNumber <= totalLines) {
+                    // This script contains the line - check if it's executable
+                    return {
+                        cause: 'line_not_executable',
+                        message: `Line ${lineNumber} is not executable code`,
+                        scriptUrl: url,
+                        requestedLine: lineNumber,
+                        totalLines: totalLines,
+                        suggestion: 'This line may be a comment, blank line, or non-executable declaration. Try setting the breakpoint on a nearby line with executable code (function call, assignment, etc.).'
+                    };
+                }
+            }
+            // Line number exceeds all scripts - get the maximum lines from all scripts
+            let maxLines = 0;
+            for (const scriptId of scriptIds) {
+                const source = await Debugger.getScriptSource({ scriptId });
+                const lineCount = source.scriptSource.split('\n').length;
+                maxLines = Math.max(maxLines, lineCount);
+            }
+            return {
+                cause: 'line_out_of_bounds',
+                message: `Line ${lineNumber} is out of bounds`,
+                scriptUrl: url,
+                requestedLine: lineNumber,
+                totalLines: maxLines,
+                suggestion: scriptIds.length > 1
+                    ? `This URL has ${scriptIds.length} inline scripts. The largest has ${maxLines} lines. Use searchCode() to find the correct script and line.`
+                    : `The script only has ${maxLines} lines. Use getSourceCode() to view the file and find valid line numbers.`
+            };
+        }
+        catch (error) {
+            // Fallback if we can't get script source
+            return {
+                cause: 'script_not_found',
+                message: `Unable to access script: ${url}`,
+                scriptUrl: url,
+                requestedLine: lineNumber,
+                suggestion: 'The script may have been unloaded. Try reloadPage().'
+            };
+        }
+    }
+    /**
+     * Resume execution
+     */
+    async resume() {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { Debugger } = this.client;
+        await Debugger.resume();
+    }
+    /**
+     * Pause execution
+     */
+    async pause() {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { Debugger } = this.client;
+        await Debugger.pause();
+    }
+    /**
+     * Handle logpoint execution limit exceeded
+     * This should be called by the LogpointExecutionTracker when a logpoint hits its limit
+     */
+    async handleLogpointLimitExceeded(metadata) {
+        // Store the metadata
+        this.logpointLimitExceeded = metadata;
+        // Pause execution
+        await this.pause();
+    }
+    /**
+     * Get information about the logpoint that exceeded its limit (if any)
+     */
+    getLogpointLimitExceeded() {
+        return this.logpointLimitExceeded;
+    }
+    /**
+     * Clear the logpoint limit exceeded state
+     */
+    clearLogpointLimitExceeded() {
+        this.logpointLimitExceeded = null;
+    }
+    /**
+     * Step over (next line)
+     */
+    async stepOver() {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { Debugger } = this.client;
+        await Debugger.stepOver();
+    }
+    /**
+     * Step into function
+     */
+    async stepInto() {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { Debugger } = this.client;
+        await Debugger.stepInto();
+    }
+    /**
+     * Step out of function
+     */
+    async stepOut() {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { Debugger } = this.client;
+        await Debugger.stepOut();
+    }
+    /**
+     * Get current call stack
+     */
+    getCallStack() {
+        if (!this.state.paused || !this.state.currentCallFrames) {
+            return undefined;
+        }
+        return this.state.currentCallFrames.map((frame) => ({
+            callFrameId: frame.callFrameId,
+            functionName: frame.functionName || '(anonymous)',
+            location: frame.location,
+            url: this.scriptIdToUrl.get(frame.location.scriptId) || 'unknown',
+            scopeChain: frame.scopeChain,
+        }));
+    }
+    /**
+     * Get variables for a specific call frame
+     */
+    /**
+     * Estimate token count for a value (rough approximation: ~4 chars per token)
+     */
+    estimateTokens(value) {
+        const str = typeof value === 'string' ? value : JSON.stringify(value);
+        return Math.ceil(str.length / 4);
+    }
+    /**
+     * Calculate effective token budget accounting for response overhead.
+     * The final MCP response includes:
+     * - Message template text (~100 tokens)
+     * - JSON code block markers and wrapper (~50 tokens)
+     * - JSON.stringify indentation adds ~30% to data size
+     */
+    calculateEffectiveBudget(maxTokens) {
+        const FIXED_OVERHEAD = 200; // Message template + code block + wrapper
+        const PROPORTIONAL_OVERHEAD = 1.3; // JSON indentation adds ~30%
+        return Math.floor((maxTokens - FIXED_OVERHEAD) / PROPORTIONAL_OVERHEAD);
+    }
+    async getVariables(callFrameId, includeGlobal = false, filter, expandObjects = true, maxDepth = 2, maxTokens = 1000) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { Runtime } = this.client;
+        const callFrame = this.state.currentCallFrames?.find((frame) => frame.callFrameId === callFrameId);
+        if (!callFrame) {
+            throw new Error(`Call frame ${callFrameId} not found`);
+        }
+        let filterRegex = null;
+        if (filter) {
+            try {
+                filterRegex = new RegExp(filter, 'i');
+            }
+            catch {
+                throw new Error(`Invalid filter regex: ${filter}`);
+            }
+        }
+        const requestedDepth = maxDepth;
+        // Collect property metadata first (without expanding)
+        const propertyMeta = [];
+        for (const scope of callFrame.scopeChain) {
+            if (scope.type === 'global' && !includeGlobal) {
+                continue;
+            }
+            const properties = await Runtime.getProperties({
+                objectId: scope.object.objectId,
+                ownProperties: true,
+            });
+            for (const prop of properties.result) {
+                if (!prop.value)
+                    continue;
+                if (filterRegex && !filterRegex.test(prop.name))
+                    continue;
+                propertyMeta.push({ prop, scopeType: scope.type });
+            }
+        }
+        const totalCount = propertyMeta.length;
+        const effectiveBudget = this.calculateEffectiveBudget(maxTokens);
+        const hasFilter = !!filter;
+        // Helper to group variables by scope
+        const groupByScope = (variables) => {
+            const grouped = {};
+            for (const v of variables) {
+                const scopeType = v.scopeType || 'unknown';
+                if (!grouped[scopeType])
+                    grouped[scopeType] = [];
+                grouped[scopeType].push({ name: v.name, value: v.value, type: v.type });
+            }
+            return grouped;
+        };
+        // Helper to compute variables at a given depth
+        const computeAtDepth = async (depth) => {
+            const variables = [];
+            const shouldExpand = expandObjects && depth > 0;
+            for (const { prop, scopeType } of propertyMeta) {
+                variables.push({
+                    name: prop.name,
+                    value: await this.formatValue(prop.value, shouldExpand, depth),
+                    type: prop.value.type,
+                    scopeType,
+                });
+            }
+            return { variables, tokens: this.estimateTokens(variables) };
+        };
+        // Helper to get names-only data
+        const getNamesOnly = (variables) => {
+            const namesByScope = {};
+            for (const v of variables) {
+                const scopeType = v.scopeType || 'unknown';
+                if (!namesByScope[scopeType])
+                    namesByScope[scopeType] = [];
+                namesByScope[scopeType].push(v.name);
+            }
+            return namesByScope;
+        };
+        // Helper to get counts-only data
+        const getCountsOnly = (variables) => {
+            const countsByScope = {};
+            for (const v of variables) {
+                const scopeType = v.scopeType || 'unknown';
+                countsByScope[scopeType] = (countsByScope[scopeType] || 0) + 1;
+            }
+            return countsByScope;
+        };
+        // Step 1: Try full data at requested depth
+        if (expandObjects && maxDepth > 0) {
+            const requestedResult = await computeAtDepth(maxDepth);
+            if (requestedResult.tokens <= effectiveBudget) {
+                return {
+                    data: groupByScope(requestedResult.variables),
+                    totalCount,
+                    usedDepth: maxDepth,
+                    requestedDepth,
+                    responseType: 'full',
+                    filterInsufficient: false,
+                };
+            }
+        }
+        // Step 2: Try full data at depth 0
+        const depth0Result = await computeAtDepth(0);
+        if (depth0Result.tokens <= effectiveBudget) {
+            // If we got here after trying requested depth, it means depth was reduced
+            const wasDepthReduced = expandObjects && maxDepth > 0;
+            return {
+                data: groupByScope(depth0Result.variables),
+                totalCount,
+                usedDepth: 0,
+                requestedDepth,
+                responseType: wasDepthReduced ? 'depth_reduced' : 'full',
+                filterInsufficient: false,
+            };
+        }
+        // Step 3: Try names-only
+        const namesOnly = getNamesOnly(depth0Result.variables);
+        const namesTokens = this.estimateTokens(namesOnly);
+        if (namesTokens <= effectiveBudget) {
+            return {
+                data: namesOnly,
+                totalCount,
+                usedDepth: 0,
+                requestedDepth,
+                responseType: 'names_only',
+                filterInsufficient: hasFilter, // Filter was provided but still too large
+            };
+        }
+        // Step 4: Fall back to counts-only (always fits)
+        const countsOnly = getCountsOnly(depth0Result.variables);
+        return {
+            data: countsOnly,
+            totalCount,
+            usedDepth: 0,
+            requestedDepth,
+            responseType: 'counts_only',
+            filterInsufficient: hasFilter,
+        };
+    }
+    /**
+     * Bounded upper limit on how long evaluateExpression() will wait for CDP to
+     * respond, in milliseconds. Exported as an instance property (rather than a
+     * module constant) so tests can override it on a per-manager basis without
+     * needing real wall-clock waits. Kept comfortably below the 180s default
+     * Puppeteer protocolTimeout that would otherwise leak through as a raw,
+     * untyped "Runtime.callFunctionOn timed out" error on this path.
+     */
+    evaluateExpressionTimeoutMs = 10_000;
+    /**
+     * Evaluate an expression in the current context.
+     *
+     * Two distinct failure modes are handled explicitly (this method used to
+     * handle neither, which is how a stack-exhaustion RangeError thrown by
+     * evaluated code could hang a caller forever with no result, no error, and
+     * no timeout):
+     *
+     * 1. The evaluated code throws. CDP reports this via `exceptionDetails` on
+     *    an otherwise-successful response - it is NOT a rejected promise - so
+     *    it must be checked explicitly and surfaced as
+     *    EvaluateExpressionExceptionError instead of being formatted as if it
+     *    were a normal return value.
+     * 2. The CDP call itself never resolves (a wedged renderer/execution
+     *    context). A bounded client-side timeout (racing the CDP call against
+     *    a timer) guarantees this method always settles, throwing
+     *    EvaluateExpressionTimeoutError instead of hanging indefinitely. We
+     *    also pass CDP's own `timeout` param so well-behaved renderers abort
+     *    the runaway script themselves and return exceptionDetails cleanly
+     *    (case 1) rather than relying solely on our client-side timer.
+     */
+    async evaluateExpression(expression, callFrameId, expandObjects = true, maxDepth = 2, options) {
+        const detailed = await this.evaluateExpressionDetailed(expression, callFrameId, expandObjects, maxDepth, { ...options, captureRaw: false });
+        return detailed.formatted;
+    }
+    /**
+     * Like evaluateExpression(), but also attempts an exact by-value capture of
+     * the result when options.captureRaw is set (used for `saveAs` and the
+     * structured `_meta.inspect.value`, so captured data does not round-trip
+     * through display formatting).
+     *
+     * Promise handling (bug-015), all empirically verified against Chrome 150:
+     * - Running page, no callFrameId: `awaitPromise: true` is passed to
+     *   Runtime.evaluate, so async results resolve to their settled value and
+     *   rejections surface as exceptionDetails (-> ExceptionError). A promise
+     *   that never settles is bounded by the client-side timeout.
+     * - Paused (callFrameId given, OR a global evaluation while the debugger is
+     *   paused - Runtime.evaluate with awaitPromise HANGS in that state, and
+     *   Debugger.evaluateOnCallFrame silently ignores awaitPromise): we never
+     *   pass awaitPromise. Instead, a Promise result is resolved through its
+     *   [[PromiseState]]/[[PromiseResult]] internal properties, which works
+     *   without running the event loop: already-settled promises yield their
+     *   exact value (or ExceptionError if rejected); a pending promise fails
+     *   fast with EvaluateExpressionPendingPromiseError instead of burning the
+     *   timeout, because it can never settle while the event loop is stopped.
+     */
+    async evaluateExpressionDetailed(expression, callFrameId, expandObjects = true, maxDepth = 2, options) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const awaitPromise = options?.awaitPromise !== false;
+        const captureRaw = options?.captureRaw === true;
+        const timeoutMs = this.evaluateExpressionTimeoutMs;
+        // Leave CDP's own timeout slightly shorter than ours so a well-behaved
+        // renderer's own abort (which yields a clean exceptionDetails response)
+        // has a chance to win the race against our client-side backstop.
+        const cdpTimeoutMs = Math.max(1000, timeoutMs - 1000);
+        let timer;
+        const timeoutGuard = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new EvaluateExpressionTimeoutError(truncateExpression(expression), timeoutMs)), timeoutMs);
+        });
+        // The whole pipeline (evaluate + promise recovery + formatting + raw
+        // capture) runs inside the client-side timeout race: the follow-up CDP
+        // calls talk to the same possibly-wedged target as the evaluation itself.
+        const work = (async () => {
+            let result;
+            if (callFrameId) {
+                const { Debugger } = this.client;
+                // awaitPromise is deliberately NOT passed: V8 ignores it on
+                // evaluateOnCallFrame (verified), so it cannot be relied on.
+                result = await Debugger.evaluateOnCallFrame({ callFrameId, expression, timeout: cdpTimeoutMs });
+            }
+            else {
+                const { Runtime } = this.client;
+                // awaitPromise while the debugger is paused hangs the CDP call
+                // (event loop stopped -> promise can never settle), so only pass it
+                // when the page is actually running.
+                const canAwaitInProtocol = awaitPromise && !this.state.paused;
+                result = await Runtime.evaluate({
+                    expression,
+                    timeout: cdpTimeoutMs,
+                    ...(canAwaitInProtocol ? { awaitPromise: true } : {}),
+                });
+            }
+            if (result.exceptionDetails) {
+                throw this.toEvaluateExpressionExceptionError(expression, result.exceptionDetails);
+            }
+            let remote = result.result;
+            // Paused-context promise recovery (see doc comment above).
+            if (awaitPromise && remote?.subtype === 'promise' && remote.objectId) {
+                remote = await this.resolveSettledPromiseWhilePaused(expression, remote);
+            }
+            const formatted = await this.formatValue(remote, expandObjects, maxDepth);
+            if (!captureRaw) {
+                return { formatted, rawCaptured: false };
+            }
+            const capture = await this.captureRawValue(remote);
+            return { formatted, ...capture };
+        })();
+        try {
+            return await Promise.race([work, timeoutGuard]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Map CDP exceptionDetails to a typed error (thrown code or awaited promise rejection). */
+    toEvaluateExpressionExceptionError(expression, details) {
+        const exceptionObject = details.exception;
+        const exceptionType = exceptionObject?.className || exceptionObject?.subtype || 'Error';
+        // `description` on an Error RemoteObject is "Message\n    at stack...".
+        // A promise rejected with a primitive has no description - the reason is
+        // carried as exception.value (details.text is just "Uncaught (in promise)").
+        const description = exceptionObject?.description;
+        const exceptionMessage = description?.split('\n')[0] ||
+            (exceptionObject && exceptionObject.value !== undefined ? String(exceptionObject.value) : undefined) ||
+            details.text ||
+            'Unknown error';
+        const exceptionStack = description?.includes('\n') ? description : undefined;
+        return new EvaluateExpressionExceptionError(truncateExpression(expression), exceptionType, exceptionMessage, exceptionStack);
+    }
+    /**
+     * Resolve a Promise RemoteObject without running the event loop, via its
+     * [[PromiseState]]/[[PromiseResult]] internal properties (readable even
+     * while the debugger is paused). Returns the settled value's RemoteObject;
+     * throws for rejected/pending promises.
+     */
+    async resolveSettledPromiseWhilePaused(expression, promiseRemote) {
+        const { Runtime } = this.client;
+        const props = await Runtime.getProperties({ objectId: promiseRemote.objectId, ownProperties: true });
+        const internal = props.internalProperties || [];
+        const state = internal.find((p) => p.name === '[[PromiseState]]')?.value?.value;
+        const resultRemote = internal.find((p) => p.name === '[[PromiseResult]]')?.value;
+        if (state === 'fulfilled') {
+            return resultRemote ?? { type: 'undefined' };
+        }
+        if (state === 'rejected') {
+            const type = resultRemote?.className || resultRemote?.subtype || 'Error';
+            const description = resultRemote?.description;
+            const message = description?.split('\n')[0] ||
+                (resultRemote && resultRemote.value !== undefined ? String(resultRemote.value) : 'Promise rejected');
+            throw new EvaluateExpressionExceptionError(truncateExpression(expression), type, message, description?.includes('\n') ? description : undefined);
+        }
+        // pending (or internal props unavailable): it cannot settle while paused.
+        throw new EvaluateExpressionPendingPromiseError(truncateExpression(expression));
+    }
+    /**
+     * Attempt an exact by-value capture of an evaluation result, WITHOUT
+     * re-executing the expression: primitives come straight off the
+     * RemoteObject; plain objects/arrays are serialized in place via
+     * Runtime.callFunctionOn(returnByValue). Values whose by-value form is
+     * lossy or impossible (DOM nodes, Date, Map/Set, functions, window - CDP
+     * serializes these to {} or errors) report rawCaptured: false so callers
+     * can fall back to the display-derived reconstruction.
+     */
+    async captureRawValue(remote) {
+        if (!remote || remote.type === 'undefined') {
+            return { rawValue: undefined, rawCaptured: true };
+        }
+        if (remote.type === 'string' || remote.type === 'number' || remote.type === 'boolean') {
+            if ('value' in remote) {
+                return { rawValue: remote.value, rawCaptured: true };
+            }
+            // Unserializable numbers (NaN, Infinity, -0) arrive as
+            // unserializableValue with no `value` - let the caller fall back.
+            return { rawCaptured: false };
+        }
+        if (remote.type === 'object') {
+            if (remote.subtype === 'null') {
+                return { rawValue: null, rawCaptured: true };
+            }
+            // Only plain JSON-like shapes serialize faithfully by value. Anything
+            // with a specialized subtype/class (date, map, set, node, typedarray,
+            // error, ...) collapses to {} under CDP's by-value serialization, which
+            // is WORSE than the display-derived fallback.
+            const className = remote.className;
+            const jsonLike = (remote.subtype === undefined || remote.subtype === 'array') &&
+                (className === undefined || className === 'Object' || className === 'Array');
+            if (jsonLike && remote.objectId) {
+                try {
+                    const { Runtime } = this.client;
+                    const cf = await Runtime.callFunctionOn({
+                        objectId: remote.objectId,
+                        functionDeclaration: 'function() { return this; }',
+                        returnByValue: true,
+                    });
+                    if (!cf.exceptionDetails) {
+                        return { rawValue: cf.result?.value, rawCaptured: true };
+                    }
+                }
+                catch {
+                    // Non-serializable (e.g. window: "Object reference chain is too
+                    // long") - fall through to the display-derived fallback.
+                }
+            }
+        }
+        return { rawCaptured: false };
+    }
+    /**
+     * Get available variables at a specific source location
+     * Useful for validating logpoint expressions
+     */
+    async getScopeVariablesAtLocation(url, lineNumber) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        // Temporarily set a breakpoint to inspect scope
+        const tempBreakpoint = await this.setBreakpoint(url, lineNumber);
+        try {
+            // Wait for the breakpoint to be hit (with timeout)
+            // Note: This requires the code to actually execute
+            // For static analysis, we'd need a different approach
+            // For now, return null to indicate we can't determine scope without execution
+            // This would require the debugger to be paused at that location
+            if (!this.state.paused || !this.state.currentCallFrames) {
+                // Remove the temporary breakpoint
+                await this.removeBreakpoint(tempBreakpoint.breakpointId);
+                return null;
+            }
+            // Get the call frame
+            const callFrame = this.state.currentCallFrames[0];
+            // Extract variable names from all scopes
+            const { Runtime } = this.client;
+            const scopes = [];
+            const allVariables = [];
+            for (const scope of callFrame.scopeChain) {
+                if (scope.type === 'global')
+                    continue; // Skip global scope
+                const properties = await Runtime.getProperties({
+                    objectId: scope.object.objectId,
+                    ownProperties: true,
+                });
+                const variableNames = properties.result
+                    .filter((prop) => prop.value && !prop.name.startsWith('[['))
+                    .map((prop) => prop.name);
+                scopes.push({
+                    type: scope.type,
+                    variables: variableNames,
+                });
+                allVariables.push(...variableNames);
+            }
+            // Remove the temporary breakpoint
+            await this.removeBreakpoint(tempBreakpoint.breakpointId);
+            return {
+                variables: [...new Set(allVariables)], // Deduplicate
+                scopes,
+            };
+        }
+        catch (error) {
+            // Clean up the breakpoint if something goes wrong
+            try {
+                await this.removeBreakpoint(tempBreakpoint.breakpointId);
+            }
+            catch (e) {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
+    }
+    /**
+     * Validate logpoint expressions at a specific location
+     * Sets temp breakpoint, waits for execution, tests expressions
+     *
+     * @param url File URL (e.g., http://localhost:3000/app.js)
+     * @param lineNumber Line number (1-based, will be converted to 0-based for CDP)
+     * @param columnNumber Optional column number (1-based, will be converted to 0-based for CDP)
+     * @param expressions Array of expressions to validate (e.g., ["user.name", "user.id"])
+     * @param timeout Max wait time for execution in milliseconds
+     * @returns Validation results with pass/fail for each expression, plus available variables
+     */
+    async validateLogpointAtActualLocation(url, lineNumber, columnNumber, expressions, timeout = 2000) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        // Note: lineNumber and columnNumber are 1-based (user input)
+        // setBreakpoint will convert them to 0-based for CDP
+        const tempBreakpoint = await this.setBreakpoint(url, lineNumber, columnNumber);
+        try {
+            // Wait for execution with timeout
+            await new Promise(resolve => setTimeout(resolve, timeout));
+            // Check if we paused at the breakpoint
+            if (!this.state.paused || !this.state.currentCallFrames) {
+                // Code didn't execute - remove breakpoint and return
+                await this.removeBreakpoint(tempBreakpoint.breakpointId);
+                return {
+                    executed: false,
+                    allValid: false,
+                    results: expressions.map(expr => ({
+                        expression: expr,
+                        valid: false,
+                        error: 'Code has not executed yet - cannot validate without execution'
+                    })),
+                };
+            }
+            // Get actual location from CDP (0-based)
+            const actualLocation = tempBreakpoint.location;
+            const actualLineUser = actualLocation.lineNumber + 1; // Convert 0-based → 1-based
+            const actualColumnUser = actualLocation.columnNumber !== undefined
+                ? actualLocation.columnNumber + 1 // Convert 0-based → 1-based
+                : undefined;
+            // Get call frame for evaluation
+            const callFrame = this.state.currentCallFrames[0];
+            // Collect all available variables
+            const { Runtime } = this.client;
+            const availableVariables = [];
+            for (const scope of callFrame.scopeChain) {
+                if (scope.type === 'global')
+                    continue; // Skip global
+                const properties = await Runtime.getProperties({
+                    objectId: scope.object.objectId,
+                    ownProperties: true,
+                });
+                properties.result
+                    .filter((prop) => prop.value && !prop.name.startsWith('[['))
+                    .forEach((prop) => availableVariables.push(prop.name));
+            }
+            // Evaluate each expression
+            const results = [];
+            for (const expr of expressions) {
+                try {
+                    const value = await this.evaluateExpression(expr, callFrame.callFrameId);
+                    results.push({
+                        expression: expr,
+                        valid: true,
+                        value,
+                    });
+                }
+                catch (error) {
+                    results.push({
+                        expression: expr,
+                        valid: false,
+                        error: String(error),
+                    });
+                }
+            }
+            // Resume execution
+            await this.resume();
+            // Remove temp breakpoint
+            await this.removeBreakpoint(tempBreakpoint.breakpointId);
+            const allValid = results.every(r => r.valid);
+            return {
+                executed: true,
+                allValid,
+                results,
+                availableVariables: [...new Set(availableVariables)], // Deduplicate
+                actualLocation: {
+                    line: actualLineUser,
+                    column: actualColumnUser,
+                },
+            };
+        }
+        catch (error) {
+            // Clean up on error
+            try {
+                if (this.state.paused) {
+                    await this.resume();
+                }
+                await this.removeBreakpoint(tempBreakpoint.breakpointId);
+            }
+            catch (e) {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
+    }
+    /**
+     * Search for the best location to set a logpoint by trying nearby lines/columns
+     * Returns suggestions ranked by how many expressions are valid
+     *
+     * @param url File URL
+     * @param lineNumber Desired line number (1-based)
+     * @param columnNumber Desired column number (1-based, optional)
+     * @param expressions Array of expressions to validate
+     * @param searchRadius Number of lines to search in each direction (default: 2)
+     * @param timeout Timeout per location test in milliseconds (default: 1000ms)
+     * @returns Array of suggestions sorted by score (best first), max 3 results
+     */
+    async findBestLogpointLocation(url, lineNumber, columnNumber, expressions, searchRadius = 2, timeout = 1000) {
+        const candidates = [];
+        // Try requested line first, then ±1, ±2, etc.
+        for (let offset = 0; offset <= searchRadius; offset++) {
+            const lines = offset === 0 ? [lineNumber] : [lineNumber - offset, lineNumber + offset];
+            for (const line of lines) {
+                if (line < 1)
+                    continue; // Skip negative lines
+                try {
+                    const validation = await this.validateLogpointAtActualLocation(url, line, columnNumber, expressions, timeout);
+                    if (validation.executed) {
+                        const validCount = validation.results.filter(r => r.valid).length;
+                        const score = Math.round((validCount / expressions.length) * 100);
+                        candidates.push({
+                            line: validation.actualLocation?.line || line,
+                            column: validation.actualLocation?.column,
+                            score,
+                            validExpressions: validation.results.filter(r => r.valid).map(r => r.expression),
+                            invalidExpressions: validation.results.filter(r => !r.valid).map(r => r.expression),
+                            availableVariables: validation.availableVariables || [],
+                            reason: score === 100 ? 'All expressions available in scope' :
+                                score > 0 ? `${validCount}/${expressions.length} expressions available` :
+                                    'No expressions available'
+                        });
+                    }
+                }
+                catch (e) {
+                    // Skip locations that error
+                    continue;
+                }
+            }
+        }
+        // Sort by score (highest first), then by proximity to original line
+        candidates.sort((a, b) => {
+            if (b.score !== a.score) {
+                return b.score - a.score; // Higher score first
+            }
+            // If scores equal, prefer closer to original line
+            return Math.abs(a.line - lineNumber) - Math.abs(b.line - lineNumber);
+        });
+        // Return top 3
+        return candidates.slice(0, 3);
+    }
+    /**
+     * Get source code from a file at a specific line range
+     */
+    async getSourceCode(url, startLine, endLine) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { Debugger } = this.client;
+        // Find the script IDs for this URL (with fallback matching for partial URLs)
+        const match = this.findScriptIds(url);
+        if (!match) {
+            throw new Error(`Script not found for URL: ${url}. Make sure the script has been loaded/parsed.`);
+        }
+        const scriptIds = match.scriptIds;
+        // If multiple scripts, find the one containing the requested line range
+        let scriptId;
+        let fullSource;
+        let totalLines;
+        if (scriptIds.length === 1) {
+            // Only one script - use it
+            scriptId = scriptIds[0];
+            const result = await Debugger.getScriptSource({ scriptId });
+            fullSource = result.scriptSource;
+            totalLines = fullSource.split('\n').length;
+        }
+        else {
+            // Multiple scripts - find the one containing the requested line
+            const targetLine = startLine || 1;
+            let found = false;
+            for (const sid of scriptIds) {
+                const result = await Debugger.getScriptSource({ scriptId: sid });
+                const source = result.scriptSource;
+                const lineCount = source.split('\n').length;
+                // Check if this script contains the requested line
+                if (targetLine <= lineCount) {
+                    scriptId = sid;
+                    fullSource = source;
+                    totalLines = lineCount;
+                    found = true;
+                    break;
+                }
+            }
+            if (!found) {
+                throw new Error(`Line ${targetLine} not found in any script for URL: ${url}. This URL has ${scriptIds.length} inline scripts.`);
+            }
+        }
+        // Split into lines
+        const lines = fullSource.split('\n');
+        // Determine the range
+        const start = startLine ? Math.max(1, startLine) : 1;
+        const end = endLine ? Math.min(totalLines, endLine) : (startLine ? Math.min(totalLines, startLine + 9) : totalLines);
+        // Extract the requested lines (convert to 0-indexed)
+        const extractedLines = lines.slice(start - 1, end);
+        // Format with line numbers, truncating source map lines
+        const formattedCode = extractedLines
+            .map((line, index) => {
+            const lineNum = start + index;
+            let displayLine = line;
+            // Detect and truncate inline source maps (they can be huge)
+            if (line.startsWith('//# sourceMappingURL=data:')) {
+                const truncateAt = 60;
+                displayLine = line.substring(0, truncateAt) + `... [source map truncated, ${Math.round(line.length / 1024)}kb]`;
+            }
+            return `${String(lineNum).padStart(4, ' ')} | ${displayLine}`;
+        })
+            .join('\n');
+        // Check if source map is available
+        const hasSourceMap = this.sourceMapHandler?.hasSourceMap(url) || false;
+        return {
+            code: formattedCode,
+            totalLines: totalLines,
+            hasSourceMap,
+        };
+    }
+    /**
+     * Inject a clickable console link in the browser
+     */
+    async injectConsoleLink(url, lineNumber, message) {
+        if (!this.state.connected) {
+            return;
+        }
+        const { Runtime } = this.client;
+        const consoleExpression = `
+      console.log(
+        '${message} %c${url}:${lineNumber}%c',
+        'color: #0066cc; text-decoration: underline; cursor: pointer; font-weight: bold',
+      );
+    `;
+        try {
+            await Runtime.evaluate({ expression: consoleExpression });
+        }
+        catch (error) {
+            // Ignore errors if console injection fails
+        }
+    }
+    /**
+     * Get detailed information about current pause state
+     */
+    getPausedInfo() {
+        if (!this.state.paused) {
+            return { paused: false };
+        }
+        const callStack = this.getCallStack();
+        const location = callStack && callStack.length > 0 ? {
+            url: callStack[0].url,
+            lineNumber: callStack[0].location.lineNumber,
+            columnNumber: callStack[0].location.columnNumber,
+            functionName: callStack[0].functionName,
+        } : undefined;
+        return {
+            paused: true,
+            location,
+            callStack,
+        };
+    }
+    /**
+     * Wait for debugger to pause (for race detection)
+     * Returns a promise that resolves when debugger pauses, or rejects on timeout
+     */
+    waitForPause(timeoutMs = 30000) {
+        debugLog('cdp-manager', `waitForPause called, already paused: ${this.state.paused}, timeout: ${timeoutMs}ms`);
+        if (this.state.paused) {
+            debugLog('cdp-manager', 'waitForPause: already paused, resolving immediately');
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            let resolved = false;
+            const wrappedResolve = () => {
+                if (resolved)
+                    return;
+                resolved = true;
+                debugLog('cdp-manager', 'waitForPause: wrappedResolve called, resolving promise');
+                clearTimeout(timeout);
+                resolve();
+            };
+            const timeout = setTimeout(() => {
+                if (resolved)
+                    return;
+                resolved = true;
+                debugLog('cdp-manager', `waitForPause: timeout after ${timeoutMs}ms, state.paused=${this.state.paused}`);
+                // Remove resolver from list
+                const index = this.pauseResolvers.indexOf(wrappedResolve);
+                if (index > -1) {
+                    this.pauseResolvers.splice(index, 1);
+                }
+                reject(new Error('Timeout waiting for pause'));
+            }, timeoutMs);
+            this.pauseResolvers.push(wrappedResolve);
+            debugLog('cdp-manager', `waitForPause: resolver added, total resolvers: ${this.pauseResolvers.length}`);
+            // Re-check after adding resolver to handle race condition
+            // where pause happened between initial check and push
+            if (this.state.paused) {
+                debugLog('cdp-manager', 'waitForPause: paused detected after adding resolver, resolving');
+                wrappedResolve();
+            }
+        });
+    }
+    /**
+     * Format a CDP RemoteObject value for display
+     * @param value The CDP RemoteObject to format
+     * @param expandObjects Whether to expand object/array contents (default: false for backward compatibility)
+     * @param maxDepth Maximum depth for object expansion (default: 2)
+     * @param currentDepth Current recursion depth (internal use)
+     */
+    async formatValue(value, expandObjects = false, maxDepth = 2, currentDepth = 0) {
+        if (value.type === 'undefined')
+            return 'undefined';
+        if (value.type === 'string')
+            return `"${value.value}"`;
+        if (value.type === 'number' || value.type === 'boolean')
+            return String(value.value);
+        if (value.type === 'object') {
+            if (value.subtype === 'null')
+                return 'null';
+            // Detect and handle DOM nodes specially (never expand)
+            const className = value.className || '';
+            if (className.startsWith('HTML') || className.includes('Element') || value.subtype === 'node') {
+                return `[${className || 'DOMNode'}]`;
+            }
+            // If expansion is disabled or we've hit max depth, return description
+            if (!expandObjects || currentDepth >= maxDepth) {
+                if (value.subtype === 'array')
+                    return `Array(${value.description})`;
+                return value.description || value.className || 'Object';
+            }
+            // Expand object/array contents with smart size limits
+            if (value.objectId) {
+                try {
+                    const { Runtime } = this.client;
+                    const properties = await Runtime.getProperties({
+                        objectId: value.objectId,
+                        ownProperties: true,
+                    });
+                    if (value.subtype === 'array') {
+                        // Smart array handling based on size
+                        const numericProps = properties.result.filter((p) => !isNaN(parseInt(p.name, 10)));
+                        const arrayLength = numericProps.length;
+                        // For large arrays, truncate to first 10 elements
+                        if (arrayLength > 20) {
+                            const arrayElements = [];
+                            let itemsShown = 0;
+                            for (const prop of numericProps.slice(0, 10)) {
+                                const index = parseInt(prop.name, 10);
+                                if (prop.value) {
+                                    arrayElements[index] = await this.formatValue(prop.value, expandObjects, maxDepth, currentDepth + 1);
+                                    itemsShown++;
+                                }
+                            }
+                            // Add truncation indicator
+                            arrayElements.push(`... ${arrayLength - itemsShown} more items (use evaluateExpression to inspect)`);
+                            return arrayElements;
+                        }
+                        // Small arrays - show all elements
+                        const arrayElements = [];
+                        for (const prop of properties.result) {
+                            const index = parseInt(prop.name, 10);
+                            if (!isNaN(index) && prop.value) {
+                                arrayElements[index] = await this.formatValue(prop.value, expandObjects, maxDepth, currentDepth + 1);
+                            }
+                        }
+                        return arrayElements;
+                    }
+                    else {
+                        // Smart object handling based on property count
+                        const validProps = properties.result.filter((p) => p.value && !p.name.startsWith('[['));
+                        const propCount = validProps.length;
+                        // For very large objects, show summary with first few keys
+                        if (propCount > 50) {
+                            const firstKeys = validProps.slice(0, 5).map((p) => p.name);
+                            return `[Object with ${propCount} properties] {${firstKeys.join(', ')}, ...} - use evaluateExpression to inspect`;
+                        }
+                        // For moderately large objects (10-50 props), limit depth
+                        if (propCount > 10 && currentDepth > 0) {
+                            const firstKeys = validProps.slice(0, 10).map((p) => p.name);
+                            return `[Object with ${propCount} properties] {${firstKeys.join(', ')}${propCount > 10 ? ', ...' : ''}}`;
+                        }
+                        // Small objects - expand normally
+                        const objectProps = {};
+                        for (const prop of validProps) {
+                            objectProps[prop.name] = await this.formatValue(prop.value, expandObjects, maxDepth, currentDepth + 1);
+                        }
+                        return objectProps;
+                    }
+                }
+                catch (error) {
+                    // If expansion fails, fall back to description
+                    if (value.subtype === 'array')
+                        return `Array(${value.description})`;
+                    return value.description || value.className || 'Object';
+                }
+            }
+            // No objectId, can't expand
+            if (value.subtype === 'array')
+                return `Array(${value.description})`;
+            return value.description || value.className || 'Object';
+        }
+        if (value.type === 'function') {
+            // Extract just the function name/signature, not the full source
+            const desc = value.description || '';
+            const match = desc.match(/^(function\s+\w+|async\s+function\s+\w+|\w+)\s*\(/);
+            if (match) {
+                return `[Function: ${match[1]}]`;
+            }
+            return '[Function]';
+        }
+        return String(value.value);
+    }
+    /**
+     * Expand a CDP RemoteObject by its objectId
+     * This is used to get full object details for console messages
+     * @param objectId - The CDP object ID to expand
+     * @param maxDepth - Maximum depth for nested object expansion (default: 2)
+     */
+    async expandObjectById(objectId, maxDepth = 2) {
+        if (!this.state.connected || !this.client) {
+            throw new Error('Not connected to debugger');
+        }
+        const { Runtime } = this.client;
+        // Get the object properties
+        const properties = await Runtime.getProperties({
+            objectId,
+            ownProperties: true,
+        });
+        // Build the expanded object
+        const result = {};
+        const validProps = properties.result.filter((p) => p.value && !p.name.startsWith('[['));
+        for (const prop of validProps.slice(0, 20)) { // Limit to 20 properties for console output
+            result[prop.name] = await this.formatValue(prop.value, true, maxDepth, 0);
+        }
+        if (validProps.length > 20) {
+            result['...'] = `(${validProps.length - 20} more properties)`;
+        }
+        return result;
+    }
+    /**
+     * Get all loaded scripts
+     */
+    getAllScripts() {
+        return Array.from(this.scriptIdToUrl.entries()).map(([scriptId, url]) => ({
+            scriptId,
+            url,
+        }));
+    }
+    /**
+     * Search within a specific script using regex
+     */
+    async searchInScript(scriptId, pattern, caseSensitive = false, isRegex = true) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { Debugger } = this.client;
+        try {
+            const result = await Debugger.searchInContent({
+                scriptId,
+                query: pattern,
+                caseSensitive,
+                isRegex,
+            });
+            return (result.result || []).map((match) => ({
+                lineNumber: match.lineNumber,
+                lineContent: match.lineContent,
+            }));
+        }
+        catch (error) {
+            // Script might not support search or other error
+            return [];
+        }
+    }
+    /**
+     * Get a specific line from a script by scriptId and line number
+     * Returns the full line content (useful for getting full webpack eval lines)
+     */
+    async getScriptLine(scriptId, lineNumber) {
+        if (!this.state.connected) {
+            return null;
+        }
+        const { Debugger } = this.client;
+        try {
+            const result = await Debugger.getScriptSource({ scriptId });
+            const lines = result.scriptSource.split('\n');
+            // lineNumber is 0-indexed from searchInContent
+            if (lineNumber >= 0 && lineNumber < lines.length) {
+                return lines[lineNumber];
+            }
+            return null;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    // ============================================
+    // DOMDebugger Methods (DOM/Event/XHR Breakpoints)
+    // ============================================
+    /**
+     * Generate a unique ID for advanced breakpoints
+     */
+    generateAdvancedBpId(prefix) {
+        return `${prefix}-${++this.advancedBpCounter}`;
+    }
+    /**
+     * Resolve a CSS selector to a CDP nodeId
+     * @param selector - CSS selector to resolve
+     * @returns nodeId for the element
+     */
+    async resolveSelector(selector) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { DOM } = this.client;
+        // Get document root
+        const { root } = await DOM.getDocument();
+        // Query selector to get nodeId
+        const { nodeId } = await DOM.querySelector({
+            nodeId: root.nodeId,
+            selector,
+        });
+        if (!nodeId || nodeId === 0) {
+            throw new Error(`Element not found: ${selector}`);
+        }
+        return nodeId;
+    }
+    /**
+     * Set a DOM breakpoint on a node
+     * Pauses execution when the specified DOM mutation occurs
+     * @param nodeId - The node ID from resolveSelector
+     * @param type - Type of DOM change to break on
+     * @param selector - Original CSS selector (for reference/display)
+     */
+    async setDOMBreakpoint(nodeId, type, selector) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { DOMDebugger } = this.client;
+        await DOMDebugger.setDOMBreakpoint({ nodeId, type });
+        const id = this.generateAdvancedBpId('dom-bp');
+        const info = {
+            breakpointId: id,
+            type: 'dom',
+            nodeId,
+            domBreakpointType: type,
+            selector,
+        };
+        this.domBreakpoints.set(id, info);
+        return info;
+    }
+    /**
+     * Remove a DOM breakpoint by its ID
+     */
+    async removeDOMBreakpoint(breakpointId) {
+        const bp = this.domBreakpoints.get(breakpointId);
+        if (!bp) {
+            throw new Error(`DOM breakpoint not found: ${breakpointId}`);
+        }
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { DOMDebugger } = this.client;
+        await DOMDebugger.removeDOMBreakpoint({
+            nodeId: bp.nodeId,
+            type: bp.domBreakpointType,
+        });
+        this.domBreakpoints.delete(breakpointId);
+    }
+    /**
+     * Get all DOM breakpoints
+     */
+    getDOMBreakpoints() {
+        return Array.from(this.domBreakpoints.values());
+    }
+    /**
+     * Set an event listener breakpoint
+     * Pauses execution when the specified event fires
+     * @param eventName - DOM event name (e.g., 'click', 'submit', 'input')
+     * @param targetName - Optional EventTarget interface filter (e.g., 'HTMLInputElement')
+     */
+    async setEventListenerBreakpoint(eventName, targetName) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { DOMDebugger } = this.client;
+        await DOMDebugger.setEventListenerBreakpoint({ eventName, targetName });
+        const id = this.generateAdvancedBpId('event-bp');
+        const info = {
+            breakpointId: id,
+            type: 'event',
+            eventName,
+            targetName,
+        };
+        this.eventBreakpoints.set(id, info);
+        return info;
+    }
+    /**
+     * Remove an event listener breakpoint by its ID
+     */
+    async removeEventListenerBreakpoint(breakpointId) {
+        const bp = this.eventBreakpoints.get(breakpointId);
+        if (!bp) {
+            throw new Error(`Event listener breakpoint not found: ${breakpointId}`);
+        }
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { DOMDebugger } = this.client;
+        await DOMDebugger.removeEventListenerBreakpoint({
+            eventName: bp.eventName,
+            targetName: bp.targetName,
+        });
+        this.eventBreakpoints.delete(breakpointId);
+    }
+    /**
+     * Get all event listener breakpoints
+     */
+    getEventListenerBreakpoints() {
+        return Array.from(this.eventBreakpoints.values());
+    }
+    /**
+     * Set an XHR/Fetch breakpoint
+     * Pauses execution when an XHR or Fetch request URL contains the pattern
+     * @param urlPattern - URL substring to match
+     */
+    async setXHRBreakpoint(urlPattern) {
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { DOMDebugger } = this.client;
+        await DOMDebugger.setXHRBreakpoint({ url: urlPattern });
+        const id = this.generateAdvancedBpId('xhr-bp');
+        const info = {
+            breakpointId: id,
+            type: 'xhr',
+            urlPattern,
+        };
+        this.xhrBreakpoints.set(id, info);
+        return info;
+    }
+    /**
+     * Remove an XHR/Fetch breakpoint by its ID
+     */
+    async removeXHRBreakpoint(breakpointId) {
+        const bp = this.xhrBreakpoints.get(breakpointId);
+        if (!bp) {
+            throw new Error(`XHR breakpoint not found: ${breakpointId}`);
+        }
+        if (!this.state.connected) {
+            throw new Error('Not connected to debugger');
+        }
+        const { DOMDebugger } = this.client;
+        await DOMDebugger.removeXHRBreakpoint({ url: bp.urlPattern });
+        this.xhrBreakpoints.delete(breakpointId);
+    }
+    /**
+     * Get all XHR/Fetch breakpoints
+     */
+    getXHRBreakpoints() {
+        return Array.from(this.xhrBreakpoints.values());
+    }
+}
+//# sourceMappingURL=cdp-manager.js.map