From ae1572f370e9289cbb7f0fe6c9f10924e0e292bc Mon Sep 17 00:00:00 2001
From: Frank Stellmacher <171614930+Psychotoxical@users.noreply.github.com>
Date: Sat, 30 May 2026 18:39:44 +0200
Subject: [PATCH] docs(linux): clarify AppImage is the X11/XWayland channel
 (#928)

After #731 the .deb/.rpm/Nix packages follow the session display server,
but AppImage still pins GDK_BACKEND=x11 via its AppRun hook. Document the
asymmetry in the install guidance and complete the #731 changelog entry so
users know which package gives a native-Wayland launch.
---
 CHANGELOG.md | 1 +
 README.md    | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4a4e4ffc..c7c9bf8b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -202,6 +202,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 **By [@cucadmuh](https://github.com/cucadmuh), PR [#731](https://github.com/Psychotoxical/psysonic/pull/731)**
 
 * **Nix / AUR** default installs follow the session GDK backend instead of pinning `GDK_BACKEND=x11`; startup applies **`webkit2gtk-nvidia-quirk`** only (skip with **`PSYSONIC_WEBKIT_GPU_ACCEL`**). **`nix run .#psysonic-x11-legacy`** keeps the old explicit X11 launcher.
+* **AppImage stays on X11/XWayland**: unlike the `.deb` / `.rpm` / Nix packages it still pins `GDK_BACKEND=x11` (set by the bundle's AppRun hook), so it doubles as the legacy channel. Use `.deb`, `.rpm`, AUR, or the Nix default for a native-Wayland launch.
 * **NVIDIA + forced X11** on a Wayland user session no longer greys out the webview — the quirk uses the DMABUF renderer path instead of Wayland explicit-sync disable.
 * **Wayland + GPU compositing:** clearer UI text via on-demand hardware acceleration on main and mini webviews; **Settings → System** adds **Wayland text rendering** presets (Balanced / Sharp / GPU / Minimal). Opt out with **`PSYSONIC_SKIP_WAYLAND_FONT_TUNING`**.
 
diff --git a/README.md b/README.md
index 18ec2584..05c6cf6e 100644
--- a/README.md
+++ b/README.md
@@ -153,6 +153,8 @@ curl -fsSL https://raw.githubusercontent.com/Psychotoxical/psysonic/main/scripts
 
 Linux builds are also available through GitHub Releases, AUR and Cachix/Nix.
 
+> **AppImage runs under X11/XWayland** — it pins `GDK_BACKEND=x11` for a stable WebKitGTK stack. For a native-Wayland launch, use the `.deb`, `.rpm`, AUR, or Nix packages, which follow your session's display server.
+
 ## Windows
 
 Download the latest installer from the [GitHub Releases](https://github.com/Psychotoxical/psysonic/releases/latest).