docs(xwayland): state that builtin shows menus, popups and tooltips

commit: c5b7312cf66e30eeb3de5efa6df9babd26c77712
author: brice · 7h ago · 2026-10-22 15:23 UTC
committer: brice · 4h ago · 2026-10-22 17:54 UTC
parent: 47739da
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

4 files · +8 -5

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`; no menus, 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`; shows menus, popups and tooltips; no clipboard or XSETTINGS yet). 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`; no menus, 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`; shows menus, popups and tooltips; no clipboard or XSETTINGS yet). Wine can run natively on Wayland.
153			153
154		### Windows and workspaces	154		### Windows and workspaces
155			155

M docs/config.md +1 -1


@@ -103,7 +103,7 @@ destination output, even if that output has no windows. Same-screen workspace
103	103		switches and mouse focus do not trigger a flash.
104	104		It runs when `animations = on`.
105	105
106		-	`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 and popups (override-redirect windows), clipboard and XSETTINGS are not supported yet; use `satellite` if you need them.
	106	+	`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`. Clipboard and XSETTINGS are not supported; use `satellite` if you need them.
107	107
108	108		## Automatic terminal
109	109


@@ -103,7 +103,7 @@ destination output, even if that output has no windows. Same-screen workspace
103		switches and mouse focus do not trigger a flash.	103		switches and mouse focus do not trigger a flash.
104		It runs when `animations = on`.	104		It runs when `animations = on`.
105			105
106	-	`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 and popups (override-redirect windows), clipboard and XSETTINGS are not supported yet; use `satellite` if you need them.	106	+	`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`. Clipboard and XSETTINGS are not supported; use `satellite` if you need them.
107			107
108		## Automatic terminal	108		## Automatic terminal
109			109

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 and popups, clipboard and XSETTINGS are not supported yet; use `satellite` if you need them.
	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. Clipboard and XSETTINGS are not supported; use `satellite` if you need them.
62	62
63	63		## Session locking
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 and popups, clipboard and XSETTINGS are not supported yet; use `satellite` if you need them.	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. Clipboard and XSETTINGS are not supported; use `satellite` if you need them.
62			62
63		## Session locking	63		## Session locking
64			64

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


@@ -66,12 +66,15 @@ WAYLAND_DISPLAY=<name> go run ./examples/testime -preedit nihon -commit 日本
66	66
67	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.
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`) that paints its window green, prints `mapped WxH` and `focus`, and exits 0 on `WM_DELETE_WINDOW`. 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`) 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`. 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;
73	73		- a second probe tiles beside the first;
74		-	- `key Super+q` closes the focused probe within 2 seconds and the state drops to one window.
	74	+	- `key Super+q` closes the focused probe within 2 seconds and the state drops to one window;
	75	+	- an override-redirect menu is drawn magenta above the green toplevel at its X position, is not listed in the state, leaves focus on the toplevel and disappears from the screenshot once the probe unmaps it;
	76	+	- a menu is dismissed when its owner gets `FocusOut` because another X11 window took the focus;
	77	+	- a menu with an empty input shape is still drawn and still not a window.
75	78
76	79		Run it by hand with `go test -tags xwayland -race ./internal/app -run TestXwayland -count=1 -v`.
77	80

 `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 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`) that paints its window green, prints `mapped WxH` and `focus`, and exits 0 on `WM_DELETE_WINDOW`. 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`) 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`. 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 second probe tiles beside the first;
-- `key Super+q` closes the focused probe within 2 seconds and the state drops to one window.
+- `key Super+q` closes the focused probe within 2 seconds and the state drops to one window;
+- an override-redirect menu is drawn magenta above the green toplevel at its X position, is not listed in the state, leaves focus on the toplevel and disappears from the screenshot once the probe unmaps it;
+- a menu is dismissed when its owner gets `FocusOut` because another X11 window took the focus;
+- a menu with an empty input shape is still drawn and still not a window.
 Run it by hand with `go test -tags xwayland -race ./internal/app -run TestXwayland -count=1 -v`.