docs(xwayland): clipboard bridge, XSETTINGS and root cursor

commit: 4afca7a9016a2d74f7d3b91c86c62b710cf3edd8
author: brice · 5h ago · 2026-10-22 16:36 UTC
committer: brice · 4h ago · 2026-10-22 17:55 UTC
parent: def433b
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

4 files · +9 -6

M README.md +1 -1


@@ -149,7 +149,7 @@ See [Configuration](docs/config.md) for all keys, actions, bindings and automati
149	149		- Explicit sync carries client fences to the GPU and KMS, enabled by default with no flag. HDR10 on capable displays includes configurable SDR brightness.
150	150		- Separate workspaces and fractional scale per output; workspaces move when a monitor is unplugged and return when it reconnects.
151	151		- Hidden apps get frame callbacks once per second and the suspended state, whether on another workspace, in a hidden stash, off screen or under fullscreen. Captured windows keep their output's refresh rate.
152		-	- Steam and other X11 clients run through xwayland-satellite, or through the experimental built-in window manager (`xwayland = builtin`; menus, popups and tooltips, fullscreen games with keyboard grab; no clipboard or XSETTINGS yet). Wine can run natively on Wayland.
	152	+	- Steam and other X11 clients run through xwayland-satellite, or through the experimental built-in window manager (`xwayland = builtin`; menus, popups and tooltips, fullscreen games with keyboard grab; text clipboard and primary selection in both directions, XSETTINGS and a themed root cursor). Wine can run natively on Wayland.
153	153
154	154		### Windows and workspaces
155	155


@@ -149,7 +149,7 @@ See [Configuration](docs/config.md) for all keys, actions, bindings and automati
149		- Explicit sync carries client fences to the GPU and KMS, enabled by default with no flag. HDR10 on capable displays includes configurable SDR brightness.	149		- Explicit sync carries client fences to the GPU and KMS, enabled by default with no flag. HDR10 on capable displays includes configurable SDR brightness.
150		- Separate workspaces and fractional scale per output; workspaces move when a monitor is unplugged and return when it reconnects.	150		- Separate workspaces and fractional scale per output; workspaces move when a monitor is unplugged and return when it reconnects.
151		- Hidden apps get frame callbacks once per second and the suspended state, whether on another workspace, in a hidden stash, off screen or under fullscreen. Captured windows keep their output's refresh rate.	151		- Hidden apps get frame callbacks once per second and the suspended state, whether on another workspace, in a hidden stash, off screen or under fullscreen. Captured windows keep their output's refresh rate.
152	-	- Steam and other X11 clients run through xwayland-satellite, or through the experimental built-in window manager (`xwayland = builtin`; menus, popups and tooltips, fullscreen games with keyboard grab; no clipboard or XSETTINGS yet). Wine can run natively on Wayland.	152	+	- Steam and other X11 clients run through xwayland-satellite, or through the experimental built-in window manager (`xwayland = builtin`; menus, popups and tooltips, fullscreen games with keyboard grab; text clipboard and primary selection in both directions, XSETTINGS and a themed root cursor). Wine can run natively on Wayland.
153			153
154		### Windows and workspaces	154		### Windows and workspaces
155			155

M docs/config.md +2 -2


@@ -28,7 +28,7 @@ See [examples/config](../examples/config) for every key with its default.
28	28		\| `terminal.auto-open` \| `first` \| Open a terminal on the first workspace (`first`), on every empty one (`all`), or never (`off`) \|
29	29		\| `startup` \| none \| Commands run at session start, separated by `;` \|
30	30		\| `xwayland` \| `satellite` \| `off`, `satellite`, `builtin` or a satellite binary path \|
31		-	\| `xwayland.xsettings` \| `on` \| With `xwayland = builtin`, publish the cursor theme, cursor size and DPI to X11 apps through XSETTINGS (restart required); `off` leaves them to the apps \|
	31	+	\| `xwayland.xsettings` \| `on` \| With `xwayland = builtin`, publish `Gtk/CursorThemeName`, `Gtk/CursorThemeSize` and `Xft/DPI` to X11 apps through XSETTINGS (restart required); `off` leaves them to the apps \|
32	32		\| `background` \| `#111111` \| Background color \|
33	33		\| `border.radius` \| `0` \| Corner radius in logical pixels, `0` to `64`; floats always, tiles only with gaps \|
34	34		\| `border.width` \| `2` \| Border width in pixels; `0` hides borders \|

@@ -104,7 +104,7 @@ destination output, even if that output has no windows. Same-screen workspace
104	104		switches and mouse focus do not trigger a flash.
105	105		It runs when `animations = on`.
106	106
107		-	`xwayland = satellite` uses `xwayland-satellite` from `PATH`; a custom path also selects satellite. `off` disables X11. `builtin` (experimental): neferwl starts `Xwayland` itself and manages X11 windows as its window manager: windows tile, take focus, close with `close-window` (`WM_DELETE_WINDOW`) and show their title and class. Menus, popups and tooltips (override-redirect windows) are drawn above their window at the right place and never appear as windows in `neferwl state`. X11 apps get the cursor theme and size from `XCURSOR_THEME` and `XCURSOR_SIZE`, the DPI of the first output (96 times its scale) through XSETTINGS (`xwayland.xsettings = off` turns it off), and the themed arrow on the X background. Clipboard is not supported; use `satellite` if you need it.
	107	+	`xwayland = satellite` uses `xwayland-satellite` from `PATH`; a custom path also selects satellite. `off` disables X11. `builtin` (experimental): neferwl starts `Xwayland` itself and manages X11 windows as its window manager: windows tile, take focus, close with `close-window` (`WM_DELETE_WINDOW`) and show their title and class. Menus, popups and tooltips (override-redirect windows) are drawn above their window at the right place and never appear as windows in `neferwl state`. X11 apps get the cursor theme and size from `XCURSOR_THEME` and `XCURSOR_SIZE`, the DPI of the first output (96 times its scale) through XSETTINGS (`xwayland.xsettings = off` turns it off), and the themed arrow on the X background. The clipboard and the primary selection are shared with X11 apps in both directions (text only; nothing crosses while the session is locked or otherwise protected).
108	108
109	109		## Automatic terminal
110	110


@@ -28,7 +28,7 @@ See [examples/config](../examples/config) for every key with its default.
28		\| `terminal.auto-open` \| `first` \| Open a terminal on the first workspace (`first`), on every empty one (`all`), or never (`off`) \|	28		\| `terminal.auto-open` \| `first` \| Open a terminal on the first workspace (`first`), on every empty one (`all`), or never (`off`) \|
29		\| `startup` \| none \| Commands run at session start, separated by `;` \|	29		\| `startup` \| none \| Commands run at session start, separated by `;` \|
30		\| `xwayland` \| `satellite` \| `off`, `satellite`, `builtin` or a satellite binary path \|	30		\| `xwayland` \| `satellite` \| `off`, `satellite`, `builtin` or a satellite binary path \|
31	-	\| `xwayland.xsettings` \| `on` \| With `xwayland = builtin`, publish the cursor theme, cursor size and DPI to X11 apps through XSETTINGS (restart required); `off` leaves them to the apps \|	31	+	\| `xwayland.xsettings` \| `on` \| With `xwayland = builtin`, publish `Gtk/CursorThemeName`, `Gtk/CursorThemeSize` and `Xft/DPI` to X11 apps through XSETTINGS (restart required); `off` leaves them to the apps \|
32		\| `background` \| `#111111` \| Background color \|	32		\| `background` \| `#111111` \| Background color \|
33		\| `border.radius` \| `0` \| Corner radius in logical pixels, `0` to `64`; floats always, tiles only with gaps \|	33		\| `border.radius` \| `0` \| Corner radius in logical pixels, `0` to `64`; floats always, tiles only with gaps \|
34		\| `border.width` \| `2` \| Border width in pixels; `0` hides borders \|	34		\| `border.width` \| `2` \| Border width in pixels; `0` hides borders \|

@@ -104,7 +104,7 @@ destination output, even if that output has no windows. Same-screen workspace
104		switches and mouse focus do not trigger a flash.	104		switches and mouse focus do not trigger a flash.
105		It runs when `animations = on`.	105		It runs when `animations = on`.
106			106
107	-	`xwayland = satellite` uses `xwayland-satellite` from `PATH`; a custom path also selects satellite. `off` disables X11. `builtin` (experimental): neferwl starts `Xwayland` itself and manages X11 windows as its window manager: windows tile, take focus, close with `close-window` (`WM_DELETE_WINDOW`) and show their title and class. Menus, popups and tooltips (override-redirect windows) are drawn above their window at the right place and never appear as windows in `neferwl state`. X11 apps get the cursor theme and size from `XCURSOR_THEME` and `XCURSOR_SIZE`, the DPI of the first output (96 times its scale) through XSETTINGS (`xwayland.xsettings = off` turns it off), and the themed arrow on the X background. Clipboard is not supported; use `satellite` if you need it.	107	+	`xwayland = satellite` uses `xwayland-satellite` from `PATH`; a custom path also selects satellite. `off` disables X11. `builtin` (experimental): neferwl starts `Xwayland` itself and manages X11 windows as its window manager: windows tile, take focus, close with `close-window` (`WM_DELETE_WINDOW`) and show their title and class. Menus, popups and tooltips (override-redirect windows) are drawn above their window at the right place and never appear as windows in `neferwl state`. X11 apps get the cursor theme and size from `XCURSOR_THEME` and `XCURSOR_SIZE`, the DPI of the first output (96 times its scale) through XSETTINGS (`xwayland.xsettings = off` turns it off), and the themed arrow on the X background. The clipboard and the primary selection are shared with X11 apps in both directions (text only; nothing crosses while the session is locked or otherwise protected).
108			108
109		## Automatic terminal	109		## Automatic terminal
110			110

M docs/desktop.md +1 -1


@@ -58,7 +58,7 @@ By default, X11 apps such as Steam run through [xwayland-satellite](https://gith
58	58		xwayland = off # no X11 support
59	59		```
60	60
61		-	With `xwayland = builtin` (experimental), neferwl starts `Xwayland` itself and manages X11 windows: they tile, take focus and close like Wayland windows. Menus, popups and tooltips of X11 apps are shown above their window and do not take the keyboard focus. X11 apps get the cursor theme, cursor size and DPI through XSETTINGS (`xwayland.xsettings = off` to disable). Clipboard is not supported; use `satellite` if you need it.
	61	+	With `xwayland = builtin` (experimental), neferwl starts `Xwayland` itself and manages X11 windows: they tile, take focus and close like Wayland windows. Menus, popups and tooltips of X11 apps are shown above their window and do not take the keyboard focus. X11 apps get the cursor theme (`XCURSOR_THEME`), cursor size (`XCURSOR_SIZE`) and DPI (96 times the scale of the first output) through XSETTINGS (`Gtk/CursorThemeName`, `Gtk/CursorThemeSize`, `Xft/DPI`; `xwayland.xsettings = off` to disable), and the X background shows the themed arrow. The clipboard and the primary selection work between X11 and Wayland apps in both directions, for text; large copies are transferred in chunks (INCR). While the session is locked, no selection data crosses.
62	62
63	63		Games with `builtin`:
64	64


@@ -58,7 +58,7 @@ By default, X11 apps such as Steam run through [xwayland-satellite](https://gith
58		xwayland = off # no X11 support	58		xwayland = off # no X11 support
59		```	59		```
60			60
61	-	With `xwayland = builtin` (experimental), neferwl starts `Xwayland` itself and manages X11 windows: they tile, take focus and close like Wayland windows. Menus, popups and tooltips of X11 apps are shown above their window and do not take the keyboard focus. X11 apps get the cursor theme, cursor size and DPI through XSETTINGS (`xwayland.xsettings = off` to disable). Clipboard is not supported; use `satellite` if you need it.	61	+	With `xwayland = builtin` (experimental), neferwl starts `Xwayland` itself and manages X11 windows: they tile, take focus and close like Wayland windows. Menus, popups and tooltips of X11 apps are shown above their window and do not take the keyboard focus. X11 apps get the cursor theme (`XCURSOR_THEME`), cursor size (`XCURSOR_SIZE`) and DPI (96 times the scale of the first output) through XSETTINGS (`Gtk/CursorThemeName`, `Gtk/CursorThemeSize`, `Xft/DPI`; `xwayland.xsettings = off` to disable), and the X background shows the themed arrow. The clipboard and the primary selection work between X11 and Wayland apps in both directions, for text; large copies are transferred in chunks (INCR). While the session is locked, no selection data crosses.
62			62
63		Games with `builtin`:	63		Games with `builtin`:
64			64

M docs/dev/headless.md +5 -2


@@ -64,9 +64,9 @@ WAYLAND_DISPLAY=<name> go run ./examples/testime -preedit nihon -commit 日本
64	64
65	65		## X11 check
66	66
67		-	`make e2e-xwayland` runs the end-to-end test of the built-in window manager (`xwayland = builtin`). It is behind the `xwayland` build tag, so `go test ./...` and `make check` only compile it (`go vet -tags xwayland`). It needs `Xwayland` on `PATH` and a GPU, and skips without Xwayland.
	67	+	`make e2e-xwayland` runs the end-to-end test of the built-in window manager (`xwayland = builtin`). It is behind the `xwayland` build tag, so `go test ./...` and `make check` only compile it (`go vet -tags xwayland`). It needs `Xwayland` on `PATH` and a GPU, and skips without Xwayland. The clipboard test also needs `wl-copy` and `wl-paste` (wl-clipboard) and skips without them; they run with the headless `WAYLAND_DISPLAY` and need no extra focus step, since the focused probe window is enough for `wl-copy --foreground` to set the selection.
68	68
69		-	The test starts a headless NeferWL with a real `Xwayland` on the first free X display (a live session's `:0` stays untouched) and runs `internal/app/testdata/x11probe`, a small X11 client (`-class`, `-title`, `-size`, `-sleep`, `-at X,Y`) that paints its window green, prints `mapped WxH` and `focus`, and exits 0 on `WM_DELETE_WINDOW`. With `-override` it also maps a magenta override-redirect window (`-override-at`, `-override-size`, `-override-type menu\|tooltip`, `-override-for`, `-override-shape`, `-override-dismiss-on-focusout`) and prints `override mapped`, `override unmapped` or `dismissed`. `-fullscreen` (with `-fullscreen-delay`, `-fullscreen-off`) requests `_NET_WM_STATE_FULLSCREEN` by client message and prints `fullscreen WxH` / `fullscreen off WxH` when the window manager publishes the state; `-keyboard-grab` calls `XGrabKeyboard` and prints `grab`. `-at` also sends a ConfigureRequest with the window rect before the map, like games do. It checks:
	69	+	The test starts a headless NeferWL with a real `Xwayland` on the first free X display (a live session's `:0` stays untouched) and runs `internal/app/testdata/x11probe`, a small X11 client (`-class`, `-title`, `-size`, `-sleep`, `-at X,Y`) that paints its window green, prints `mapped WxH` and `focus`, and exits 0 on `WM_DELETE_WINDOW`. With `-override` it also maps a magenta override-redirect window (`-override-at`, `-override-size`, `-override-type menu\|tooltip`, `-override-for`, `-override-shape`, `-override-dismiss-on-focusout`) and prints `override mapped`, `override unmapped` or `dismissed`. `-fullscreen` (with `-fullscreen-delay`, `-fullscreen-off`) requests `_NET_WM_STATE_FULLSCREEN` by client message and prints `fullscreen WxH` / `fullscreen off WxH` when the window manager publishes the state; `-keyboard-grab` calls `XGrabKeyboard` and prints `grab`. Windowless modes: `-copy TEXT\|@file` (with `-copy-sel CLIPBOARD\|PRIMARY`, `-copy-for`) owns a selection and serves `TARGETS`, `UTF8_STRING`, `STRING` and `TEXT`, with INCR above 64 KiB, and prints `copy owned`; `-paste CLIPBOARD\|PRIMARY` prints `paste "<text>"`, `paste len=N sha256=H` above 4 KiB, or `paste none`; `-xsettings` prints `xsettings serial=N Xft/DPI=… Gtk/CursorThemeName=… Gtk/CursorThemeSize=…` or `xsettings none`; `-root-cursor` prints `cursor WxH` from XFixes `GetCursorImage`. `-at` also sends a ConfigureRequest with the window rect before the map, like games do. It checks:
70	70
71	71		- the state lists one visible `X11Probe` window with the probe's pid, and the screenshot is mostly green inside its tile;
72	72		- the probe receives focus;

@@ -78,6 +78,9 @@ The test starts a headless NeferWL with a real `Xwayland` on the first free X di
78	78		- a fullscreen request 1.5 s after the map fills the output (all green, no gap) and `Super+Shift+f` leaves it; the client can also leave it itself; a request at the map stays tiled (the 1 s grace);
79	79		- with the keyboard grab, `Super+q` does not close a fullscreen focused client and works again once it leaves fullscreen; on a windowed client it closes it;
80	80		- on two outputs, a window created at the second output's origin opens on `HEADLESS-2` and fullscreens there;
	81	+	- clipboard: `wl-copy` text of 4 KiB and 1 MiB (INCR) is read by `x11probe -paste`, and an `x11probe -copy` of the same sizes is read byte-exact by `wl-paste`, for CLIPBOARD and PRIMARY; `wl-copy --clear` gives `paste none`;
	82	+	- XSETTINGS: serial, `Xft/DPI=98304` (scale 1) or `196608` (`output.HEADLESS-1.scale = 2`), and the cursor theme and size from `XCURSOR_THEME`/`XCURSOR_SIZE`; `xwayland.xsettings = off` leaves no owner;
	83	+	- root cursor: `GetCursorImage` over the root is the theme arrow at the theme size (a throwaway theme in `XCURSOR_PATH`);
81	84		- a window rule `rule.games.app-id = steam_app_\d+` floats an X11 window of class `steam_app_413150`, and not another class.
82	85
83	86		Not covered headless: relative pointer lock (needs a real pointer device) and Xwayland output hotplug (`--size` is fixed); these are unit-tested in the `wayland` adapter.

 ## X11 check
-`make e2e-xwayland` runs the end-to-end test of the built-in window manager (`xwayland = builtin`). It is behind the `xwayland` build tag, so `go test ./...` and `make check` only compile it (`go vet -tags xwayland`). It needs `Xwayland` on `PATH` and a GPU, and skips without Xwayland.
+`make e2e-xwayland` runs the end-to-end test of the built-in window manager (`xwayland = builtin`). It is behind the `xwayland` build tag, so `go test ./...` and `make check` only compile it (`go vet -tags xwayland`). It needs `Xwayland` on `PATH` and a GPU, and skips without Xwayland. The clipboard test also needs `wl-copy` and `wl-paste` (wl-clipboard) and skips without them; they run with the headless `WAYLAND_DISPLAY` and need no extra focus step, since the focused probe window is enough for `wl-copy --foreground` to set the selection.
-The test starts a headless NeferWL with a real `Xwayland` on the first free X display (a live session's `:0` stays untouched) and runs `internal/app/testdata/x11probe`, a small X11 client (`-class`, `-title`, `-size`, `-sleep`, `-at X,Y`) that paints its window green, prints `mapped WxH` and `focus`, and exits 0 on `WM_DELETE_WINDOW`. With `-override` it also maps a magenta override-redirect window (`-override-at`, `-override-size`, `-override-type menu|tooltip`, `-override-for`, `-override-shape`, `-override-dismiss-on-focusout`) and prints `override mapped`, `override unmapped` or `dismissed`. `-fullscreen` (with `-fullscreen-delay`, `-fullscreen-off`) requests `_NET_WM_STATE_FULLSCREEN` by client message and prints `fullscreen WxH` / `fullscreen off WxH` when the window manager publishes the state; `-keyboard-grab` calls `XGrabKeyboard` and prints `grab`. `-at` also sends a ConfigureRequest with the window rect before the map, like games do. It checks:
+The test starts a headless NeferWL with a real `Xwayland` on the first free X display (a live session's `:0` stays untouched) and runs `internal/app/testdata/x11probe`, a small X11 client (`-class`, `-title`, `-size`, `-sleep`, `-at X,Y`) that paints its window green, prints `mapped WxH` and `focus`, and exits 0 on `WM_DELETE_WINDOW`. With `-override` it also maps a magenta override-redirect window (`-override-at`, `-override-size`, `-override-type menu|tooltip`, `-override-for`, `-override-shape`, `-override-dismiss-on-focusout`) and prints `override mapped`, `override unmapped` or `dismissed`. `-fullscreen` (with `-fullscreen-delay`, `-fullscreen-off`) requests `_NET_WM_STATE_FULLSCREEN` by client message and prints `fullscreen WxH` / `fullscreen off WxH` when the window manager publishes the state; `-keyboard-grab` calls `XGrabKeyboard` and prints `grab`. Windowless modes: `-copy TEXT|@file` (with `-copy-sel CLIPBOARD|PRIMARY`, `-copy-for`) owns a selection and serves `TARGETS`, `UTF8_STRING`, `STRING` and `TEXT`, with INCR above 64 KiB, and prints `copy owned`; `-paste CLIPBOARD|PRIMARY` prints `paste "<text>"`, `paste len=N sha256=H` above 4 KiB, or `paste none`; `-xsettings` prints `xsettings serial=N Xft/DPI=… Gtk/CursorThemeName=… Gtk/CursorThemeSize=…` or `xsettings none`; `-root-cursor` prints `cursor WxH` from XFixes `GetCursorImage`. `-at` also sends a ConfigureRequest with the window rect before the map, like games do. It checks:
 - the state lists one visible `X11Probe` window with the probe's pid, and the screenshot is mostly green inside its tile;
 - the probe receives focus;
 - a fullscreen request 1.5 s after the map fills the output (all green, no gap) and `Super+Shift+f` leaves it; the client can also leave it itself; a request at the map stays tiled (the 1 s grace);
 - with the keyboard grab, `Super+q` does not close a fullscreen focused client and works again once it leaves fullscreen; on a windowed client it closes it;
 - on two outputs, a window created at the second output's origin opens on `HEADLESS-2` and fullscreens there;
+- clipboard: `wl-copy` text of 4 KiB and 1 MiB (INCR) is read by `x11probe -paste`, and an `x11probe -copy` of the same sizes is read byte-exact by `wl-paste`, for CLIPBOARD and PRIMARY; `wl-copy --clear` gives `paste none`;
+- XSETTINGS: serial, `Xft/DPI=98304` (scale 1) or `196608` (`output.HEADLESS-1.scale = 2`), and the cursor theme and size from `XCURSOR_THEME`/`XCURSOR_SIZE`; `xwayland.xsettings = off` leaves no owner;
+- root cursor: `GetCursorImage` over the root is the theme arrow at the theme size (a throwaway theme in `XCURSOR_PATH`);
 - a window rule `rule.games.app-id = steam_app_\d+` floats an X11 window of class `steam_app_413150`, and not another class.
 Not covered headless: relative pointer lock (needs a real pointer device) and Xwayland output hotplug (`--size` is fixed); these are unit-tested in the `wayland` adapter.