NebulaBrowser/GPU-FIX-README.md

GPU Fix Guide for Nebula Browser

Common GPU Issues

Nebula Browser is an Electron-based application that uses Chromium's rendering engine. Some systems may experience GPU-related issues such as:

• Black/blank screens
• Webviews not loading content
• Flickering or visual artifacts
• Application crashes

SteamOS / Steam Deck

Symptoms

On SteamOS (Steam Deck), you may see:

• Browser chrome loads (tab bar, URL bar visible)
• Web page content area is completely black/empty
• No error messages visible

Cause

This is caused by GPU compositing conflicts between Electron's Chromium renderer and Gamescope (Steam Deck's compositor). The AMD GPU in Steam Deck handles nested compositor contexts differently.

Solution

Option 1: Automatic Detection (Recommended) The latest version of Nebula automatically detects SteamOS/Gamescope and applies the necessary fixes. Simply update to the latest version.

Option 2: Manual Launch Script Use the provided start-steamos.sh script:

chmod +x start-steamos.sh
./start-steamos.sh

Option 3: Command-line Flags If running manually, add these flags:

electron . --ozone-platform=x11 --disable-gpu-compositing --disable-gpu-vsync --no-sandbox --disable-dev-shm-usage

Option 4: Environment Variable Set the ELECTRON_OZONE_PLATFORM_HINT environment variable:

export ELECTRON_OZONE_PLATFORM_HINT=x11
npm start

Linux (General)

Wayland

If running on a Wayland compositor (GNOME Wayland, KDE Wayland, Sway, etc.):

electron . --ozone-platform=wayland --enable-features=UseOzonePlatform,WaylandWindowDecorations

X11

For X11 sessions:

electron . --ozone-platform=x11

NVIDIA GPUs

If using NVIDIA proprietary drivers:

electron . --disable-gpu-sandbox --no-sandbox

Windows

Intel/AMD Integrated Graphics Issues

If experiencing blank screens on Windows with integrated graphics:

1. Try running with start-gpu-safe.bat
2. Update your graphics drivers
3. Disable hardware acceleration in settings (if available)

Multiple GPU Systems

On laptops with both integrated and discrete GPUs:

• Right-click the Nebula shortcut
• Select "Run with graphics processor"
• Choose your dedicated GPU

macOS

macOS typically has fewer GPU issues, but if problems occur:

electron . --disable-gpu

Diagnostic Information

To see GPU information and diagnostics:

1. Open Nebula Browser
2. Navigate to nebula://gpu or chrome://gpu
3. Check the "Graphics Feature Status" section

Reporting Issues

If none of the above solutions work, please report the issue with:

1. Operating system and version
2. GPU model and driver version
3. Contents of chrome://gpu page
4. Any error messages from terminal/console