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.
2026-07-21 23:05:46 +00:00 · 2026-05-18 21:00:46 +03:00
parent b4782aeedb
commit 70c2fdfbf9
61 changed files with 1602 additions and 712 deletions
@@ -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
+    }
+}