feat(linux): auto-configure WebKit env for NVIDIA+Wayland at startup

[nvandamme]

Problem

WebKitGTK rendering fails on the NVIDIA + Wayland combination (blank windows,
Gdk-Message: Error 71 (Protocol error) dispatching to Wayland display),
forcing users to manually export GDK_BACKEND=x11 and
WEBKIT_DISABLE_COMPOSITING_MODE=1 before launching.

Solution

Detect that combination in main() before any webview is created and set those
variables automatically, respecting pre-set values. This follows the Tauri-
documented pattern (https://v2.tauri.app/develop/debug/linux-graphics) and
covers all Linux dist formats at once instead of per-format packaging hooks.

Verification

Verified end-to-end on an NVIDIA + KDE Plasma Wayland workstation:

• Clean launch → both variables auto-set (confirmed via child process env)
• Main window renders correctly with no protocol errors
• Pre-set values are respected (no override when user configured them)

[nvandamme]

Note that there is an extended tauri plugin at https://github.com/hrzlgnm/webkit2gtk-nvidia-quirk that might better cover Wayland+Nvidia tauri rendering. In my case, Kwin/Plasma isn't yet handled.

[Hakanbaban53]

Hi @nvandamme,

Thank you for tackling the notorious WebKitGTK + NVIDIA + Wayland rendering issue! It's a well-known pain point on Linux desktop setups.

While automatic workarounds are very helpful, there are a few important architectural points and regressions we should address before merging this:

1. Avoid forcing GDK_BACKEND=x11

• Blurry UI with Fractional Scaling: Forcing GDK_BACKEND=x11 drops native Wayland support and routes rendering through XWayland. On modern KDE Plasma and GNOME setups using fractional scaling (e.g. 125%, 150%), XWayland windows are bitmap-upscaled by the compositor, resulting in a noticeably blurry UI and fuzzy text.
• Modern NVIDIA Drivers (555+): With the introduction of explicit sync (linux-drm-syncobj-v1) in NVIDIA driver versions 555/560/565, WebKitGTK renders natively on Wayland without the "Error 71" protocol crash.
• Flatpak / Pure-Wayland Environments: In sandbox or container environments where the X11 socket is not shared (or pure Wayland compositors where XWayland is disabled), setting GDK_BACKEND=x11 causes the app to crash on launch with Cannot open display.

2. Preferred WebKitGTK Workaround

According to WebKitGTK and Tauri upstream guidelines, the crash is caused by the DMABUF hardware renderer on older NVIDIA drivers. The recommended way to fix rendering while preserving native Wayland (crisp scaling, native gestures) is:

if std::env::var("WEBKIT_DISABLE_DMABUF_RENDERER").is_err() {
    std::env::set_var("WEBKIT_DISABLE_DMABUF_RENDERER", "1");
}

Optionally combined with WEBKIT_DISABLE_COMPOSITING_MODE=1.

We should leave GDK_BACKEND alone so the compositor can run natively on Wayland, allowing users who specifically need XWayland fallback to pass GDK_BACKEND=x11 manually via their environment or desktop launcher.

3. Exclude Headless / Web-Server Builds

In headless web-server mode (--features web-server), Rclone Manager runs completely headless (e.g. in Docker, TrueNAS, or remote Linux servers) with no GUI or WebKitGTK webview. Scanning /sys/class/drm and setting display variables is unnecessary overhead there.

Please gate the functions with:

#[cfg(all(desktop, target_os = "linux", not(feature = "web-server")))]

4. Move logic to src-tauri/src/utils/app/platform.rs

To keep lib.rs minimal and maintain clean architectural separation, please move the GPU detection and environment configuration helper into src-tauri/src/utils/app/platform.rs (e.g. pub fn apply_linux_graphics_quirks()) and invoke it at the entry point of run().

Could you please update the PR to drop GDK_BACKEND=x11 in favor of WEBKIT_DISABLE_DMABUF_RENDERER=1, add the target cfg guards, and move the helpers into platform.rs?

Thanks again for investigating this and helping improve the Linux desktop experience!

[Hakanbaban53]

By the way, I checked the repository you shared (webkit2gtk-nvidia-quirk):

Interestingly, that crate validates the exact concern regarding GDK_BACKEND=x11. They specifically avoid forcing GDK_BACKEND=x11 because dropping down to XWayland breaks native Wayland fractional scaling (causing blurry text and UI) and degrades rendering performance. Instead, they rely on:

WEBKIT_DISABLE_DMABUF_RENDERER=1

The reason you likely ran into issues on KWin/Plasma is that KWin often requires disabling compositing mode alongside the DMABUF renderer:

if std::env::var("WEBKIT_DISABLE_DMABUF_RENDERER").is_err() {
    std::env::set_var("WEBKIT_DISABLE_DMABUF_RENDERER", "1");
}
if std::env::var("WEBKIT_DISABLE_COMPOSITING_MODE").is_err() {
    std::env::set_var("WEBKIT_DISABLE_COMPOSITING_MODE", "1");
}

Combining these two environment variables addresses the crash on KWin/Plasma, Hyprland, and GNOME alike, while keeping the window running natively on Wayland without needing GDK_BACKEND=x11.

We don't need to pull in an external crate dependency either; handling the lightweight GPU detection natively inside platform.rs with these two variables keeps the binary clean, dependency-free, and Wayland-native.

[nvandamme]

added a PR about Kwin/plasma on the mentioned plugin :
hrzlgnm/webkit2gtk-nvidia-quirk#12

hint: it works with __NV_DISABLE_EXPLICIT_SYNC=1 under Kwin+Nvidia while allowing wayland

i'll try with yours and report back

[Hakanbaban53]

Looks fantastic now! Thank you for addressing all the feedback so quickly and adding thorough unit tests.

Retaining native Wayland without forcing XWayland while keeping the logic cleanly encapsulated in platform.rs ensures great rendering across all Linux environments and packaging formats (including Flatpak).

LGTM! 🚀

[nvandamme]

• Dropped GDK_BACKEND=x11 entirely in favor of WEBKIT_DISABLE_DMABUF_RENDERER + WEBKIT_DISABLE_COMPOSITING_MODE only for nvidia GPUs
• Added the #[cfg(all(desktop, target_os = "linux", not(feature = "web-server")))] gate; headless builds no longer touch /sys/class/drm.
• Moved everything to utils/app/platform.rs::apply_linux_graphics_quirks() with unit tests; lib.rs keeps only the gated call.

One refinement I kept: scoping to NVIDIA GPUs (/proc/driver/nvidia/version or PCI vendor 0x10de). The rendering bugs seems specific to the NVIDIA EGL stack: on Mesa (Intel/AMD) the DMA-BUF renderer works fine, so disabling it there would regress their path without fixing anything.