browser-debug.js

/**
 * browser-debug.js - Diagnostic instrumentation for BrowserApp
 *
 * Wraps BrowserApp methods to trace event flow with correlation IDs.
 * Outputs structured logs to console and collects for analysis.
 */

const DEBUG_LOG = [];
let correlationCounter = 0;
const DEBUG_CONSOLE_ENABLED = false;

function debugConsole(method, ...args) {
    if (!DEBUG_CONSOLE_ENABLED) return;
    console[method](...args);
}

function generateCorrelationId() {
    return `evt-${++correlationCounter}-${Date.now()}`;
}

function debugLog(correlationId, event, data) {
    const entry = {
        correlationId,
        timestamp: new Date().toISOString(),
        event,
        data,
        stack: new Error().stack.split('\n').slice(2, 6).join('\n')
    };
    DEBUG_LOG.push(entry);
    debugConsole('log', `[DEBUG ${correlationId}] ${event}`, JSON.stringify(data, null, 2));
    return entry;
}

// Expose for console inspection
window.DEBUG_LOG = DEBUG_LOG;
window.getDebugLog = () => JSON.stringify(DEBUG_LOG, null, 2);
window.clearDebugLog = () => { DEBUG_LOG.length = 0; correlationCounter = 0; };
window.printDebugSummary = () => {
    const summary = {};
    DEBUG_LOG.forEach(e => {
        summary[e.event] = (summary[e.event] || 0) + 1;
    });
    console.table(summary);
    return summary;
};

/**
 * Instruments a BrowserApp instance for debugging.
 * Call this after BrowserApp is constructed.
 */
export function instrumentBrowserApp(browserApp) {
    const webviewEl = browserApp.webviewEl;
    const webviewId = browserApp.webviewId;

    if (!webviewEl) {
        debugConsole('error', '[DEBUG] Cannot instrument: webviewEl is null for', webviewId);
        return browserApp;
    }

    debugConsole('log', `[DEBUG] Instrumenting BrowserApp for webviewId=${webviewId}`);

    // Check if createTab exists
    if (typeof webviewEl.createTab !== 'function') {
        debugConsole('error', '[DEBUG] webviewEl.createTab is not a function:', typeof webviewEl.createTab);
        return browserApp;
    }

    // Track all createTab calls with stack trace
    const originalCreateTab = webviewEl.createTab.bind(webviewEl);
    let createTabCallCount = 0;
    webviewEl.createTab = function(url) {
        const callNum = ++createTabCallCount;
        const cid = generateCorrelationId();
        const stack = new Error().stack;
        debugLog(cid, 'createTab:called', {
            url,
            webviewId,
            callNumber: callNum,
            callerStack: stack.split('\n').slice(1, 5).join('\n')
        });
        return originalCreateTab(url).then(result => {
            debugLog(cid, 'createTab:resolved', { result, callNumber: callNum });
            return result;
        }).catch(err => {
            debugLog(cid, 'createTab:rejected', { error: err.message, callNumber: callNum });
            throw err;
        });
    };

    // Track all switchToTab calls
    const originalSwitchToTab = webviewEl.switchToTab.bind(webviewEl);
    webviewEl.switchToTab = function(index) {
        const cid = generateCorrelationId();
        debugLog(cid, 'switchToTab:called', { index, webviewId });
        return originalSwitchToTab(index).then(result => {
            debugLog(cid, 'switchToTab:resolved', { result });
            return result;
        }).catch(err => {
            debugLog(cid, 'switchToTab:rejected', { error: err.message });
            throw err;
        });
    };

    // Track all closeTab calls
    const originalCloseTab = webviewEl.closeTab.bind(webviewEl);
    webviewEl.closeTab = function(index) {
        const cid = generateCorrelationId();
        debugLog(cid, 'closeTab:called', { index, webviewId });
        return originalCloseTab(index).then(result => {
            debugLog(cid, 'closeTab:resolved', { result });
            return result;
        }).catch(err => {
            debugLog(cid, 'closeTab:rejected', { error: err.message });
            throw err;
        });
    };

    // Track ALL events from webview (in capture phase to see before app handlers)
    const eventsToTrack = [
        'ready', 'api-ready', 'tab-created', 'tab-closed',
        'active-tab-changed', 'did-start-loading', 'did-stop-loading',
        'did-navigate', 'policy-denied'
    ];

    eventsToTrack.forEach(eventName => {
        webviewEl.addEventListener(eventName, (e) => {
            const cid = generateCorrelationId();
            debugLog(cid, `event:${eventName}`, {
                detail: e.detail,
                eventPhase: e.eventPhase
            });
        }, true); // Capture phase
    });

    // Track click events on tab bar with full target info
    const tabBar = browserApp.ui.tabBar;
    if (tabBar) {
        tabBar.addEventListener('click', (e) => {
            const cid = generateCorrelationId();
            debugLog(cid, 'tabBar:click:capture', {
                targetTagName: e.target.tagName,
                targetClassName: e.target.className,
                targetDataset: { ...e.target.dataset },
                closestTab: e.target.closest('.browser-tab-ie')?.dataset || null,
                closestTabClass: e.target.closest('.browser-tab-ie')?.className || null,
                isNewTabBtn: e.target.classList.contains('browser-new-tab-btn-ie'),
                eventPhase: e.eventPhase,
            });
        }, true); // Capture phase to see before other handlers
    }

    // Track new tab button clicks
    const newTabBtn = browserApp.ui.newTabButton;
    if (newTabBtn) {
        newTabBtn.addEventListener('click', (e) => {
            const cid = generateCorrelationId();
            debugLog(cid, 'newTabBtn:click:capture', {
                eventPhase: e.eventPhase,
            });
        }, true); // Capture phase
    }

    debugConsole('log', '[DEBUG] BrowserApp instrumented. Commands:');
    debugConsole('log', '  window.getDebugLog() - get full log as JSON');
    debugConsole('log', '  window.printDebugSummary() - show event counts');
    debugConsole('log', '  window.clearDebugLog() - clear log');

    return browserApp;
}