[Feedback]: Main window never becomes visible until the app is launched a second time — ready-to-show does not fire while the window is hidden

先重現 issue 中的 Windows 封裝版啟動流程，並檢查 out/main/index.js，尤其是隱藏視窗的設定，以及 ready-to-show、second-instance、deep-link 和 notification-click 處理器。檢查第一次 paint 前的可見性表現，包括背景節流和回報的 GPU fallback。完成的標準是：第一次啟動能可靠地顯示主視窗，不需要第二個執行個體，並避免出現無法解釋的黑屏閃現。

What problem are you trying to solve?

Summary

After installing, the first launch appears to do nothing: no window, no taskbar entry, no error — for as long as you wait. Launching the app a second time brings the window up in under half a second. This happens on every launch, so the app can only be opened by launching it twice.

Environment

• Command Code Desktop 0.1.31 (packaged)
• Installer CommandCode-0.1.31-x64-setup.exe, size 145234320, sha512 Kap6h9HtsAdGCqAsGiCo/gddarFzRbdUn+l1a7Gov0gjYyHHb35t3aM362xR9wxNpSuWOWDzfY+pQpp9G33LIA==
• Windows 11 (Windows PowerShell 5.1.26100.9482)
• Display 1600x900 @ scale 1.2
• GPU vendor 4318 / device 8580, driver 32.0.16.1692

Steps to reproduce

1. Quit Command Code completely.
2. Launch Command Code.exe once.
3. Do not touch anything — just watch the screen.

Expected

The window appears within a couple of seconds.

Actual

No window appears. Verified with a 60-second instrumented watch (user32 EnumWindows polled every 100ms): no window was ever reported visible. Launching a second instance at t+60s made the main window visible at t+60.89s — 0.44s later.

Evidence

Window-visibility timeline alongside main.log:

t+0.00s   launched Command Code.exe (pid 16228)
t+0.69s   main.log: Command Code starting - v0.1.31 (packaged: true)
t+0.83s   main.log: [startup] ... main.harness-loaded +44ms (837ms)     <- window created, hidden
t+60.21s  *** launched a 2nd instance ***
t+60.29s  PROC+ pid=9736 (2nd main process)
t+60.89s  WIN+ MAIN APP WINDOW FIRST BECAME VISIBLE
          hwnd=2164394 class=Chrome_WidgetWin_1 size=1741x1042 title=[Command Code]
t+61.45s  main.log: [startup] ... main.ready-to-show +59988ms (60825ms)

Two observations:

1. ready-to-show fired at +59988ms, i.e. at the moment the second instance arrived — not when the renderer finished a fixed amount of work. Across 5 launches the value tracked only how long the user waited (22012ms, 25038ms, 27024ms, 27930ms, 59988ms).

2. Chromium's own log places the second instance immediately before it:

[16952:0917/175428.395:VERBOSE1:chrome\browser\process_singleton_win.cc:114]
Handling STARTUP request from another process

28ms later ready-to-show fired; 130ms after that the window became visible.

Root cause

out/main/index.js — the window is created hidden with a black background:

backgroundColor: "#000000",
show: false,

and is only ever revealed from the ready-to-show handler:

win.on("ready-to-show", () => {
  ...
  if (!win.isDestroyed()) win.show();
});

The only other callers of win.show() are the second-instance, deep-link and notification-click handlers:

app.on("second-instance", (_event, argv) => {
  ...
  const win = pickWindowToReveal(mainWindow, appWindows);
  if (!win) { createWindow(); return; }
  if (win.isMinimized()) win.restore();
  win.show();
  win.focus();
});

So visibility depends on ready-to-show firing for a window that is not yet visible. On this machine it never does while hidden, so the window is never shown — until a second instance calls win.show(), at which point the first paint finally happens and ready-to-show fires.

I can't prove from outside the app why the hidden window's first paint is deferred. Worth checking: hidden-window rendering throttling (webPreferences.backgroundThrottling is left at default), and a GPU/compositor problem — the run log shows Chromium later relaunching the GPU process in software mode (--disable-gpu-sandbox --use-gl=disabled).

This also explains the "black window flashes for a moment" that users report: backgroundColor: "#000000" means the window is shown as a solid black rectangle before the UI paints.

What would improve it?

Suggested fix

Do not make the first paint a hard precondition for visibility. A fallback timer is sufficient:

const reveal = () => {
  if (!win.isDestroyed() && !win.isVisible()) win.show();
};
win.once("ready-to-show", reveal);
setTimeout(reveal, 3000);

Also worth considering webPreferences: { backgroundThrottling: false }, and reconsidering the show: false + "#000000" combination — if the window is shown early by any path it renders as a black rectangle, which is what users are seeing.

What do you do today?

No response

Product area

None