testdrive-jsui/docs/features/debug-control.md

Debug Control

Development and debugging tools 🐛

The Debug Control provides comprehensive debugging capabilities including real-time console message capture, error tracking, performance monitoring, and system information display. Essential for development, troubleshooting, and quality assurance workflows. Positioned in the west by default. Disabled by default - enable explicitly for development.

---

Overview

The Debug Control serves as a central hub for all debugging activities, capturing console messages, tracking errors, monitoring performance, and displaying system information. Perfect for developers troubleshooting issues or optimizing performance.

Position

• Default: West (w) - middle-left side
• Appearance: 🐛 icon when collapsed
• Title: "Debug"
• Status: Disabled by default (enable for development)

Key Features

• 📝 Console capture - Records all console.log, error, warn, info, debug
• 🚨 Error tracking - Captures global errors and unhandled promises
• 📊 Performance metrics - Page load times, session duration
• 💻 System information - Browser, viewport, memory, language
• 🔍 Message filtering - Filter by error/warn/info/debug levels
• 💾 Export logs - Download debug session as JSON
• ⏸️ Pause/Resume - Control message recording

---

Configuration

Enable Debug Control

Important: Debug control is disabled by default. You must explicitly enable it:

new TestDriveJSUI({
    container: '#editor',
    controls: {
        debugControl: true  // Enable debug panel (default: false)
    }
});

Custom Position

new TestDriveJSUI({
    container: '#editor',
    controls: {
        debugControl: true
    },
    controlPositions: {
        debugControl: 'w'  // West (default), or: nw, ne, e, se, s, sw
    }
});

---

Features

1. Console Message Capture

The Debug Control automatically captures all console output.

Captured Methods

• console.log() → INFO messages
• console.error() → ERROR messages
• console.warn() → WARN messages
• console.info() → INFO messages
• console.debug() → DEBUG messages

How It Works

Initialization:

1. Saves original console methods
2. Overrides each method with custom wrapper
3. Wrapper calls original method (preserves normal console behavior)
4. Wrapper also logs to Debug Control

Example:

console.log('Application started');
// ✅ Shows in browser console (normal)
// ✅ Shows in Debug Control (captured)

Restoration: When Debug Control is destroyed, original console methods are restored.

Message Structure

Each captured message includes:

• Category: LOG, ERROR, WARN, INFO, DEBUG
• Timestamp: Absolute time (HH:MM:SS)
• Relative time: Milliseconds since session start
• Message: Combined text from all arguments
• Level: error, warn, info, debug (for filtering)

---

2. Error Tracking

Captures errors automatically without requiring try/catch blocks.

Global Error Capture

Window errors:

window.addEventListener('error', (event) => {
    // Captured: message, filename, line number
});

Example captured error:

ERROR: Uncaught TypeError: Cannot read property 'foo' of undefined at script.js:42

Unhandled Promise Rejections

Promise rejections:

window.addEventListener('unhandledrejection', (event) => {
    // Captured: rejection reason
});

Example:

fetch('/api/data')
    .then(res => res.json())
    // No .catch() - rejection captured automatically

Captured message:

PROMISE_REJECT: Unhandled promise rejection: NetworkError: Failed to fetch

---

3. System Information

Displays comprehensive browser and environment details.

Displayed Information

Property	Description	Example
Markitect	Version number	1.0.0
Viewport	Window dimensions	1920x1080
Screen	Physical display size	2560x1440
Memory	JavaScript heap usage	Used: 45MB
Language	Browser language	en-US
Status	Online/offline	Online
Protocol	HTTP/HTTPS	https:

Additional info (not displayed but available):

• User agent string
• Color depth
• Timezone
• Cookies enabled

Memory Information

Note: performance.memory is only available in Chrome/Edge with --enable-precise-memory-info flag.

Fallback: Shows "Not available" if memory API unavailable

---

4. Performance Metrics

Real-time performance monitoring.

Metrics Displayed

Metric	Description	Calculation
Page Load	Total page load time	loadEventEnd - navigationStart
DOM Ready	DOM parsing complete	domContentLoadedEventEnd - navigationStart
First Byte	Time to first response byte	responseStart - navigationStart
Session Time	Time since Debug Control started	Current time - startTime
Debug Messages	Total messages captured	messages.length

Units: Milliseconds for load metrics, seconds for session time

Example display:

Page Load: 1247ms
DOM Ready: 892ms
First Byte: 124ms
Session Time: 45s
Debug Messages: 37

---

5. Message Filtering

Filter messages by level to focus on specific types.

Filter Options

• ALL - Show all messages (default)
• ERROR - Only error messages
• WARN - Only warnings
• INFO - Only info messages
• DEBUG - Only debug messages

Usage

Click filter button in Debug Control panel.

Visual feedback:

• Active filter: Blue button
• Inactive filters: Gray buttons

Status display: Shows "Filter: ERROR | Messages: 5/37"

• 5 = filtered count
• 37 = total count

---

6. Message Display

Shows last 20 messages in scrollable container.

Message Appearance

Color coding:

• Error: Red border, red badge (#dc3545)
• Warn: Yellow border, yellow badge (#ffc107)
• Info: Teal border, teal badge (#17a2b8)
• Debug: Gray border, gray badge (#6c757d)

Message format:

┌─────────────────────────────┐
│ [ERROR]     14:32:15       │
│ Cannot read property 'x'   │
└─────────────────────────────┘

Auto-scroll: Enabled by default, scrolls to newest message

Message Limit

Max messages: 100 (oldest messages are discarded)

Displayed: Last 20 messages visible in panel

Reason: Prevent memory issues with long sessions

---

7. Control Actions

Four action buttons for managing debug session.

🗑️ Clear

Removes all captured messages.

Usage: Click "🗑️ Clear" button

Effect:

• Empties messages array
• Clears display
• Also clears MarkitectDebugSystem if present

Use case: Start fresh debugging session

💾 Export

Download debug log as JSON file.

Usage: Click "💾 Export" button

File contents:

{
  "timestamp": "2025-12-16T14:30:52.123Z",
  "session": {
    "startTime": "2025-12-16T14:25:12.456Z",
    "duration": 340000,
    "messageCount": 37
  },
  "system": {
    "userAgent": "Mozilla/5.0...",
    "viewport": "1920x1080",
    "url": "http://localhost:8080/editor.html"
  },
  "messages": [
    {
      "id": 1702742452123.456,
      "timestamp": 1702742452123,
      "category": "ERROR",
      "message": "Cannot read property...",
      "level": "error",
      "displayTime": "14:32:15",
      "relativeTime": 123456
    }
    // ... more messages
  ]
}

Filename: debug-log-YYYY-MM-DD.json

Use cases:

• Share logs with team
• Attach to bug reports
• Archive for analysis

⏸️ Pause / ▶️ Record

Toggle message capture on/off.

Usage: Click "⏸️ Pause" or "▶️ Record" button

States:

• Recording (▶️): Yellow button, captures messages
• Paused (⏸️): Gray button, ignores new messages

Use case: Pause during noisy operations, resume for specific testing

Status indicator: Shows "Recording: 🟢 Active" or "🔴 Paused" at bottom

🧪 Test

Add random test message to verify Debug Control is working.

Usage: Click "🧪 Test" button

Generates: Random message from:

• "This is a test info message" (INFO)
• "This is a test warning message" (WARN)
• "This is a test error message" (ERROR)
• "This is a test debug message" (DEBUG)

Use case: Verify Debug Control is capturing and displaying correctly

---

Examples

Basic Usage (Development Mode)

const editor = new TestDriveJSUI({
    container: '#editor',
    markdown: '# My Document',
    controls: {
        editControl: true,
        statusControl: true,
        contentsControl: true,
        debugControl: true  // Enable for development
    }
});

// Debug messages will be captured
console.log('Editor initialized');
console.error('Oops, something went wrong');

Production Mode (Debug Disabled)

// Default: debug control is OFF
const editor = new TestDriveJSUI({
    container: '#editor',
    controls: {
        debugControl: false  // Explicit disable (default)
    }
});

// Console still works normally, just not captured
console.log('Normal console output');

Environment-Based Configuration

const isDevelopment = window.location.hostname === 'localhost';

const editor = new TestDriveJSUI({
    container: '#editor',
    controls: {
        debugControl: isDevelopment  // Auto-enable in dev
    }
});

Custom Error Reporting

const editor = new TestDriveJSUI({
    container: '#editor',
    controls: { debugControl: true }
});

// Add custom error handler
window.addEventListener('error', (event) => {
    // Send to analytics
    fetch('/api/errors', {
        method: 'POST',
        body: JSON.stringify({
            message: event.message,
            filename: event.filename,
            lineno: event.lineno,
            timestamp: new Date().toISOString()
        })
    });
});

---

API Reference

Properties

Access via editor.debugControl:

const debugCtrl = editor.debugControl;

// Message storage
debugCtrl.messages = [
    {
        id: 1702742452123.456,
        timestamp: 1702742452123,
        category: 'ERROR',
        message: 'Error text',
        level: 'error',
        displayTime: '14:32:15',
        relativeTime: 123456
    },
    // ... more messages
];

// Configuration
debugCtrl.maxMessages = 100;           // Message limit
debugCtrl.messageFilter = 'all';       // Current filter
debugCtrl.autoScroll = true;           // Auto-scroll enabled
debugCtrl.isRecording = true;          // Recording state
debugCtrl.startTime = 1702742452000;   // Session start

// Original console methods (for restoration)
debugCtrl.originalConsole = {
    log: Function,
    error: Function,
    warn: Function,
    info: Function,
    debug: Function
};

// Performance marks
debugCtrl.performanceMarks = new Map();

// Control config
debugCtrl.config.position = 'w';       // Compass position
debugCtrl.config.icon = '🐛';          // Panel icon
debugCtrl.config.title = 'Debug';      // Panel title
debugCtrl.isExpanded;                   // true if expanded

Methods

const debugCtrl = editor.debugControl;

// Add debug message programmatically
debugCtrl.addDebugMessage('CUSTOM', 'Custom message text', 'info');
// Parameters: category, message, level

// Get filtered messages
const filtered = debugCtrl.getFilteredMessages();
// Returns: Array of messages matching current filter

// Clear all messages
debugCtrl.clearMessages();

// Export messages to JSON file
debugCtrl.exportMessages();

// Toggle recording on/off
debugCtrl.toggleRecording();

// Add test message
debugCtrl.addTestMessage();

// Set message filter
debugCtrl.setMessageFilter('error');  // 'all', 'error', 'warn', 'info', 'debug'

// Generate HTML components
const systemInfoHTML = debugCtrl.generateSystemInfoHTML();
const performanceHTML = debugCtrl.generatePerformanceHTML();
const messagesHTML = debugCtrl.generateMessagesHTML();
const buttonsHTML = debugCtrl.generateControlButtonsHTML();
const filterHTML = debugCtrl.generateFilterControlsHTML();

---

Advanced Usage

Custom Message Categories

const editor = new TestDriveJSUI({
    container: '#editor',
    controls: { debugControl: true }
});

// Add custom category messages
editor.debugControl.addDebugMessage('DATABASE', 'Query executed in 45ms', 'info');
editor.debugControl.addDebugMessage('API', 'Request to /api/users completed', 'info');
editor.debugControl.addDebugMessage('AUTH', 'User authentication failed', 'error');

Performance Marking

const debugCtrl = editor.debugControl;

// Mark start of operation
debugCtrl.performanceMarks.set('render-start', Date.now());

// ... perform rendering ...

// Mark end and calculate duration
const startTime = debugCtrl.performanceMarks.get('render-start');
const duration = Date.now() - startTime;
debugCtrl.addDebugMessage('PERF', `Rendering took ${duration}ms`, 'debug');

Conditional Logging

const DEBUG_ENABLED = true;

function debugLog(message) {
    if (DEBUG_ENABLED && editor.debugControl) {
        editor.debugControl.addDebugMessage('APP', message, 'debug');
    }
}

debugLog('User clicked save button');
debugLog('Validation passed');

Batch Export on Error

const editor = new TestDriveJSUI({
    container: '#editor',
    controls: { debugControl: true }
});

// Auto-export logs when critical error occurs
window.addEventListener('error', (event) => {
    if (event.message.includes('Critical')) {
        editor.debugControl.exportMessages();
        alert('Critical error logged. Debug log downloaded.');
    }
});

Monitor Specific Functions

function monitorFunction(fn, name) {
    return function(...args) {
        const startTime = performance.now();
        editor.debugControl.addDebugMessage('CALL', `${name} called with args: ${JSON.stringify(args)}`, 'debug');

        try {
            const result = fn.apply(this, args);
            const duration = performance.now() - startTime;
            editor.debugControl.addDebugMessage('RESULT', `${name} completed in ${duration.toFixed(2)}ms`, 'info');
            return result;
        } catch (error) {
            editor.debugControl.addDebugMessage('ERROR', `${name} failed: ${error.message}`, 'error');
            throw error;
        }
    };
}

// Use monitored function
const saveDocument = monitorFunction(originalSaveFunction, 'saveDocument');

---

Troubleshooting

Debug Control Not Appearing

Problem: Panel doesn't show even when enabled

Solutions:

1. Verify configuration:

   console.log(editor.config.controls.debugControl); // Should be true
   

2. Check if DebugControl is loaded:

   console.log(typeof DebugControl); // Should be 'function'
   

3. Verify instance exists:

   console.log(editor.debugControl); // Should be object
   

4. Check browser console for errors

Messages Not Captured

Problem: Console messages don't appear in Debug Control

Solutions:

1. Check recording status:

   console.log(editor.debugControl.isRecording); // Should be true
   

2. Verify console override:

   console.log(typeof editor.debugControl.originalConsole); // Should be 'object'
   

3. Test manually:

   editor.debugControl.addDebugMessage('TEST', 'Manual test', 'info');
   

4. Check if panel is expanded: Click the 🐛 icon to expand

Performance Issues

Problem: Debug Control slows down application

Causes & Solutions:

1. Too many messages:

   • Clear messages regularly
   • Reduce maxMessages:

   editor.debugControl.maxMessages = 50; // Lower limit
   

2. Noisy logging:

   • Pause recording during intensive operations:

   editor.debugControl.toggleRecording(); // Pause
   // ... intensive work ...
   editor.debugControl.toggleRecording(); // Resume
   

3. Disable in production:

   controls: {
       debugControl: process.env.NODE_ENV === 'development'
   }
   

Export Not Working

Problem: Export button doesn't download file

Solutions:

1. Check browser download permissions
2. Verify popup/download blocker settings
3. Test programmatically:

   editor.debugControl.exportMessages();
   

4. Check browser console for errors

---

Best Practices

For Development

1. Enable only in development:

   debugControl: window.location.hostname === 'localhost'
   

2. Use meaningful categories:

   addDebugMessage('USER_ACTION', 'Clicked save', 'info');
   addDebugMessage('VALIDATION', 'Email format invalid', 'warn');
   

3. Export before refreshing: Save logs if you need to refresh page

4. Clear between tests: Start fresh for each test scenario

For QA/Testing

1. Enable for bug reproduction:

   controls: { debugControl: true }
   

2. Export logs with bug reports: Include debug-log.json

3. Filter by ERROR: Focus on failures

4. Track timing: Monitor performance metrics

For Production Debugging

Generally: Keep debug control disabled in production

Exception: Enable temporarily for specific user sessions:

// Enable debug for admin users only
const isAdmin = checkUserRole();
const editor = new TestDriveJSUI({
    controls: {
        debugControl: isAdmin
    }
});

Security note: Debug logs may contain sensitive information (URLs, user actions). Don't expose in production.

---

Performance Considerations

Memory Usage

Per message: ~200 bytes (category, message, timestamps)

• 100 messages: ~20 KB
• 1000 messages: ~200 KB

Max limit: Default 100 messages prevents unbounded growth

CPU Impact

Console override: Minimal overhead (~0.1ms per message)

Display updates: Only when panel is expanded

Auto-scroll: Negligible performance impact

Recommendations

1. Disable in production: Saves memory and CPU
2. Lower maxMessages for long sessions: Prevent accumulation
3. Pause during intensive operations: Reduce overhead
4. Export and clear periodically: Free memory

---

Related Features

• Edit Control - Document actions
• Status Control - Document statistics
• Contents Control - Navigation

---

See Also:

• API Reference
• Examples

---

Version: 1.0.0 Last Updated: 2025-12-16