🤖 Fix splash screen white flash and improve error handling

## Problem
- Splash screen sometimes showed white flash during startup
- No user-visible error messages when startup fails
- Users see black screen with no feedback if app fails to start

## Solution

### 1. Fix White Flash
Added `backgroundColor: '#1f1f1f'` to splash window configuration to match
the splash HTML background color (hsl(0 0% 12%)). This eliminates any white
flash if HTML loads slowly.

### 2. Comprehensive Error Handling
Wrapped entire `app.whenReady()` in try/catch to handle all startup failures:
- Close splash screen on error
- Show error dialog with full error message and stack trace
- Quit app gracefully after showing error
- Ensures users always see startup failures instead of silent black screen

### 3. Update Documentation
- Corrected service load time comment (~100ms, not ~6-13s)
- Added note that spinner may freeze briefly during service loading
- This is acceptable since splash still provides visual feedback

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

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

The backgroundColor fix and error handling are simple, reliable improvements
that don't add complexity. Future performance gains should come from loading
less code (tree-shaking) rather than moving work to worker threads.

Author: ammar-agent

README.md

@@ -58,13 +58,13 @@ Download pre-built binaries from [the releases page](https://github.com/coder/cm
 ## Screenshots
 
 <div align="center">
-  <p><em>Git divergence UI keeps you looped in on changes and potential conflicts:</em></p>
-  <img src="./docs/img/git-status.webp" alt="Screenshot of git status" />
+  <p><em>Mermaid diagrams make it easier to review complex proposals from the Agent:</em></p>
+  <img src="./docs/img/plan-mermaid.webp" alt="Screenshot of mermaid diagram" />
 </div>
 
 <div align="center">
-  <p><em>Mermaid diagrams make it easier to review complex proposals from the Agent:</em></p>
-  <img src="./docs/img/plan-mermaid.webp" alt="Screenshot of mermaid diagram" />
+  <p><em>Git divergence UI keeps you looped in on changes and potential conflicts:</em></p>
+  <img src="./docs/img/git-status.webp" alt="Screenshot of git status" />
 </div>
 
 <div align="center">

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cmux",
-  "version": "0.2.0",
+  "version": "0.1.0",
   "description": "cmux - coder multiplexer",
   "main": "dist/main.js",
   "license": "AGPL-3.0-only",

src/main.ts

@@ -210,6 +210,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,
@@ -255,8 +256,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
@@ -267,7 +269,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 },
@@ -357,45 +359,65 @@ 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", () => {