docs(xwayland): describe the built-in window manager and the xwayland e2e check

commit: 6299b4da7aefb68ba4172e4c7a9995e39619d45f
author: brice · 20h ago · 2026-10-22 13:59 UTC
committer: brice · 20h ago · 2026-10-22 13:59 UTC
parent: 77212a0
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

4 files · +16 -3

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; 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`; no menus, 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; 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`; no menus, 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. It does not manage X11 windows yet; use `satellite` for X11 apps.
	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.
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. It does not manage X11 windows yet; use `satellite` for X11 apps.	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.
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. It does not manage X11 windows yet; use `satellite` for X11 apps.
	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.
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. It does not manage X11 windows yet; use `satellite` for X11 apps.	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.
62			62
63		## Session locking	63		## Session locking
64			64

M docs/dev/headless.md +13 -0


@@ -62,6 +62,19 @@ WAYLAND_DISPLAY=<name> go run ./examples/testime -preedit nihon -commit 日本
62	62
63	63		`-count <n>` exits after n commits; `-delay` sets the time between preedit and commit.
64	64
	65	+	## X11 check
	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.
	68	+
	69	+	The test starts a headless NeferWL with a real `Xwayland` 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:
	70	+
	71	+	- the state lists one visible `X11Probe` window with the probe's pid, and the screenshot is mostly green inside its tile;
	72	+	- the probe receives focus;
	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.
	75	+
	76	+	Run it by hand with `go test -tags xwayland -race ./internal/app -run TestXwayland -count=1 -v`.
	77	+
65	78		## Colour check
66	79
67	80		`make color-check` renders `examples/testpattern` on a headless output and checks the colours, in SDR and in HDR (`--headless-hdr`). It needs a GPU and `/dev/udmabuf`, and is not part of `make check`.


@@ -62,6 +62,19 @@ WAYLAND_DISPLAY=<name> go run ./examples/testime -preedit nihon -commit 日本
62		62
63	`-count <n>` exits after n commits; `-delay` sets the time between preedit and commit.	63		`-count <n>` exits after n commits; `-delay` sets the time between preedit and commit.
64		64
		65	+	## X11 check
		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.
		68	+
		69	+	The test starts a headless NeferWL with a real `Xwayland` 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:
		70	+
		71	+	- the state lists one visible `X11Probe` window with the probe's pid, and the screenshot is mostly green inside its tile;
		72	+	- the probe receives focus;
		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.
		75	+
		76	+	Run it by hand with `go test -tags xwayland -race ./internal/app -run TestXwayland -count=1 -v`.
		77	+
65	## Colour check	78		## Colour check
66		79
67	`make color-check` renders `examples/testpattern` on a headless output and checks the colours, in SDR and in HDR (`--headless-hdr`). It needs a GPU and `/dev/udmabuf`, and is not part of `make check`.	80		`make color-check` renders `examples/testpattern` on a headless output and checks the colours, in SDR and in HDR (`--headless-hdr`). It needs a GPU and `/dev/udmabuf`, and is not part of `make check`.