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:

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

### Custom Position

```javascript
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**:
```javascript
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**:
```javascript
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**:
```javascript
window.addEventListener('unhandledrejection', (event) => {
    // Captured: rejection reason
});
```

**Example**:
```javascript
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**:
```json
{
  "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)

```javascript
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)

```javascript
// 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

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

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

### Custom Error Reporting

```javascript
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`:

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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:
   ```javascript
   console.log(editor.config.controls.debugControl); // Should be true
   ```

2. Check if DebugControl is loaded:
   ```javascript
   console.log(typeof DebugControl); // Should be 'function'
   ```

3. Verify instance exists:
   ```javascript
   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**:
   ```javascript
   console.log(editor.debugControl.isRecording); // Should be true
   ```

2. **Verify console override**:
   ```javascript
   console.log(typeof editor.debugControl.originalConsole); // Should be 'object'
   ```

3. **Test manually**:
   ```javascript
   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:
   ```javascript
   editor.debugControl.maxMessages = 50; // Lower limit
   ```

2. **Noisy logging**:
   - Pause recording during intensive operations:
   ```javascript
   editor.debugControl.toggleRecording(); // Pause
   // ... intensive work ...
   editor.debugControl.toggleRecording(); // Resume
   ```

3. **Disable in production**:
   ```javascript
   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:
   ```javascript
   editor.debugControl.exportMessages();
   ```
4. Check browser console for errors

---

## Best Practices

### For Development

1. **Enable only in development**:
   ```javascript
   debugControl: window.location.hostname === 'localhost'
   ```

2. **Use meaningful categories**:
   ```javascript
   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**:
   ```javascript
   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:

```javascript
// 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](edit-control.md)** - Document actions
- **[Status Control](status-control.md)** - Document statistics
- **[Contents Control](contents-control.md)** - Navigation

---

**See Also**:
- [API Reference](../api/debug-control.md)
- [Examples](../../examples/)

---

**Version**: 1.0.0
**Last Updated**: 2025-12-16