docs: document CC_SWITCH_GDK_BACKEND Linux Wayland escape hatch

Document the opt-in CC_SWITCH_GDK_BACKEND environment variable (added in
#4351) that overrides the AppImage's hardcoded GDK_BACKEND=x11, letting
Wayland+NVIDIA users switch back to native Wayland when the webview goes
click-dead and black-screens on resize. The override is generic, so
tiling-Wayland users can set it to x11 for the inverse input bug.

- CHANGELOG.md: new Unreleased/Fixed entry (#4351, fixes #4350)
- README.md / README_ZH / README_JA / README_DE: FAQ entry across all locales
- docs/user-manual/{zh,en,ja}/5-faq/5.2-questions.md: Linux troubleshooting entry

docs/user-manual/en/5-faq/5.2-questions.md

@@ -29,6 +29,22 @@ chmod +x CC-Switch-*.AppImage
 ./CC-Switch-*.AppImage --no-sandbox
 ```
 
+### Linux: Clicks Don't Register / Black Screen on Resize (Wayland + NVIDIA)
+
+**Problem**: The web content area is completely unclickable (the title-bar minimize/maximize/close buttons still work), and the window black-screens on resize or maximize-restore. Common on Wayland sessions with an NVIDIA GPU.
+
+**Cause**: The AppImage's GTK launch hook unconditionally forces `GDK_BACKEND=x11` (XWayland) to dodge a historical native-Wayland crash. On newer Wayland + NVIDIA setups, forced XWayland leaves the WebKitGTK web content unable to receive pointer events. The existing `WEBKIT_DISABLE_*` mitigations don't help here because the root cause is the forced window backend, not rendering.
+
+**Solution**: Use the dedicated `CC_SWITCH_GDK_BACKEND` environment variable to switch back to native Wayland (it is read before GTK init, and the hook never overrides it):
+
+```bash
+CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
+```
+
+- When launching from a desktop icon, add it to the `.desktop` `Exec=` line (e.g. `env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage`) or set it in your session environment — otherwise an icon launch won't see the variable.
+- The variable is generic: on tiling Wayland compositors (sway/Hyprland) where clicks don't register, set `CC_SWITCH_GDK_BACKEND=x11` instead.
+- Leaving it unset behaves exactly as before (still x11), with no side effects.
+
 ## Provider Issues
 
 ### Provider Switch Doesn't Take Effect

docs/user-manual/ja/5-faq/5.2-questions.md

@@ -29,6 +29,22 @@ chmod +x CC-Switch-*.AppImage
 ./CC-Switch-*.AppImage --no-sandbox
 ```
 
+### Linux：クリックが効かない / リサイズで黒画面（Wayland + NVIDIA）
+
+**問題**：Web コンテンツ領域がまったくクリックできません（タイトルバーの最小化/最大化/閉じるボタンは動作します）。ウィンドウのリサイズや最大化-復元後に黒画面になります。Wayland セッション + NVIDIA GPU でよく発生します。
+
+**原因**：AppImage の GTK 起動フックが、過去のネイティブ Wayland クラッシュを避けるために `GDK_BACKEND=x11`（XWayland）を無条件で強制します。新しい Wayland + NVIDIA 環境では、強制された XWayland によって WebKitGTK の Web コンテンツがポインタイベントを受け取れなくなります。既存の `WEBKIT_DISABLE_*` の緩和策は、根本原因が強制されたウィンドウバックエンドであり描画ではないため、ここでは効きません。
+
+**解決方法**：専用の環境変数 `CC_SWITCH_GDK_BACKEND` でネイティブ Wayland に戻します（GTK 初期化前に読み取られ、フックが上書きしません）：
+
+```bash
+CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
+```
+
+- デスクトップアイコンから起動する場合は、`.desktop` の `Exec=` 行に追記するか（例：`env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage`）、セッション環境で設定してください。そうしないとアイコン起動では変数が読み取られません。
+- この変数は汎用です：タイル型 Wayland コンポジタ（sway/Hyprland）でクリックが効かない場合は、`CC_SWITCH_GDK_BACKEND=x11` を設定してください。
+- 未設定の場合は現状とまったく同じ動作（x11 のまま）で、副作用はありません。
+
 ## プロバイダーに関する問題
 
 ### プロバイダーを切り替えても反映されない

docs/user-manual/zh/5-faq/5.2-questions.md

@@ -29,6 +29,22 @@ chmod +x CC-Switch-*.AppImage
 ./CC-Switch-*.AppImage --no-sandbox
 ```
 
+### Linux 点击无响应 / 缩放后黑屏（Wayland + NVIDIA）
+
+**问题**：主界面网页内容区完全点不动（标题栏的最小化/最大化/关闭仍可点），窗口缩放或最大化-还原后黑屏。常见于 Wayland 会话 + NVIDIA 显卡。
+
+**原因**：AppImage 的 GTK 启动钩子会无条件强制 `GDK_BACKEND=x11`（走 XWayland）以规避历史上的原生 Wayland 崩溃；但在较新的 Wayland + NVIDIA 环境下，强制 XWayland 反而使 WebKitGTK 的网页内容收不到指针事件。现有的 `WEBKIT_DISABLE_*` 缓解措施对此无效，因为根因是被强制的窗口后端，而非渲染。
+
+**解决方法**：用专用环境变量 `CC_SWITCH_GDK_BACKEND` 切回原生 Wayland（该开关在 GTK 初始化前生效，钩子不会覆盖它）：
+
+```bash
+CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
+```
+
+- 从桌面图标启动时，把它写进 `.desktop` 的 `Exec=` 行（如 `env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage`），或在会话环境中设置，否则图标启动读不到该变量。
+- 该变量是通用的：在 tiling Wayland 合成器（sway/Hyprland）下若反而出现点击失效，可设 `CC_SWITCH_GDK_BACKEND=x11`。
+- 不设置时行为与现状完全一致（仍走 x11），无副作用。
+
 ## 供应商问题
 
 ### 切换供应商后不生效