fix(linux): AppImage blank window — stop bundling stale libwayland-client (#106)

.github/workflows/appimage-smoke.yml

@@ -0,0 +1,65 @@
+# Builds the Linux AppImage on PRs that touch packaging and asserts it does not
+# bundle libwayland-client.so.0 (stale copies break EGL on Mesa >= 24.2 hosts, #106).
+name: AppImage smoke
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/release.yml'
+      - '.github/workflows/appimage-smoke.yml'
+      - 'src-tauri/**'
+
+jobs:
+  appimage-smoke:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Linux dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev patchelf
+
+      # Same pre-seed as release.yml — see the comment there (#106).
+      - name: Pre-seed linuxdeploy with fixed excludelist (#106)
+        run: |
+          mkdir -p ~/.cache/tauri
+          curl -fsSL --retry 3 -o ~/.cache/tauri/linuxdeploy-x86_64.AppImage \
+            https://github.com/linuxdeploy/linuxdeploy/releases/download/1-alpha-20251107-1/linuxdeploy-x86_64.AppImage
+          chmod +x ~/.cache/tauri/linuxdeploy-x86_64.AppImage
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 8
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install frontend dependencies
+        run: pnpm install
+
+      - name: Build AppImage
+        env:
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+        run: pnpm tauri build --bundles appimage
+
+      - name: Assert AppImage bundles no libwayland-client (#106)
+        run: |
+          APPIMAGE=$(find src-tauri/target/release/bundle/appimage -name '*.AppImage' | head -1)
+          test -n "$APPIMAGE"
+          "$APPIMAGE" --appimage-extract > /dev/null
+          echo "=== bundled usr/lib ==="
+          find squashfs-root/usr/lib -maxdepth 1 -name '*.so*' -printf '%f\n' | sort
+          find squashfs-root/usr/lib -name 'libwebkit2gtk-4.1.so*' | grep -q . # sanity: extraction worked
+          if find squashfs-root/usr/lib -name 'libwayland-client.so*' | grep -q .; then
+            echo "::error::AppImage bundles libwayland-client.so.0 — breaks EGL on Mesa >= 24.2 hosts (#106)"
+            exit 1
+          fi

.github/workflows/release.yml

@@ -138,6 +138,21 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev patchelf
 
+      # tauri-bundler downloads linuxdeploy from tauri-apps/binary-releases (built 2024-07-29,
+      # excludelist predates the libwayland-client.so.0 entry added 2024-11-03). That stale
+      # excludelist bundles noble's libwayland-client 1.22 into the AppImage; host Mesa >= 24.2
+      # needs wl_display_create_queue_with_name (wayland 1.23) -> EGL vendor load fails ->
+      # "Could not create default EGL display: EGL_BAD_PARAMETER" blank window (#106).
+      # The bundler skips the download when the file already sits in its tools cache, so we
+      # pre-seed a pinned upstream build whose compiled-in excludelist has the fix.
+      - name: Pre-seed linuxdeploy with fixed excludelist (#106)
+        if: matrix.platform == 'ubuntu-24.04'
+        run: |
+          mkdir -p ~/.cache/tauri
+          curl -fsSL --retry 3 -o ~/.cache/tauri/linuxdeploy-x86_64.AppImage \
+            https://github.com/linuxdeploy/linuxdeploy/releases/download/1-alpha-20251107-1/linuxdeploy-x86_64.AppImage
+          chmod +x ~/.cache/tauri/linuxdeploy-x86_64.AppImage
+
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
@@ -166,3 +181,15 @@ jobs:
           releaseId: ${{ needs.create-release.outputs.release_id }}
           includeUpdaterJson: true
           args: ${{ matrix.args }}
+
+      - name: Assert AppImage bundles no libwayland-client (#106)
+        if: matrix.platform == 'ubuntu-24.04'
+        run: |
+          APPIMAGE=$(find src-tauri/target/release/bundle/appimage -name '*.AppImage' | head -1)
+          test -n "$APPIMAGE"
+          "$APPIMAGE" --appimage-extract > /dev/null
+          find squashfs-root/usr/lib -name 'libwebkit2gtk-4.1.so*' | grep -q . # sanity: extraction worked
+          if find squashfs-root/usr/lib -name 'libwayland-client.so*' | grep -q .; then
+            echo "::error::AppImage bundles libwayland-client.so.0 — breaks EGL on Mesa >= 24.2 hosts (#106)"
+            exit 1
+          fi

src-tauri/src/lib.rs

@@ -782,11 +782,13 @@ struct StartupEnvOverride {
     value: &'static str,
 }
 
-// WebKitGTK 2.42+ defaults to a DMA-BUF renderer that fails to create an EGL
-// display on several Linux GPU/driver stacks (NVIDIA, VMs, recent Mesa shipped
-// by Fedora and openSUSE Tumbleweed), leaving an empty window and aborting with
-// `Could not create default EGL display: EGL_BAD_PARAMETER` (#106). Forcing the
-// legacy, non-accelerated path restores rendering on those machines.
+// Helps with rendering glitches on fragile GPU stacks (NVIDIA, VMs) where EGL
+// itself works. NOTE: these vars cannot prevent the `Could not create default
+// EGL display: EGL_BAD_PARAMETER` abort from #106 — since WebKitGTK 2.46 the
+// WebProcess initializes its EGL display before the preference store is applied
+// (WebPage.cpp: drawingArea->updatePreferences runs ahead of updatePreferences),
+// so the abort is reachable regardless. The actual #106 fix is in release.yml:
+// the AppImage must not bundle libwayland-client.so.0.
 #[cfg(any(test, target_os = "linux"))]
 const LINUX_WEBKIT_RENDER_OVERRIDES: [StartupEnvOverride; 2] = [
     StartupEnvOverride { key: "WEBKIT_DISABLE_DMABUF_RENDERER", value: "1" },
@@ -816,7 +818,6 @@ fn apply_linux_webkit_overrides() {
 
 #[cfg_attr(mobile, tauri::mobile_entry_point)]
 pub fn run() {
-    // Work around WebKitGTK's EGL/DMA-BUF abort before anything spawns (#106).
     #[cfg(target_os = "linux")]
     apply_linux_webkit_overrides();