diff --git a/.cursor/skills/verify-kawa/SKILL.md b/.cursor/skills/verify-kawa/SKILL.md index 994eb71..bff954a 100644 --- a/.cursor/skills/verify-kawa/SKILL.md +++ b/.cursor/skills/verify-kawa/SKILL.md @@ -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 @@ -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)" @@ -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. @@ -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 @@ -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`. @@ -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: @@ -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" ``` @@ -122,11 +148,11 @@ 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 @@ -134,6 +160,9 @@ All under `.cursor/skills/verify-kawa/scripts/`, executable (except the `.c` sou .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. diff --git a/.cursor/skills/verify-kawa/features/README.md b/.cursor/skills/verify-kawa/features/README.md index 706581e..ddc2fab 100644 --- a/.cursor/skills/verify-kawa/features/README.md +++ b/.cursor/skills/verify-kawa/features/README.md @@ -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`. @@ -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 @@ -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`. diff --git a/.cursor/skills/verify-kawa/features/activation.md b/.cursor/skills/verify-kawa/features/activation.md new file mode 100644 index 0000000..294cc5a --- /dev/null +++ b/.cursor/skills/verify-kawa/features/activation.md @@ -0,0 +1,34 @@ +# Activation and attention + +kawa implements `xdg_activation_v1` (`activation.go`). A window that asks to be activated with a valid token is focused and raised, and shown again if it was hidden. A request kawa refuses marks the window as wanting attention instead: a red border, even on client-decorated windows, and a red entry in the main menu if the window is hidden. Attention clears when the window gets focus. Programs started by `New` get a trusted token in `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID`. + +## Sub-features + +- `act-new-token` — `New` children get a trusted token, so a program that activates with it on startup gets focus. +- `act-launch` — a client that gets a token from a click on its own focused surface and hands it to a program it starts lets that program take focus, even when the request comes before the window maps (kawa remembers it). +- `act-refused` — a token without a seat serial, or from a surface that never had focus, is refused. The window gets the attention border. Clicking the window clears it. +- `act-hidden-attention` — a refused request from a hidden (minimized) window turns its main-menu entry red. +- `act-unhide` — an allowed request for a hidden window shows and focuses it (a single-instance app raised by a second launch). + +## How to get to it (user POV) + +- Launch an app from another app (a launcher, a link in a terminal): the new window takes focus. +- An app that tries to grab focus without user action gets a red border instead; click it. +- A hidden app that wants attention shows a red entry under `Hide` in the main menu. + +## Driving it with process + Wayland client + +Preconditions: `compositor-boot` proven; launched with `-terms "$VERIFY_KAWA_ROOT/.cursor/skills/verify-kawa/scripts/new-cmd.sh"`; `AC=$VERIFY_KAWA_ACTIVATION_CLIENT` (built by `launch.sh`). Usage and modes are in the header of `scripts/activation-client.c`. Each window is a flat color picked from its name, and the client prints `token done`, `activate`, and `keyboard enter/leave` on stdout. Start clients outside `New` with their output in evidence and the PID in `$VERIFY_KAWA_HOME/pids/` (SKILL.md Drive, `bgc`). kawa's stderr logs `activation request for "NAME": allowed=BOOL mapped=BOOL` for each request. + +- `act-launch`: `echo "$AC alpha launch $AC charlie start" >"$VERIFY_KAWA_HOME/new-cmd"`, `New` a box, then click inside `alpha`. `charlie` maps with focus and its title in the bar (`$shot act-launch-C`); the log shows `"charlie": allowed=true mapped=false`. +- `act-refused`: `bgc bravo "$AC" bravo self 2`. After 2 s it has a red border and the bar keeps the old title (`$shot act-B-attention`, log `allowed=false mapped=true`). Click it: border gone, focused (`$shot act-B-clicked`). +- `act-hidden-attention`: `bgc delta env ACTIVATION_CLIENT_MINIMIZE=1 "$AC" delta self 2`. kawa hides it on the minimize request; after 2 s the bar menu shows a red `delta` entry (`$shot act-hidden-attention`). +- `act-unhide`: `mkfifo "$VERIFY_KAWA_HOME/echo.fifo"`, `bgc echo env ACTIVATION_CLIENT_MINIMIZE=1 "$AC" echo fifo "$VERIFY_KAWA_HOME/echo.fifo"` (it hides). Then `New` with `$AC writer launch sh -c 'echo "$XDG_ACTIVATION_TOKEN" >'"$VERIFY_KAWA_HOME"'/echo.fifo'` in `new-cmd` and click `writer`. `echo` comes back focused (`$shot act-fifo-unhidden`, log `allowed=true`). +- Keep `$VERIFY_KAWA_HOME/logs/new.log` (the `New` clients' output) in evidence before cleanup. + +## Gotchas + +- Use names of several letters. Colors come from a hash of the name, and one-letter names give nearly the same gray. +- `self` gets a token with no serial, so it is always refused. `self-stale` uses the last click's serial and is refused once another window has been focused since. +- The attention border is drawn over client decorations, so it is visible on GTK windows too. +- kawa treats a client's minimize request as `Hide`. diff --git a/.cursor/skills/verify-kawa/features/background.md b/.cursor/skills/verify-kawa/features/background.md index 893b08a..2d171fb 100644 --- a/.cursor/skills/verify-kawa/features/background.md +++ b/.cursor/skills/verify-kawa/features/background.md @@ -1,11 +1,12 @@ # Background image -Optional wallpaper via `-bg PATH` and `-bgscale` (`stretch`, `center`, `fit`, `fill`). On success kawa logs `loaded %q as background`. +Optional wallpaper via `-bg PATH` and `-bgscale` (`stretch`, `center`, `fit`, `fill`; default `stretch`). On success kawa logs `loaded %q as background`. The image is placed in the area below the status bar. ## Sub-features -- `bg-load` — decode image and create texture. -- `bg-scale` — scaling mode from `-bgscale`. +- `bg-load` — decode the image and create a texture. +- `bg-scale` — `stretch` fills the area ignoring aspect; `center` draws it at natural size, centered; `fill` scales it to fit inside the area, keeping aspect, centered (letterboxed); `fit` is `fill` for an image larger than the area and natural size otherwise. +- `bg-errors` — a bad path or undecodable file logs `load "…" as background: …` or `decode "…" as background: …` and kawa runs without a background. ## How to get to it (user POV) @@ -13,12 +14,14 @@ Optional wallpaper via `-bg PATH` and `-bgscale` (`stretch`, `center`, `fit`, `f ## Driving it with process + Wayland client -Preconditions: baseline; a small PNG/JPEG under `$VERIFY_KAWA_HOME`. +Preconditions: baseline; two test images, e.g. `ffmpeg -f lavfi -i testsrc=size=200x100:rate=1 -frames:v 1 small.png` and the same at `1600x900` as `big.png`. -- Stop any prior instance (`cleanup.sh`), then `launch.sh -bg "$VERIFY_KAWA_HOME/bg.png" -bgscale fit`. -- Proof: stderr contains `loaded "..." as background`, the compositor reaches the ready line, and `screenshot.sh background` shows the image. +- For each mode, `cleanup.sh` any prior instance, then `launch.sh -bg "$PWD/small.png" -bgscale MODE`, `sleep 1`, `$shot background-small-MODE`. Also `-bg big.png -bgscale fit` (`$shot background-big-fit`). +- Proof: stderr contains `loaded "..." as background`, the ready line arrives, and the screenshots match the modes above. +- `bg-errors`: `launch.sh -bg /nonexistent.png` still reaches the ready line and logs `load "/nonexistent.png" as background: open /nonexistent.png: no such file or directory`. ## Gotchas -- Bad path/decode logs an error and continues without a background. -- Unknown `-bgscale` is rejected during flag parsing: kawa prints `invalid value "..." for flag -bgscale: unknown scaling method: "..."` plus usage to stderr and exits with status 2 before starting, so `launch.sh` reports `kawa died before client connect`. +- Take the screenshot a second after launch; right after the ready line the window may not have drawn yet and comes out white. +- With `fit` and an image smaller than the screen, kawa currently draws the image at the output's top-left corner, partly under the status bar, instead of centering it. That is a product bug; `center` places it correctly. +- Unknown `-bgscale` is rejected during flag parsing: kawa prints `invalid value "..." for flag -bgscale: unknown scaling method: "..."` plus usage and exits with status 2 before starting, so `launch.sh` reports `kawa died before client connect`. diff --git a/.cursor/skills/verify-kawa/features/compositor-boot.md b/.cursor/skills/verify-kawa/features/compositor-boot.md index bef1223..3293e6e 100644 --- a/.cursor/skills/verify-kawa/features/compositor-boot.md +++ b/.cursor/skills/verify-kawa/features/compositor-boot.md @@ -5,8 +5,8 @@ Starts kawa as a nested/X11 compositor with an isolated runtime dir, waits for t ## Sub-features - `boot-x11` starts with `DISPLAY` set and `WAYLAND_DISPLAY` unset (X11 backend). -- `ready-log` observes `Running Wayland compositor on WAYLAND_DISPLAY=` on stderr. -- `client-registry` connects with `wayland-registry` and prints globals including `wl_compositor`. +- `ready-log` observes `Running Wayland compositor on WAYLAND_DISPLAY=` on stderr, followed by `Running Xwayland on DISPLAY=:N`. +- `client-registry` connects with `wayland-registry` and prints globals including `wl_compositor`. On master it lists 19, among them `zwlr_layer_shell_v1`, `xdg_activation_v1`, `wp_presentation`, `zwlr_data_control_manager_v1`, `zwp_primary_selection_device_manager_v1`, and `xwayland_shell_v1`. ## How to get to it (user POV) @@ -15,7 +15,7 @@ Starts kawa as a nested/X11 compositor with an isolated runtime dir, waits for t ## Driving it with process + Wayland client -Preconditions: baseline; `launch.sh` succeeded; `doctor.sh` passed. +Preconditions: baseline (a private Xvfb exported as `DISPLAY`); `launch.sh` succeeded; `doctor.sh` passed. - **Launch.** `.cursor/skills/verify-kawa/scripts/launch.sh` then `source "$VERIFY_KAWA_HOME/env.sh"`. - **Doctor.** `.cursor/skills/verify-kawa/scripts/doctor.sh`. @@ -26,7 +26,8 @@ Preconditions: baseline; `launch.sh` succeeded; `doctor.sh` passed. ## Gotchas - Missing `XDG_RUNTIME_DIR` (or not mode 0700) → `can't auto add wayland socket`; kawa exits. Always use `$VERIFY_KAWA_HOME/run`. -- Leaving `WAYLAND_DISPLAY` set nests into another compositor (possibly another agent). Prefer unset + `DISPLAY=:9`. +- Leaving `WAYLAND_DISPLAY` set nests into another compositor (possibly another agent's). `launch.sh` unsets it; when running kawa by hand, unset it too or wlroots picks the Wayland backend. +- On a fresh X server the X11 backend's window has no title, because wlroots only looks up the atoms it names the window with. `launch.sh` creates them first, and `doctor.sh` fails if the `wlroots - X11-1` window is missing. Start Xvfb with `-noreset` so the atoms survive the last client disconnecting. - DRM FD / dmabuf errors on stderr can appear and still be OK if the ready line arrives. - Never `pkill kawa`; only the PID under `$VERIFY_KAWA_HOME/pids`. - Socket name is often a short string (not a full path); clients resolve it under `XDG_RUNTIME_DIR`. diff --git a/.cursor/skills/verify-kawa/features/layer-shell.md b/.cursor/skills/verify-kawa/features/layer-shell.md new file mode 100644 index 0000000..e0b06b0 --- /dev/null +++ b/.cursor/skills/verify-kawa/features/layer-shell.md @@ -0,0 +1,33 @@ +# Layer shell + +kawa implements `zwlr_layer_shell_v1` (`layers.go`) for wallpapers, panels, launchers, and notifications. Surfaces with an exclusive zone shrink the area used for new windows and tiling. Top and overlay surfaces that ask for exclusive keyboard get it and give it back when they let go, and layer popups (panel menus) are kept on screen below the status bar and drawn above everything. + +## Sub-features + +- `layer-background` — background-layer surfaces (`swaybg`) draw under windows. kawa's own `-bg` is not needed. +- `layer-zone` — exclusive zones (a `waybar` panel) are taken out of the usable area, so the New box, tiling, and popups stay clear of them. Zones are arranged starting from the overlay layer, and the usable area starts below kawa's status bar. `exclusive_zone -1` surfaces use the whole output. +- `layer-popup` — popups from layer surfaces (`waybar` GTK menus) open on screen and above all layers. +- `layer-keyboard` — exclusive keyboard on the top and overlay layers (`fuzzel`). Typing goes to it, the bar title is empty, and when it closes focus returns to the window that had it. `on_demand` surfaces get the keyboard when clicked. +- `layer-overlay` — overlay notifications (`mako`) sit above windows. +- Input order: layer popups, then overlay and top layers, then windows, then bottom and background layers. + +## How to get to it (user POV) + +- Run a wallpaper (`swaybg`), a panel (`waybar`), a launcher (`fuzzel`), or a notification daemon (`mako`) in kawa. + +## Driving it with process + Wayland client + +Preconditions: `compositor-boot` proven with `-terms weston-terminal` or `new-cmd.sh`; `swaybg`, `waybar`, `fuzzel`, `mako`, and `notify-send` installed. kawa's stderr logs `new layer surface "NAMESPACE" on X11-1 in layer N` for each one. Give each run its own config directory, `C=$VERIFY_KAWA_HOME/cfg`, and start every client with `bgc` (SKILL.md Drive) so `cleanup.sh` stops it. + +- `layer-background`: `bgc swaybg swaybg -c '#336633'`; `$shot layer-swaybg`. A right-press on it still opens kawa's menu. +- `layer-zone`: write `$C/waybar/config` as `{"layer":"top","position":"top","height":30,"exclusive":true,"modules-left":["custom/menu"],"modules-right":["clock"],"custom/menu":{"format":"MENU","menu":"on-click","menu-file":"$C/waybar/menu.xml","menu-actions":{"one":"true"}},"clock":{"format":"{:%H:%M:%S}","interval":1}}` (with `$C` expanded) and `$C/waybar/menu.xml` as a GtkBuilder `GtkMenu` with id `menu` and a few `GtkMenuItem`s. `bgc waybar env XDG_CONFIG_HOME="$C" waybar`. Drag a `New` box that starts above the panel: the window is clamped below it (`$shot layer-waybar-zone`). Tile a window: it starts below the panel (`$shot layer-waybar-tiled`). +- `layer-popup`: click `MENU` on the panel; the menu opens below it (`$shot layer-waybar-popup`). Press Escape to close it. +- `layer-keyboard`: with a terminal focused and no popup open, `printf '[main]\nlayer=overlay\n' >"$C/fuzzel/fuzzel.ini"` and `bgc fuzzel env XDG_CONFIG_HOME="$C" fuzzel`. Type `zzq`: fuzzel filters and the bar title is empty (`$shot layer-fuzzel-exclusive`). Press Escape, type `echo back`: it lands in the terminal (`$shot layer-fuzzel-restored`). +- `layer-overlay`: `printf 'layer=overlay\nanchor=top-right\ndefault-timeout=0\n' >"$C/mako/config"`, `bgc mako mako -c "$C/mako/config"`, `notify-send hello`; the notification is at the top right, below the panel (`$shot layer-mako`). + +## Gotchas + +- Close any popup (waybar menu) before mapping an exclusive-keyboard surface. If an xdg_popup grab is open when fuzzel maps, the keyboard stays with the old window even after the popup closes. That is a product bug; don't record it as a layer-shell pass. +- A click on empty desktop does not dismiss an open popup. Press Escape, or click the popup's own surface. +- waybar and other GTK clients need a session bus. `launch.sh` starts a private one and exports it in `env.sh`; without it GTK autolaunches a bus on the X display that later runs share. +- Don't point clients at `~/.config`. Keep configs under `$VERIFY_KAWA_HOME` so runs don't depend on each other. diff --git a/.cursor/skills/verify-kawa/features/maximize.md b/.cursor/skills/verify-kawa/features/maximize.md index e25c76a..ede1c13 100644 --- a/.cursor/skills/verify-kawa/features/maximize.md +++ b/.cursor/skills/verify-kawa/features/maximize.md @@ -1,25 +1,33 @@ # Maximize / tiling -Windows can be tiled/maximized under the status bar. The main menu item `Tile` runs `toggleViewTiling`. Maximized/tiled views sit under floating windows (wishful-thinking behavior in README, implemented via tiling). +Tiled windows share the usable area below the status bar (and any layer-shell exclusive zones) in rows, 15 px in from its edges, and sit under floating windows. The main menu item `Tile` toggles tiling for the window you pick; a client's maximize request does the same. Untiling puts the window back where it was. ## Sub-features -- `tile-toggle` — menu `Tile` then select a view. -- `request-maximize` — clients may request maximize via xdg/Xwayland hooks on the view. +- `tile-toggle` — menu `Tile`, then right-click a window. Again on a tiled window restores its old geometry. +- `tile-rows` — several tiled windows split the area side by side (`TiledRows`). +- `tile-csd` — client-decorated windows (GTK) are tiled by their window geometry, so the visible frame fits the tile exactly. +- `tile-swap` — `Move` a tiled window onto another tiled window to swap them. +- `request-maximize` — a client maximize request (GTK headerbar double-click, `xdg_toplevel.set_maximized`) toggles tiling. +- `tile-zones` — layer-shell exclusive zones shrink the tile area (layer-shell.md). ## How to get to it (user POV) -- Right-click → `Tile` → click the target window. -- Or use a client that requests maximize. +- Right-click empty desktop → `Tile` → right-click the target window. +- Or double-click a client-decorated window's title bar, or use its maximize button if it has one. ## Driving it with process + Wayland client -Preconditions: `compositor-boot` proven; a client window present (window-menu `New`). +Preconditions: `compositor-boot` proven; one window from `New` (window-menu.md), and a GTK window (`gtk3-demo` via `new-cmd.sh`) for `tile-csd` and `tile-rows`. -- Drive with `xdotool` per SKILL.md Drive: right-press on empty space → move to `Tile` → release → right-click the window. -- Proof: `screenshot.sh maximize-tiled` shows the view filling the area under the status bar, not an internal `SetMaximized` call from a unit test. +- `tile-toggle`: from the bar, pick `Tile` (item 2), then `xdotool mousemove --window "$wid" 480 380 click 3`; `$shot maximize-tiled`. Repeat to untile; `$shot maximize-untiled` shows the old position and size. +- `tile-rows` and `tile-csd`: tile a second, GTK window; `$shot maximize-two-tiled` shows both side by side with the GTK frame filling its tile. +- `tile-swap`: pick `Move` (item 3), right-press the left tile, drag onto the right one and release; `$shot maximize-tile-swap` shows them swapped. +- `request-maximize`: `New` a `gtk3-demo` window, double-click its headerbar (`xdotool mousemove --window "$wid" X Y click --repeat 2 --delay 80 1`); it tiles (`$shot maximize-request`). Double-click again; it returns to its box (`$shot maximize-request-untiled`). +- Proof is the screenshot, not an internal `SetMaximized` call from a unit test. ## Gotchas -- There is no separate menu label `Maximize`; use `Tile`. -- Status bar remains visible when tiled. +- There is no menu label `Maximize`; use `Tile`. +- The status bar stays visible when tiled. +- Border resize does nothing on a tiled window. diff --git a/.cursor/skills/verify-kawa/features/popups.md b/.cursor/skills/verify-kawa/features/popups.md new file mode 100644 index 0000000..bda6406 --- /dev/null +++ b/.cursor/skills/verify-kawa/features/popups.md @@ -0,0 +1,24 @@ +# Popups + +XDG popups (context menus, dropdowns) are configured on their first commit and unconstrained to the usable area of the parent window's output (`view.go`), so a menu opened near the bottom or right edge flips or slides to stay on screen and below the status bar. + +## Sub-features + +- `popup-map` — a popup from a toplevel maps at its requested position. +- `popup-unconstrain` — a popup that would leave the usable area is flipped or slid back onto it. + +## How to get to it (user POV) + +- Right-click inside a GTK app near the bottom-right corner of the screen; the menu opens up and to the left instead of off screen. + +## Driving it with process + Wayland client + +Preconditions: `compositor-boot` proven with `new-cmd.sh`; `gtk3-demo` installed. + +- `echo gtk3-demo >"$VERIFY_KAWA_HOME/new-cmd"`, `New` a box from 420,380 to 1020,760 so the window touches the bottom-right corner (`$shot popup-gtk3-mapped`; the client-decorated window fits the box exactly). +- Right-click in its source text view near the corner: `xdotool mousemove --window "$wid" 990 740 click 3`; `$shot popup-unconstrained` shows the context menu above and to the left of the pointer, fully on screen. Press Escape to close it. + +## Gotchas + +- A click on empty desktop does not dismiss an open popup (kawa sends no button event there). Use Escape. +- Close popups before driving keyboard focus elsewhere; an open popup grab keeps the keyboard (see layer-shell.md). diff --git a/.cursor/skills/verify-kawa/features/presentation.md b/.cursor/skills/verify-kawa/features/presentation.md new file mode 100644 index 0000000..be55a4b --- /dev/null +++ b/.cursor/skills/verify-kawa/features/presentation.md @@ -0,0 +1,26 @@ +# Presentation time and GTK4 + +kawa advertises `wp_presentation` and reports each surface as presented when its texture is drawn on an output (`render.go`). GTK4 uses that feedback to pace frames, so GTK4 apps animate and respond normally. + +## Sub-features + +- `presentation-global` — `wp_presentation` is in the registry. +- `presentation-feedback` — clients get `presented` events while they draw. +- `gtk4-app` — a GTK4 app maps, redraws on input, and its title follows its state in the bar. + +## How to get to it (user POV) + +- Run any GTK4 app (`gtk4-demo`) in kawa and click around. + +## Driving it with process + Wayland client + +Preconditions: `compositor-boot` proven; `gtk4-demo` installed (`/usr/bin/gtk4-demo`, or the `org.gtk.Demo4` flatpak). + +- `bgc gtk4 env WAYLAND_DEBUG=1 GDK_BACKEND=wayland gtk4-demo`; `$shot gtk4-demo`. +- Count `grep -c 'wp_presentation_feedback#[0-9]*\.presented' "$VERIFY_KAWA_EVIDENCE/gtk4.stderr"`, click a few demo entries (`$shot gtk4-demo-clicked`), count again; the number grows and the bar shows the new title. +- `presentation-global`: the `wayland-registry` capture lists `wp_presentation`. + +## Gotchas + +- `WAYLAND_DEBUG` output is large; keep it in evidence, not on the terminal. +- GTK4 apps need the session bus that `launch.sh` exports. diff --git a/.cursor/skills/verify-kawa/features/status-bar.md b/.cursor/skills/verify-kawa/features/status-bar.md index 26ebef2..1bfaa1c 100644 --- a/.cursor/skills/verify-kawa/features/status-bar.md +++ b/.cursor/skills/verify-kawa/features/status-bar.md @@ -1,31 +1,33 @@ # Status bar -A top status bar is drawn on the primary output. The focused window title is pushed into the bar via `StatusBar.SetTitle`. README plans a clock/time display; that is not separately logged today and needs a visual capture later. +A bar across the top of the primary output shows the focused window's title, kept up to date when the title changes. Pressing on it opens kawa's menus. README plans a clock; it is not implemented. ## Sub-features -- `bar-chrome` — bar region (`StatusBarHeight`) rendered each frame on the status-bar output. -- `focused-title` — bar title tracks the focused view title. -- `time-display` — planned (README); not asserted by log today. +- `bar-chrome` — bar region (`StatusBarHeight`) drawn each frame on the status-bar output. +- `focused-title` — the bar shows the focused window's title and follows title changes. It is empty while a layer surface (a launcher) has the keyboard. +- `bar-menus` — left-press → system menu (`Log Out`); right-press → main menu. +- `time-display` — planned in README; not implemented. ## How to get to it (user POV) - Start kawa; look at the top of the compositor window. -- Focus a window; the bar title updates. +- Focus a window, or let it change its title; the bar follows. - Left-click the status bar for the system menu (`Log Out`); right-click it for the main menu. ## Driving it with process + Wayland client Preconditions: `compositor-boot` proven. -- `bar-chrome`: `screenshot.sh status-bar` after boot shows the bar across the top. -- `focused-title`: map a window (window-menu `New`), then `screenshot.sh`; the bar shows its title. -- Bar menus: `xdotool mousemove --window "$wid" 600 10 mousedown 3` → main menu; `mousedown 1` → `Log Out`. Screenshot each, then move below the menu before `mouseup` to cancel. -- `time-display`: not implemented; report as such. +- `bar-chrome`: `$shot status-bar-boot` after boot shows the bar across the top. +- `focused-title`: map a window (window-menu `New`), then `$shot`; the bar shows its title. A GTK app that changes its title (clicking entries in `gtk4-demo`) changes the bar. +- `bar-menus`: `xdotool mousemove --window "$wid" 600 10 mousedown 3` → main menu (`$shot status-bar-right`); `mousedown 1` → `Log Out` (`$shot status-bar-left`). Move below the menu before releasing to cancel (`$shot after-bar-cancel`). +- `time-display`: not implemented; report it as such. - Do not call `SetTitle` from a test helper and call that proof. ## Gotchas -- Title updates are render-path side effects; there is no stdout clock line to grep. +- Title updates are render-path side effects; there is no log line to grep. - Any press with Y ≤ `StatusBarHeight` (or with Logo held) opens a menu: left → system, right → main (`mode.go`). - Releasing button 1 without moving selects `Log Out` and shuts kawa down. +- A layer-shell panel (waybar) is placed below kawa's bar, not over it. diff --git a/.cursor/skills/verify-kawa/features/window-management.md b/.cursor/skills/verify-kawa/features/window-management.md new file mode 100644 index 0000000..1e8768c --- /dev/null +++ b/.cursor/skills/verify-kawa/features/window-management.md @@ -0,0 +1,35 @@ +# Window management + +The main menu's `Move`, `Resize`, `Close`, and `Hide` act on a window you pick with a right-click after choosing the item. Windows can also be moved and resized directly: right-press a server-side border to move, left-press it to resize, and client-side decorations (a GTK headerbar) ask kawa to move or resize. Hidden windows get main-menu entries that bring them back. + +## Sub-features + +- `move` — `Move`, then right-press a window and drag; it follows the pointer until release. Right-press on a server-side border does the same without the menu. +- `resize` — `Resize`, then right-click a window and right-drag a new box. The window takes the box on release. +- `border-resize` — left-press on a server-side border drags that edge or corner (not while tiled). +- `client-move` — a client move or resize request (GTK headerbar drag, CSD edge) starts the same interaction. +- `close` — `Close`, then right-click a window: XDG windows get `close`, X11 windows `WM_DELETE_WINDOW`. kawa reaps its exited children. +- `hide` — `Hide`, then right-click a window: it disappears and its title is added to the end of the main menu. Choosing that entry shows it again. +- `tile-swap` — moving a tiled window onto another tiled window swaps their places (see maximize.md). + +## How to get to it (user POV) + +- Right-click empty desktop, choose the action, then right-click the window to act on. For `Move` and `Resize` keep the button held and drag. +- Drag a window by its title bar (client decorations) or its border (server decorations). +- Hidden windows are listed below `Hide` in the main menu. + +## Driving it with process + Wayland client + +Preconditions: `compositor-boot` proven; one or two windows from `New` (window-menu.md). Open menus from the bar with the `barmenu` pattern in SKILL.md Drive: item 1 `Resize`, 3 `Move`, 4 `Close`, 5 `Hide`, 6 and up hidden windows. + +- `move`: pick `Move`, then `xdotool mousemove --window "$wid" 400 300 mousedown 3 sleep 0.2 mousemove --window "$wid" 420 320 sleep 0.2 mousemove --window "$wid" 300 250 sleep 0.3 mouseup 3`; `$shot wm-move`. +- `resize`: pick `Resize`, `xdotool mousemove --window "$wid" 400 300 click 3`, then right-drag a box `mousedown 3 … mousemove … mouseup 3` with one more small `mousemove` just before `mouseup 3`; `$shot wm-resize`. Repeat it to prove it works again. +- `client-move`: left-drag a GTK headerbar in several steps (`mousedown 1`, moves of 10, 30, 100, 50 px, `mouseup 1`), then move the pointer again; the window stays where it was dropped (`$shot wm-client-move`). +- `close`: pick `Close`, right-click the window; `kill -0 PID` fails afterwards and `ps --ppid` no longer lists it (`$shot wm-closed`). +- `hide`: pick `Hide`, right-click the window (`$shot wm-hidden`), open the menu again (`$shot wm-hidden-menu` shows the title at item 6), pick item 6 (`$shot wm-unhidden`). + +## Gotchas + +- `Resize` shows a box until it passes the minimum size, then switches to resizing the window, which only applies on the next motion. Without one extra pointer motion before release, the window keeps its old size. +- A right-press on a window's border starts a move, not the menu. Open the menu from the bar or empty desktop. +- After `Hide`, the hidden window keeps keyboard focus and its title stays in the bar; keys typed then still reach it. That is a product bug, not harness drift; click another window before typing. diff --git a/.cursor/skills/verify-kawa/features/window-menu.md b/.cursor/skills/verify-kawa/features/window-menu.md index e638a44..bd66448 100644 --- a/.cursor/skills/verify-kawa/features/window-menu.md +++ b/.cursor/skills/verify-kawa/features/window-menu.md @@ -1,28 +1,41 @@ -# Window menu / new terminal +# Window menu / new windows -Right-click opens the main menu (`New`, `Resize`, `Tile`, `Move`, `Close`, `Hide`). Choosing `New` runs the first working entry from `-terms` (default `sakura`, `alacritty`) via `Server.exec`. +Right-pressing empty desktop or the status bar opens the main menu: `New`, `Resize`, `Tile`, `Move`, `Close`, `Hide`, then one entry per hidden window. `New` asks for a box, starts the first `-terms` entry that will run (default `sakura`, `alacritty`), and puts the program's window in that box. The box stays on screen until the window maps or the program exits. ## Sub-features -- `main-menu` — right-click → main menu items from `mainMenuText`. -- `system-menu` — left-click on status bar → `Log Out` (shuts down the compositor). -- `new-terminal` — `New` spawns a terminal from `-terms`. +- `main-menu` — right-press on empty desktop, on the status bar, or anywhere with Logo held opens the main menu (`mainMenuText` in `kawa.go`, `onMainMenuSelected` in `mode.go`). +- `system-menu` — left-press on the status bar opens a menu with only `Log Out`, which shuts the compositor down. +- `new-window` — `New`, then right-drag a box. Once the drag passes the minimum size (128x24), kawa starts the program. The child gets `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` set to a trusted activation token. Its stdout and stderr go to `/dev/null`. +- `new-box` — the red-bordered box stays drawn after the drag until a window whose PID matches the child maps, or the child exits (`startNew` in `mode.go`). A program that exits without a window clears the box. +- `new-late-map` — a window that maps after the drag ended takes the box and gets keyboard focus. The next click is not swallowed. +- `new-early-map` — a window that maps while the drag is still going border-resizes with the pointer until release. +- `new-grandchild` — a window opened by some other process (for example a grandchild after the started program exited) does not match the box. It opens centered on the output, on top but unfocused. ## How to get to it (user POV) -- Right-click empty space or a window decoration area to open the main menu. -- Select `New`, then drag out a rectangle to place the new terminal. -- Pass `-terms 'foot,alacritty'` (comma-separated list via the flag’s string-list parser) to prefer available terminals. +- Right-click empty desktop or the status bar to open the main menu. A right-press on a window's server-side border starts a move instead, and a press in a window's content goes to that window. +- Choose `New`, then right-drag out a box for the new window. +- Pass `-terms 'foot,alacritty'` (comma-separated). Each entry is split on whitespace, so an entry can carry arguments, e.g. `-terms 'foot -e htop'`. ## Driving it with process + Wayland client -Preconditions: `compositor-boot` proven; `launch.sh -terms TERM` with an installed terminal when the defaults (`sakura`, `alacritty`) are not installed (e.g. `-terms weston-terminal`). +Preconditions: `compositor-boot` proven; launched with `-terms "$VERIFY_KAWA_ROOT/.cursor/skills/verify-kawa/scripts/new-cmd.sh"` (absolute path) or with an installed terminal (e.g. `-terms weston-terminal`). -- Drive with `xdotool` per SKILL.md Drive: right-press → `screenshot.sh window-menu-main` → release on `New` → right-drag a rectangle. -- Proof: the terminal is a child of the kawa PID, stderr logs `new xdg_surface`, and `screenshot.sh` shows it in the dragged rectangle. +- Open menus from the bar so the item positions are fixed (SKILL.md Drive): `xdotool mousemove --window "$wid" 600 10 mousedown 3`, `$shot window-menu-main`, then move to `y=20+19*I` and release to pick item `I`. +- `new-window`: pick `New` (item 0), then right-drag `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`. Proof: `ps -o pid,cmd --ppid "$(cat "$VERIFY_KAWA_HOME/pids/kawa.pid")"` lists the program, `tr '\0' '\n' "$VERIFY_KAWA_HOME/new-cmd"`, drag a box, `$shot new-box-waiting` within 2 s (box still drawn), then `$shot new-box-cleared` after 3 s (box gone). +- `new-late-map`: `echo "sh -c 'sleep 2; exec weston-terminal'" >"$VERIFY_KAWA_HOME/new-cmd"`, drag, `$shot new-late-waiting`, wait 4 s, `$shot new-late-mapped` (window in the box, title in the bar). Then a bar right-press still opens the menu (`$shot new-late-menu`). +- `new-grandchild`: `echo "sh -c '(sleep 2; weston-terminal) & exit 0'" >"$VERIFY_KAWA_HOME/new-cmd"`, drag. The box clears when `sh` exits, and the terminal later appears centered without focus (`$shot new-fork-mapped`). +- `system-menu`: `xdotool mousemove --window "$wid" 600 10 mousedown 1`, `$shot status-bar-left`, then `mousemove --window "$wid" 600 300 mouseup 1` to cancel. - Never mark verified by calling `onMainMenuNew` from Go tests alone. ## Gotchas - If no terminal from `-terms` starts, stderr logs `no valid terminals found for new window`. -- `Log Out` terminates the display — do not select it during other proofs without intending cleanup. +- Use an absolute path for `-terms` entries that are scripts. kawa starts them from its own working directory. +- Because kawa discards the program's output, a `-terms weston-terminal` failure is silent. Use `new-cmd.sh` when you need the output. +- `Log Out` terminates the display. Releasing button 1 on the bar without moving selects it. +- A menu opened away from the bar puts the last-chosen item under the pointer, shifted to stay on screen, so near the screen edges the item under the pointer is not the one you expect. A press near the bottom-right corner can land on `Hide`. +- If the drag never passes the minimum size, nothing is started. diff --git a/.cursor/skills/verify-kawa/features/xwayland.md b/.cursor/skills/verify-kawa/features/xwayland.md new file mode 100644 index 0000000..8da57f5 --- /dev/null +++ b/.cursor/skills/verify-kawa/features/xwayland.md @@ -0,0 +1,27 @@ +# Xwayland + +kawa starts Xwayland at startup and runs X11 programs as ordinary windows with kawa's own border and title bar. X programs started by `New` land in the New box (kawa matches them by PID), `Close` sends them `WM_DELETE_WINDOW`, and the clipboard and primary selection are shared between X and Wayland clients through the seat. + +## Sub-features + +- `xwayland-start` — stderr logs `Running Xwayland on DISPLAY=:N`. kawa exports that `DISPLAY`, so everything it starts, `New` included, talks to Xwayland. +- `xwayland-new` — an X program started by `New` maps in the box with server-side decorations and its title in the bar. +- `xwayland-close` — `Close` on an X window makes it exit, and kawa reaps it. +- `xwayland-clipboard` — the CLIPBOARD selection copies X → Wayland and Wayland → X. +- `xwayland-primary` — the PRIMARY selection copies both ways too. `zwp_primary_selection_device_manager_v1` and `zwlr_data_control_manager_v1` are advertised. + +## How to get to it (user POV) + +- Start an X11 program (from `New` or a terminal inside kawa). Copy in an X program and paste in a Wayland one, or the reverse. + +## Driving it with process + Wayland client + +Preconditions: `compositor-boot` proven with `new-cmd.sh` as `-terms`; `xclock`, `xclip`, `xsel`, `wl-copy`, `wl-paste`, `xdotool` installed. Get the Xwayland display with `XD=$(sed -n 's/.*Running Xwayland on DISPLAY=\(:[0-9]*\).*/\1/p' "$VERIFY_KAWA_HOME/logs/kawa.stderr" | tail -n1)`. It is not the parent `DISPLAY` that `xdotool` and `screenshot.sh` use. + +- `xwayland-new`: `echo xclock >"$VERIFY_KAWA_HOME/new-cmd"`, `New` a box. `$shot xwayland-xclock-new` shows the clock in the box with kawa's border and `xclock` in the bar. +- `xwayland-clipboard` and `xwayland-primary`, with xclock focused (click it first). X → Wayland: `printf x2w | DISPLAY=$XD xclip -selection clipboard -i`, then `wl-paste -n` prints `x2w`. Wayland → X: `wl-copy w2x`, then `DISPLAY=$XD xclip -selection clipboard -o` (and `xsel -b -o`) print `w2x`. Repeat with `-selection primary`, `wl-paste -p`, `wl-copy -p`, and `xsel -p`. Save the four results to `$VERIFY_KAWA_EVIDENCE/xwayland-clipboard.txt`. Run `xclip -i` in the background with its PID recorded; it stays up to serve the selection. +- `xwayland-close`: `Close`, right-click xclock; its PID exits and `ps --ppid` no longer lists it (`$shot xwayland-closed`). + +## Gotchas + +- X → Wayland copies only work while an X window has keyboard focus. With a Wayland window focused, `wl-paste` reports `Nothing is copied`; this is how wlroots hands selections to Xwayland, not a kawa bug. Wayland → X works either way. diff --git a/.cursor/skills/verify-kawa/scripts/activation-client.c b/.cursor/skills/verify-kawa/scripts/activation-client.c new file mode 100644 index 0000000..c098f44 --- /dev/null +++ b/.cursor/skills/verify-kawa/scripts/activation-client.c @@ -0,0 +1,224 @@ +/* activation-client: a tiny xdg-activation-v1 test client for kawa. + * It maps a 320x200 window, titled NAME, in a solid color picked from NAME, + * and prints what it does and keyboard enter/leave on stdout. + * activation-client NAME launch CMD... on each click, get a token (click serial + own surface) and start CMD with it + * activation-client NAME start activate with $XDG_ACTIVATION_TOKEN before mapping + * activation-client NAME start-after activate with $XDG_ACTIVATION_TOKEN after mapping + * activation-client NAME self SECS after SECS, get a token with no serial or surface and activate self + * activation-client NAME self-stale SECS after SECS, get a token from the last click's serial and own surface, activate self + * activation-client NAME fifo PATH activate with each token written to the FIFO at PATH, like a single-instance app + * ACTIVATION_CLIENT_MINIMIZE=1 asks to be minimized right after mapping. + * launch.sh generates the protocol code with wayland-scanner and builds this. */ +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include "xdg-shell-client.h" +#include "xdg-activation-v1-client.h" + +static struct wl_compositor *compositor; +static struct wl_shm *shm; +static struct wl_seat *seat; +static struct xdg_wm_base *wm_base; +static struct xdg_activation_v1 *activation; +static struct wl_surface *surface; +static struct xdg_toplevel *toplevel; +static const char *name, *mode; +static char **cmd; +static uint32_t last_serial; +static int configured, running = 1; +static double deadline; + +static double now(void) { + struct timespec ts; + clock_gettime(CLOCK_MONOTONIC, &ts); + return ts.tv_sec + ts.tv_nsec / 1e9; +} + +static void draw(int w, int h, uint32_t color) { + int stride = w * 4, size = stride * h; + int fd = memfd_create("activation-client", 0); + ftruncate(fd, size); + uint32_t *px = mmap(NULL, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); + for (int i = 0; i < w * h; i++) px[i] = color; + munmap(px, size); + struct wl_shm_pool *pool = wl_shm_create_pool(shm, fd, size); + struct wl_buffer *buf = wl_shm_pool_create_buffer(pool, 0, w, h, stride, WL_SHM_FORMAT_XRGB8888); + wl_shm_pool_destroy(pool); + close(fd); + wl_surface_attach(surface, buf, 0, 0); + wl_surface_damage_buffer(surface, 0, 0, w, h); + wl_surface_commit(surface); +} + +static void activate(const char *token, const char *why) { + printf("%s: activate %s (%s)\n", name, token, why); + fflush(stdout); + xdg_activation_v1_activate(activation, token, surface); +} + +static void token_done(void *data, struct xdg_activation_token_v1 *t, const char *token) { + printf("%s: token done %s\n", name, token); + fflush(stdout); + if (strcmp(mode, "launch") == 0) { + if (fork() == 0) { + setenv("XDG_ACTIVATION_TOKEN", token, 1); + setenv("DESKTOP_STARTUP_ID", token, 1); + execvp(cmd[0], cmd); + _exit(127); + } + } else { + activate(token, mode); + } + xdg_activation_token_v1_destroy(t); +} +static const struct xdg_activation_token_v1_listener token_listener = { .done = token_done }; + +static void request_token(int with_serial) { + struct xdg_activation_token_v1 *t = xdg_activation_v1_get_activation_token(activation); + xdg_activation_token_v1_add_listener(t, &token_listener, NULL); + if (with_serial) { + xdg_activation_token_v1_set_serial(t, last_serial, seat); + xdg_activation_token_v1_set_surface(t, surface); + } + xdg_activation_token_v1_commit(t); +} + +static void p_enter(void *d, struct wl_pointer *p, uint32_t s, struct wl_surface *sf, wl_fixed_t x, wl_fixed_t y) {} +static void p_leave(void *d, struct wl_pointer *p, uint32_t s, struct wl_surface *sf) {} +static void p_motion(void *d, struct wl_pointer *p, uint32_t t, wl_fixed_t x, wl_fixed_t y) {} +static void p_button(void *d, struct wl_pointer *p, uint32_t serial, uint32_t t, uint32_t button, uint32_t state) { + if (state != WL_POINTER_BUTTON_STATE_PRESSED) return; + last_serial = serial; + if (strcmp(mode, "launch") == 0) request_token(1); +} +static void p_axis(void *d, struct wl_pointer *p, uint32_t t, uint32_t a, wl_fixed_t v) {} +static const struct wl_pointer_listener pointer_listener = { p_enter, p_leave, p_motion, p_button, p_axis }; + +static void k_keymap(void *d, struct wl_keyboard *k, uint32_t f, int32_t fd, uint32_t sz) { close(fd); } +static void k_enter(void *d, struct wl_keyboard *k, uint32_t s, struct wl_surface *sf, struct wl_array *keys) { + printf("%s: keyboard enter\n", name); + fflush(stdout); +} +static void k_leave(void *d, struct wl_keyboard *k, uint32_t s, struct wl_surface *sf) { + printf("%s: keyboard leave\n", name); + fflush(stdout); +} +static void k_key(void *d, struct wl_keyboard *k, uint32_t s, uint32_t t, uint32_t key, uint32_t st) {} +static void k_mods(void *d, struct wl_keyboard *k, uint32_t s, uint32_t a, uint32_t b, uint32_t c, uint32_t g) {} +static void k_repeat(void *d, struct wl_keyboard *k, int32_t r, int32_t dl) {} +static const struct wl_keyboard_listener keyboard_listener = { k_keymap, k_enter, k_leave, k_key, k_mods, k_repeat }; + +static void seat_caps(void *d, struct wl_seat *s, uint32_t caps) { + static int done; + if (done) return; + done = 1; + if (caps & WL_SEAT_CAPABILITY_POINTER) wl_pointer_add_listener(wl_seat_get_pointer(s), &pointer_listener, NULL); + if (caps & WL_SEAT_CAPABILITY_KEYBOARD) wl_keyboard_add_listener(wl_seat_get_keyboard(s), &keyboard_listener, NULL); +} +static void seat_name(void *d, struct wl_seat *s, const char *n) {} +static const struct wl_seat_listener seat_listener = { seat_caps, seat_name }; + +static void wm_ping(void *d, struct xdg_wm_base *b, uint32_t serial) { xdg_wm_base_pong(b, serial); } +static const struct xdg_wm_base_listener wm_listener = { wm_ping }; + +static void xs_configure(void *d, struct xdg_surface *xs, uint32_t serial) { + xdg_surface_ack_configure(xs, serial); + if (!configured) { + configured = 1; + uint32_t h = 0; + for (const char *c = name; *c; c++) h = h * 31 + (unsigned char)*c; + draw(320, 200, 0xFF000000 | (h & 0x7F7F7F) | 0x404040); + if (strcmp(mode, "start-after") == 0 && getenv("XDG_ACTIVATION_TOKEN")) + activate(getenv("XDG_ACTIVATION_TOKEN"), "after map"); + if (getenv("ACTIVATION_CLIENT_MINIMIZE")) { + printf("%s: set_minimized\n", name); + fflush(stdout); + xdg_toplevel_set_minimized(toplevel); + } + } else { + wl_surface_commit(surface); + } +} +static const struct xdg_surface_listener xs_listener = { xs_configure }; + +static void tl_configure(void *d, struct xdg_toplevel *t, int32_t w, int32_t h, struct wl_array *s) {} +static void tl_close(void *d, struct xdg_toplevel *t) { running = 0; } +static const struct xdg_toplevel_listener tl_listener = { tl_configure, tl_close }; + +static void reg_global(void *d, struct wl_registry *r, uint32_t id, const char *iface, uint32_t v) { + if (!strcmp(iface, wl_compositor_interface.name)) compositor = wl_registry_bind(r, id, &wl_compositor_interface, 4); + else if (!strcmp(iface, wl_shm_interface.name)) shm = wl_registry_bind(r, id, &wl_shm_interface, 1); + else if (!strcmp(iface, wl_seat_interface.name)) { seat = wl_registry_bind(r, id, &wl_seat_interface, 1); wl_seat_add_listener(seat, &seat_listener, NULL); } + else if (!strcmp(iface, xdg_wm_base_interface.name)) { wm_base = wl_registry_bind(r, id, &xdg_wm_base_interface, 1); xdg_wm_base_add_listener(wm_base, &wm_listener, NULL); } + else if (!strcmp(iface, xdg_activation_v1_interface.name)) activation = wl_registry_bind(r, id, &xdg_activation_v1_interface, 1); +} +static void reg_remove(void *d, struct wl_registry *r, uint32_t id) {} +static const struct wl_registry_listener reg_listener = { reg_global, reg_remove }; + +int main(int argc, char **argv) { + if (argc < 3) { fprintf(stderr, "usage: activation-client NAME MODE [ARGS]\n"); return 2; } + name = argv[1]; + signal(SIGCHLD, SIG_IGN); /* reap what launch starts */ + mode = argv[2]; + cmd = argv + 3; + struct wl_display *dpy = wl_display_connect(NULL); + if (!dpy) { perror("connect"); return 1; } + wl_registry_add_listener(wl_display_get_registry(dpy), ®_listener, NULL); + wl_display_roundtrip(dpy); + wl_display_roundtrip(dpy); + if (!activation) { fprintf(stderr, "%s: no xdg_activation_v1\n", name); } + + surface = wl_compositor_create_surface(compositor); + struct xdg_surface *xs = xdg_wm_base_get_xdg_surface(wm_base, surface); + xdg_surface_add_listener(xs, &xs_listener, NULL); + toplevel = xdg_surface_get_toplevel(xs); + xdg_toplevel_add_listener(toplevel, &tl_listener, NULL); + xdg_toplevel_set_title(toplevel, name); + xdg_toplevel_set_app_id(toplevel, name); + if (strcmp(mode, "start") == 0 && activation && getenv("XDG_ACTIVATION_TOKEN")) + activate(getenv("XDG_ACTIVATION_TOKEN"), "before map"); + wl_surface_commit(surface); + + if (!strcmp(mode, "self") || !strcmp(mode, "self-stale")) + deadline = now() + (argc > 3 ? atof(argv[3]) : 5); + + struct pollfd pfd[2] = { { .fd = wl_display_get_fd(dpy), .events = POLLIN }, { .fd = -1, .events = POLLIN } }; + if (!strcmp(mode, "fifo")) pfd[1].fd = open(argv[3], O_RDWR | O_NONBLOCK); + while (running) { + wl_display_dispatch_pending(dpy); + wl_display_flush(dpy); + int timeout = -1; + if (deadline > 0) { + double left = deadline - now(); + if (left <= 0) { + deadline = 0; + request_token(!strcmp(mode, "self-stale")); + continue; + } + timeout = (int)(left * 1000) + 1; + } + if (poll(pfd, 2, timeout) <= 0) continue; + if (pfd[1].revents & POLLIN) { + char buf[256]; + ssize_t n = read(pfd[1].fd, buf, sizeof(buf) - 1); + if (n > 0) { + buf[n] = 0; + buf[strcspn(buf, "\n")] = 0; + activate(buf, "fifo"); + wl_display_flush(dpy); + } + } + if ((pfd[0].revents & POLLIN) && wl_display_dispatch(dpy) < 0) break; + } + return 0; +} diff --git a/.cursor/skills/verify-kawa/scripts/cleanup.sh b/.cursor/skills/verify-kawa/scripts/cleanup.sh index 1ff3874..5b3329b 100755 --- a/.cursor/skills/verify-kawa/scripts/cleanup.sh +++ b/.cursor/skills/verify-kawa/scripts/cleanup.sh @@ -14,6 +14,8 @@ case "$VERIFY_KAWA_HOME" in ;; esac +kawa_pid=$(cat "$VERIFY_KAWA_HOME/pids/kawa.pid" 2>/dev/null || true) + if [ -d "$VERIFY_KAWA_HOME/pids" ]; then for f in "$VERIFY_KAWA_HOME/pids"/*; do [ -f "$f" ] || continue @@ -31,5 +33,69 @@ if [ -d "$VERIFY_KAWA_HOME/pids" ]; then done fi +# Programs can outlive their recorded PIDs: grandchildren of New, and the +# D-Bus session that GTK clients autolaunch on the X display along with the +# portals it starts. They all carry this run's XDG_RUNTIME_DIR, so stop the +# caller's processes that still have it, except for this script, the shells +# that started it, and its own children. +run="$VERIFY_KAWA_HOME/run" +ppid_of() { + sed -n 's/^[0-9]* (.*) [A-Za-z] \([0-9]*\) .*/\1/p' "/proc/$1/stat" 2>/dev/null +} +keep=" " +p=$$ +while [ -n "$p" ] && [ "$p" -gt 1 ]; do + keep="$keep$p " + p=$(ppid_of "$p") +done +mine() { + case "$keep" in *" $1 "*) return 0 ;; esac + p=$(ppid_of "$1") + while [ -n "$p" ] && [ "$p" -gt 1 ]; do + [ "$p" != "$$" ] || return 0 + p=$(ppid_of "$p") + done + return 1 +} +residue() { + for env in /proc/[0-9]*/environ; do + pid=${env#/proc/} + pid=${pid%/environ} + [ -O "$env" ] || continue + tr '\0' '\n' <"$env" 2>/dev/null | grep -qxF "XDG_RUNTIME_DIR=$run" || continue + mine "$pid" || printf '%s\n' "$pid" + done +} +for sig in TERM KILL; do + pids=$(residue) + [ -n "$pids" ] || break + printf 'cleanup: stopping leftover processes (SIG%s): %s\n' "$sig" "$(echo $pids)" + kill -s "$sig" $pids 2>/dev/null || true + sleep 1 +done + +# xdg-document-portal mounts $XDG_RUNTIME_DIR/doc; rm cannot remove a mount. +if grep -qF " $run/doc " /proc/self/mounts; then + fusermount3 -u "$run/doc" 2>/dev/null || fusermount -u "$run/doc" 2>/dev/null || true + n=0 + while [ "$n" -lt 20 ] && grep -qF " $run/doc " /proc/self/mounts; do + sleep 0.1 + n=$((n + 1)) + done +fi + +# kawa does not clean up after itself on SIGTERM, so the X lock and socket +# of the Xwayland it started are left behind. Remove the ones that name it. +if [ -n "$kawa_pid" ] && ! kill -0 "$kawa_pid" 2>/dev/null; then + for lock in /tmp/.X*-lock; do + [ -O "$lock" ] || continue + [ "$(tr -d ' \0\n' <"$lock" 2>/dev/null)" = "$kawa_pid" ] || continue + n=${lock#/tmp/.X} + n=${n%-lock} + rm -f "/tmp/.X11-unix/X$n" "$lock" + printf 'cleanup: removed stale Xwayland display :%s\n' "$n" + done +fi + rm -rf "$VERIFY_KAWA_HOME" printf 'cleanup: removed %s (evidence kept at %s)\n' "$VERIFY_KAWA_HOME" "${VERIFY_KAWA_EVIDENCE:-unset}" diff --git a/.cursor/skills/verify-kawa/scripts/doctor.sh b/.cursor/skills/verify-kawa/scripts/doctor.sh index c8b971b..93f031f 100755 --- a/.cursor/skills/verify-kawa/scripts/doctor.sh +++ b/.cursor/skills/verify-kawa/scripts/doctor.sh @@ -51,9 +51,10 @@ case "$mode" in esac if [ -z "${DISPLAY:-}" ]; then - fail "DISPLAY is unset; X11 backend needs a parent X display (e.g. DISPLAY=:9)" + fail "DISPLAY is unset; X11 backend needs a parent X display (start a private Xvfb, see SKILL.md Launch)" fi -if [ -n "${WAYLAND_DISPLAY:-}" ]; then +# Clients are pointed at kawa's own socket on purpose; only another one is suspect. +if [ -n "${WAYLAND_DISPLAY:-}" ] && [ "$WAYLAND_DISPLAY" != "${VERIFY_KAWA_WAYLAND_DISPLAY:-}" ]; then # Nested under another compositor is allowed for interactive use, but # verification prefers X11 so we do not attach to another agent's session. printf 'doctor: warning WAYLAND_DISPLAY=%s is set; prefer unsetting it so kawa uses the X11 backend\n' "$WAYLAND_DISPLAY" >&2 @@ -113,6 +114,9 @@ if [ -f "$VERIFY_KAWA_HOME/pids/kawa.pid" ]; then fi [ "$VERIFY_KAWA_WAYLAND_DISPLAY" = "$sock" ] \ || fail "VERIFY_KAWA_WAYLAND_DISPLAY=$VERIFY_KAWA_WAYLAND_DISPLAY != log sock $sock" + # screenshot.sh and the xdotool recipes find kawa's window by this title. + xwininfo -root -tree | grep -q '"wlroots - X11-1"' \ + || fail "no \"wlroots - X11-1\" window on DISPLAY=$DISPLAY (kawa was started without launch.sh, or on a display it cannot title)" fi printf 'doctor: ok bin=%s home=%s display=%s wlroots=%s\n' \ diff --git a/.cursor/skills/verify-kawa/scripts/launch.sh b/.cursor/skills/verify-kawa/scripts/launch.sh index b540fab..ec834b9 100755 --- a/.cursor/skills/verify-kawa/scripts/launch.sh +++ b/.cursor/skills/verify-kawa/scripts/launch.sh @@ -46,18 +46,31 @@ export GOTOOLCHAIN=auto # Prefer X11 backend so we do not nest into another agent's Wayland session. unset WAYLAND_DISPLAY || true -if [ -z "${DISPLAY:-}" ]; then - for s in /tmp/.X11-unix/X*; do - [ -e "$s" ] || continue - n=$(basename "$s" | sed 's/^X//') - DISPLAY=":$n" - break - done - [ -n "${DISPLAY:-}" ] || fail "no DISPLAY and no /tmp/.X11-unix sockets" - export DISPLAY -fi +# Guessing a display could land kawa on another agent's X server, so the +# caller has to name its own. +[ -n "${DISPLAY:-}" ] || fail "DISPLAY is unset; start a private Xvfb (see SKILL.md Launch) and export DISPLAY" +xdpyinfo >/dev/null 2>&1 || fail "cannot connect to DISPLAY=$DISPLAY" +export DISPLAY unset WLR_BACKENDS || true +# The X11 backend only looks up the atoms that it names its window with and +# never creates them, so on a fresh X server the window stays untitled and +# screenshot.sh cannot find it. Create them first. +python3 - <<'PY' || fail "could not intern the X11 backend's window atoms on DISPLAY=$DISPLAY" +import ctypes +x = ctypes.CDLL("libX11.so.6") +x.XOpenDisplay.restype = ctypes.c_void_p +x.XOpenDisplay.argtypes = [ctypes.c_char_p] +x.XInternAtom.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_int] +x.XCloseDisplay.argtypes = [ctypes.c_void_p] +d = x.XOpenDisplay(None) +if not d: + raise SystemExit(1) +for name in (b"WM_PROTOCOLS", b"WM_DELETE_WINDOW", b"_NET_WM_NAME", b"UTF8_STRING"): + x.XInternAtom(d, name, 0) +x.XCloseDisplay(d) +PY + # Do not override the real HOME (module cache / toolchain live there). case "${HOME:-}" in /tmp/verify-kawa-*) @@ -84,6 +97,25 @@ helper_bin="$VERIFY_KAWA_HOME/bin/wayland-registry" gcc -O2 -o "$helper_bin" "$helper_src" $(pkg-config --cflags --libs wayland-client) export VERIFY_KAWA_HELPER="$helper_bin" +# activation-client drives xdg-activation (features/activation.md). It needs +# wayland-protocols for the protocol XML; without it only that helper is missing. +act_bin="$VERIFY_KAWA_HOME/bin/activation-client" +if protocols=$(pkg-config --variable=pkgdatadir wayland-protocols 2>/dev/null) && [ -n "$protocols" ]; then + gen="$VERIFY_KAWA_HOME/bin/gen" + mkdir -p "$gen" + for xml in "$protocols/stable/xdg-shell/xdg-shell.xml" "$protocols/staging/xdg-activation/xdg-activation-v1.xml"; do + base=$(basename "$xml" .xml) + wayland-scanner client-header "$xml" "$gen/$base-client.h" + wayland-scanner private-code "$xml" "$gen/$base-protocol.c" + done + gcc -O2 -Wall -I"$gen" -o "$act_bin" \ + "$VERIFY_KAWA_ROOT/.cursor/skills/verify-kawa/scripts/activation-client.c" \ + "$gen/xdg-shell-protocol.c" "$gen/xdg-activation-v1-protocol.c" \ + $(pkg-config --cflags --libs wayland-client) +else + printf 'launch: warning: wayland-protocols not found by pkg-config; activation-client not built\n' >&2 +fi + if [ -f "$VERIFY_KAWA_HOME/pids/kawa.pid" ]; then old=$(cat "$VERIFY_KAWA_HOME/pids/kawa.pid") if [ -n "$old" ] && kill -0 "$old" 2>/dev/null; then @@ -91,6 +123,19 @@ if [ -f "$VERIFY_KAWA_HOME/pids/kawa.pid" ]; then fi fi +# A private session bus. Without one, GTK clients autolaunch a bus on the X +# display that every later run on that display shares, and the portals it +# starts mount $XDG_RUNTIME_DIR/doc. cleanup.sh stops it with the rest. +unset DBUS_SESSION_BUS_ADDRESS || true +if command -v dbus-daemon >/dev/null 2>&1; then + bus="unix:path=$XDG_RUNTIME_DIR/bus" + dbus-daemon --session --fork --address="$bus" --print-pid >"$VERIFY_KAWA_HOME/pids/dbus.pid" \ + || fail "could not start a private D-Bus session" + export DBUS_SESSION_BUS_ADDRESS="$bus" +else + printf 'launch: warning: dbus-daemon not found; GTK clients will autolaunch a shared session bus\n' >&2 +fi + stdout_log="$VERIFY_KAWA_HOME/logs/kawa.stdout" stderr_log="$VERIFY_KAWA_HOME/logs/kawa.stderr" : >"$stdout_log" @@ -163,9 +208,13 @@ printf '%s\n' "$sock" >"$VERIFY_KAWA_HOME/wayland-display" printf "export VERIFY_KAWA_EVIDENCE='%s'\n" "$VERIFY_KAWA_EVIDENCE" printf "export VERIFY_KAWA_BIN='%s'\n" "$VERIFY_KAWA_BIN" printf "export VERIFY_KAWA_HELPER='%s'\n" "$VERIFY_KAWA_HELPER" + printf "export VERIFY_KAWA_ACTIVATION_CLIENT='%s'\n" "$act_bin" printf "export VERIFY_KAWA_WAYLAND_DISPLAY='%s'\n" "$sock" printf "export XDG_RUNTIME_DIR='%s'\n" "$XDG_RUNTIME_DIR" printf "export DISPLAY='%s'\n" "$DISPLAY" + if [ -n "${DBUS_SESSION_BUS_ADDRESS:-}" ]; then + printf "export DBUS_SESSION_BUS_ADDRESS='%s'\n" "$DBUS_SESSION_BUS_ADDRESS" + fi printf "export PKG_CONFIG_PATH='%s'\n" "$PKG_CONFIG_PATH" printf "export LD_LIBRARY_PATH='%s'\n" "$LD_LIBRARY_PATH" printf "export CGO_ENABLED=1\n" diff --git a/.cursor/skills/verify-kawa/scripts/new-cmd.sh b/.cursor/skills/verify-kawa/scripts/new-cmd.sh new file mode 100755 index 0000000..46a94be --- /dev/null +++ b/.cursor/skills/verify-kawa/scripts/new-cmd.sh @@ -0,0 +1,16 @@ +#!/bin/sh +# A -terms entry that lets one kawa run start different programs from New. +# It runs the shell command line in $VERIFY_KAWA_HOME/new-cmd, or +# weston-terminal if that file is missing or empty. The command replaces +# this process (eval exec), so the window's PID is the one kawa started, +# which is how kawa matches a window to its New box. +# kawa throws away the output of what it starts, so it goes to +# $VERIFY_KAWA_HOME/logs/new.log instead. +set -eu +f="${VERIFY_KAWA_HOME:?}/new-cmd" +exec >>"$VERIFY_KAWA_HOME/logs/new.log" 2>&1 +printf 'new-cmd: pid %s: %s\n' "$$" "$(cat "$f" 2>/dev/null || echo weston-terminal)" +if [ -s "$f" ]; then + eval "exec $(cat "$f")" +fi +exec weston-terminal