From 1ff76bb198d44644f5b32905b667bc654281be81 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 13 Oct 2025 13:31:17 -0500
Subject: [PATCH 01/10] =?UTF-8?q?=F0=9F=A4=96=20Add=20splash=20screen=20fo?=
 =?UTF-8?q?r=20instant=20startup=20feedback?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Problem

Users see dock icon but no window for 6-13s during app startup (varies by machine).
Even with lazy-loaded services (#223), the renderer makes IPC calls on mount which
requires services to be loaded first, so the main window can't appear until everything
is ready.

## Solution

Added native splash screen that appears instantly (<100ms) while services load.

## Implementation

**Three-phase startup:**

1. **Show splash** - Native BrowserWindow with static HTML (<100ms)
   - No React, no IPC, no heavy dependencies
   - Matches app theme colors from colors.tsx
   - Shows "Loading services..." with spinner

2. **Load services** - Happens while splash is visible (~6-13s)
   - Config, IpcMain, AI SDK, tokenizer modules
   - User gets instant visual feedback

3. **Show main window** - Close splash, reveal app
   - Services guaranteed ready when window appears
   - Main window uses "ready-to-show" event to avoid white flash

## Changes

- **Added `static/splash.html`** - Lightweight loading screen matching app theme
- **Modified `src/main.ts`** - Three-phase startup with splash screen
- **Updated `Makefile`** - Copy splash.html to dist during build

## Benefits

- ✅ Instant visual feedback (<100ms vs 6-13s black screen)
- ✅ No user confusion ("is it broken?")
- ✅ Services guaranteed ready (no race conditions)
- ✅ Clean transition to main window
- ✅ All tests pass (410 tests)

_Generated with `cmux`_
---
 Makefile           |  8 +++--
 src/main.ts        | 55 ++++++++++++++++++++++++++++++-
 static/splash.html | 81 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 141 insertions(+), 3 deletions(-)
 create mode 100644 static/splash.html

diff --git a/Makefile b/Makefile
index b7ec50ff0..0c3d1edd5 100644
--- a/Makefile
+++ b/Makefile
@@ -22,7 +22,7 @@
 include fmt.mk
 
 .PHONY: all build dev start clean help
-.PHONY: build-renderer version build-icons
+.PHONY: build-renderer version build-icons build-static
 .PHONY: lint lint-fix typecheck static-check
 .PHONY: test test-unit test-integration test-watch test-coverage test-e2e
 .PHONY: dist dist-mac dist-win dist-linux
@@ -62,7 +62,7 @@ start: node_modules/.installed build-main build-preload ## Build and start Elect
 	@bun x electron --remote-debugging-port=9222 .
 
 ## Build targets (can run in parallel)
-build: node_modules/.installed src/version.ts build-renderer build-main build-preload build-icons ## Build all targets
+build: node_modules/.installed src/version.ts build-renderer build-main build-preload build-icons build-static ## Build all targets
 
 build-main: node_modules/.installed dist/main.js ## Build main process
 
@@ -86,6 +86,10 @@ build-renderer: node_modules/.installed src/version.ts ## Build renderer process
 	@echo "Building renderer..."
 	@bun x vite build
 
+build-static: ## Copy static assets to dist
+	@echo "Copying static assets..."
+	@cp static/splash.html dist/splash.html
+
 # Always regenerate version file (marked as .PHONY above)
 version: ## Generate version file
 	@./scripts/generate-version.sh
diff --git a/src/main.ts b/src/main.ts
index 4a86d96ad..fbbbe02e8 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -126,6 +126,7 @@ if (!gotTheLock) {
 }
 
 let mainWindow: BrowserWindow | null = null;
+let splashWindow: BrowserWindow | null = null;
 
 function createMenu() {
   const template: MenuItemConstructorOptions[] = [
@@ -182,6 +183,44 @@ function createMenu() {
   Menu.setApplicationMenu(menu);
 }
 
+/**
+ * Create and show splash screen - instant visual feedback (<100ms)
+ *
+ * Shows a lightweight native window with static HTML while services load.
+ * No IPC, no React, no heavy dependencies - just immediate user feedback.
+ */
+function showSplashScreen() {
+  splashWindow = new BrowserWindow({
+    width: 400,
+    height: 300,
+    frame: false,
+    transparent: true,
+    alwaysOnTop: true,
+    center: true,
+    resizable: false,
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+    },
+  });
+
+  void splashWindow.loadFile(path.join(__dirname, "splash.html"));
+
+  splashWindow.on("closed", () => {
+    splashWindow = null;
+  });
+}
+
+/**
+ * Close splash screen
+ */
+function closeSplashScreen() {
+  if (splashWindow) {
+    splashWindow.close();
+    splashWindow = null;
+  }
+}
+
 async function createWindow() {
   // Lazy-load Config and IpcMain only when window is created
   // This defers loading heavy AI SDK dependencies until actually needed
@@ -218,11 +257,17 @@ async function createWindow() {
     // Hide menu bar on Linux by default (like VS Code)
     // User can press Alt to toggle it
     autoHideMenuBar: process.platform === "linux",
+    show: false, // Don't show until ready-to-show event
   });
 
   // Register IPC handlers with the main window
   ipcMain.register(electronIpcMain, mainWindow);
 
+  // Show window once it's ready to avoid white flash
+  mainWindow.once("ready-to-show", () => {
+    mainWindow?.show();
+  });
+
   // Open all external links in default browser
   mainWindow.webContents.setWindowOpenHandler(({ url }) => {
     void shell.openExternal(url);
@@ -278,7 +323,12 @@ if (gotTheLock) {
     }
 
     createMenu();
+
+    // Show splash screen immediately, then load services, then show main window
+    // This gives instant visual feedback (<100ms) while services load (~6-13s)
+    showSplashScreen();
     await createWindow();
+    closeSplashScreen();
 
     // Start loading tokenizer modules in background after window is created
     // This ensures accurate token counts for first API calls (especially in e2e tests)
@@ -301,7 +351,10 @@ if (gotTheLock) {
     // Only create window if app is ready and no window exists
     // This prevents "Cannot create BrowserWindow before app is ready" error
     if (app.isReady() && mainWindow === null) {
-      void createWindow();
+      showSplashScreen();
+      void createWindow().then(() => {
+        closeSplashScreen();
+      });
     }
   });
 }
diff --git a/static/splash.html b/static/splash.html
new file mode 100644
index 000000000..4004fcbaa
--- /dev/null
+++ b/static/splash.html
@@ -0,0 +1,81 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>cmux - Loading</title>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    body {
+      width: 400px;
+      height: 300px;
+      /* Match --color-background (hsl(0 0% 12%)) */
+      background: hsl(0 0% 12%);
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      /* Match --color-text (hsl(0 0% 83%)) */
+      color: hsl(0 0% 83%);
+      overflow: hidden;
+      border-radius: 12px;
+      box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+    }
+
+    .logo {
+      font-size: 48px;
+      font-weight: 700;
+      letter-spacing: -2px;
+      margin-bottom: 24px;
+      /* Gradient from plan mode blue (hsl(210 70% 40%)) to exec mode purple (hsl(268.56deg 94.04% 55.19%)) */
+      background: linear-gradient(135deg, hsl(210 70% 45%) 0%, hsl(268.56deg 94.04% 55.19%) 100%);
+      -webkit-background-clip: text;
+      -webkit-text-fill-color: transparent;
+      background-clip: text;
+    }
+
+    .loading-text {
+      font-size: 16px;
+      /* Match --color-text-secondary (hsl(0 0% 42%)) */
+      color: hsl(0 0% 42%);
+      margin-bottom: 16px;
+    }
+
+    .spinner {
+      width: 40px;
+      height: 40px;
+      /* Match --color-border (hsl(240 2% 25%)) */
+      border: 3px solid hsl(240 2% 25%);
+      /* Match --color-plan-mode (hsl(210 70% 40%)) */
+      border-top-color: hsl(210 70% 40%);
+      border-radius: 50%;
+      animation: spin 0.8s linear infinite;
+    }
+
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    .version {
+      position: absolute;
+      bottom: 20px;
+      font-size: 11px;
+      /* Match --color-text-secondary (hsl(0 0% 42%)) */
+      color: hsl(0 0% 42%);
+    }
+  </style>
+</head>
+<body>
+  <div class="logo">cmux</div>
+  <div class="loading-text">Loading services...</div>
+  <div class="spinner"></div>
+  <div class="version">coder multiplexer</div>
+</body>
+</html>
+

From fa797d42da797906482f642566eab0a1bcf0c2fe Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 13 Oct 2025 13:33:36 -0500
Subject: [PATCH 02/10] Add console logs for splash screen show/close + ensure
 build-static runs on start

---
 Makefile    | 2 +-
 src/main.ts | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 0c3d1edd5..5006b16e2 100644
--- a/Makefile
+++ b/Makefile
@@ -58,7 +58,7 @@ dev: node_modules/.installed build-main ## Start development server (Vite + Type
 		"bun x concurrently \"bun x tsc -w -p tsconfig.main.json\" \"bun x tsc-alias -w -p tsconfig.main.json\"" \
 		"vite"
 
-start: node_modules/.installed build-main build-preload ## Build and start Electron app
+start: node_modules/.installed build-main build-preload build-static ## Build and start Electron app
 	@bun x electron --remote-debugging-port=9222 .
 
 ## Build targets (can run in parallel)
diff --git a/src/main.ts b/src/main.ts
index fbbbe02e8..c2c1450a2 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -190,6 +190,7 @@ function createMenu() {
  * No IPC, no React, no heavy dependencies - just immediate user feedback.
  */
 function showSplashScreen() {
+  console.log("Showing splash screen...");
   splashWindow = new BrowserWindow({
     width: 400,
     height: 300,
@@ -216,6 +217,7 @@ function showSplashScreen() {
  */
 function closeSplashScreen() {
   if (splashWindow) {
+    console.log("Closing splash screen...");
     splashWindow.close();
     splashWindow = null;
   }

From d26388d90aa0bd2d66fcc166d308706ab3730f62 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 13 Oct 2025 13:35:20 -0500
Subject: [PATCH 03/10] Fix: Extract service loading out of createWindow to
 keep splash visible during heavy loading

The issue was services were loading inside createWindow(), so splash closed
immediately after loading finished. Now services load while splash is visible,
giving proper visual feedback during the 6-13s startup time.
---
 src/main.ts | 71 +++++++++++++++++++++++++++++++++--------------------
 1 file changed, 45 insertions(+), 26 deletions(-)

diff --git a/src/main.ts b/src/main.ts
index c2c1450a2..df2654672 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -223,28 +223,43 @@ function closeSplashScreen() {
   }
 }
 
-async function createWindow() {
-  // Lazy-load Config and IpcMain only when window is created
-  // This defers loading heavy AI SDK dependencies until actually needed
-  if (!config || !ipcMain || !loadTokenizerModulesFn) {
-    /* 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 that would block app startup if loaded statically
-    // - Loading happens once on first window creation, then cached
-    const [
-      { Config: ConfigClass },
-      { IpcMain: IpcMainClass },
-      { loadTokenizerModules: loadTokenizerFn },
-    ] = await Promise.all([
-      import("./config"),
-      import("./services/ipcMain"),
-      import("./utils/main/tokenizer"),
-    ]);
-    /* eslint-enable no-restricted-syntax */
-    config = new ConfigClass();
-    ipcMain = new IpcMainClass(config);
-    loadTokenizerModulesFn = loadTokenizerFn;
+/**
+ * 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.
+ */
+async function loadServices(): Promise<void> {
+  if (config && ipcMain && loadTokenizerModulesFn) return; // Already loaded
+
+  console.log("Loading services...");
+  const startTime = Date.now();
+
+  /* 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
+  // - Loading happens once, then cached
+  const [
+    { Config: ConfigClass },
+    { IpcMain: IpcMainClass },
+    { loadTokenizerModules: loadTokenizerFn },
+  ] = await Promise.all([
+    import("./config"),
+    import("./services/ipcMain"),
+    import("./utils/main/tokenizer"),
+  ]);
+  /* eslint-enable no-restricted-syntax */
+  config = new ConfigClass();
+  ipcMain = new IpcMainClass(config);
+  loadTokenizerModulesFn = loadTokenizerFn;
+
+  console.log(`Services loaded in ${Date.now() - startTime}ms`);
+}
+
+function createWindow() {
+  if (!ipcMain) {
+    throw new Error("Services must be loaded before creating window");
   }
 
   mainWindow = new BrowserWindow({
@@ -326,10 +341,13 @@ if (gotTheLock) {
 
     createMenu();
 
-    // Show splash screen immediately, then load services, then show main window
-    // This gives instant visual feedback (<100ms) while services load (~6-13s)
+    // Three-phase startup:
+    // 1. Show splash immediately (<100ms)
+    // 2. Load services while splash visible (~6-13s)
+    // 3. Show main window, close splash
     showSplashScreen();
-    await createWindow();
+    await loadServices();
+    createWindow();
     closeSplashScreen();
 
     // Start loading tokenizer modules in background after window is created
@@ -354,7 +372,8 @@ if (gotTheLock) {
     // This prevents "Cannot create BrowserWindow before app is ready" error
     if (app.isReady() && mainWindow === null) {
       showSplashScreen();
-      void createWindow().then(() => {
+      void loadServices().then(() => {
+        createWindow();
         closeSplashScreen();
       });
     }

From 70ebccf7e2f5fc214bf9ada066fb9d9ba8b605a3 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 13 Oct 2025 13:37:41 -0500
Subject: [PATCH 04/10] Fix: Close splash only when main window is
 ready-to-show

The real delay is loading the renderer (React app, JS parsing), not services.
Now splash stays visible until the main window's ready-to-show event fires,
keeping it on screen for the full 6-13s startup time.

Console output will now be:
- Showing splash screen...
- Loading services...
- Services loaded in ~100ms
- [6-13s delay while renderer loads]
- Main window ready to show
- Closing splash screen...
- Tokenizer modules loaded
---
 src/main.ts | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/main.ts b/src/main.ts
index df2654672..1caaee980 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -280,9 +280,11 @@ function createWindow() {
   // Register IPC handlers with the main window
   ipcMain.register(electronIpcMain, mainWindow);
 
-  // Show window once it's ready to avoid white flash
+  // Show window once it's ready and close splash
   mainWindow.once("ready-to-show", () => {
+    console.log("Main window ready to show");
     mainWindow?.show();
+    closeSplashScreen();
   });
 
   // Open all external links in default browser
@@ -343,12 +345,13 @@ if (gotTheLock) {
 
     // Three-phase startup:
     // 1. Show splash immediately (<100ms)
-    // 2. Load services while splash visible (~6-13s)
-    // 3. Show main window, close splash
+    // 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
     showSplashScreen();
     await loadServices();
     createWindow();
-    closeSplashScreen();
+    // 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)
@@ -374,7 +377,7 @@ if (gotTheLock) {
       showSplashScreen();
       void loadServices().then(() => {
         createWindow();
-        closeSplashScreen();
+        // Note: splash closes in ready-to-show event handler
       });
     }
   });

From 50dc4fa923d93e1d6546d25cdbaaa3d110f9f598 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 13 Oct 2025 13:38:47 -0500
Subject: [PATCH 05/10] Fix splash visibility and parallel build safety

- Set transparent: false for better visibility
- Add show: true to ensure splash appears immediately
- Add error handling and success logging for splash.html loading
- Fix parallel build: mkdir -p dist before copying splash.html

This addresses Codex P1 comment about parallel build race condition.
---
 Makefile    |  1 +
 src/main.ts | 12 ++++++++++--
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 5006b16e2..f1f5534d9 100644
--- a/Makefile
+++ b/Makefile
@@ -88,6 +88,7 @@ build-renderer: node_modules/.installed src/version.ts ## Build renderer process
 
 build-static: ## Copy static assets to dist
 	@echo "Copying static assets..."
+	@mkdir -p dist
 	@cp static/splash.html dist/splash.html
 
 # Always regenerate version file (marked as .PHONY above)
diff --git a/src/main.ts b/src/main.ts
index 1caaee980..d3bba64c6 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -195,19 +195,27 @@ function showSplashScreen() {
     width: 400,
     height: 300,
     frame: false,
-    transparent: true,
+    transparent: false, // Changed to false for better visibility
     alwaysOnTop: true,
     center: true,
     resizable: false,
+    show: true, // Explicitly show immediately
     webPreferences: {
       nodeIntegration: false,
       contextIsolation: true,
     },
   });
 
-  void splashWindow.loadFile(path.join(__dirname, "splash.html"));
+  splashWindow.loadFile(path.join(__dirname, "splash.html"))
+    .then(() => {
+      console.log("Splash screen HTML loaded successfully");
+    })
+    .catch((err) => {
+      console.error("Failed to load splash screen:", err);
+    });
 
   splashWindow.on("closed", () => {
+    console.log("Splash screen closed event");
     splashWindow = null;
   });
 }

From f570bd6f418b9ccb187dfc7fcf4869d62e8ac759 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 13 Oct 2025 13:41:18 -0500
Subject: [PATCH 06/10] Fix splash timing: wait for HTML to load + add
 millisecond timestamps

Key fixes:
- Make showSplashScreen() async and await loadFile() before showing
- Set show: false initially, then show() after HTML loads
- This ensures splash is visible BEFORE services load
- Add millisecond timestamps to all startup console.logs for debugging

Now the sequence will be:
1. [timestamp] Showing splash screen...
2. [timestamp] Splash screen loaded and visible (Xms)
3. [timestamp] Loading services...
4. [timestamp] Services loaded in Xms
5. [6-13s delay while renderer loads]
6. [timestamp] Main window ready to show
7. [timestamp] Closing splash screen...
8. [timestamp] Tokenizer modules loaded
---
 src/main.ts | 48 +++++++++++++++++++++++++-----------------------
 1 file changed, 25 insertions(+), 23 deletions(-)

diff --git a/src/main.ts b/src/main.ts
index d3bba64c6..10b388270 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -189,33 +189,34 @@ function createMenu() {
  * Shows a lightweight native window with static HTML while services load.
  * No IPC, no React, no heavy dependencies - just immediate user feedback.
  */
-function showSplashScreen() {
-  console.log("Showing splash screen...");
+async function showSplashScreen() {
+  const startTime = Date.now();
+  console.log(`[${startTime}] Showing splash screen...`);
+  
   splashWindow = new BrowserWindow({
     width: 400,
     height: 300,
     frame: false,
-    transparent: false, // Changed to false for better visibility
+    transparent: false,
     alwaysOnTop: true,
     center: true,
     resizable: false,
-    show: true, // Explicitly show immediately
+    show: false, // Don't show until HTML is loaded
     webPreferences: {
       nodeIntegration: false,
       contextIsolation: true,
     },
   });
 
-  splashWindow.loadFile(path.join(__dirname, "splash.html"))
-    .then(() => {
-      console.log("Splash screen HTML loaded successfully");
-    })
-    .catch((err) => {
-      console.error("Failed to load splash screen:", err);
-    });
+  // Wait for splash HTML to load before showing
+  await splashWindow.loadFile(path.join(__dirname, "splash.html"));
+  splashWindow.show();
+  
+  const loadTime = Date.now() - startTime;
+  console.log(`[${Date.now()}] Splash screen loaded and visible (${loadTime}ms)`);
 
   splashWindow.on("closed", () => {
-    console.log("Splash screen closed event");
+    console.log(`[${Date.now()}] Splash screen closed event`);
     splashWindow = null;
   });
 }
@@ -225,7 +226,7 @@ function showSplashScreen() {
  */
 function closeSplashScreen() {
   if (splashWindow) {
-    console.log("Closing splash screen...");
+    console.log(`[${Date.now()}] Closing splash screen...`);
     splashWindow.close();
     splashWindow = null;
   }
@@ -240,8 +241,8 @@ function closeSplashScreen() {
 async function loadServices(): Promise<void> {
   if (config && ipcMain && loadTokenizerModulesFn) return; // Already loaded
 
-  console.log("Loading services...");
   const startTime = Date.now();
+  console.log(`[${startTime}] Loading services...`);
 
   /* eslint-disable no-restricted-syntax */
   // Dynamic imports are justified here for performance:
@@ -262,7 +263,8 @@ async function loadServices(): Promise<void> {
   ipcMain = new IpcMainClass(config);
   loadTokenizerModulesFn = loadTokenizerFn;
 
-  console.log(`Services loaded in ${Date.now() - startTime}ms`);
+  const loadTime = Date.now() - startTime;
+  console.log(`[${Date.now()}] Services loaded in ${loadTime}ms`);
 }
 
 function createWindow() {
@@ -290,7 +292,7 @@ function createWindow() {
 
   // Show window once it's ready and close splash
   mainWindow.once("ready-to-show", () => {
-    console.log("Main window ready to show");
+    console.log(`[${Date.now()}] Main window ready to show`);
     mainWindow?.show();
     closeSplashScreen();
   });
@@ -352,11 +354,11 @@ if (gotTheLock) {
     createMenu();
 
     // Three-phase startup:
-    // 1. Show splash immediately (<100ms)
+    // 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
-    showSplashScreen();
+    await showSplashScreen(); // Wait for splash to actually load
     await loadServices();
     createWindow();
     // Note: splash closes in ready-to-show event handler
@@ -366,7 +368,7 @@ if (gotTheLock) {
     // Loading happens asynchronously and won't block the UI
     if (loadTokenizerModulesFn) {
       void loadTokenizerModulesFn().then(() => {
-        console.log("Tokenizer modules loaded");
+        console.log(`[${Date.now()}] Tokenizer modules loaded`);
       });
     }
     // No need to auto-start workspaces anymore - they start on demand
@@ -382,11 +384,11 @@ if (gotTheLock) {
     // Only create window if app is ready and no window exists
     // This prevents "Cannot create BrowserWindow before app is ready" error
     if (app.isReady() && mainWindow === null) {
-      showSplashScreen();
-      void loadServices().then(() => {
+      void (async () => {
+        await showSplashScreen();
+        await loadServices();
         createWindow();
-        // Note: splash closes in ready-to-show event handler
-      });
+      })();
     }
   });
 }

From 374cfe91a6b3b92f25add0532abad93742e811b8 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 13 Oct 2025 13:43:08 -0500
Subject: [PATCH 07/10] Use human-readable timestamps (HH:MM:SS.mmm) in startup
 logs

Example output:
[13:25:10.092] Showing splash screen...
[13:25:10.200] Splash screen loaded and visible (108ms)
[13:25:10.201] Loading services...
[13:25:10.303] Services loaded in 102ms
[13:25:18.478] Tokenizer modules loaded
[13:25:18.877] Main window ready to show
[13:25:18.878] Closing splash screen...
---
 src/main.ts | 28 ++++++++++++++++++++--------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/src/main.ts b/src/main.ts
index 10b388270..7bcf0eb59 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -128,6 +128,18 @@ if (!gotTheLock) {
 let mainWindow: BrowserWindow | null = null;
 let splashWindow: BrowserWindow | null = null;
 
+/**
+ * Format timestamp as HH:MM:SS.mmm for readable logging
+ */
+function timestamp(): string {
+  const now = new Date();
+  const hours = String(now.getHours()).padStart(2, "0");
+  const minutes = String(now.getMinutes()).padStart(2, "0");
+  const seconds = String(now.getSeconds()).padStart(2, "0");
+  const ms = String(now.getMilliseconds()).padStart(3, "0");
+  return `${hours}:${minutes}:${seconds}.${ms}`;
+}
+
 function createMenu() {
   const template: MenuItemConstructorOptions[] = [
     {
@@ -191,7 +203,7 @@ function createMenu() {
  */
 async function showSplashScreen() {
   const startTime = Date.now();
-  console.log(`[${startTime}] Showing splash screen...`);
+  console.log(`[${timestamp()}] Showing splash screen...`);
   
   splashWindow = new BrowserWindow({
     width: 400,
@@ -213,10 +225,10 @@ async function showSplashScreen() {
   splashWindow.show();
   
   const loadTime = Date.now() - startTime;
-  console.log(`[${Date.now()}] Splash screen loaded and visible (${loadTime}ms)`);
+  console.log(`[${timestamp()}] Splash screen loaded and visible (${loadTime}ms)`);
 
   splashWindow.on("closed", () => {
-    console.log(`[${Date.now()}] Splash screen closed event`);
+    console.log(`[${timestamp()}] Splash screen closed event`);
     splashWindow = null;
   });
 }
@@ -226,7 +238,7 @@ async function showSplashScreen() {
  */
 function closeSplashScreen() {
   if (splashWindow) {
-    console.log(`[${Date.now()}] Closing splash screen...`);
+    console.log(`[${timestamp()}] Closing splash screen...`);
     splashWindow.close();
     splashWindow = null;
   }
@@ -242,7 +254,7 @@ async function loadServices(): Promise<void> {
   if (config && ipcMain && loadTokenizerModulesFn) return; // Already loaded
 
   const startTime = Date.now();
-  console.log(`[${startTime}] Loading services...`);
+  console.log(`[${timestamp()}] Loading services...`);
 
   /* eslint-disable no-restricted-syntax */
   // Dynamic imports are justified here for performance:
@@ -264,7 +276,7 @@ async function loadServices(): Promise<void> {
   loadTokenizerModulesFn = loadTokenizerFn;
 
   const loadTime = Date.now() - startTime;
-  console.log(`[${Date.now()}] Services loaded in ${loadTime}ms`);
+  console.log(`[${timestamp()}] Services loaded in ${loadTime}ms`);
 }
 
 function createWindow() {
@@ -292,7 +304,7 @@ function createWindow() {
 
   // Show window once it's ready and close splash
   mainWindow.once("ready-to-show", () => {
-    console.log(`[${Date.now()}] Main window ready to show`);
+    console.log(`[${timestamp()}] Main window ready to show`);
     mainWindow?.show();
     closeSplashScreen();
   });
@@ -368,7 +380,7 @@ if (gotTheLock) {
     // Loading happens asynchronously and won't block the UI
     if (loadTokenizerModulesFn) {
       void loadTokenizerModulesFn().then(() => {
-        console.log(`[${Date.now()}] Tokenizer modules loaded`);
+        console.log(`[${timestamp()}] Tokenizer modules loaded`);
       });
     }
     // No need to auto-start workspaces anymore - they start on demand

From 5538aca408a4caa159fd5db6841953964829263e Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 13 Oct 2025 13:44:25 -0500
Subject: [PATCH 08/10] Add 100ms delay after showing splash to ensure it
 renders

The splash window.show() call was happening but the OS/Electron wasn't
actually rendering it before we continued. Adding a small delay ensures
the splash is visible on screen before we start the heavy work.

This makes the splash actually appear for the full 8+ seconds of loading
instead of only flashing briefly at the end.
---
 src/main.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/main.ts b/src/main.ts
index 7bcf0eb59..f07884961 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -226,6 +226,10 @@ async function showSplashScreen() {
   
   const loadTime = Date.now() - startTime;
   console.log(`[${timestamp()}] Splash screen loaded and visible (${loadTime}ms)`);
+  
+  // Give the OS/Electron time to actually render the splash window before continuing
+  // Without this delay, the window is created but not visible until much later
+  await new Promise((resolve) => setTimeout(resolve, 100));
 
   splashWindow.on("closed", () => {
     console.log(`[${timestamp()}] Splash screen closed event`);

From 930219d7452bffbc685cc3a9dd4b6ab4b14ce174 Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 13 Oct 2025 13:45:03 -0500
Subject: [PATCH 09/10] Wait for splash 'show' event + setImmediate for proper
 rendering

Instead of blindly delaying 100ms, properly wait for:
1. The 'show' event to fire (window is shown)
2. setImmediate to give event loop a tick for painting

This ensures the splash is actually rendered before we block the
main thread with createWindow() and renderer loading.
---
 src/main.ts | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/src/main.ts b/src/main.ts
index f07884961..debb348d9 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -220,16 +220,20 @@ async function showSplashScreen() {
     },
   });
 
-  // Wait for splash HTML to load before showing
+  // Wait for splash HTML to load
   await splashWindow.loadFile(path.join(__dirname, "splash.html"));
-  splashWindow.show();
   
-  const loadTime = Date.now() - startTime;
-  console.log(`[${timestamp()}] Splash screen loaded and visible (${loadTime}ms)`);
-  
-  // Give the OS/Electron time to actually render the splash window before continuing
-  // Without this delay, the window is created but not visible until much later
-  await new Promise((resolve) => setTimeout(resolve, 100));
+  // Wait for the window to actually be shown and rendered before continuing
+  // This ensures the splash is visible before we block the event loop with heavy work
+  await new Promise<void>((resolve) => {
+    splashWindow!.once("show", () => {
+      const loadTime = Date.now() - startTime;
+      console.log(`[${timestamp()}] Splash screen shown (${loadTime}ms)`);
+      // Give one more event loop tick for the window to actually paint
+      setImmediate(resolve);
+    });
+    splashWindow!.show();
+  });
 
   splashWindow.on("closed", () => {
     console.log(`[${timestamp()}] Splash screen closed event`);

From 1561fb0ba13c1312ad65ca5dd92181f42205354b Mon Sep 17 00:00:00 2001
From: Ammar <ammar+ai@ammar.io>
Date: Mon, 13 Oct 2025 13:47:47 -0500
Subject: [PATCH 10/10] Apply prettier formatting to main.ts

---
 src/main.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/main.ts b/src/main.ts
index debb348d9..c8894ac28 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -204,7 +204,7 @@ function createMenu() {
 async function showSplashScreen() {
   const startTime = Date.now();
   console.log(`[${timestamp()}] Showing splash screen...`);
-  
+
   splashWindow = new BrowserWindow({
     width: 400,
     height: 300,
@@ -222,7 +222,7 @@ async function showSplashScreen() {
 
   // Wait for splash HTML to load
   await splashWindow.loadFile(path.join(__dirname, "splash.html"));
-  
+
   // Wait for the window to actually be shown and rendered before continuing
   // This ensures the splash is visible before we block the event loop with heavy work
   await new Promise<void>((resolve) => {