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/hooks/useArtistsInfiniteScroll.ts

@@ -4,6 +4,8 @@ import { APP_MAIN_SCROLL_VIEWPORT_ID } from '../constants/appScroll';
 interface UseArtistsInfiniteScrollArgs {
   pageSize: number;
   resetDeps: ReadonlyArray<unknown>;
+  /** IntersectionObserver root (e.g. Artists in-page overlay viewport). */
+  getScrollRoot?: () => HTMLElement | null;
 }
 
 interface UseArtistsInfiniteScrollResult {
@@ -32,6 +34,7 @@ interface UseArtistsInfiniteScrollResult {
 export function useArtistsInfiniteScroll({
   pageSize,
   resetDeps,
+  getScrollRoot,
 }: UseArtistsInfiniteScrollArgs): UseArtistsInfiniteScrollResult {
   const [visibleCount, setVisibleCount] = useState(pageSize);
   const [loadingMore, setLoadingMore] = useState(false);
@@ -58,7 +61,7 @@ export function useArtistsInfiniteScroll({
     observerInst.current = null;
     if (!node) return;
 
-    const rootEl = document.getElementById(APP_MAIN_SCROLL_VIEWPORT_ID);
+    const rootEl = getScrollRoot?.() ?? document.getElementById(APP_MAIN_SCROLL_VIEWPORT_ID);
     const observer = new IntersectionObserver(
       entries => {
         if (entries[0]?.isIntersecting) loadMoreRef.current();
@@ -70,7 +73,7 @@ export function useArtistsInfiniteScroll({
     );
     observer.observe(node);
     observerInst.current = observer;
-  }, []);
+  }, [getScrollRoot]);
 
   useEffect(() => () => {
     observerInst.current?.disconnect();

src/hooks/useMainScrollingIndicator.ts

@@ -1,17 +1,20 @@
 import { useEffect, useState } from 'react';
-import { APP_MAIN_SCROLL_VIEWPORT_ID } from '../constants/appScroll';
+import {
+  APP_MAIN_SCROLL_VIEWPORT_ID,
+  MAIN_ROUTE_INPAGE_SCROLL_VIEWPORT_ID_BY_PATH,
+} from '../constants/appScroll';
 
 const SCROLL_IDLE_MS = 180;
 
 /**
- * `true` while the main route viewport or the Now Playing viewport is
- * actively scrolling, falling back to `false` after `SCROLL_IDLE_MS` of
- * silence. Used to fade out the queue handle (and similar floating
- * controls) while the user is scrolling, so they don't sit on top of the
- * overlay scrollbar thumb.
+ * `true` while a tracked viewport is actively scrolling, then `false` after
+ * `SCROLL_IDLE_MS` of silence. Used to fade out the queue handle (and similar
+ * floating controls) while the user is scrolling, so they don't sit on top of
+ * the overlay scrollbar thumb.
  *
- * Re-binds on `pathname` change because Now Playing's viewport mounts
- * lazily and isn't in the DOM on every route.
+ * Tracks `#app-main-scroll-viewport`, and on browse routes with a locked main
+ * scroll also the matching in-page overlay viewport. Re-binds on `pathname`
+ * because Now Playing's viewport mounts lazily.
  */
 export function useMainScrollingIndicator(pathname: string): boolean {
   const [isMainScrolling, setIsMainScrolling] = useState(false);
@@ -22,6 +25,11 @@ export function useMainScrollingIndicator(pathname: string): boolean {
     if (appViewport) viewports.add(appViewport);
     const nowPlayingViewport = document.querySelector<HTMLElement>('.np-main__viewport');
     if (nowPlayingViewport) viewports.add(nowPlayingViewport);
+    const inpageId = MAIN_ROUTE_INPAGE_SCROLL_VIEWPORT_ID_BY_PATH[pathname];
+    if (inpageId) {
+      const inpageVp = document.getElementById(inpageId);
+      if (inpageVp) viewports.add(inpageVp);
+    }
     if (viewports.size === 0) return;
 
     let scrollHideTimer: number | null = null;

src/hooks/useMainstageInpageHeaderTight.ts

@@ -0,0 +1,39 @@
+import { useEffect, useState } from 'react';
+
+const TIGHT_AFTER_PX = 10;
+const LOOSE_BELOW_PX = 2;
+
+/**
+ * Compact the browse toolbar when the in-page overlay viewport scrolls down,
+ * same thresholds as Artists (`> 10` tight, `< 2` loose).
+ */
+export function useMainstageInpageHeaderTight(
+  scrollBodyEl: HTMLElement | null,
+  resetDeps: ReadonlyArray<unknown>,
+): boolean {
+  const [tight, setTight] = useState(false);
+
+  useEffect(() => {
+    if (!scrollBodyEl) return;
+    const el = scrollBodyEl;
+    const onScroll = () => {
+      const y = el.scrollTop;
+      setTight(prev => {
+        if (y > TIGHT_AFTER_PX) return true;
+        if (y < LOOSE_BELOW_PX) return false;
+        return prev;
+      });
+    };
+    el.addEventListener('scroll', onScroll, { passive: true });
+    onScroll();
+    return () => el.removeEventListener('scroll', onScroll);
+  }, [scrollBodyEl]);
+
+  useEffect(() => {
+    setTight(false);
+    // Spread values so deps track filter keys, not a new array identity each render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [...resetDeps]);
+
+  return tight;
+}

src/hooks/usePlatformShellSetup.ts

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react';
 import { invoke } from '@tauri-apps/api/core';
 import { useAuthStore } from '../store/authStore';
+import type { LinuxWaylandTextRenderProfile } from '../store/authStoreTypes';
 import { IS_LINUX, IS_MACOS, IS_WINDOWS } from '../utils/platform';
 
 /**
@@ -12,8 +13,10 @@ import { IS_LINUX, IS_MACOS, IS_WINDOWS } from '../utils/platform';
  */
 export function usePlatformShellSetup(): { isTilingWm: boolean } {
   const [isTilingWm, setIsTilingWm] = useState(false);
+  const [waylandTextUi, setWaylandTextUi] = useState(false);
   const useCustomTitlebar = useAuthStore(s => s.useCustomTitlebar);
   const linuxWebkitKineticScroll = useAuthStore(s => s.linuxWebkitKineticScroll);
+  const linuxWaylandTextRenderProfile = useAuthStore(s => s.linuxWaylandTextRenderProfile);
   const loggingMode = useAuthStore(s => s.loggingMode);
 
   useEffect(() => {
@@ -28,11 +31,54 @@ export function usePlatformShellSetup(): { isTilingWm: boolean } {
     }).catch(() => {});
   }, []);
 
+  useEffect(() => {
+    if (!IS_LINUX) return;
+    invoke<boolean>('linux_wayland_text_render_settings_available')
+      .then(av => {
+        setWaylandTextUi(av);
+        if (av) {
+          document.documentElement.setAttribute('data-linux-session', 'wayland');
+        } else {
+          document.documentElement.removeAttribute('data-linux-session');
+          document.documentElement.removeAttribute('data-wayland-text-profile');
+        }
+      })
+      .catch(() => {});
+  }, []);
+
   useEffect(() => {
     const platform = IS_LINUX ? 'linux' : IS_MACOS ? 'macos' : IS_WINDOWS ? 'windows' : 'unknown';
     document.documentElement.setAttribute('data-platform', platform);
   }, []);
 
+  // Wayland text profile: CSS on <html> updates live; Rust persists for next launch / new mini webview
+  // (WebKitGTK can hang when hardware-acceleration-policy is toggled repeatedly at runtime).
+  useEffect(() => {
+    if (!IS_LINUX || !waylandTextUi) {
+      document.documentElement.removeAttribute('data-wayland-text-profile');
+      return;
+    }
+
+    let cancelHydration: (() => void) | undefined;
+
+    const apply = (profile: LinuxWaylandTextRenderProfile) => {
+      document.documentElement.setAttribute('data-wayland-text-profile', profile);
+      invoke('set_linux_wayland_text_render_profile', { profile }).catch(() => {});
+    };
+
+    apply(linuxWaylandTextRenderProfile);
+
+    if (!useAuthStore.persist.hasHydrated()) {
+      cancelHydration = useAuthStore.persist.onFinishHydration(() => {
+        apply(useAuthStore.getState().linuxWaylandTextRenderProfile);
+      });
+    }
+
+    return () => {
+      cancelHydration?.();
+    };
+  }, [IS_LINUX, waylandTextUi, linuxWaylandTextRenderProfile]);
+
   // Sync custom titlebar preference with native decorations on Linux.
   // On tiling WMs decorations are always off (no native title bar to replace).
   useEffect(() => {
@@ -46,6 +92,23 @@ export function usePlatformShellSetup(): { isTilingWm: boolean } {
     invoke('set_linux_webkit_smooth_scrolling', { enabled: linuxWebkitKineticScroll }).catch(() => {});
   }, [linuxWebkitKineticScroll]);
 
+  // Persist rehydrates after first paint — default store has kinetic scroll ON until localStorage merges.
+  // Re-apply OS WebKit prefs after hydrate (same pattern as useMiniWindowSetup) so OFF stays OFF.
+  useEffect(() => {
+    if (!IS_LINUX) return;
+    const applySmoothFromStore = () => {
+      invoke('set_linux_webkit_smooth_scrolling', {
+        enabled: useAuthStore.getState().linuxWebkitKineticScroll,
+      }).catch(() => {});
+    };
+    if (useAuthStore.persist.hasHydrated()) {
+      applySmoothFromStore();
+    }
+    return useAuthStore.persist.onFinishHydration(() => {
+      applySmoothFromStore();
+    });
+  }, []);
+
   useEffect(() => {
     invoke('set_logging_mode', { mode: loggingMode }).catch(() => {});
   }, [loggingMode]);

src/hooks/useResizeClientHeight.ts

@@ -37,3 +37,23 @@ export function useRefElementClientHeight(
   }, [ref, fallback]);
   return h;
 }
+
+/** ResizeObserver on a concrete element (e.g. callback-ref state for in-page scrollers). */
+export function useElementClientHeightForElement(
+  element: HTMLElement | null,
+  fallback = 600,
+): number {
+  const [h, setH] = useState(fallback);
+  useLayoutEffect(() => {
+    if (!element) {
+      setH(fallback);
+      return;
+    }
+    const update = () => setH(element.clientHeight);
+    const ro = new ResizeObserver(update);
+    ro.observe(element);
+    update();
+    return () => ro.disconnect();
+  }, [element, fallback]);
+  return h;
+}