Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
57 changes: 43 additions & 14 deletions .cursor/skills/verify-kawa/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: verify-kawa
description: Drive the kawa Wayland compositor (rio-inspired nested session / X11 backend) — boot, client connect, menus, tiling, background. Use when proving compositor behavior after changes to deedles.dev/kawa; never DRM/session.
description: Drive the kawa Wayland compositor (rio-inspired nested session / X11 backend) — boot, client connect, menus, window management, tiling, activation, layer shell, popups, Xwayland and clipboard, presentation, background. Use when proving compositor behavior after changes to deedles.dev/kawa; never DRM/session.
---

# Verify Kawa
Expand All @@ -11,7 +11,16 @@ This skill is for agents. Commands are literal. Harness is **process + Wayland c

## Launch

From the repo root (`deedles.dev/kawa`), on a branch with wlroots 0.20 bindings (`wlr-0.20` or a branch based on it):
From the repo root (`deedles.dev/kawa`), on `master` or a branch based on it. kawa's X11 backend needs a parent X server; start a private one so no other session shares it:

```sh
n=49 # any free display number: [ ! -e /tmp/.X11-unix/X$n ]
Xvfb ":$n" -screen 0 1024x768x24 -ac -noreset >/tmp/xvfb-$n.log 2>&1 &
echo $! >/tmp/xvfb-$n.pid
export DISPLAY=":$n"
```

`-noreset` keeps the X server from resetting when its last client goes, which would drop the atoms `launch.sh` creates (step 2). Kill this Xvfb by its PID when the run is over.

```sh
export VERIFY_KAWA_ROOT="$(pwd)"
Expand All @@ -30,12 +39,13 @@ source "$VERIFY_KAWA_HOME/env.sh"
`launch.sh` does all of the following (do not skip):

1. Finds `wlroots-0.20` via the caller's `PKG_CONFIG_PATH` (prepending `VERIFY_KAWA_PKG_CONFIG_PATH` if set) and fails if it is missing; prepends its `libdir` to `LD_LIBRARY_PATH`; sets `CGO_ENABLED=1`, `GOTOOLCHAIN=auto`.
2. Unsets `WAYLAND_DISPLAY` and keeps/chooses `DISPLAY` (on this box prefer `DISPLAY=:9`) so kawa uses the **X11 backend**, not another agent’s compositor.
2. Unsets `WAYLAND_DISPLAY` and requires `DISPLAY` (it fails rather than guess one) so kawa uses the **X11 backend**, not another agent’s compositor. It then creates the `WM_PROTOCOLS`, `WM_DELETE_WINDOW`, `_NET_WM_NAME` and `UTF8_STRING` atoms on that display: the X11 backend only looks them up, so on a fresh X server its window would stay untitled and `screenshot.sh` could not find it.
3. Creates `XDG_RUNTIME_DIR=$VERIFY_KAWA_HOME/run` with mode **0700**. Without this, kawa dies with `XDG_RUNTIME_DIR is invalid or not set` / `can't auto add wayland socket`. DRM FD / dmabuf messages on stderr are noisy but non-fatal until the socket fails.
4. Builds `go build -o "$VERIFY_KAWA_HOME/bin/kawa" .` and compiles `.cursor/skills/verify-kawa/scripts/wayland-registry.c` → `$VERIFY_KAWA_HOME/bin/wayland-registry`.
5. Starts kawa in the background with `launch.sh`'s arguments; writes PID to `$VERIFY_KAWA_HOME/pids/kawa.pid`; captures stdout/stderr under `$VERIFY_KAWA_HOME/logs/`.
6. Waits for ready log line: `Running Wayland compositor on WAYLAND_DISPLAY=...` (from `kawa.go`). May also log Xwayland `DISPLAY=...`.
7. Exports `VERIFY_KAWA_WAYLAND_DISPLAY` (socket **name**, often under `$XDG_RUNTIME_DIR`) via `$VERIFY_KAWA_HOME/env.sh`.
4. Builds `go build -o "$VERIFY_KAWA_HOME/bin/kawa" .`, compiles `.cursor/skills/verify-kawa/scripts/wayland-registry.c` → `$VERIFY_KAWA_HOME/bin/wayland-registry`, and, when `wayland-protocols` is on pkg-config, `activation-client.c` → `$VERIFY_KAWA_HOME/bin/activation-client` (protocol code generated with `wayland-scanner`).
5. Starts a private D-Bus session bus at `$XDG_RUNTIME_DIR/bus` (PID in `pids/dbus.pid`). Without it, GTK clients autolaunch a bus tied to the X display that later runs on the same display would share.
6. Starts kawa in the background with `launch.sh`'s arguments; writes PID to `$VERIFY_KAWA_HOME/pids/kawa.pid`; captures stdout/stderr under `$VERIFY_KAWA_HOME/logs/`.
7. Waits for ready log line: `Running Wayland compositor on WAYLAND_DISPLAY=...` (from `kawa.go`). kawa then logs `Running Xwayland on DISPLAY=:N`, the display X clients inside kawa use.
8. Exports `VERIFY_KAWA_WAYLAND_DISPLAY` (socket **name**, under `$XDG_RUNTIME_DIR`), `VERIFY_KAWA_ACTIVATION_CLIENT`, and `DBUS_SESSION_BUS_ADDRESS` via `$VERIFY_KAWA_HOME/env.sh`.

Never run as a DRM session. Never `pkill kawa`. Do not permanently unset the user’s session compositor.

Expand All @@ -52,7 +62,7 @@ source "$VERIFY_KAWA_HOME/env.sh"
.cursor/skills/verify-kawa/scripts/doctor.sh
```

Pass means: isolated `.../bin/kawa`, `VERIFY_KAWA_HOME` under `/tmp/verify-kawa-*`, `XDG_RUNTIME_DIR=$VERIFY_KAWA_HOME/run` mode 0700, `DISPLAY` set, `wlroots-0.20` via pkg-config, registry helper present, and if a PID file exists the process is alive with the ready line and matching `VERIFY_KAWA_WAYLAND_DISPLAY`.
Pass means: isolated `.../bin/kawa`, `VERIFY_KAWA_HOME` under `/tmp/verify-kawa-*`, `XDG_RUNTIME_DIR=$VERIFY_KAWA_HOME/run` mode 0700, `DISPLAY` set, `wlroots-0.20` via pkg-config, registry helper present, and if a PID file exists the process is alive with the ready line, matching `VERIFY_KAWA_WAYLAND_DISPLAY`, and a `wlroots - X11-1` window on `DISPLAY`. It warns if `WAYLAND_DISPLAY` points anywhere other than kawa's socket.

## Drive

Expand All @@ -63,8 +73,14 @@ Harness = process control + Wayland client against kawa’s socket. No Playwrigh
| Boot | ready line + PID alive |
| Client connect | `WAYLAND_DISPLAY=$VERIFY_KAWA_WAYLAND_DISPLAY XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR timeout 5 wayland-registry` prints `wl_compositor` (and other globals) and `globals=N` with N>0, exit 0 |
| Status bar | screenshot shows the focused title; left-click on the bar → system menu (`Log Out`), right-click → main menu. Clock/time (README) is not implemented |
| Window menu / New | right-click → menu items `New`, `Resize`, `Tile`, `Move`, `Close`, `Hide`; `New` + right-drag starts a `-terms` child and maps its window (screenshot) |
| Window menu / New | right-click → menu items `New`, `Resize`, `Tile`, `Move`, `Close`, `Hide`, then hidden windows; `New` + right-drag starts a `-terms` child and maps its window in the box (screenshot) |
| Window management | `Move` / `Resize` / `Close` / `Hide` + right-click a window (screenshots, `ps --ppid`) |
| Maximize / tiling | menu `Tile` → right-click a window → it fills the area under the status bar (screenshot) |
| Activation | `activation-client` windows; kawa log `activation request for "NAME": allowed=...` + screenshots |
| Layer shell | swaybg, waybar, fuzzel, mako; kawa log `new layer surface ...` + screenshots |
| Popups | GTK context menu near the screen corner stays on screen (screenshot) |
| Xwayland | xclock via `New`; `xclip`/`xsel` ↔ `wl-copy`/`wl-paste` results |
| Presentation | `WAYLAND_DEBUG` count of `wp_presentation_feedback…presented` grows in gtk4-demo |
| Background | launch with `-bg PATH` (`-bgscale` stretch\|center\|fit\|fill); log `loaded ... as background` |

Pointer input: `xdotool` on the parent X display (`DISPLAY` from `env.sh`) drives kawa's X11 backend window. Screenshots: `screenshot.sh NAME` grabs that window with `xwd -id` and converts it with `ffmpeg` to `$VERIFY_KAWA_EVIDENCE/NAME.png`.
Expand All @@ -75,11 +91,20 @@ wid=$(xwininfo -root -tree | sed -n 's/^ *\(0x[0-9a-f]*\) "wlroots - X11-1".*/\1
shot=.cursor/skills/verify-kawa/scripts/screenshot.sh
```

Menus open on button press with the last-chosen item (initially the first) under the pointer; releasing the same button selects the item under the pointer. Items are ~19 px apart. Release off the menu to cancel.
Menus open on button press with the last-chosen item (initially the first) under the pointer, shifted to stay on screen; releasing the same button selects the item under the pointer. Items are ~19 px apart. Release off the menu to cancel. Because of the shift, a menu opened near a screen edge does not have the expected item under the pointer. From the status bar the menu is pushed below the bar with item 0 at the pointer whatever was chosen last, so open menus there when the item matters:

```sh
# barmenu I: pick main-menu item I (0 New, 1 Resize, 2 Tile, 3 Move, 4 Close, 5 Hide, 6+ hidden windows)
barmenu() { xdotool mousemove --window "$wid" 600 10 mousedown 3 sleep 0.3 mousemove --window "$wid" 600 $((20+19*$1)) sleep 0.3 mouseup 3 sleep 0.3; }
# bgc NAME CMD...: start a client against kawa, output in evidence, PID where cleanup.sh finds it
bgc() { n=$1; shift; "$@" >"$VERIFY_KAWA_EVIDENCE/$n.stdout" 2>"$VERIFY_KAWA_EVIDENCE/$n.stderr" & echo $! >"$VERIFY_KAWA_HOME/pids/$n.pid"; }
```

Start clients with `WAYLAND_DISPLAY=$VERIFY_KAWA_WAYLAND_DISPLAY` exported. For `New`, launch kawa with `-terms "$VERIFY_KAWA_ROOT/.cursor/skills/verify-kawa/scripts/new-cmd.sh"` and write the command line to start into `$VERIFY_KAWA_HOME/new-cmd` before each `New` (window-menu.md).

- **Main menu:** `xdotool mousemove --window "$wid" 400 300 mousedown 3`, then `$shot window-menu-main`.
- **New:** with the pointer still on `New`, `xdotool mouseup 3`; then `xdotool mousemove --window "$wid" 200 150 mousedown 3 sleep 0.2 mousemove --window "$wid" 260 200 sleep 0.2 mousemove --window "$wid" 700 520 sleep 0.3 mouseup 3`. After ~2 s, `ps -o pid,cmd --ppid "$(cat "$VERIFY_KAWA_HOME/pids/kawa.pid")"` lists the terminal; `$shot window-menu-new` shows it in the dragged rectangle and its title in the status bar.
- **Tile:** press 3 on empty space (a press on a window edge starts a move instead), move down to `Tile` (+38 px if `New` was last chosen), release, then right-click the window: `xdotool mousemove --window "$wid" 950 300 mousedown 3 sleep 0.3 mousemove --window "$wid" 950 338 sleep 0.3 mouseup 3 sleep 0.3 mousemove --window "$wid" 480 380 click 3`; `$shot maximize-tiled`.
- **Tile:** `barmenu 2`, then right-click the window: `xdotool mousemove --window "$wid" 480 380 click 3`; `$shot maximize-tiled`. A right-press on a window's border starts a move instead of opening the menu.
- **Status bar:** `xdotool mousemove --window "$wid" 600 10 mousedown 3` → main menu (`$shot status-bar-right`); `mousedown 1` on the bar → `Log Out` (`$shot status-bar-left`). Move below the menu before `mouseup` unless you intend to log out; releasing button 1 in place selects `Log Out` and shuts kawa down.

Capture every drive:
Expand All @@ -90,10 +115,11 @@ export WAYLAND_DISPLAY="$VERIFY_KAWA_WAYLAND_DISPLAY"
.cursor/skills/verify-kawa/scripts/capture.sh compositor-boot-registry -- wayland-registry
```

Also copy kawa logs into evidence after a successful boot:
Also copy kawa logs (and `new.log` if `new-cmd.sh` ran) into evidence after a successful boot and again before cleanup:

```sh
cp "$VERIFY_KAWA_HOME/logs/kawa.stderr" "$VERIFY_KAWA_EVIDENCE/kawa.stderr"
cp "$VERIFY_KAWA_HOME/logs/new.log" "$VERIFY_KAWA_EVIDENCE/new.log" 2>/dev/null || true
cp "$VERIFY_KAWA_HOME/pids/kawa.pid" "$VERIFY_KAWA_EVIDENCE/kawa.pid"
printf '%s\n' "$VERIFY_KAWA_WAYLAND_DISPLAY" >"$VERIFY_KAWA_EVIDENCE/wayland-display.txt"
```
Expand Down Expand Up @@ -122,18 +148,21 @@ source "$VERIFY_KAWA_HOME/env.sh" # if not already
.cursor/skills/verify-kawa/scripts/cleanup.sh
```

Kills PIDs under `$VERIFY_KAWA_HOME/pids` (SIGTERM then SIGKILL), then `rm -rf "$VERIFY_KAWA_HOME"`. Does **not** delete `$VERIFY_KAWA_EVIDENCE`. Never `pkill kawa`.
Kills PIDs under `$VERIFY_KAWA_HOME/pids` (SIGTERM then SIGKILL). Then it stops your remaining processes whose environment has `XDG_RUNTIME_DIR=$VERIFY_KAWA_HOME/run` (grandchildren of `New`, portals started over the bus), except itself and the shells that started it, unmounts `$XDG_RUNTIME_DIR/doc` if a document portal mounted it, removes the X lock and socket that kawa's Xwayland leaves behind (kawa does not clean them up on SIGTERM), and runs `rm -rf "$VERIFY_KAWA_HOME"`. Does **not** delete `$VERIFY_KAWA_EVIDENCE`. Never `pkill kawa`. Run it as the last step of a drive, from a shell that is not also running clients you still need for this run. Then kill your private Xvfb by the PID you saved.

## Helpers

All under `.cursor/skills/verify-kawa/scripts/`, executable (except the `.c` source):
All under `.cursor/skills/verify-kawa/scripts/`, executable (except the `.c` sources):

```sh
.cursor/skills/verify-kawa/scripts/launch.sh
.cursor/skills/verify-kawa/scripts/doctor.sh
.cursor/skills/verify-kawa/scripts/capture.sh compositor-boot-registry -- wayland-registry
.cursor/skills/verify-kawa/scripts/screenshot.sh NAME
.cursor/skills/verify-kawa/scripts/cleanup.sh
.cursor/skills/verify-kawa/scripts/new-cmd.sh # as a -terms entry, not run by hand
```

`new-cmd.sh` runs the command line in `$VERIFY_KAWA_HOME/new-cmd` (default `weston-terminal`) with `exec`, so the window keeps the PID kawa started, and logs it with the program's output to `$VERIFY_KAWA_HOME/logs/new.log`. `activation-client.c` is compiled by `launch.sh` into `$VERIFY_KAWA_ACTIVATION_CLIENT`; its modes are in its header comment and activation.md.

`wayland-registry.c` is compiled by `launch.sh` into `$VERIFY_KAWA_HOME/bin/wayland-registry`. `capture.sh` rewrites the token `wayland-registry` to that binary. `NAME` is a single path segment.
18 changes: 13 additions & 5 deletions .cursor/skills/verify-kawa/features/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,12 @@ This directory is the maintained source for verifying user-facing kawa composito

## Baseline preconditions

- Repo root is `deedles.dev/kawa` (`go.mod`), on wlroots 0.20 bindings (`wlr-0.20`).
- Repo root is `deedles.dev/kawa` (`go.mod`), on `master` or a branch based on it (wlroots 0.20 bindings).
- `VERIFY_KAWA_BIN` is a `go build` of `.` from this checkout into `$VERIFY_KAWA_HOME/bin/kawa` (`CGO_ENABLED=1`, `GOTOOLCHAIN=auto`, wlroots 0.20 on `PKG_CONFIG_PATH` / `LD_LIBRARY_PATH`).
- `VERIFY_KAWA_HOME` is a fresh `/tmp/verify-kawa-$RUN_ID`.
- `XDG_RUNTIME_DIR=$VERIFY_KAWA_HOME/run` exists with mode `0700`.
- `DISPLAY` is set (prefer `:9` on this box); `WAYLAND_DISPLAY` is **unset** for the compositor process so the X11 backend is used.
- `DISPLAY` names an X server this run started (a private Xvfb, see SKILL.md Launch); `WAYLAND_DISPLAY` is **unset** for the compositor process so the X11 backend is used.
- Clients are started with `WAYLAND_DISPLAY=$VERIFY_KAWA_WAYLAND_DISPLAY` and the `DBUS_SESSION_BUS_ADDRESS` from `env.sh`, and their PIDs are written under `$VERIFY_KAWA_HOME/pids/`.
- Never DRM/session (`WLR_BACKENDS` must not force drm/libinput session).
- `VERIFY_KAWA_EVIDENCE` is set for this run.
- `doctor.sh` passed after `launch.sh`.
Expand All @@ -20,6 +21,7 @@ This directory is the maintained source for verifying user-facing kawa composito
- Harness is process + Wayland client (`wayland-registry`) + `xdotool` on the parent X display for pointer/menu features (see SKILL.md Drive). Never fake input via internal hooks.
- Capture via `capture.sh` and `screenshot.sh`. Keep PID, logs, registry dump, and screenshots in evidence.
- Restore nothing outside `$VERIFY_KAWA_HOME` and evidence.
- One long-lived instance can serve most features. Relaunch for features that need different flags (`-bg`, `-terms`).

## Proof and skip reporting

Expand All @@ -34,7 +36,13 @@ Each feature file: H1, one paragraph, then exactly four H2s: `Sub-features`, `Ho
## Features

- [Compositor boot + client connect](./compositor-boot.md) — launch, ready line, registry dump (**prove this**).
- [Status bar](./status-bar.md) — bar chrome / focused title / bar menus; time display not implemented.
- [Window menu / new terminal](./window-menu.md) — right-click menu, `-terms`, `New`.
- [Maximize / tiling](./maximize.md) — menu `Tile` / maximize paths.
- [Status bar](./status-bar.md) — focused title, bar menus; time display not implemented.
- [Window menu / new windows](./window-menu.md) — main and system menus, `-terms`, `New`, the New box, late and foreign windows.
- [Window management](./window-management.md) — `Move`, `Resize`, `Close`, `Hide` and unhide, border and client moves.
- [Maximize / tiling](./maximize.md) — `Tile`, rows, swaps, maximize requests.
- [Activation and attention](./activation.md) — `xdg_activation_v1`, New tokens, attention border and menu entry.
- [Layer shell](./layer-shell.md) — wallpapers, panels and exclusive zones, layer popups, launchers, notifications.
- [Popups](./popups.md) — XDG popups kept on screen.
- [Xwayland](./xwayland.md) — X11 windows, `Close`, clipboard and primary selection both ways.
- [Presentation time and GTK4](./presentation.md) — `wp_presentation` feedback, GTK4 apps.
- [Background image](./background.md) — `-bg` / `-bgscale`.
Loading
Loading