koring-launcher/CRASH_MONITOR_PLAN.md

Crash Monitor Implementation Plan

1. Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    Main Process                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │ Crash Logger (file-based, survives crashes)       │  │
│  │ - ipcMain.on('renderer-error') → write to file    │  │
│  │ - process.on('uncaughtException') → write to file │  │
│  │ - app.on('render-process-gone') → write to file   │  │
│  │ - app.on('child-process-gone') → write to file    │  │
│  └──────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────┐                      │
│  │ UtilityProcess (monitor)     │  ← isolated process  │
│  │ - Watches crash log file     │    survives window    │
│  │ - Sends crash events via     │    crashes           │
│  │   MessagePort to main        │                      │
│  └──────────────────────────────┘                      │
│  ┌──────────────────────────────┐                      │
│  │ Crash Monitor Window         │  ← separate window   │
│  │ - Shows crash dialogs        │    custom UI          │
│  │ - Log viewer window          │                      │
│  └──────────────────────────────┘                      │
└─────────────────────────────────────────────────────────┘
         ↕ IPC (contextBridge)
┌─────────────────────────────────────────────────────────┐
│  Renderer (Main Window)                                 │
│  - window.onerror → ipcRenderer.send('renderer-error')  │
│  - unhandledrejection → ipcRenderer.send(...)           │
│  - webContents 'render-process-gone' → recover          │
└─────────────────────────────────────────────────────────┘

2. Implementation Steps

Step 1: Create Crash Logger Module

File: electron/core/crash-logger.ts

• Initialize crash log path (koring-crash.log next to executable)
• Write crash events synchronously to survive crashes
• Buffer recent events for breadcrumb trail
• Log rotation (keep last 1000 lines)

Step 2: Create Crash Monitor Window

File: electron/handlers/crash-monitor.ts

• Separate BrowserWindow (hidden by default)
• Listens for crash events from main process
• Shows custom crash dialog UI
• Can be opened from developer tools

Step 3: Create Log Viewer Window

File: electron/handlers/log-viewer.ts

• Separate BrowserWindow for viewing logs
• Real-time log streaming via IPC
• Filter by log level (error, warn, info)
• Export logs functionality

Step 4: Create Crash Dialog UI

File: src/components/crash/CrashDialog.tsx

• Custom styled crash dialog
• Shows error details, stack trace
• Options: Restart, View Logs, Close
• Uses existing UI components (shadcn/ui)

Step 5: Create Log Viewer UI

File: src/components/crash/LogViewer.tsx

• Log list with syntax highlighting
• Search/filter functionality
• Real-time updates

Step 6: Update Main Process

File: electron/main.ts

• Initialize crash logger early
• Set up crash event handlers
• Create crash monitor window

Step 7: Update Preload Script

File: electron/preload.ts

• Add renderer error capture
• Expose crash-related IPC methods

3. Key Features

1. Crash Detection:

   • Renderer crashes (render-process-gone)
   • Main process errors (uncaughtException, unhandledRejection)
   • GPU/utility crashes (child-process-gone)
   • Unresponsive detection (unresponsive event)

2. Crash Dialog:

   • Custom styled UI matching launcher theme
   • Error message and stack trace display
   • One-click restart option
   • View logs option

3. Log Viewer:

   • Can be opened from developer tools
   • Real-time log streaming
   • Search and filter capabilities
   • Export functionality

4. Process Isolation:

   • Crash monitor runs in separate window
   • Main window crashes don't affect monitor
   • Monitor can restart main window

4. Files to Create/Modify

New Files:

• electron/core/crash-logger.ts
• electron/handlers/crash-monitor.ts
• electron/handlers/log-viewer.ts
• src/components/crash/CrashDialog.tsx
• src/components/crash/LogViewer.tsx
• src/pages/crash/index.tsx

Modified Files:

• electron/main.ts - Add crash monitoring initialization
• electron/preload.ts - Add error capture and IPC methods
• src/types/electron.d.ts - Add new IPC method types

5. UI Design

The crash dialog and log viewer will use the existing design system:

• Glass effects with backdrop-filter
• Dark theme compatible
• Consistent spacing and typography
• Uses shadcn/ui components where appropriate

6. Testing Plan

1. Test crash detection by triggering intentional errors
2. Verify crash dialog appears correctly
3. Test log viewer functionality
4. Verify main window can be restarted from crash dialog
5. Test log export functionality

7. Questions for User

1. What specific crash scenarios should we prioritize?
2. Do you want the log viewer always accessible or only in dev mode?
3. Should crash reports be sent to a server or just stored locally?
4. Any specific UI preferences for the crash dialog beyond the existing design system?