🤖 Fix splash screen white flash and improve startup error handling (#232)

## Problem

While the splash screen from PR #226 provides instant visual feedback,
two issues remain:

1. **White flash** - Splash window sometimes shows white background
briefly before HTML loads
2. **Silent startup failures** - If the app fails to start, users see
nothing (no window, no error)

## Solution

### Fix White Flash

Set `backgroundColor: '#1f1f1f'` on splash window to match the HTML
background color. This ensures consistent dark background even if HTML
hasn't rendered yet.

### Comprehensive Error Handling

Wrap entire `app.whenReady()` in try/catch to handle all startup
failures:
- Close splash screen if startup fails
- Show error dialog with full error message and stack trace  
- Quit app gracefully after showing error
- Users always see what went wrong instead of silent black screen

### Documentation Updates

- Corrected service load time (~100ms, not ~6-13s) in code comments
- Added note that spinner may freeze briefly during service loading
- This is acceptable since splash still provides visual feedback

## Testing

- ✅ TypeScript checks pass
- ✅ ESLint passes (only pre-existing warnings)
- ✅ Manual testing confirms no white flash
- ✅ Error handling tested by introducing deliberate startup error

## Impact

- ✅ No white flash - consistent dark background from first frame
- ✅ Better error UX - users see what went wrong during startup  
- ✅ More accurate documentation

## Related

- Builds on PR #226 (splash screen)
- Complements PR #230 (E2E test fixes)
- See issue #231 for future tree-shaking optimization

Simple, reliable improvements without added complexity.

_Generated with `cmux`_

---------

Co-authored-by: Ammar Bandukwala <[email protected]>

Author: ammar-agent

src/main.ts

@@ -221,6 +221,7 @@ async function showSplashScreen() {
     height: 300,
     frame: false,
     transparent: false,
+    backgroundColor: "#1f1f1f", // Match splash HTML background (hsl(0 0% 12%)) - prevents white flash
     alwaysOnTop: true,
     center: true,
     resizable: false,
@@ -266,8 +267,9 @@ function closeSplashScreen() {
 /**
  * Load backend services (Config, IpcMain, AI SDK, tokenizer)
  *
- * Heavy initialization (~6-13s) happens here while splash is visible.
- * This is the slow part that delays app startup.
+ * Heavy initialization (~100ms) happens here while splash is visible.
+ * Note: Spinner may freeze briefly during this phase. This is acceptable since
+ * the splash still provides visual feedback that the app is loading.
  */
 async function loadServices(): Promise<void> {
   if (config && ipcMain && loadTokenizerModulesFn) return; // Already loaded
@@ -278,7 +280,7 @@ async function loadServices(): Promise<void> {
   /* eslint-disable no-restricted-syntax */
   // Dynamic imports are justified here for performance:
   // - IpcMain transitively imports the entire AI SDK (ai, @ai-sdk/anthropic, etc.)
-  // - These are large modules (~6-13s load time) that would block splash from appearing
+  // - These are large modules (~100ms load time) that would block splash from appearing
   // - Loading happens once, then cached
   const [
     { Config: ConfigClass },
@@ -368,45 +370,63 @@ function createWindow() {
 // Only setup app handlers if we got the lock
 if (gotTheLock) {
   void app.whenReady().then(async () => {
-    console.log("App ready, creating window...");
+    try {
+      console.log("App ready, creating window...");
+
+      // Install React DevTools in development
+      if (!app.isPackaged && installExtension && REACT_DEVELOPER_TOOLS) {
+        try {
+          const extension = await installExtension(REACT_DEVELOPER_TOOLS, {
+            loadExtensionOptions: { allowFileAccess: true },
+          });
+          console.log(`✅ React DevTools installed: ${extension.name} (id: ${extension.id})`);
+        } catch (err) {
+          console.log("❌ Error installing React DevTools:", err);
+        }
+      }
 
-    // Install React DevTools in development
-    if (!app.isPackaged && installExtension && REACT_DEVELOPER_TOOLS) {
-      try {
-        const extension = await installExtension(REACT_DEVELOPER_TOOLS, {
-          loadExtensionOptions: { allowFileAccess: true },
+      createMenu();
+
+      // Three-phase startup:
+      // 1. Show splash immediately (<100ms) and wait for it to load
+      // 2. Load services while splash visible (fast - ~100ms)
+      // 3. Create window and start loading content (splash stays visible)
+      // 4. When window ready-to-show: close splash, show main window
+      //
+      // Skip splash in E2E tests to avoid app.firstWindow() grabbing the wrong window
+      if (!isE2ETest) {
+        await showSplashScreen(); // Wait for splash to actually load
+      }
+      await loadServices();
+      createWindow();
+      // Note: splash closes in ready-to-show event handler
+
+      // Start loading tokenizer modules in background after window is created
+      // This ensures accurate token counts for first API calls (especially in e2e tests)
+      // Loading happens asynchronously and won't block the UI
+      if (loadTokenizerModulesFn) {
+        void loadTokenizerModulesFn().then(() => {
+          console.log(`[${timestamp()}] Tokenizer modules loaded`);
         });
-        console.log(`✅ React DevTools installed: ${extension.name} (id: ${extension.id})`);
-      } catch (err) {
-        console.log("❌ Error installing React DevTools:", err);
       }
-    }
+      // No need to auto-start workspaces anymore - they start on demand
+    } catch (error) {
+      console.error(`[${timestamp()}] Startup failed:`, error);
 
-    createMenu();
+      closeSplashScreen();
 
-    // Three-phase startup:
-    // 1. Show splash immediately (<100ms) and wait for it to load
-    // 2. Load services while splash visible (fast - ~100ms)
-    // 3. Create window and start loading content (splash stays visible)
-    // 4. When window ready-to-show: close splash, show main window
-    //
-    // Skip splash in E2E tests to avoid app.firstWindow() grabbing the wrong window
-    if (!isE2ETest) {
-      await showSplashScreen(); // Wait for splash to actually load
-    }
-    await loadServices();
-    createWindow();
-    // Note: splash closes in ready-to-show event handler
-
-    // Start loading tokenizer modules in background after window is created
-    // This ensures accurate token counts for first API calls (especially in e2e tests)
-    // Loading happens asynchronously and won't block the UI
-    if (loadTokenizerModulesFn) {
-      void loadTokenizerModulesFn().then(() => {
-        console.log(`[${timestamp()}] Tokenizer modules loaded`);
-      });
+      // Show error dialog to user
+      const errorMessage =
+        error instanceof Error ? `${error.message}\n\n${error.stack ?? ""}` : String(error);
+
+      dialog.showErrorBox(
+        "Startup Failed",
+        `The application failed to start:\n\n${errorMessage}\n\nPlease check the console for details.`
+      );
+
+      // Quit after showing error
+      app.quit();
     }
-    // No need to auto-start workspaces anymore - they start on demand
   });
 
   app.on("window-all-closed", () => {