Linux: session-native GDK/WebKit mitigations and in-page browse scroll (#731)

* feat(linux): session GDK defaults, nvidia-quirk, optional x11-legacy wrap

Ship PSYSONIC_ALLOW_NATIVE_GDK from Nix/AUR instead of pinning WEBKIT_DISABLE_*
and GDK x11. Add flake psysonic-x11-legacy for the old wrap; alias gdk-session
to psysonic. Startup uses webkit2gtk-nvidia-quirk and Wayland-aware compositing;
refresh Help (a45) and nixos-install docs.

* fix(linux): session GDK and nvidia-quirk only; drop wrapper env heuristics

Remove PSYSONIC_ALLOW_NATIVE_GDK and devShell GDK/WEBKIT exports; stop
synthesizing GDK/WebKit vars in main.rs. Update Nix/AUR wrappers, install
docs, CHANGELOG, and help FAQ with practical user-facing workarounds.

* fix(linux): X11-pinned GDK uses DMABUF quirk path, not Wayland explicit-sync

When GDK_BACKEND is forced to x11 on a wayland user session, webkit2gtk-nvidia-quirk
would still apply __NV_DISABLE_EXPLICIT_SYNC and gray out the webview. Map that case
to WEBKIT_DISABLE_DMABUF_RENDERER like native X11.

* fix(ui): stabilize WebKitGTK/Wayland hover paint for nav and media cards

Sidebar nav links avoid transition:all and promote icons with translateZ(0).
Artist rows and album/artist/song cards use compositing hints; card shadows
and borders no longer interpolate so cover zoom can stay smooth without jitter.

* fix(ui): isolate artist/album card text and cover paint on WebKitGTK

Promote cover blocks with contain/paint and text stacks with translateZ(0);
use artist-card-info on the artists grid for the same layout as other cards.

* feat(artists): in-page overlay scroll and locked main viewport

Move list/grid into an inner OverlayScrollArea, stop sticky toolbar from
owning the route scroll, align the rail with the main panel edge, and skip
the main-route overlay thumb when the viewport cannot scroll vertically.

* feat(browse): extend in-page overlay scroll to more library routes

Reuse the locked main viewport pattern from Artists for Albums, Composers,
Lossless albums, and New releases; wire VirtualCardGrid and scroll chrome
to the matching in-page viewport ids.

* fix(linux): improve Wayland GPU compositing text clarity in WebKitGTK

Use on-demand hardware acceleration on main and mini webviews when the
session is Wayland and compositing stays on; gate subpixel body AA on the
same conditions via new Tauri probes. Document PSYSONIC_SKIP_WAYLAND_FONT_TUNING
for opt-out and changelog.

* fix(rust): satisfy clippy needless_return in Linux webkit helpers

* fix(linux): tune Wayland text rendering with HW policy env and CSS

Allow PSYSONIC_WEBKIT_WAYLAND_HW_POLICY to select WebKit hardware
acceleration policy (never/always vs default on-demand). Extend Wayland
font CSS to #root with geometricPrecision and text-size-adjust on html.

* feat(linux): Wayland text presets in settings, safe WebKit apply, CPU default

Persist profile to app config; apply WebKit policy at startup/mini only to
avoid WebKitGTK hangs on live toggles. UI + CSS preview stays live; default
preset is sharp (CPU-friendly).

* fix(linux): map Wayland sharp preset to OnDemand WebKit policy

HardwareAccelerationPolicy::Never at startup broke main-viewport wheel
scrolling on WebKitGTK+Wayland; sharp vs balanced remains a CSS AA path.
Use PSYSONIC_WEBKIT_WAYLAND_HW_POLICY for a true Never policy.

* fix(rust): gate Linux-only Wayland WebKit helpers for Windows builds

Re-export startup helpers only under cfg(linux) and drop non-Linux stubs so
Windows compiles without unused-import and dead-code warnings.

* chore(release): CHANGELOG + credits for Linux session/WebKit work (PR #731)

Consolidate scattered incremental changelog notes into two [1.47.0]
entries with PR link; remove duplicate Linux blocks from [1.46.0] Fixed.
Append settings credit line for cucadmuh.

src-tauri/src/lib.rs

@@ -137,8 +137,12 @@ pub fn run() {
             #[cfg(target_os = "linux")]
             {
                 use tauri::Manager;
+                let handle = app.handle().clone();
+                sync_wayland_text_profile_cache_from_disk(&handle);
                 if let Some(win) = app.get_webview_window("main") {
                     let _ = win.set_decorations(false);
+                    let _ = linux_webkit_apply_wayland_gpu_font_tuning(&win);
+                    let _ = linux_webkit_reapply_cached_wayland_text_render_profile(&win);
                 }
             }
 
@@ -338,12 +342,16 @@ pub fn run() {
             cli_publish_search_results,
             set_window_decorations,
             set_linux_webkit_smooth_scrolling,
+            linux_wayland_gpu_font_tuning_active,
+            linux_wayland_text_render_settings_available,
+            set_linux_wayland_text_render_profile,
             set_logging_mode,
             export_runtime_logs,
             frontend_debug_log,
             performance_cpu_snapshot,
             set_subsonic_wire_user_agent,
             no_compositing_mode,
+            linux_xdg_session_type,
             is_tiling_wm_cmd,
             open_mini_player,
             preload_mini_player,

src-tauri/src/lib_commands/app_api/mod.rs

@@ -2,7 +2,7 @@ mod cli_bridge;
 mod core;
 mod integration;
 mod perf;
-mod platform;
+pub(crate) mod platform;
 
 // Tauri commands re-exported for the lib.rs invoke_handler.
 pub(crate) use cli_bridge::{
@@ -14,7 +14,15 @@ pub(crate) use core::{
     set_subsonic_wire_user_agent,
 };
 pub(crate) use perf::performance_cpu_snapshot;
-pub(crate) use platform::{set_linux_webkit_smooth_scrolling, set_window_decorations};
+pub(crate) use platform::{
+    linux_wayland_gpu_font_tuning_active, linux_wayland_text_render_settings_available,
+    set_linux_wayland_text_render_profile, set_linux_webkit_smooth_scrolling, set_window_decorations,
+};
+#[cfg(target_os = "linux")]
+pub(crate) use platform::{
+    linux_webkit_apply_wayland_gpu_font_tuning, linux_webkit_reapply_cached_wayland_text_render_profile,
+    sync_wayland_text_profile_cache_from_disk,
+};
 pub(crate) use integration::{
     check_dir_accessible, mpris_set_metadata, mpris_set_playback, register_global_shortcut,
     unregister_global_shortcut,

src-tauri/src/lib_commands/app_api/platform.rs

@@ -1,7 +1,141 @@
 //! Native-window + WebKitGTK platform tweaks exposed as Tauri commands.
 
+#[cfg(target_os = "linux")]
+use std::path::PathBuf;
+#[cfg(target_os = "linux")]
+use std::sync::{Mutex, OnceLock};
 use tauri::Manager;
 
+#[cfg(target_os = "linux")]
+const LINUX_WAYLAND_TEXT_PROFILE_FILE: &str = "linux_wayland_text_profile";
+
+#[cfg(target_os = "linux")]
+fn last_wayland_text_render_profile_cell() -> &'static Mutex<Option<String>> {
+    static CELL: OnceLock<Mutex<Option<String>>> = OnceLock::new();
+    CELL.get_or_init(|| Mutex::new(None))
+}
+
+#[cfg(target_os = "linux")]
+fn sanitized_wayland_text_profile(profile: &str) -> String {
+    match profile.trim() {
+        "balanced" | "sharp" | "gpu" | "minimal" => profile.trim().to_string(),
+        _ => "sharp".to_string(),
+    }
+}
+
+#[cfg(target_os = "linux")]
+fn wayland_text_profile_persist_path(app: &tauri::AppHandle) -> Option<PathBuf> {
+    app.path().app_config_dir().ok().map(|p| p.join(LINUX_WAYLAND_TEXT_PROFILE_FILE))
+}
+
+/// Load persisted Wayland text profile into the in-process cache before the main webview is tuned.
+#[cfg(target_os = "linux")]
+pub(crate) fn sync_wayland_text_profile_cache_from_disk(app: &tauri::AppHandle) {
+    let Some(path) = wayland_text_profile_persist_path(app) else {
+        return;
+    };
+    let Ok(text) = std::fs::read_to_string(&path) else {
+        return;
+    };
+    let s = sanitized_wayland_text_profile(&text);
+    if let Ok(mut g) = last_wayland_text_render_profile_cell().lock() {
+        *g = Some(s);
+    }
+}
+
+#[cfg(target_os = "linux")]
+fn remember_wayland_text_render_profile(profile: &str, app: Option<&tauri::AppHandle>) {
+    let s = sanitized_wayland_text_profile(profile);
+    if let Ok(mut g) = last_wayland_text_render_profile_cell().lock() {
+        *g = Some(s.clone());
+    }
+    if let Some(app) = app {
+        if let Some(path) = wayland_text_profile_persist_path(app) {
+            if let Some(parent) = path.parent() {
+                let _ = std::fs::create_dir_all(parent);
+            }
+            let _ = std::fs::write(&path, s);
+        }
+    }
+}
+
+/// Re-apply the last **Settings** Wayland text profile to a webview (used when the mini window is built).
+#[cfg(target_os = "linux")]
+pub(crate) fn linux_webkit_reapply_cached_wayland_text_render_profile(win: &tauri::WebviewWindow) -> Result<(), String> {
+    let p = last_wayland_text_render_profile_cell()
+        .lock()
+        .ok()
+        .and_then(|g| g.clone())
+        .unwrap_or_else(|| "sharp".to_string());
+    linux_webkit_apply_wayland_text_render_profile(win, &p)
+}
+
+/// `PSYSONIC_WEBKIT_WAYLAND_HW_POLICY` → WebKit hardware acceleration policy when
+/// [`linux_webkit_apply_wayland_gpu_font_tuning`] runs. Default **`ondemand`**;
+/// set **`never`** / **`software`** to force CPU-friendly layers (often sharper text
+/// at the cost of compositor work); **`always`** forces the previous aggressive GPU path for A/B.
+#[cfg(target_os = "linux")]
+fn wayland_hw_acceleration_policy_from_env() -> webkit2gtk::HardwareAccelerationPolicy {
+    use webkit2gtk::HardwareAccelerationPolicy;
+    let v = std::env::var("PSYSONIC_WEBKIT_WAYLAND_HW_POLICY")
+        .map(|s| s.to_ascii_lowercase())
+        .unwrap_or_default();
+    match v.as_str() {
+        "never" | "off" | "0" | "software" => HardwareAccelerationPolicy::Never,
+        "always" | "on" | "1" | "gpu" => HardwareAccelerationPolicy::Always,
+        _ => HardwareAccelerationPolicy::OnDemand,
+    }
+}
+
+/// Wayland session with WebKit GPU compositing (`WEBKIT_DISABLE_COMPOSITING_MODE` not forced on).
+#[cfg(target_os = "linux")]
+pub(crate) fn linux_wayland_gpu_compositing_context() -> bool {
+    let wayland = std::env::var("XDG_SESSION_TYPE")
+        .map(|v| v.eq_ignore_ascii_case("wayland"))
+        .unwrap_or(false);
+    let no_comp = std::env::var("WEBKIT_DISABLE_COMPOSITING_MODE")
+        .map(|v| v == "1")
+        .unwrap_or(false);
+    wayland && !no_comp
+}
+
+/// True when [`linux_webkit_apply_wayland_gpu_font_tuning`] would change WebKit settings
+/// (Wayland + GPU compositing, user has not set `PSYSONIC_SKIP_WAYLAND_FONT_TUNING`).
+#[cfg(target_os = "linux")]
+pub(crate) fn linux_wayland_gpu_font_tuning_should_apply() -> bool {
+    fn skip_tuning() -> bool {
+        matches!(
+            std::env::var("PSYSONIC_SKIP_WAYLAND_FONT_TUNING").as_deref(),
+            Ok("1") | Ok("true") | Ok("yes")
+        )
+    }
+    if skip_tuning() {
+        return false;
+    }
+    linux_wayland_gpu_compositing_context()
+}
+
+/// WebKitGTK on Wayland with compositing: prefer on-demand GPU promotion so body
+/// text is less often rasterised into GL layers (common "washed" / blurry look).
+/// No-op when [`linux_wayland_gpu_font_tuning_should_apply`] is false.
+#[cfg(target_os = "linux")]
+pub(crate) fn linux_webkit_apply_wayland_gpu_font_tuning(win: &tauri::WebviewWindow) -> Result<(), String> {
+    if !linux_wayland_gpu_font_tuning_should_apply() {
+        return Ok(());
+    }
+    win
+        .with_webview(|platform| {
+            use webkit2gtk::{SettingsExt, WebViewExt};
+            if let Some(settings) = platform.inner().settings() {
+                let policy = wayland_hw_acceleration_policy_from_env();
+                if settings.hardware_acceleration_policy() != policy {
+                    settings.set_hardware_acceleration_policy(policy);
+                }
+            }
+        })
+        .map_err(|e| e.to_string())
+}
+
 /// Toggle native window decorations at runtime (Linux custom title bar opt-out).
 #[tauri::command]
 pub(crate) fn set_window_decorations(enabled: bool, app_handle: tauri::AppHandle) {
@@ -47,3 +181,88 @@ pub(crate) fn set_linux_webkit_smooth_scrolling(enabled: bool, app_handle: tauri
     }
     Ok(())
 }
+
+/// True when [`linux_webkit_apply_wayland_gpu_font_tuning`] would change WebKit settings
+/// (Wayland + GPU compositing, user has not set `PSYSONIC_SKIP_WAYLAND_FONT_TUNING`).
+#[tauri::command]
+pub(crate) fn linux_wayland_gpu_font_tuning_active() -> bool {
+    #[cfg(target_os = "linux")]
+    {
+        linux_wayland_gpu_font_tuning_should_apply()
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        false
+    }
+}
+
+#[cfg(target_os = "linux")]
+fn hardware_acceleration_policy_from_render_profile(profile: &str) -> webkit2gtk::HardwareAccelerationPolicy {
+    use webkit2gtk::HardwareAccelerationPolicy;
+    match profile.trim() {
+        // `Never` here has been observed to break main-viewport wheel scrolling on WebKitGTK
+        // under Wayland+GPU compositing after the policy is applied at startup. CSS still
+        // differentiates "sharp"; use `PSYSONIC_WEBKIT_WAYLAND_HW_POLICY=never` for true Never.
+        "sharp" => HardwareAccelerationPolicy::OnDemand,
+        "gpu" => HardwareAccelerationPolicy::Always,
+        "balanced" | "minimal" => HardwareAccelerationPolicy::OnDemand,
+        _ => HardwareAccelerationPolicy::OnDemand,
+    }
+}
+
+/// Apply WebKit hardware acceleration policy from a **Settings** profile (`balanced` / `sharp` /
+/// `gpu` / `minimal`). Call only at webview creation / startup — toggling this at runtime wedges
+/// WebKitGTK on some Wayland stacks after a few changes.
+#[cfg(target_os = "linux")]
+pub(crate) fn linux_webkit_apply_wayland_text_render_profile(
+    win: &tauri::WebviewWindow,
+    profile: &str,
+) -> Result<(), String> {
+    if !linux_wayland_gpu_compositing_context() {
+        return Ok(());
+    }
+    let policy = hardware_acceleration_policy_from_render_profile(profile);
+    win
+        .with_webview(move |platform| {
+            use webkit2gtk::{SettingsExt, WebViewExt};
+            if let Some(settings) = platform.inner().settings() {
+                if settings.hardware_acceleration_policy() != policy {
+                    settings.set_hardware_acceleration_policy(policy);
+                }
+            }
+        })
+        .map_err(|e| e.to_string())
+}
+
+/// Persist the Wayland text profile for the next app start and for new mini-player webviews.
+/// Does **not** touch WebKit on existing windows (avoids WebKitGTK hangs when toggling policy live).
+#[tauri::command]
+pub(crate) fn set_linux_wayland_text_render_profile(
+    profile: String,
+    app_handle: tauri::AppHandle,
+) -> Result<(), String> {
+    #[cfg(target_os = "linux")]
+    {
+        if !linux_wayland_gpu_compositing_context() {
+            return Ok(());
+        }
+        remember_wayland_text_render_profile(&profile, Some(&app_handle));
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        let _ = (profile, app_handle);
+    }
+    Ok(())
+}
+
+#[tauri::command]
+pub(crate) fn linux_wayland_text_render_settings_available() -> bool {
+    #[cfg(target_os = "linux")]
+    {
+        linux_wayland_gpu_compositing_context()
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        false
+    }
+}

src-tauri/src/lib_commands/sync/mod.rs

@@ -1,7 +1,7 @@
 mod tray;
 
 pub(crate) use tray::{
-    is_tiling_wm_cmd, no_compositing_mode, set_tray_menu_labels, set_tray_tooltip,
+    is_tiling_wm_cmd, linux_xdg_session_type, no_compositing_mode, set_tray_menu_labels, set_tray_tooltip,
     toggle_tray_icon,
 };
 // Internal helpers consumed elsewhere in the shell crate:

src-tauri/src/lib_commands/sync/tray.rs

@@ -398,6 +398,20 @@ pub(crate) fn no_compositing_mode() -> bool {
         .unwrap_or(false)
 }
 
+/// Tauri command: `XDG_SESSION_TYPE` from the host environment (e.g. `wayland`, `x11`).
+/// Used for Linux-only UI tweaks such as font rasterisation hints; empty string when unset.
+#[tauri::command]
+pub(crate) fn linux_xdg_session_type() -> String {
+    #[cfg(target_os = "linux")]
+    {
+        std::env::var("XDG_SESSION_TYPE").unwrap_or_default()
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        String::new()
+    }
+}
+
 #[cfg(not(target_os = "linux"))]
 pub(crate) fn is_tiling_wm() -> bool {
     false

src-tauri/src/lib_commands/ui/mini.rs

@@ -249,6 +249,12 @@ pub(crate) fn build_mini_player_window(
         .build()
         .map_err(|e| format!("failed to build mini player window: {e}"))?;
 
+    #[cfg(target_os = "linux")]
+    {
+        let _ = crate::lib_commands::linux_webkit_apply_wayland_gpu_font_tuning(&win);
+        let _ = crate::lib_commands::linux_webkit_reapply_cached_wayland_text_render_profile(&win);
+    }
+
     // Inject pause script immediately when the window is created hidden.
     // On Windows WebView2 keeps the GPU context alive even with
     // `SetIsVisible(false)` — this JS stops all rendering work.

src-tauri/src/main.rs

@@ -2,75 +2,41 @@
 #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
 
 #[cfg(target_os = "linux")]
-#[derive(Debug, Clone, Copy, PartialEq)]
-enum GpuVendor {
-    Nvidia,
-    Intel,
-    Amd,
-}
+use webkit2gtk_nvidia_quirk::{
+    apply_workaround_with_options, needs_workaround, set_webkit_disable_dmabuf_renderer,
+    ApplyWorkaroundOptions, WorkaroundKind,
+};
 
 #[cfg(target_os = "linux")]
-fn detect_gpu_vendor() -> Option<GpuVendor> {
-    use std::fs;
-
-    if fs::metadata("/proc/driver/nvidia/version").is_ok() {
-        return Some(GpuVendor::Nvidia);
+fn apply_linux_webkit_nvidia_quirk() {
+    if std::env::var("PSYSONIC_WEBKIT_GPU_ACCEL").is_ok() {
+        return;
     }
 
-    // Iterate every `/sys/class/drm/card*` — hybrid laptops expose multiple
-    // cards, and some systems have no `card0` at all.
-    let entries = fs::read_dir("/sys/class/drm").ok()?;
-    for entry in entries.flatten() {
-        let name = entry.file_name();
-        let Some(name) = name.to_str() else { continue };
-        if !name.starts_with("card") || name.contains('-') {
-            continue;
-        }
-        let Ok(vendor_id) = fs::read_to_string(entry.path().join("device/vendor")) else {
-            continue;
-        };
-        match vendor_id.trim() {
-            "0x10de" => return Some(GpuVendor::Nvidia),
-            "0x8086" => return Some(GpuVendor::Intel),
-            "0x1002" => return Some(GpuVendor::Amd),
-            _ => {}
+    // dev.sh gpu-x11 / nix psysonic-x11-legacy: WebKit uses the X11 GDK path while the session
+    // may still be `XDG_SESSION_TYPE=wayland`. The quirk maps that to `__NV_DISABLE_EXPLICIT_SYNC`,
+    // which mismatches a real X11 EGL stack and can leave the webview gray — mirror the native-X11
+    // branch (`WEBKIT_DISABLE_DMABUF_RENDERER` only) whenever GDK is pinned to x11 first in the list.
+    let forced_x11_gdk = std::env::var("GDK_BACKEND").ok().is_some_and(|s| {
+        matches!(s.split(',').next().map(str::trim), Some("x11"))
+    });
+    if forced_x11_gdk {
+        match needs_workaround() {
+            WorkaroundKind::None => {}
+            WorkaroundKind::DisableWebkitDmabufRenderer | WorkaroundKind::DisableNvExplicitSync => {
+                set_webkit_disable_dmabuf_renderer();
+            }
         }
+    } else {
+        apply_workaround_with_options(ApplyWorkaroundOptions::default());
     }
-
-    None
 }
 
 fn main() {
-    // WebKitGTK on Wayland can be unstable — default to X11 when GDK_BACKEND is unset,
-    // except when PSYSONIC_ALLOW_NATIVE_GDK is set (e.g. Nix psysonic-gdk-session wrapper).
-    // Users can still override by setting GDK_BACKEND before launch.
-    //
-    // Safety: set_var modifies global process state. These calls are safe here
-    // because we're in main() before the Tauri runtime starts — no other threads
-    // exist yet. If this code moves to lazy init or a plugin context, it would
-    // need synchronization or marking as unsafe (Rust 2024+).
+    // Linux GTK/WebKit: `webkit2gtk-nvidia-quirk` (skipped when `PSYSONIC_WEBKIT_GPU_ACCEL` is set).
+    // Forced `GDK_BACKEND=x11` uses the X11-only mitigation path — see `apply_linux_webkit_nvidia_quirk`.
     #[cfg(target_os = "linux")]
-    {
-        // Nix `psysonic-gdk-session` sets this so we do not pin X11 when the packager asked for
-        // session-native GDK (e.g. Wayland). Local dev can export the same var before `tauri dev`.
-        let allow_native_gdk = std::env::var("PSYSONIC_ALLOW_NATIVE_GDK").is_ok();
-        if std::env::var("GDK_BACKEND").is_err() && !allow_native_gdk {
-            std::env::set_var("GDK_BACKEND", "x11");
-        }
-        if std::env::var("WEBKIT_DISABLE_COMPOSITING_MODE").is_err() {
-            std::env::set_var("WEBKIT_DISABLE_COMPOSITING_MODE", "1");
-        }
-
-        // NVIDIA proprietary adds a small but reproducible overhead on the
-        // DMA-BUF renderer path (blind A/B confirmed on NVIDIA + proprietary).
-        // Unknown GPUs keep the WebKitGTK default — VMs, ARM SBCs and anything
-        // exotic should not be regressed by a guess.
-        if std::env::var("WEBKIT_DISABLE_DMABUF_RENDERER").is_err()
-            && matches!(detect_gpu_vendor(), Some(GpuVendor::Nvidia))
-        {
-            std::env::set_var("WEBKIT_DISABLE_DMABUF_RENDERER", "1");
-        }
-    }
+    apply_linux_webkit_nvidia_quirk();
 
     let args: Vec<String> = std::env::args().collect();
     if psysonic_lib::cli::wants_version(&args) {