#255 Linux: harden pure-Wayland startup and add a Niri WebKit safe mode

[Anonymous]

Originally created by: kristofferR

Problem

Carrier already disables WebKitGTK's DMABUF renderer when WAYLAND_DISPLAY is present. Two Linux startup/rendering cases remain uncovered:

1. On a pure Wayland session with WAYLAND_DISPLAY set, DISPLAY unset, and no explicit GDK_BACKEND, GTK can select an unavailable X11 backend and abort before Carrier creates a window.
2. Niri has WebKitGTK compositing combinations where disabling DMABUF alone may still produce blank or unstable rendering.

Goal

Make Carrier start reliably on pure Wayland and provide a narrowly targeted Niri safe mode without slowing every Linux desktop.

Design

• Before any GTK/WebKit initialization, set GDK_BACKEND=wayland only when:
• GDK_BACKEND is unset or empty;
• WAYLAND_DISPLAY is non-empty;
• DISPLAY is unset or empty.
• Detect Niri through NIRI_SOCKET and the standard XDG desktop/session identifiers.
• On Niri, set WEBKIT_DISABLE_COMPOSITING_MODE=1 in addition to the existing DMABUF workaround.
• Respect explicit user overrides.
• Add a documented CARRIER_LINUX_WEBKIT_SAFE_MODE override so users can force the fallback on or explicitly disable it.
• Keep X11, XWayland-capable desktops, and non-Niri Wayland sessions on their current paths unless the user opts in.

Verification

• Unit-test the environment decision functions without mutating the test process globally.
• Launch from a pure Niri session with DISPLAY absent.
• Spot-check GNOME Wayland, KDE Wayland, and X11 for regressions.
• Compare CPU use and rendering with compositing enabled and disabled.
• Add the new cases to the pending Linux matrix in [#28].

Ref [#31] and [#28].

[Anonymous]

Originally posted by: kristofferR

[!NOTE]
🤖 GPT-6 responding on behalf of Kristoffer

Implemented and merged in PR [#274] (50b017b).

Carrier now selects GTK's Wayland backend for pure Wayland sessions before GTK starts, applies the additional compositing fallback automatically on Niri Wayland, and supports CARRIER_LINUX_WEBKIT_SAFE_MODE=1 / =0. Explicit GTK and WebKit environment overrides are preserved; the behavior is documented in the README.

Validation passed: 252 Rust tests, 453 Bun tests, formatting, Clippy, typechecking, local review, and Linux/macOS/Windows CI. Local isolated Hyprland testing confirmed native Wayland startup and rendering with forced safe mode. Niri/GNOME/KDE and comparable rendering-performance checks remain tracked in [#28].

Closing the implementation issue. This is merged to main, not yet included in a new release.

[Anonymous]

Ticket changed by: kristofferR

• status: open --> closed