[MuriloPortoPereira]

Summary

Fixes the black/transparent screen and input freezing on Linux with NVIDIA GPUs (tested on Linux Mint Cinnamon X11 and Arch/Hyprland Wayland with NVIDIA RTX cards).

Related issues:

• Resolves Linux/NVIDIA: UI renders the first frame, then all repaints are empty (transparent window) #2514 (Linux/NVIDIA: UI renders the first frame, then all repaints are empty)
• Resolves Transparent UI Bug #2294 (Transparent UI Bug)
• Addresses Black horizontal bars flicker when the mouse moves over the interface. #2438 (Black horizontal bars flicker when the mouse moves over the interface)
• Complements and builds upon fix(linux): use an opaque webview background #2496, Fix WebKitGTK rendering on NVIDIA Linux and focus the login form #2031, Disable NVIDIA explicit sync for WebKitGTK on Linux #2056

---

The Problem

1. Transparent Webview Surface: In setup_main_window.rs, the window was initialized with .background_color(Color(0, 0, 0, 0)). On Linux, WebKitGTK struggles with transparent window surfaces under both Wayland and X11 compositors. As soon as animated content or mouse movement triggered repaints, the webview surface composition failed, resulting in a black (X11) or completely transparent/pass-through (Wayland) canvas with only media/video and isolated <input> elements rendered.
2. GBM Buffer Failures & NVIDIA Explicit Sync: With proprietary NVIDIA drivers, WebKitGTK's DMABUF renderer attempts to allocate GBM buffers of the window size (Failed to create GBM buffer of size 2400x1300: Argumento inválido), and explicit sync causes pipeline stalls/hangs.
3. Fragile Workaround Traps: Attempting to disable GStreamer plugins to bypass the video player resulted in WebKitWebProcess crashing (GLib-GObject-CRITICAL: invalid (NULL) pointer instance), leaving behind an unresponsive zombie window that rejects all clicks and inputs.

---

Solution

1. Opaque Background in setup_main_window.rs for Linux:
   • On Linux, initialize the webview background with opaque Color(18, 19, 22, 255) matching --st-bg.
   • macOS and Windows retain Color(0, 0, 0, 0) for native titlebar styling.
2. Safe Fallbacks in artcraft-wrapper (Flatpak/Linux package):
   • Provide default environment variables to force shared memory (SHM), avoid failing GBM buffer allocation, and disable NVIDIA explicit sync:
     • WEBKIT_DMABUF_RENDERER_FORCE_SHM=1
     • WEBKIT_DMABUF_RENDERER_DISABLE_GBM=1
     • WEBKIT_WEBGL_DISABLE_GBM=1
     • __NV_DISABLE_EXPLICIT_SYNC=1
   • Keeps full user-overridable syntax (${VAR:-1}) so users can still customize their execution environment if needed.

---

Verification

• System: Linux Mint (Cinnamon, X11), NVIDIA GeForce RTX 3080 Ti (driver 595.99.02).
• Results:
  • Login modal (Create your account) renders crisply side-by-side with the showcase video.
  • Video plays smoothly without corrupting the surrounding UI or turning the canvas black.
  • WebKitWebProcess remains stable and healthy (no segfaults/core dumps).
  • All clicks, form inputs, and buttons respond as expected.

[netlify]

❌ Deploy Preview for storyteller-docs failed. Why did it fail? →

Name	Link
🔨 Latest commit	1dd81ce
🔍 Latest deploy log	https://app.netlify.com/projects/storyteller-docs/deploys/6aef842079cee9020fd854c3

[eliets2]

First-pass review notes (automated; combined from specialist angles: tests, maintainability, performance, user experience). Please treat as suggestions and verify before acting.

Summary: This pull request fixes black/transparent screens and input freezing on Linux with NVIDIA GPUs by making the WebKitGTK window background opaque on Linux and adding Flatpak wrapper environment variables to force shared-memory rendering, disable GBM buffers, and disable NVIDIA explicit sync.

Logical units:

• Opaque Linux background in crates/desktop/artcraft/src/core/lifecycle/startup/setup_main_window.rs
• Default environment variables in packaging/linux/artcraft-wrapper

Findings:

• [maintainability] [performance] [user experience] packaging/linux/artcraft-wrapper and setup_main_window.rs (setup_main_window): the opaque background and the WEBKIT_DMABUF_RENDERER_FORCE_SHM=1, WEBKIT_DMABUF_RENDERER_DISABLE_GBM=1, WEBKIT_WEBGL_DISABLE_GBM=1, and explicit-sync settings are applied to all Linux users, including AMD/Intel systems where the existing path works. This can remove intentional transparency/rounded-corner styling and silently downgrade rendering performance via CPU shared-memory copies and disabled GPU buffer paths. Gate the background and variables on NVIDIA hardware/driver detection or make them opt-in, and measure frame time, CPU use, and memory use before/after on unaffected hardware.
• [user experience] setup_main_window.rs (setup_main_window): the pre-paint color is hardcoded to the default dark theme Color(18, 19, 22, 255), so light or custom-theme users will see a dark flash before content loads. Derive the color from the selected theme, or update it once the theme is known.
• [user experience] setup_main_window.rs (setup_main_window): an opaque dark window with no loading or error indicator is indistinguishable from a still-loading or failed webview. Show a loading indicator until first content paint and an error state on failure.
• [user experience] packaging/linux/artcraft-wrapper: performance-affecting rendering variables are set silently with no in-app notice or setting, so users cannot discover or undo degraded video or scrolling. Add a settings toggle or surface the override in the app's help/about UI.
• [maintainability] setup_main_window.rs (setup_main_window): Color(18, 19, 22, 255) duplicates the --st-bg CSS value as a magic number with no shared source, so a theme change will cause a pre-paint flash mismatch. Extract a shared constant or add the CSS file location to the comment so both are updated together.
• [tests] packaging/linux/artcraft-wrapper: the four new environment variables have no automated test for their defaults or override behavior. Add a script test asserting each defaults to 1 when unset and is preserved when preset, e.g. to 0.
• [tests] setup_main_window.rs: the Linux-only opaque background branch has no regression test. Add a test or CI check asserting Linux uses opaque Color(18, 19, 22, 255) and non-Linux retains Color(0, 0, 0, 0).
• [tests] packaging/linux/artcraft-wrapper: the interaction between WEBKIT_DMABUF_RENDERER_FORCE_SHM/DISABLE_GBM and the existing WEBKIT_DISABLE_DMABUF_RENDERER=0 default is untested, while the fix depends on DMABUF remaining enabled while GBM is bypassed. Test that combination explicitly.
• [tests] Verification evidence covers only one X11/NVIDIA configuration, while the summary also claims Wayland results. Add a reproducible test matrix or documented checklist covering X11 and Wayland, with and without NVIDIA, before treating the Wayland claim as verified.

Overlaps: The pull request description lists complements to #2496, #2031, and #2056; no other overlap findings were reported.

Verdict: Needs changes. The 3 most important points are: (1) scope the opaque background and rendering workarounds to affected NVIDIA systems or make them opt-in, with performance measurements on unaffected hardware; (2) add tests for the wrapper defaults/overrides, the DMABUF/GBM combination, and the Linux background branch; (3) derive the pre-paint color from the theme and add loading/error feedback instead of a blank dark screen.