Skip to content

docs: describe Wayland flags as compositor/WebKitGTK workarounds #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
3xian merged 1 commit into from
Sep 3, 2026
Merged

docs: describe Wayland flags as compositor/WebKitGTK workarounds #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,10 @@ Download a prebuilt installer from **[GitHub Releases](https://github.com/3xian/
- macOS: Apple Silicon and Intel builds
- Linux: build from source; CI installers are not available yet

On Wayland (niri, Sway, Hyprland, …) WebKitGTK cannot composite a transparent
window, and GTK client-side decorations render as a black bar. Launch with:
On some Wayland compositors (niri, Sway, Hyprland, …) Overlay CSD and
acrylic transparency mis-render with WebKitGTK. These flags are a
workaround until that stack handles the default chrome; they can be
dropped then. Launch with:

```bash
PinkCode --disable-csd --disable-transparency
Expand Down Expand Up @@ -130,7 +132,7 @@ npm run check # frontend + Rust (fmt/clippy/test) — same as CI
| Flag | Meaning |
|------|---------|
| `--disable-csd` | Hide client-side decorations (black title bar on Wayland) |
| `--disable-transparency` | Opaque window (WebKitGTK has no Wayland alpha protocol) |
| `--disable-transparency` | Opaque window (WebKitGTK + compositor alpha) |
| `-h`, `--help` | Show flags |

## Architecture
Expand Down
18 changes: 10 additions & 8 deletions src-tauri/src/cli.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
//! Startup flags for window chrome that must be applied before the webview exists.
//!
//! Acrylic + Overlay CSD is shaped for macOS/Windows. On Wayland, WebKitGTK
//! cannot composite an alpha surface (no protocol support), and GTK CSD shows
//! as a black bar. These flags rewrite `tauri.conf.json` window fields in
//! memory so the window is created opaque and undecorated.
//! Acrylic + Overlay CSD is shaped for macOS/Windows. On some Wayland
//! compositors the same chrome mis-renders with WebKitGTK. These flags are a
//! compatibility workaround: they rewrite `tauri.conf.json` window fields in
//! memory so the window is created with `decorations=false` and
//! `transparent=false`. Drop them when the stack handles the default chrome.

use tauri::utils::config::{Color, WindowConfig};
use tauri::TitleBarStyle;
Expand All @@ -20,8 +21,8 @@ Usage:
Options:
--disable-csd Hide client-side decorations (fixes the black
title bar on Wayland compositors such as niri)
--disable-transparency Opaque window (WebKitGTK has no Wayland
protocol for alpha compositing)
--disable-transparency Opaque window (WebKitGTK + compositor alpha
on some Wayland setups)
-h, --help Show this help
";

Expand All @@ -37,8 +38,9 @@ pub enum Action {
}

impl Flags {
/// GTK reads `GTK_CSD` at init; `set_decorations(false)` after the window
/// exists is not enough to stop the black CSD bar.
/// GTK reads `GTK_CSD` at gtk_init. This only disables GTK's default CSD;
/// Tao still installs a custom titlebar. `decorations=false` in `apply()`
/// is what actually hides chrome.
pub fn prepare_env(self) {
if self.disable_csd {
#[cfg(target_os = "linux")]
Expand Down