Black screen on macOS 26 — GPU process crashes on startup (Electron 34 incompatibility)

[quaid]

Environment

• macOS version: 26.5.1 (Darwin 25.5.0, Build 25F80)
• AINative Studio version: 2.0.0 (released 2026-01-16)
• Electron version: 34.3.2 (from app bundle)
• Hardware: Apple Silicon (ARM64)

Symptom

App opens a window with standard macOS chrome (traffic light buttons visible) but renders a solid black screen. The app name never appears in the macOS menu bar, even when clicking the window directly. The app is non-interactive.

What was tried

All of the following were attempted without success:

1. Gatekeeper quarantine removal — xattr -rd com.apple.quarantine /Applications/AINativeStudio.app — eliminated as a cause
2. GPU cache purge — deleted GPUCache, DawnGraphiteCache, DawnWebGPUCache from ~/Library/Application Support/AINative Studio/ — no effect
3. --disable-gpu via ~/.ainativestudio/argv.json — no effect
4. Full software rendering stack via argv.json:

   {
     "disable-gpu": true,
     "disable-gpu-sandbox": true,
     "use-gl": "swiftshader",
     "disable-software-rasterizer": false,
     "no-sandbox": true
   }

   No effect.

Diagnosis

Running the Electron binary directly with --enable-logging --v=1 captured the following histogram on shutdown:

Histogram: GPU.GPUProcessTerminationStatus2 recorded 1 samples, mean = 4.0
4  -O  (1 = 100.0%)

Status code 4 = ABNORMAL_TERMINATION (crash). The GPU process crashes every launch regardless of --disable-gpu or SwiftShader flags. This is consistent with a known pattern in Electron 34 on macOS 26: the GPU IPC channel uses Metal/CoreAnimation APIs that changed in macOS 26, causing the GPU helper process to crash before the renderer can composite any frame — leaving the window permanently black.

GPU.ProcessLifetimeEvents.SwiftShader recorded 0 samples, confirming the SwiftShader fallback path is not being reached.

The main.log written to ~/Library/Application Support/AINative Studio/logs/ contains only two lines on each launch (update check), indicating the main process itself starts fine but the renderer never comes up due to the GPU process crash.

Root cause

Electron 34.3.2 does not support macOS 26. This is a well-known upstream issue — Electron 35 includes fixes for macOS 26 GPU/Metal API changes.

Recommended fix

Upgrade Electron to 35.x (or the latest stable at time of build). The Electron changelog for 35+ includes explicit macOS 26 compatibility fixes for the GPU process.

A secondary option is to ship a build with --disable-gpu and --use-gl=swiftshader baked into the app launch script as a temporary workaround while the Electron upgrade is in progress, though as shown above this does not resolve the issue in 34.3.2 because the GPU process crashes before the flag is respected.

No other workarounds were found to be effective.