Skip to content

fix(viewer): apply NVIDIA and WebKitGTK workarounds before creating the webview - #226

Merged
zackees merged 2 commits into
mainfrom
fix/linux-nvidia-webkit-workarounds
Sep 12, 2026
Merged

zackees merged 2 commits into
mainfrom
fix/linux-nvidia-webkit-workarounds

Conversation

@zackees

@zackees zackees commented Sep 12, 2026

Copy link
Copy Markdown
Member

Summary

On Linux the viewer is WebKitGTK. On NVIDIA hosts it failed three ways: the Wayland window died instantly with Error 71 (Protocol error) dispatching to Wayland display, the X11 window painted solid grey, and the pthread WASM build could not bootstrap because JavaScriptCore hides SharedArrayBuffer even when the page is cross-origin isolated (The object can not be cloned from loadWasmModuleToWorker).

crates/fastled-cli/src/linux_graphics.rs runs in the internal viewer process before tauri::Builder, so the WebKit processes inherit the environment. It sets, only when the variable is unset so user overrides win:

Variable When Why
JSC_useSharedArrayBuffer=1 always expose SharedArrayBuffer for the pthread build
__NV_DISABLE_EXPLICIT_SYNC=1 NVIDIA driver loaded keeps the fast DMA-BUF path alive on Wayland (Tauri's documented fix)
WEBKIT_DISABLE_DMABUF_RENDERER=1 NVIDIA and X11 backend DMA-BUF import fails on X11; only the shared-memory path paints

The decision is a pure function of host facts with four unit tests. apply() reports what it changed on stderr.

Measurements (RTX 3060, driver 595.71.05, WebKitGTK 2.52.6, KDE Wayland)

  • Wayland, DMA-BUF on with explicit sync off: Tauri UI process ~14% CPU at 1400x1000, window stays up.
  • DMA-BUF disabled (previous only-working option): ~53% CPU, scaling with window area (~90% of a core at 1800x1300), because the UI process copies the window through the CPU every frame.
  • With this change and no manual environment: Wayland window stays up, X11 window renders the sketch.

Known remaining issue (upstream)

WebKitGTK 2.52.6 on this KDE desktop with fractional scaling reports devicePixelRatio = -0.0208 and negative innerWidth on the Wayland backend (plain MiniBrowser shows the same), which collapses page layout. X11 reports a sane ratio. Not addressed here.

Verification

  • soldr cargo fmt --all --check clean, soldr cargo build --release -p fastled-cli clean.
  • Local cargo test/clippy could not complete on this NixOS host because tikv-jemalloc-sys (via zccache-fingerprint) fails its configure step under the zccache C wrapper (cannot determine return type of strerror_r); relying on CI for those.

🤖 Generated with Claude Code

https://claude.ai/code/session_01M9rUkvoW2gVKYurtQJpi4i

zackees and others added 2 commits September 12, 2026 16:18
…he webview

On Linux the Tauri viewer is WebKitGTK, and on NVIDIA hosts it failed in
three ways: the Wayland window died at once with "Error 71 (Protocol
error)", the X11 window painted solid grey, and the pthread WASM build
could not bootstrap because JavaScriptCore hides SharedArrayBuffer.

A new linux_graphics module runs in the internal viewer process before
tauri::Builder, so the WebKit processes inherit the environment. It sets,
only when the variable is unset:

- JSC_useSharedArrayBuffer=1 always
- __NV_DISABLE_EXPLICIT_SYNC=1 when the NVIDIA kernel driver is loaded,
  which keeps the fast DMA-BUF path working on Wayland (Tauri's
  documented fix)
- WEBKIT_DISABLE_DMABUF_RENDERER=1 when NVIDIA and the X11 backend,
  where DMA-BUF import fails and only the shared-memory path paints

The decision is a pure function with unit tests. Verified on NixOS with
WebKitGTK 2.52.6, driver 595.71.05, KDE Wayland: with no manual
environment the Wayland window now stays up and the X11 window renders
the sketch.

Refs the fastled-wasm Linux graphics guidance at
https://v2.tauri.app/develop/debug/linux-graphics/

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M9rUkvoW2gVKYurtQJpi4i
…1.95.0

The pinned zccache commit pulled in tikv-jemalloc-sys, whose configure
step fails under the zccache C wrapper ("cannot determine return type
of strerror_r"), so tests and clippy could not build on this host. The
current zccache release no longer depends on jemalloc; it requires
rustc 1.95.0, so rust-toolchain.toml moves from 1.94.1 to 1.95.0.

Verified locally on 1.95.0: the linux_graphics unit tests, workspace
clippy with -D warnings, the format check, and a release build.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M9rUkvoW2gVKYurtQJpi4i
@zackees

zackees commented Sep 12, 2026

Copy link
Copy Markdown
Member Author

Follow-up commit: zccache-fingerprint moved to 1.13.22 (drops tikv-jemalloc-sys, whose configure step broke local builds under the zccache C wrapper) and rust-toolchain.toml to 1.95.0, which that release requires. With that, the linux_graphics unit tests, workspace clippy with -D warnings, the format check, and a release build all pass locally; the earlier 'relying on CI' caveat no longer applies.

@zackees
zackees merged commit c36f84d into main Sep 12, 2026
22 checks passed
@zackees
zackees deleted the fix/linux-nvidia-webkit-workarounds branch September 12, 2026 23:54
zackees added a commit that referenced this pull request Sep 12, 2026
Viewer sets the NVIDIA and WebKitGTK workarounds itself on Linux (#226).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M9rUkvoW2gVKYurtQJpi4i
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant