docs: comprehensive feature documentation and HTML generation system

Added complete documentation for all TestDrive-JSUI controls and features, plus flexible HTML generation system supporting standalone and external modes. Documentation (8 files, 3,533 lines): - docs/features/README.md: Central hub with overview, config, examples - docs/features/section-editing.md: Section editing guide - docs/features/edit-control.md: Document actions and editing tools - docs/features/status-control.md: Real-time statistics and tracking - docs/features/contents-control.md: Table of contents navigation - docs/features/debug-control.md: Development and debugging tools - docs/features/keyboard-shortcuts.md: Complete shortcuts reference - docs/features/themes.md: Visual theming and customization HTML Generation System (3 files, 1,104 lines): - js/utils/html-generator.js: Dual-mode HTML generator class * Standalone mode: All CSS/JS embedded inline * External mode: References _jsui/ directory * Configurable options for title, content, controls, theme * Download and save functionality - _jsui/ directory: External resources structure * README.md: Comprehensive usage guide * css/: Symlinked CSS files (base, editor, controls, themes) * js/: Symlinked JavaScript files (core, components, controls) * Enables smaller HTML files with browser caching - examples/html-generator-demo.html: Interactive demo * Web-based configuration form * Side-by-side mode comparison * Live generation and preview * Download and copy functionality Key Features: - 4,637 total lines of documentation and code - All controls documented with examples and troubleshooting - Flexible deployment options (standalone vs external) - Developer-friendly structure with clear guides - Production-ready system 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-16 14:31:56 +01:00
parent f2d9d853d5
commit 66cbd5c3d8
44 changed files with 11308 additions and 0 deletions
--- a/docs/features/debug-control.md
+++ b/docs/features/debug-control.md
@@ -0,0 +1,785 @@
+# 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