Desktop Window Management#

Element Desktop (Electron) manages its main window through apps/desktop/src/electron-main.ts, which handles the full window lifecycle: creation, show/hide state, close behavior, single-instance enforcement, and crash recovery. Three behaviors are most commonly encountered in practice: tray icon toggling, Linux/Wayland taskbar binding, and GPU-crash blank windows.

Tray Icon and Window Toggle#

The tray is implemented in apps/desktop/src/tray.ts. Key behaviors:

• Creation: The tray icon is created at startup only when minimizeToTray is enabled in the user store 1. Tray is skipped entirely on macOS 2.
• Toggle logic: Clicking the tray icon calls toggleWin(). It hides the window if the window is visible, not minimized, and focused; otherwise it restores/shows and focuses it.
• Close → minimize-to-tray: When a tray is active (or on macOS), close events are intercepted — the window is hidden instead of destroyed 3. global.appQuitting is the escape hatch: set to true via before-quit / before-quit-for-update, it lets the actual quit proceed 4.
• Dynamic icon: The tray icon tracks the page favicon (page-favicon-updated) and updates accordingly. On Windows the PNG is first converted to .ico 5.
• Windows GUID: On Windows, the tray is constructed with a stable GUID derived from the cert subject name and user-data path, so Windows can persist user tray preferences across app restarts 6.

Wayland Window Binding / Taskbar Attachment (Linux)#

On Linux, GNOME and other desktops use StartupWMClass in the .desktop file to bind a running window to its launcher icon. Element Desktop ships StartupWMClass=Element (capital E), but the Electron process reports a lowercase WM_CLASS:

WM_CLASS(STRING) = "element", "element"

This case mismatch prevents GNOME Shell (Wayland or X11) from matching the window to the pinned launcher, causing a second generic-icon instance to appear in the dock instead of focusing the existing one 7. The stable package (element-desktop 1.12.22/1.12.23) still ships the incorrect value 7.

Root cause: electron-builder historically set StartupWMClass from productName ("Element") rather than the actual Electron window class. This is a known upstream bug (electron-userland/electron-builder#4974), addressed in electron-builder v26.15.0 (PR #9832). The Element repo is on electron-builder 26.15.3 but the generated .desktop file still needs verification 8. The Linux build config lives in apps/desktop/electron-builder.ts L138–143.

User workaround (takes effect without reboot):

1. Create ~/.local/share/applications/element-desktop.desktop overriding the system file.
2. Change StartupWMClass=Element → StartupWMClass=element.
3. Restart the GNOME Shell session 7.

For system-wide fixes, editing /usr/share/applications/element-desktop.desktop and running sudo update-desktop-database also works 7.

Note on stable vs. nightly: The real WM_CLASS for stable appears to be element; for nightly it appears to be element-nightly. Proposals to fix via StartupWMClass: variant.name (element-desktop) may not produce the correct value — see PR #33635 and issue #33472 for the open discussion 7.

GPU Rendering Failures / Blank Windows#

GPU process crashes produce a permanent white/blank window — the user cannot recover without killing the app. This is an upstream Electron/Chromium issue (corrupted GPU cache or driver incompatibility) that cannot be fixed in-repo 9.

Automatic recovery (renderer-recovery.ts): setupRendererRecovery(win) is called on the main window at startup 10. It listens for render-process-gone and unresponsive events and automatically reloads the renderer. Key parameters 11:

• Cap: at most 3 reloads within a 60-second rolling window — after that a dialog is shown instead.
• Recoverable crash reasons: crashed, oom, launch-failed, integrity-failure 12.
• Excluded reasons: clean-exit, killed, abnormal-exit, memory-eviction — these are intentional or ambiguous and are not reloaded 13.
• The recoverIfCrashed() method is also called on activate (macOS dock click) and second-instance events so a hidden crashed window is healed before being shown 14.

Manual workarounds for persistent blank windows:

• Disable GPU acceleration at runtime: launch with --disable-gpu flag 15.
• Disable hardware acceleration persistently: set disableHardwareAcceleration: true in the user store; the main process checks this at startup and calls app.disableHardwareAcceleration() before any window is created 16.
• Delete the GPU cache directory (<userData>/GPUCache) and restart.

Tracked in: element-web#22656 (GPU error / blank window) and element-web#32222 (renderer crash auto-recovery).

Key Files#