@lardexx/arenacode 2.11.11 → 2.11.13

package/README.md

@@ -121,7 +121,7 @@ How the copy is built and tested: [`docs/TUI.md`](docs/TUI.md).
 | `wheel` | scroll the transcript (three lines a notch) |
 | `pgup` / `pgdn` (or `ctrl+u` / `ctrl+j`) | scroll a page; `alt+↑` / `alt+↓` a line |
 | `home` / `end` | jump to the top / back to the bottom (when the prompt is empty) |
-| `ctrl+x` then | `q` quit · `n` new session · `l` switch session · `t` theme · `a` Ask and Proceed / Proceed · `d` tool output · `s` stop |
+| `ctrl+x` then | `q` quit · `n` new session · `l` switch session · `e` expand the last diff · `t` theme · `a` Ask and Proceed / Proceed · `d` tool output · `s` stop |
 | `ctrl+c` | interrupt, then quit |
 
 **The same four flows as the desktop client.** The Windows app is the reference for how a task reaches the bridge,
@@ -172,8 +172,39 @@ outside the keymap borrow an unused keycode with `XChangeKeyboardMapping` and gi
 from `XQueryTree` + `XGetGeometry` + `XTranslateCoordinates` + `_NET_WM_NAME`, focus from `XSetInputFocus`, and
 screenshots are `XGetImage` + `XGetPixel` encoded to PNG by the client itself (zlib). This is what makes it testable:
 `node test/native.js` runs it against a real X server (Xvfb is enough) — a window is created, the client types into it
-and the X events the server delivered are compared with the requested keycodes, chords, buttons and pixels. On Wayland
-the XWayland display is used. `ui app launch` still starts the program's own `.desktop` command; nothing else is spawned.
+and the X events the server delivered are compared with the requested keycodes, chords, buttons and pixels.
+`ui app launch` still starts the program's own `.desktop` command; nothing else is spawned.
+
+**Wayland** is a different backend (`src/automation/wayland.js`), picked automatically when `XDG_SESSION_TYPE=wayland`
+and `/dev/uinput` is writable. XTest cannot reach a native Wayland client — the compositor has no such entry point — so
+input goes through the kernel instead: a virtual pointer and keyboard are declared on `/dev/uinput`
+(`EV_KEY`/`EV_REL`, `UI_SET_*`, `UI_DEV_CREATE`) and the events written there are the same ones libinput reads, which
+means they work in *every* native Wayland window regardless of toolkit. Typing maps characters through
+`libxkbcommon` (`xkb_state_key_get_utf32`), so the layout in use is respected and shifted characters are typed with
+shift instead of guessed; if the library is missing a complete US map is used instead, and characters that the keymap
+cannot produce are refused by name rather than typed as something else. Screenshots take the two routes that Wayland
+allows: `org.freedesktop.portal.Screenshot` first (xdg-desktop-portal, so GNOME, KDE and wlroots all work; the desktop
+asks for confirmation once) and the `org.gnome.Shell.Screenshot` D-Bus service afterwards, with the XWayland root window
+as the last resort. Both D-Bus paths are tested for real against a private `dbus-daemon` and a stub of each service
+(`test/wayland.js`), the uinput path by reading the injected events back from `/dev/input/eventN` — the same node
+libinput opens.
+
+Wayland hides things that X11 exposes, and the client says so instead of failing quietly: `ui state` lists the XWayland
+windows and marks them as such (native windows cannot be enumerated by any client), `ui app switch`/`resize` are
+refused because a client may not focus or resize another client's window, and an absolute `ui move`/`ui click x y` needs
+the pointer position, which comes from XWayland — without it the answer is an explicit error rather than a click in the
+wrong place. Wheel, keys, typing and clicking at the current position work everywhere.
+
+To let your user open `/dev/uinput`, install the udev rule that ships in this package:
+
+```bash
+sudo cp dist/arenacode-uinput.rules /etc/udev/rules.d/
+sudo udevadm control --reload-rules && sudo udevadm trigger
+sudo usermod -aG input $USER     # then log out and back in
+```
+
+Without it the client stays on the X11 backend, keeps working for XWayland windows and reports
+`native.degraded` with the reason.
 
 **macOS** is native too, again with no helper binaries: mouse with `CGEventCreateMouseEvent` + `CGEventPost`
 (left/right/middle, double and triple click through the click-state field, drag interpolated), keyboard with
@@ -317,8 +348,10 @@ number, new line number, the sign, the text — painted on the diff backgrounds
 - A new file is all additions, a deleted one all deletions; text that did not change draws no card at all.
 - The diff is computed **locally for the display** and never travels to the bridge: the agent still receives the
   same `{ ok, path, size }` it always received.
-- `ctrl+x d` hides the block (it toggles every card); at most 20 rows are drawn, then `… n more lines`, and a
-  binary file gets no diff.
+- A long change is drawn as 20 rows and then a `⋯ n more lines` row. **That row is clickable**: the card opens
+  and shows every row, ending with `− collapse diff` (also clickable) to close it again. Without a mouse,
+  `ctrl+x e` does the same on the last diff of the session.
+- `ctrl+x d` hides the blocks entirely (it toggles every card), and a binary file gets no diff.
 
 ### Sessions
 
@@ -443,6 +476,10 @@ Environment variables override the file: `ARENACODE_URL`, `ARENACODE_KEY`, `AREN
 | `bridge unreachable` | tunnel down or wrong URL — check `/health` on the bridge, then `/settings` in the interface |
 | agent never answers | the agent is not listening: run `bash listen.sh` in the bridge folder |
 | everything hangs after a turn | `--idle-timeout` closes the session; the task state is in the interface |
+| Wayland: `ui` does nothing in native windows | `/dev/uinput` is not writable — install `dist/arenacode-uinput.rules` (see *What runs on your machine*) and log in again |
+| Wayland: `ui state` shows no windows | only XWayland windows can be listed; open the app with its X11 backend or use `ui app` |
+| Wayland: `ui shot` asks for confirmation | that is the desktop's own portal dialog — it appears once per session |
+| Wayland: `ui click 100 200` refuses | absolute positioning needs the XWayland pointer; use `ui keys`/`ui scroll`, or run the app under XWayland |
 
 ## Development
 

package/dist/arenacode-uinput.rules

@@ -0,0 +1,8 @@
+# Let members of the "input" group create virtual input devices, so the Computer Agent
+# can drive native Wayland windows through /dev/uinput instead of XTest (which Wayland
+# does not accept).
+#
+#   sudo cp arenacode-uinput.rules /etc/udev/rules.d/
+#   sudo udevadm control --reload-rules && sudo udevadm trigger
+#   sudo usermod -aG input "$USER"     # log out and back in afterwards
+KERNEL=="uinput", SUBSYSTEM=="misc", MODE="0660", GROUP="input", OPTIONS+="static_node=uinput"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lardexx/arenacode",
-  "version": "2.11.11",
+  "version": "2.11.13",
   "description": "Terminal client for ArenaCode: talks to an arena-bridge, streams the Agent Mode timeline, and runs local commands, file operations and computer automation on your PC (windows-use.dll on Windows, Xlib/XTest on Linux, osascript on macOS). Node port of the ArenaCode desktop client.",
   "license": "MIT",
   "type": "commonjs",
@@ -12,6 +12,7 @@
     "node": ">=18.0.0"
   },
   "files": [
+    "dist/",
     "bin/",
     "src/",
     "docs/",
@@ -20,7 +21,7 @@
     "vendor/"
   ],
   "scripts": {
-    "test": "node test/cli-surface.js && node test/sessions.js && node test/diff.js && node test/shell.js && node test/context.js && node test/integration.js && node test/parity.js && node test/automation.js && node test/native.js"
+    "test": "node test/cli-surface.js && node test/sessions.js && node test/diff.js && node test/shell.js && node test/context.js && node test/integration.js && node test/parity.js && node test/automation.js && node test/native.js && node test/wayland.js"
   },
   "keywords": [
     "arenacode",

package/src/automation/wayland.js

@@ -0,0 +1,947 @@
+'use strict';
+
+// Wayland support for the Computer Agent.
+//
+// Wayland has no XTest, no global window list and no `XGetImage` of another client's
+// surface, so the X11 backend only ever reaches XWayland applications. This module adds
+// the pieces that do work on a native Wayland session, without helper binaries:
+//
+//   input      /dev/uinput — a virtual mouse + keyboard created by the kernel itself.
+//              Works on every compositor (and on X11 too), no cooperation needed.
+//   text       libxkbcommon reads the active keymap, so `ui type` sends the right keys
+//              for the layout in use instead of assuming US.
+//   screenshot org.gnome.Shell.Screenshot over D-Bus (GNOME Wayland), then the X11 root
+//              window (XWayland), then an honest error.
+//   windows    XWayland windows through libX11; native Wayland windows cannot be listed
+//              by design, and the answer says so instead of pretending.
+//
+// Everything here is FFI: libc, libxkbcommon and libdbus, no external commands.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { requireFfi } = require('./ffi');
+
+const isLinux = process.platform === 'linux';
+
+// ---------------------------------------------------------------- session detection --
+
+/**
+ * Tells whether the desktop session is Wayland.
+ * XDG_SESSION_TYPE wins (set by the display manager); WAYLAND_DISPLAY is the fallback a
+ * lot of shells set; XDG_CURRENT_DESKTOP only says which desktop it is.
+ */
+function detect(env = process.env) {
+  const type = String(env.XDG_SESSION_TYPE || '').toLowerCase();
+  const display = String(env.WAYLAND_DISPLAY || '');
+  const desktop = String(env.XDG_CURRENT_DESKTOP || '').toLowerCase();
+  const x11 = Boolean(env.DISPLAY);
+  const wayland = type === 'wayland' || (type !== 'x11' && display !== '');
+  return {
+    wayland,
+    x11,
+    compositor: desktop || (wayland ? 'wayland' : 'x11'),
+    // XWayland is there when an X display is exported next to the Wayland one
+    xwayland: wayland && x11,
+    display: display || null,
+    xdisplay: env.DISPLAY || null,
+  };
+}
+
+function uinputPath() {
+  return process.env.ARENACODE_UINPUT || '/dev/uinput';
+}
+
+/** Can we create a virtual device right now? */
+function uinputAccess() {
+  const file = uinputPath();
+  try {
+    const fd = fs.openSync(file, 'r+');
+    fs.closeSync(fd);
+    return { ok: true, path: file };
+  } catch (err) {
+    return {
+      ok: false,
+      path: file,
+      error: err.code === 'EACCES' || err.code === 'EPERM'
+        ? `no access to ${file}: add your user to the "input" group or run: sudo chmod 660 ${file}`
+        : `${file} unusable: ${err.message}`,
+    };
+  }
+}
+
+// ---------------------------------------------------------------- key names / layout --
+
+// Linux input event codes (linux/input-event-codes.h), the ones a virtual device can send.
+const KEYS = {
+  esc: 1, escape: 1, '1': 2, '2': 3, '3': 4, '4': 5, '5': 6, '6': 7, '7': 8, '8': 9, '9': 10, '0': 11,
+  minus: 12, equal: 13, backspace: 14, tab: 15,
+  q: 16, w: 17, e: 18, r: 19, t: 20, y: 21, u: 22, i: 23, o: 24, p: 25, bracketleft: 26, bracketright: 27,
+  enter: 28, return: 28, ctrl: 29, control: 29, a: 30, s: 31, d: 32, f: 33, g: 34, h: 35, j: 36, k: 37, l: 38,
+  semicolon: 39, apostrophe: 40, quote: 40, grave: 41, backtick: 41, shift: 42, backslash: 43,
+  z: 44, x: 45, c: 46, v: 47, b: 48, n: 49, m: 50, comma: 51, period: 52, dot: 52, slash: 53, shiftright: 54,
+  alt: 56, option: 56, space: 57, spacebar: 57, capslock: 58,
+  f1: 59, f2: 60, f3: 61, f4: 62, f5: 63, f6: 64, f7: 65, f8: 66, f9: 67, f10: 68, f11: 87, f12: 88,
+  home: 102, up: 103, arrowup: 103, pageup: 104, pgup: 104, left: 105, arrowleft: 105,
+  right: 106, arrowright: 106, end: 107, down: 108, arrowdown: 108, pagedown: 109, pgdn: 109,
+  insert: 110, ins: 110, delete: 111, del: 111, meta: 125, super: 125, win: 125, cmd: 125, command: 125,
+  menu: 127, printscreen: 99, scrolllock: 70, pause: 119, numlock: 69,
+  numpad0: 82, numpad1: 79, numpad2: 80, numpad3: 81, numpad4: 75, numpad5: 76, numpad6: 77,
+  numpad7: 71, numpad8: 72, numpad9: 73, numpadadd: 78, numpadsub: 74, numpadmul: 55, numpaddiv: 98,
+  numpadenter: 96, numpadperiod: 83,
+};
+const MODIFIERS = new Set(['ctrl', 'control', 'alt', 'option', 'shift', 'meta', 'super', 'win', 'cmd', 'command', 'shiftright']);
+
+// US layout, used when libxkbcommon is not installed: char -> [keycode, shift]
+const US_BASE = {
+  '-': 12, '=': 13, '[': 26, ']': 27, ';': 39, "'": 40, '`': 41, '\\': 43, ',': 51, '.': 52, '/': 53, ' ': 57,
+};
+const US_PAIRS = { '!': '1', '@': '2', '#': '3', $: '4', '%': '5', '^': '6', '&': '7', '*': '8', '(': '9', ')': '0',
+  _: '-', '+': '=', '{': '[', '}': ']', ':': ';', '"': "'", '~': '`', '|': '\\', '<': ',', '>': '.', '?': '/' };
+
+function usCharMap() {
+  const map = new Map();
+  for (const [ch, code] of Object.entries(US_BASE)) map.set(ch, { code, shift: false });
+  for (const [ch, base] of Object.entries(US_PAIRS)) map.set(ch, { code: US_BASE[base] || KEYS[base], shift: true });
+  for (let i = 0; i < 26; i += 1) {
+    const lower = String.fromCharCode(97 + i);
+    const code = 30 + [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, -1, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24][i];
+    map.set(lower, { code, shift: false });
+    map.set(lower.toUpperCase(), { code, shift: true });
+  }
+  for (let d = 0; d <= 9; d += 1) map.set(String(d), { code: 2 + d, shift: false });
+  map.set('\n', { code: KEYS.enter, shift: false });
+  map.set('\t', { code: KEYS.tab, shift: false });
+  return map;
+}
+
+/**
+ * char -> { code, shift } from the keymap libxkbcommon reports (the one the desktop is
+ * actually using). Falls back to the US table when the library or the keymap is missing.
+ */
+function charMap() {
+  try {
+    const koffi = requireFfi();
+    const xkb = koffi.load('libxkbcommon.so.0');
+    const context_new = xkb.func('void *xkb_context_new(int flags)');
+    const keymap_new = xkb.func('void *xkb_keymap_new_from_names(void *ctx, void *names, int flags)');
+    const state_new = xkb.func('void *xkb_state_new(void *keymap)');
+    const key_get_utf32 = xkb.func('unsigned int xkb_state_key_get_utf32(void *state, unsigned int keycode)');
+    const mod_index = xkb.func('unsigned int xkb_keymap_mod_get_index(void *keymap, const char *name)');
+    const update_mask = xkb.func('int xkb_state_update_mask(void *state, unsigned int depressed, unsigned int latched, unsigned int locked, unsigned int g1, unsigned int g2, unsigned int g3)');
+
+    const ctx = context_new(0);
+    const keymap = keymap_new(ctx, null, 0);
+    if (!keymap) throw new Error('no keymap');
+    const plain = state_new(keymap);
+    const shifted = state_new(keymap);
+    const shiftIndex = Number(mod_index(keymap, 'Shift')) || 0;
+    update_mask(shifted, 2 ** shiftIndex, 0, 0, 0, 0, 0);
+
+    const map = new Map();
+    // xkb keycodes are evdev codes + 8
+    for (let code = 1; code <= 255; code += 1) {
+      const kc = code + 8;
+      const a = key_get_utf32(plain, kc);
+      const b = key_get_utf32(shifted, kc);
+      if (a) map.set(String.fromCodePoint(a), { code, shift: false });
+      if (b && !map.has(String.fromCodePoint(b))) map.set(String.fromCodePoint(b), { code, shift: true });
+    }
+    if (!map.size) throw new Error('empty keymap');
+    map.source = 'xkbcommon';
+    return map;
+  } catch (err) {
+    const map = usCharMap();
+    map.source = 'us-fallback';
+    map.reason = err.message;
+    return map;
+  }
+}
+
+/** `ctrl+shift+s` -> [{code, down}] using the Linux keycodes. */
+function keySequence(combo) {
+  // "ctrl+shift+s" and "tab x3" both work: plus or space separates the parts
+  const parts = String(combo || '').toLowerCase().split(/[+\s]+/).map((p) => p.trim()).filter(Boolean);
+  if (!parts.length) return [];
+  let repeat = 1;
+  const mods = [];
+  const main = [];
+  for (const part of parts) {
+    if (part === 'repeat' || /^x\d+$/.test(part)) {
+      repeat = part === 'repeat' ? 2 : Number(part.slice(1));
+      continue;
+    }
+    const code = KEYS[part] !== undefined ? KEYS[part] : (part.length === 1 ? KEYS[part] || null : null);
+    if (code === null || code === undefined) continue;
+    if (MODIFIERS.has(part)) mods.push(code);
+    else main.push(code);
+  }
+  const out = [];
+  const times = Math.max(1, Math.min(50, repeat));
+  for (let i = 0; i < times; i += 1) {
+    if (!main.length && mods.length) {
+      const only = mods[mods.length - 1];
+      out.push({ code: only, down: true }, { code: only, down: false });
+      continue;
+    }
+    for (const code of mods) out.push({ code, down: true });
+    for (const code of main) out.push({ code, down: true }, { code, down: false });
+    for (const code of [...mods].reverse()) out.push({ code, down: false });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- uinput device --
+
+const EV_SYN = 0x00;
+const EV_KEY = 0x01;
+const EV_REL = 0x02;
+const EV_ABS = 0x03;
+const REL_X = 0x00;
+const REL_Y = 0x01;
+const REL_WHEEL = 0x08;
+const REL_HWHEEL = 0x06;
+const ABS_X = 0x00;
+const ABS_Y = 0x01;
+const BTN_LEFT = 0x110;
+const BTN_RIGHT = 0x111;
+const BTN_MIDDLE = 0x112;
+const SYN_REPORT = 0;
+
+const UI_SET_EVBIT = 0x40045564;
+const UI_SET_KEYBIT = 0x40045565;
+const UI_SET_RELBIT = 0x40045566;
+const UI_SET_ABSBIT = 0x40045567;
+const UI_DEV_CREATE = 0x5501;
+const UI_DEV_DESTROY = 0x5502;
+
+const O_WRONLY = 1;
+
+/** struct input_event on x86_64/arm64: timeval (16) + type (2) + code (2) + value (4). */
+const EVENT_SIZE = 24;
+
+/** Builds the buffers a caller writes to /dev/uinput. Pure, so it can be tested. */
+function eventBuffer(events) {
+  const buffer = Buffer.alloc(EVENT_SIZE * (events.length + 1));
+  let at = 0;
+  for (const ev of events) {
+    // time left at zero: the kernel stamps the event on write
+    buffer.writeUInt16LE(ev.type & 0xffff, at + 16);
+    buffer.writeUInt16LE(ev.code & 0xffff, at + 18);
+    buffer.writeInt32LE(ev.value | 0, at + 20);
+    at += EVENT_SIZE;
+  }
+  buffer.writeUInt16LE(EV_SYN, at + 16);
+  buffer.writeUInt16LE(SYN_REPORT, at + 18);
+  buffer.writeInt32LE(0, at + 20);
+  return buffer;
+}
+
+let device = null; // { fd, kind }
+
+/** ioctl returns -1 on failure; without this check the next write fails with a bare EINVAL. */
+function check(rc, what) {
+  if (rc === -1) throw new Error(`${what} failed (errno ${process.errno || 'unknown'})`);
+  return rc;
+}
+
+function ioctlInt(koffi, fd, request, value) {
+  const libc = koffi.load('libc.so.6');
+  const ioctl = libc.func('int ioctl(int fd, unsigned long request, int arg)');
+  return ioctl(fd, request, value);
+}
+
+function ioctlNone(koffi, fd, request) {
+  const libc = koffi.load('libc.so.6');
+  const ioctl = libc.func('int ioctl(int fd, unsigned long request)');
+  return ioctl(fd, request);
+}
+
+/**
+ * Opens /dev/uinput and declares a pointer + keyboard device.
+ * Kept open for the life of the process so the compositor sees one stable device.
+ */
+function ensureDevice({ keyboard = true, pointer = true } = {}) {
+  if (device && device.keyboard === keyboard && device.pointer === pointer) return device;
+  if (device) destroyDevice();
+  const access = uinputAccess();
+  if (!access.ok) throw new Error(access.error);
+  const koffi = requireFfi();
+  const file = access.path;
+  const nodesBefore = listEventNodes();
+  const fd = fs.openSync(file, O_WRONLY);
+  const setup = () => {
+    if (pointer) {
+      check(ioctlInt(koffi, fd, UI_SET_EVBIT, EV_REL), 'UI_SET_EVBIT EV_REL');
+      check(ioctlInt(koffi, fd, UI_SET_RELBIT, REL_X), 'UI_SET_RELBIT REL_X');
+      check(ioctlInt(koffi, fd, UI_SET_RELBIT, REL_Y), 'UI_SET_RELBIT REL_Y');
+      check(ioctlInt(koffi, fd, UI_SET_RELBIT, REL_WHEEL), 'UI_SET_RELBIT REL_WHEEL');
+      check(ioctlInt(koffi, fd, UI_SET_RELBIT, REL_HWHEEL), 'UI_SET_RELBIT REL_HWHEEL');
+      check(ioctlInt(koffi, fd, UI_SET_EVBIT, EV_KEY), 'UI_SET_EVBIT EV_KEY');
+      for (const btn of [BTN_LEFT, BTN_RIGHT, BTN_MIDDLE]) check(ioctlInt(koffi, fd, UI_SET_KEYBIT, btn), `UI_SET_KEYBIT ${btn}`);
+    }
+    if (keyboard) {
+      check(ioctlInt(koffi, fd, UI_SET_EVBIT, EV_KEY), 'UI_SET_EVBIT EV_KEY');
+      for (let code = 1; code <= 127; code += 1) check(ioctlInt(koffi, fd, UI_SET_KEYBIT, code), `UI_SET_KEYBIT ${code}`);
+    }
+    // name the device so it shows up recognisably in `libinput debug-events`
+    const libc = koffi.load('libc.so.6');
+    const write = libc.func('long write(int fd, const unsigned char *buf, long count)');
+    const name = Buffer.from('arenacode-virtual-input\0', 'utf8');
+    // struct uinput_user_dev: name[80], input_id (4 x u16), ff_effects_max (u32),
+    // then absmax/absmin/absfuzz/absflat, 64 s32 each. ff_effects_max must stay 0:
+    // a non-zero value makes the kernel refuse UI_DEV_CREATE with EINVAL.
+    const uinput_user_dev = Buffer.alloc(1116);
+    name.copy(uinput_user_dev, 0);
+    uinput_user_dev.writeUInt16LE(0x03, 80); // bustype BUS_USB
+    uinput_user_dev.writeUInt16LE(0x1209, 82); // vendor (pid.codes)
+    uinput_user_dev.writeUInt16LE(0x0001, 84); // product
+    uinput_user_dev.writeUInt16LE(1, 86); // version
+    uinput_user_dev.writeUInt32LE(0, 88); // ff_effects_max
+    // no axes are declared, so the four abs tables stay zeroed on purpose
+    const wrote = write(fd, uinput_user_dev, uinput_user_dev.length);
+    if (wrote !== uinput_user_dev.length) throw new Error(`short write of the device description (${wrote})`);
+    return check(ioctlNone(koffi, fd, UI_DEV_CREATE), 'UI_DEV_CREATE');
+  };
+  try {
+    setup();
+  } catch (err) {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* already gone */
+    }
+    throw new Error(`uinput device creation failed: ${err.message}`);
+  }
+  const eventNode = waitForDeviceNode(nodesBefore);
+  device = { fd, keyboard, pointer, path: file, eventNode };
+  return device;
+}
+
+/** Event nodes the kernel currently exposes, newest last. */
+function listEventNodes() {
+  try {
+    return fs
+      .readdirSync('/dev/input')
+      .filter((name) => /^event\d+$/.test(name))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The kernel exposes the new node a moment after UI_DEV_CREATE. Returns the node this
+ * device created, not just "some node exists": a crashed process can leave a device
+ * behind, and picking the wrong one makes every later read look empty.
+ */
+function waitForDeviceNode(before, timeoutMs = 1500) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const fresh = listEventNodes().find((name) => !before.includes(name));
+    if (fresh) return `/dev/input/${fresh}`;
+    const until = Date.now() + 20;
+    while (Date.now() < until) {
+      /* spin: this runs once per device, not per event */
+    }
+  }
+  return null;
+}
+
+function destroyDevice() {
+  if (!device) return;
+  try {
+    const koffi = requireFfi();
+    ioctlNone(koffi, device.fd, UI_DEV_DESTROY);
+  } catch {
+    /* the device goes away with the process anyway */
+  }
+  try {
+    fs.closeSync(device.fd);
+  } catch {
+    /* already closed */
+  }
+  device = null;
+}
+
+function send(events) {
+  const dev = ensureDevice({ keyboard: true, pointer: true });
+  fs.writeSync(dev.fd, eventBuffer(events));
+}
+
+// ---------------------------------------------------------------- D-Bus (screenshot) --
+
+// --- libdbus, loaded once ------------------------------------------------------
+
+let dbusCache = null;
+
+/**
+ * libdbus bindings, with the two details that cost the most time to find out:
+ *   · DBusError.name / .message are struct fields, there is no dbus_error_message()
+ *   · the value argument of the iter API is dereferenced for strings
+ *     (`*(const char **)value`), so strings go in as a pointer to a pointer
+ */
+function loadDbus() {
+  if (dbusCache) return dbusCache;
+  const koffi = requireFfi();
+  const dbus = koffi.load('libdbus-1.so.3');
+  const DBusError = koffi.struct('ArenaCodeDBusError', {
+    name: 'const char *',
+    message: 'const char *',
+    dummy: 'unsigned int',
+    padding: 'void *',
+  });
+  const f = {
+    error_init: dbus.func('void dbus_error_init(void *err)'),
+    error_is_set: dbus.func('int dbus_error_is_set(void *err)'),
+    bus_get: dbus.func('void *dbus_bus_get(int type, void *err)'),
+    add_match: dbus.func('void dbus_bus_add_match(void *conn, const char *rule, void *err)'),
+    new_call: dbus.func('void *dbus_message_new_method_call(const char *dest, const char *path, const char *iface, const char *method)'),
+    iter_init_append: dbus.func('void dbus_message_iter_init_append(void *msg, void *iter)'),
+    iter_init: dbus.func('int dbus_message_iter_init(void *msg, void *iter)'),
+    iter_append: dbus.func('int dbus_message_iter_append_basic(void *iter, int type, void *value)'),
+    iter_get: dbus.func('void dbus_message_iter_get_basic(void *iter, void *value)'),
+    iter_arg_type: dbus.func('int dbus_message_iter_get_arg_type(void *iter)'),
+    iter_next: dbus.func('int dbus_message_iter_next(void *iter)'),
+    iter_recurse: dbus.func('void dbus_message_iter_recurse(void *iter, void *child)'),
+    open_container: dbus.func('int dbus_message_iter_open_container(void *iter, int type, const char *contained_signature, void *sub)'),
+    close_container: dbus.func('int dbus_message_iter_close_container(void *iter, void *sub)'),
+    send_block: dbus.func('void *dbus_connection_send_with_reply_and_block(void *conn, void *msg, int timeout, void *err)'),
+    send: dbus.func('int dbus_connection_send(void *conn, void *msg, unsigned int *serial)'),
+    flush: dbus.func('int dbus_connection_flush(void *conn)'),
+    dispatch: dbus.func('int dbus_connection_read_write_dispatch(void *conn, int timeout)'),
+    pop: dbus.func('void *dbus_connection_pop_message(void *conn)'),
+    is_signal: dbus.func('int dbus_message_is_signal(void *msg, const char *iface, const char *name)'),
+    get_type: dbus.func('int dbus_message_get_type(void *msg)'),
+    get_path: dbus.func('const char *dbus_message_get_path(void *msg)'),
+    get_error: dbus.func('const char *dbus_message_get_error_name(void *msg)'),
+    new_signal: dbus.func('void *dbus_message_new_signal(const char *path, const char *iface, const char *name)'),
+    set_path: dbus.func('int dbus_message_set_path(void *msg, const char *path)'),
+    unref: dbus.func('void dbus_message_unref(void *msg)'),
+  };
+  dbusCache = { koffi, f, DBusError, iter: () => koffi.alloc('uint8_t', 128) };
+  return dbusCache;
+}
+
+/** Opens the session bus, or explains why it cannot be opened. */
+function openSessionBus() {
+  const { koffi, f, DBusError } = loadDbus();
+  const err = koffi.alloc(DBusError, 1);
+  f.error_init(err);
+  const conn = f.bus_get(0 /* DBUS_BUS_SESSION */, err);
+  if (!conn) {
+    if (!process.env.DBUS_SESSION_BUS_ADDRESS) {
+      throw new Error('no session bus (DBUS_SESSION_BUS_ADDRESS is not set)');
+    }
+    const decoded = f.error_is_set(err) ? koffi.decode(err, DBusError) : null;
+    const detail = decoded ? [decoded.name, decoded.message].filter(Boolean).join(': ') : 'unknown D-Bus error';
+    throw new Error(`session bus unavailable (${detail})`);
+  }
+  const err2 = koffi.alloc(DBusError, 1);
+  f.error_init(err2);
+  return { conn, err: err2, errorText: () => {
+    if (!f.error_is_set(err2)) return 'no error reported';
+    const decoded = koffi.decode(err2, DBusError);
+    return [decoded && decoded.name, decoded && decoded.message].filter(Boolean).join(': ') || 'unknown D-Bus error';
+  } };
+}
+
+/** Appends one string argument (portable form: pointer to pointer). */
+function appendString(f, koffi, iter, value) {
+  const ref = koffi.alloc('char *', 1);
+  koffi.encode(ref, 'char *', value);
+  return f.iter_append(iter, 0x73 /* 's' */, ref);
+}
+
+/** Reads a string argument out of an iterator. */
+function readString(f, koffi, iter) {
+  const ref = koffi.alloc('char *', 1);
+  f.iter_get(iter, ref);
+  return String(koffi.decode(ref, 'char *') || '');
+}
+
+/** Reads the first unsigned 32-bit argument out of an iterator. */
+function readUint32(f, koffi, iter) {
+  const slot = koffi.alloc('uint32_t', 1);
+  f.iter_get(iter, slot);
+  return koffi.decode(slot, 'uint32_t');
+}
+
+// --- screenshots ---------------------------------------------------------------
+
+/**
+ * Portable screenshot: org.freedesktop.portal.Screenshot (xdg-desktop-portal).
+ * Works on GNOME, KDE and wlroots compositors; the desktop asks the user to confirm the
+ * first time, exactly as it does for any other portal.
+ * The call returns a request handle, the file arrives with the Response signal.
+ */
+function portalScreenshot(dest, timeoutMs = 25000) {
+  const { koffi, f } = loadDbus();
+  const { conn, errorText } = openSessionBus();
+
+  // A D-Bus connection only receives broadcasts it has a match rule for: without this
+  // the Response signal never reaches us and the call looks like it hung.
+  f.add_match(conn, "type='signal',interface='org.freedesktop.portal.Request',member='Response'", null);
+  f.flush(conn);
+
+  const msg = f.new_call(
+    'org.freedesktop.portal.Desktop',
+    '/org/freedesktop/portal/desktop',
+    'org.freedesktop.portal.Screenshot',
+    'Screenshot'
+  );
+  if (!msg) throw new Error('cannot build the portal call');
+  const iter = loadDbus().iter();
+  f.iter_init_append(msg, iter);
+  if (!appendString(f, koffi, iter, '')) { // parent_window: none
+    f.unref(msg);
+    throw new Error('cannot append the parent window argument');
+  }
+  // a{sv} options: an empty dictionary is valid, the portal fills in its defaults
+  const dict = loadDbus().iter();
+  if (!f.open_container(iter, 0x61 /* 'a' */, '{sv}', dict)) {
+    f.unref(msg);
+    throw new Error('cannot build the options dictionary');
+  }
+  if (!f.close_container(iter, dict)) {
+    f.unref(msg);
+    throw new Error('cannot close the options dictionary');
+  }
+
+  const reply = f.send_block(conn, msg, timeoutMs, null);
+  f.unref(msg);
+  if (!reply) throw new Error('the portal did not answer');
+  const failure = f.get_error(reply);
+  if (failure) throw new Error(`portal unavailable (${String(failure)})`);
+
+  const replyIter = loadDbus().iter();
+  if (!f.iter_init(reply, replyIter)) throw new Error('the portal returned no request handle');
+  const handle = readString(f, koffi, replyIter);
+  if (!handle) throw new Error('the portal returned an empty request handle');
+
+  // wait for Response(u response, a{sv} results) on the request object
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    f.dispatch(conn, 250);
+    const signal = f.pop(conn);
+    if (!signal) continue;
+    const path = String(f.get_path(signal) || '');
+    const isResponse = f.is_signal(signal, 'org.freedesktop.portal.Request', 'Response') && path === handle;
+    if (!isResponse) {
+      f.unref(signal);
+      continue;
+    }
+    const it = loadDbus().iter();
+    if (!f.iter_init(signal, it)) {
+      f.unref(signal);
+      throw new Error('empty portal response');
+    }
+    const code = readUint32(f, koffi, it); // 0 ok, 1 cancelled, 2 other
+    if (code !== 0) {
+      f.unref(signal);
+      throw new Error(code === 1 ? 'the user dismissed the screenshot dialog' : `the portal refused the screenshot (code ${code})`);
+    }
+    // second argument: a{sv}. The array iterates over dict entries ('{'), each of them
+    // holds the key string and then the variant that carries the value.
+    let uri = '';
+    if (f.iter_next(it)) {
+      const array = loadDbus().iter();
+      f.iter_recurse(it, array); // array -> first dict entry
+      // DBUS_TYPE_DICT_ENTRY is 'e' (0x65); '{' is only how it looks in a signature
+      while (f.iter_arg_type(array) === 0x65) {
+        const entry = loadDbus().iter();
+        f.iter_recurse(array, entry); // dict entry -> key
+        const key = readString(f, koffi, entry);
+        const variant = loadDbus().iter();
+        if (f.iter_next(entry)) {
+          f.iter_recurse(entry, variant); // variant -> value
+          if (key === 'uri') uri = readString(f, koffi, variant);
+        }
+        if (!f.iter_next(array)) break;
+      }
+    }
+    f.unref(signal);
+    if (!uri) throw new Error('the portal returned no file uri');
+    const source = uri.startsWith('file://') ? decodeURIComponent(uri.slice('file://'.length)) : uri;
+    fs.copyFileSync(source, dest);
+    return dest;
+  }
+  void errorText;
+  throw new Error('the portal never answered (no screenshot consent given?)');
+}
+
+/**
+ * GNOME Shell service: same result, no portal needed. Kept as the fallback because some
+ * NixOS/Flatpak setups ship the shell without the screenshot backend of the portal.
+ * Signature (bbs) -> (b success, s filename).
+ */
+function gnomeScreenshot(dest) {
+  const { koffi, f } = loadDbus();
+  const { conn, errorText } = openSessionBus();
+  const msg = f.new_call('org.gnome.Shell.Screenshot', '/org/gnome/Shell/Screenshot', 'org.gnome.Shell.Screenshot', 'Screenshot');
+  if (!msg) throw new Error('cannot build the D-Bus call');
+  const iter = loadDbus().iter();
+  f.iter_init_append(msg, iter);
+  const no = koffi.alloc('int', 1);
+  const noFlash = koffi.alloc('int', 1);
+  const ref = koffi.alloc('char *', 1);
+  koffi.encode(ref, 'char *', dest);
+  const built = f.iter_append(iter, 0x62, no) && f.iter_append(iter, 0x62, noFlash) && f.iter_append(iter, 0x73, ref);
+  if (!built) {
+    f.unref(msg);
+    throw new Error('cannot append the arguments of the screenshot call');
+  }
+  const reply = f.send_block(conn, msg, 20000, null);
+  f.unref(msg);
+  if (!reply) throw new Error(`screenshot call failed (${errorText()})`);
+  const name = f.get_error(reply);
+  if (name) throw new Error(`screenshot refused (${String(name)})`);
+  const replyIter = loadDbus().iter();
+  let ok = true;
+  if (f.iter_init(reply, replyIter) && f.get_type(reply) === 2 /* METHOD_RETURN */) {
+    const value = koffi.alloc('int', 1);
+    f.iter_get(replyIter, value);
+    ok = koffi.decode(value, 'int') !== 0;
+  }
+  if (!ok) throw new Error('the compositor reported it could not take the screenshot');
+  if (!fs.existsSync(dest)) throw new Error('the compositor answered OK but wrote no file');
+  return dest;
+}
+
+// ---------------------------------------------------------------- backend --
+
+function x11Backend() {
+  // the X11 backend is still the only way to see XWayland windows and grab the root
+  try {
+    return require('./linux').backend;
+  } catch {
+    return null;
+  }
+}
+
+const wayland = {
+  name: 'wayland-uinput',
+
+  detect,
+
+  available() {
+    const session = detect();
+    if (!isLinux) return { ok: false, backend: 'wayland', error: 'Wayland support is Linux only' };
+    if (!session.wayland) {
+      return { ok: false, backend: 'wayland', error: 'not a Wayland session (XDG_SESSION_TYPE/WAYLAND_DISPLAY)' };
+    }
+    const access = uinputAccess();
+    if (!access.ok) return { ok: false, backend: 'wayland', error: access.error, session };
+    return {
+      ok: true,
+      backend: 'wayland',
+      detail: `uinput + ${session.compositor}${session.xwayland ? ' (XWayland for windows)' : ''}`,
+      session,
+    };
+  },
+
+  sysinfo() {
+    const session = detect();
+    return {
+      ok: true,
+      system: {
+        os_version: `${os.type()} ${os.release()}`,
+        session: 'wayland',
+        compositor: session.compositor,
+        xwayland: session.xwayland,
+        input: 'uinput',
+        screen_size: this.screenSize(),
+      },
+    };
+  },
+
+  screenSize() {
+    const x11 = x11Backend();
+    if (x11) {
+      try {
+        const size = x11.screenSize();
+        if (size && size.ok) return { ...size, source: 'xwayland' };
+      } catch {
+        /* no X display */
+      }
+    }
+    return { ok: false, error: 'screen size needs XWayland on Wayland (no compositor-neutral API)' };
+  },
+
+  windows() {
+    const x11 = x11Backend();
+    if (!x11) return { ok: true, windows: [], active_window: null, wayland: true, note: 'no XWayland: native Wayland windows cannot be listed' };
+    try {
+      const list = x11.windows();
+      if (!list.ok) return list;
+      return {
+        ...list,
+        wayland: true,
+        note: 'XWayland windows only: Wayland hides the native ones from every client',
+      };
+    } catch (err) {
+      return { ok: true, windows: [], wayland: true, note: `XWayland unavailable (${err.message})` };
+    }
+  },
+
+  activeWindow() {
+    const x11 = x11Backend();
+    if (x11) {
+      try {
+        return x11.activeWindow();
+      } catch {
+        /* fall through */
+      }
+    }
+    return { ok: false, error: 'the focused window is not readable on Wayland' };
+  },
+
+  state(handle = null) {
+    const list = this.windows();
+    return {
+      ok: true,
+      windows: list.windows || [],
+      active_window: this.activeWindow(),
+      interactive_elements: [],
+      scrollable_elements: [],
+      interactive_elements_text: '',
+      scrollable_elements_text: '',
+      system: { os_version: `${os.type()} ${os.release()}`, session: 'wayland' },
+      metadata: { kind: 'wayland', xwayland: detect().xwayland, elements: 'unavailable on Wayland' },
+      handle,
+    };
+  },
+
+  moveMouse(x, y) {
+    // Wayland has no absolute pointer positioning without a compositor protocol: the
+    // honest answer is a relative move from where the pointer is now.
+    const pos = this.pointerPosition();
+    const dx = Number(x) - (pos.ok ? pos.x : 0);
+    const dy = Number(y) - (pos.ok ? pos.y : 0);
+    if (!pos.ok) return { ok: false, error: 'cannot read the pointer position on Wayland: use scroll/keys, or click with absolute X11 coordinates through XWayland' };
+    send([{ type: EV_REL, code: REL_X, value: dx }, { type: EV_REL, code: REL_Y, value: dy }]);
+    return { ok: true, x: Number(x), y: Number(y), relative: true };
+  },
+
+  pointerPosition() {
+    const x11 = x11Backend();
+    if (x11 && typeof x11.pointerPosition === 'function') {
+      try {
+        const pos = x11.pointerPosition();
+        if (pos && pos.ok) return pos;
+      } catch {
+        /* nothing */
+      }
+    }
+    return { ok: false, error: 'pointer position unavailable without XWayland' };
+  },
+
+  click(x, y, { button = 'left', count = 1 } = {}) {
+    if (x !== null && x !== undefined) {
+      const moved = this.moveMouse(x, y);
+      if (!moved.ok) return moved;
+    }
+    const code = button === 'right' ? BTN_RIGHT : button === 'middle' ? BTN_MIDDLE : BTN_LEFT;
+    const events = [];
+    for (let i = 0; i < Math.max(1, count); i += 1) {
+      events.push({ type: EV_KEY, code, value: 1 }, { type: EV_KEY, code, value: 0 });
+    }
+    send(events);
+    return { ok: true, x, y, button, count };
+  },
+
+  mouseButton(x, y, button, down) {
+    if (down && x !== null && x !== undefined) {
+      const moved = this.moveMouse(x, y);
+      if (!moved.ok) return moved;
+    }
+    const code = button === 'right' ? BTN_RIGHT : button === 'middle' ? BTN_MIDDLE : BTN_LEFT;
+    send([{ type: EV_KEY, code, value: down ? 1 : 0 }]);
+    return { ok: true, x, y, button, down };
+  },
+
+  drag(x, y, x2, y2) {
+    const start = this.mouseButton(x, y, 'left', true);
+    if (!start.ok) return start;
+    const moved = this.moveMouse(x2, y2);
+    this.mouseButton(x2, y2, 'left', false);
+    return { ok: moved.ok, from: [x, y], to: [x2, y2] };
+  },
+
+  scroll(amount, x = null, y = null) {
+    const notches = Math.trunc(Number(amount) || 0);
+    if (!notches) return { ok: true, amount: 0 };
+    const events = [];
+    for (let i = 0; i < Math.abs(notches); i += 1) events.push({ type: EV_REL, code: REL_WHEEL, value: notches > 0 ? 1 : -1 });
+    send(events);
+    if (x !== null && x !== undefined) this.moveMouse(x, y);
+    return { ok: true, amount: notches };
+  },
+
+  pressKeys(combo) {
+    const seq = keySequence(combo);
+    if (!seq.length) return { ok: false, error: `unknown key: ${combo}` };
+    send(seq.map((step) => ({ type: EV_KEY, code: step.code, value: step.down ? 1 : 0 })));
+    return { ok: true, keys: combo };
+  },
+
+  typeText(text, x = null, y = null) {
+    const value = String(text ?? '');
+    if (!value) return { ok: true, chars: 0, typed: 0 };
+    if (x !== null && x !== undefined) {
+      const moved = this.moveMouse(x, y);
+      if (!moved.ok) return moved;
+    }
+    const map = charMap();
+    const missing = [];
+    const events = [];
+    for (const ch of value) {
+      const hit = map.get(ch);
+      if (!hit) {
+        missing.push(ch);
+        continue;
+      }
+      if (hit.shift) events.push({ type: EV_KEY, code: KEYS.shift, value: 1 });
+      events.push({ type: EV_KEY, code: hit.code, value: 1 }, { type: EV_KEY, code: hit.code, value: 0 });
+      if (hit.shift) events.push({ type: EV_KEY, code: KEYS.shift, value: 0 });
+    }
+    if (missing.length) {
+      return {
+        ok: false,
+        error: `the active keymap cannot type ${missing.length} character(s): ${[...new Set(missing)].join(' ')}`,
+        unmapped: [...new Set(missing)],
+        layout: map.source,
+      };
+    }
+    send(events);
+    return { ok: true, chars: value.length, typed: value.length, layout: map.source };
+  },
+
+  screenshot(dest, { annotate = false } = {}) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const attempts = [];
+    try {
+      portalScreenshot(dest);
+      const size = pngSize(dest);
+      return { ok: true, file: dest, mime: 'image/png', method: 'xdg-desktop-portal', ...size, annotated: Boolean(annotate) };
+    } catch (err) {
+      attempts.push(`portal: ${err.message}`);
+    }
+    try {
+      gnomeScreenshot(dest);
+      const size = pngSize(dest);
+      return { ok: true, file: dest, mime: 'image/png', method: 'gnome-shell-dbus', ...size, annotated: Boolean(annotate) };
+    } catch (err) {
+      attempts.push(`gnome-shell: ${err.message}`);
+    }
+    const x11 = x11Backend();
+    if (x11) {
+      try {
+        const shot = x11.screenshot(dest, { annotate });
+        if (shot && shot.ok) return { ...shot, method: 'xwayland', partial: true };
+        attempts.push(`xwayland: ${(shot && shot.error) || 'failed'}`);
+      } catch (err) {
+        attempts.push(`xwayland: ${err.message}`);
+      }
+    }
+    return {
+      ok: false,
+      error: `screenshot on this Wayland compositor needs the GNOME Shell D-Bus service: ${attempts.join(' · ')}`,
+      attempts,
+    };
+  },
+
+  listApps() {
+    const dirs = String(process.env.XDG_DATA_DIRS || '/usr/share:/usr/local/share').split(':');
+    const apps = [];
+    const seen = new Set();
+    for (const dir of dirs.filter(Boolean)) {
+      const folder = path.join(dir, 'applications');
+      let files = [];
+      try {
+        files = fs.readdirSync(folder).filter((name) => name.endsWith('.desktop'));
+      } catch {
+        continue;
+      }
+      for (const file of files) {
+        try {
+          const text = fs.readFileSync(path.join(folder, file), 'utf8');
+          const name = /^Name=(.+)$/m.exec(text)?.[1];
+          const exec = /^Exec=(.+)$/m.exec(text)?.[1];
+          const hidden = /^(NoDisplay|Hidden)=true$/m.test(text);
+          if (!name || !exec || hidden) continue;
+          const id = file.replace(/\.desktop$/, '');
+          if (seen.has(id)) continue;
+          seen.add(id);
+          apps.push({ name, app_id: id, exec: exec.replace(/%[fFuU]/g, '').trim() });
+        } catch {
+          /* unreadable entry */
+        }
+      }
+    }
+    apps.sort((a, b) => a.name.localeCompare(b.name));
+    return { ok: true, apps: apps.slice(0, 200), wayland: true };
+  },
+
+  launchApp(name) {
+    const wanted = String(name || '').trim();
+    if (!wanted) return { ok: false, error: 'no app name' };
+    const { spawn } = require('node:child_process');
+    const known = this.listApps();
+    const hit = (known.apps || []).find((app) => app.name.toLowerCase() === wanted.toLowerCase() || app.app_id.toLowerCase() === wanted.toLowerCase());
+    const command = hit ? hit.exec : wanted;
+    try {
+      const child = spawn(command, { detached: true, stdio: 'ignore', shell: true, env: { ...process.env, DISPLAY: process.env.DISPLAY || '', WAYLAND_DISPLAY: process.env.WAYLAND_DISPLAY || '' } });
+      child.unref();
+      return { ok: true, app: hit ? hit.name : wanted, command };
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+  },
+
+  focusWindow() {
+    return { ok: false, error: 'Wayland does not let a client focus another client\'s window' };
+  },
+
+  resizeWindow() {
+    return { ok: false, error: 'Wayland does not let a client resize another client\'s window' };
+  },
+
+  findWindow(name) {
+    const list = this.windows();
+    if (!list.ok) return list;
+    const { pickWindow } = require('../automation');
+    const hit = pickWindow(list.windows || [], name);
+    return hit ? { ok: true, window: hit, xwayland: true } : { ok: false, error: `window not found (XWayland only): ${name}` };
+  },
+};
+
+/** PNG width/height straight from the header, so the caller gets the numbers. */
+function pngSize(file) {
+  try {
+    const head = Buffer.alloc(24);
+    const fd = fs.openSync(file, 'r');
+    fs.readSync(fd, head, 0, 24, 0);
+    fs.closeSync(fd);
+    if (head.readUInt32BE(0) !== 0x89504e47) return {};
+    return { width: head.readUInt32BE(16), height: head.readUInt32BE(20) };
+  } catch {
+    return {};
+  }
+}
+
+module.exports = {
+  backend: wayland,
+  detect,
+  uinputAccess,
+  uinputPath,
+  charMap,
+  usCharMap,
+  keySequence,
+  eventBuffer,
+  ensureDevice,
+  destroyDevice,
+  KEYS,
+  EVENT_SIZE,
+  pngSize,
+};

package/src/automation.js

@@ -1000,13 +1000,28 @@ const automation = {
 
 let nativeBackend = null;
 let nativeKind = null;
+let nativeDegraded = null;
 
 try {
   if (isLinux) {
     // Linux has no fallback any more: the FFI backend *is* the backend (the old one
     // shelled out to xdotool, which is exactly what we do not want).
-    nativeBackend = require('./automation/linux').backend;
-    nativeKind = 'x11';
+    //
+    // On Wayland the X11 backend only ever reaches XWayland applications, so the
+    // uinput backend takes over when it can open /dev/uinput. If it cannot, we stay on
+    // X11 and say so instead of failing silently.
+    const wayland = require('./automation/wayland');
+    const session = wayland.detect();
+    if (session.wayland && wayland.backend.available().ok) {
+      nativeBackend = wayland.backend;
+      nativeKind = 'wayland';
+    } else {
+      nativeBackend = require('./automation/linux').backend;
+      nativeKind = 'x11';
+      if (session.wayland) {
+        nativeDegraded = wayland.backend.available().error || 'Wayland detected, uinput unavailable';
+      }
+    }
   } else if (isWin) {
     // The DLL ships in the package; PowerShell stays only as a safety net for the case
     // where it cannot be loaded at all.
@@ -1040,6 +1055,7 @@ if (nativeBackend) {
       kind: nativeKind,
       name: nativeBackend.name,
       dll: nativeKind === 'dll' ? require('./automation/win-dll').locate() : null,
+      degraded: nativeDegraded,
     },
     available: () => nativeBackend.available(),
     screenSize: () => nativeBackend.screenSize(),

package/src/prompts/agent-prompt.md

@@ -188,6 +188,7 @@ Starts with `[ArenaCode mode: computer-agent]`. You act on the whole PC through
 - Type exactly the text of the task: no extra spaces, line breaks or repeated characters.
 - Before typing, click the field and confirm the cursor is in it. After a window changes, take a new screenshot before clicking. Do not reuse old coordinates.
 - Coordinates are physical pixels, taken from the latest screenshot (`width` and `height` in its JSON).
+- **Wayland** (`ui sysinfo` → `session: "wayland"`): `interactive_elements` is empty and `windows` only lists XWayland windows, so read the screen and click by coordinates from the screenshot. If a click with explicit `--x/--y` returns `ok: false` because the pointer position is unknown, do not retry it: reach the control with `ui keys` (tab, arrows, enter) or `ui control --action scroll`, and say in your reply that the desktop does not allow absolute positioning.
 - Be efficient: group the predictable steps of the approved plan into short sequences, check at checkpoints rather than after every trivial step, do not repeat a completed action, and do not reopen what is already open.
 
 ### Safety

package/src/tui/app.js

@@ -305,6 +305,17 @@ class App {
       this.invalidate();
       return undefined;
     }
+    // a left click on a card's affordance row ("more lines" / "collapse diff") toggles it
+    if (key.name === 'mouse' && key.button === 0 && !key.release) {
+      const hit = this.hitTest(key.y);
+      if (hit && hit.affordance) {
+        hit.item.expanded = hit.affordance === 'more';
+        this.invalidate();
+        this.scheduleSave();
+        return undefined;
+      }
+    }
+
     // the wheel scrolls the transcript (three lines a notch, like every terminal app)
     if (key.name === 'wheel') {
       if (key.dir === 'up') st.scroll += 3;
@@ -333,6 +344,8 @@ class App {
         return this.openHelp();
       case 'l':
         return this.openSessions();
+      case 'e':
+        return this.toggleLastDiff();
       case 't': {
         const names = themeNames();
         const next = names[(names.indexOf(this.themeName) + 1) % names.length];
@@ -636,6 +649,7 @@ class App {
       } },
       { title: 'Sessions (switch between sessions)', hint: 'ctrl+x l', slash: '/sessions', run: () => this.openSessions() },
       { title: 'Queue: tasks on the bridge', hint: '', slash: '/queue', run: () => this.openTasks() },
+      { title: 'Expand the last diff', hint: 'ctrl+x e', run: () => this.toggleLastDiff() },
       { title: 'Toggle detail', hint: 'ctrl+x d', run: () => {
         this.state.details = !this.state.details;
         this.toast(`details ${this.state.details ? 'on' : 'off'}`);
@@ -891,6 +905,28 @@ class App {
     return undefined;
   }
 
+  /** Screen row (1-based, as the mouse reports it) -> the card drawn there, if any. */
+  hitTest(row) {
+    const view = this._chatView;
+    if (!view || !view.map) return null;
+    const index = view.start + (Number(row) - 1) - view.pad;
+    return view.map[index] || null;
+  }
+
+  /** `ctrl+x e`: expand (or close) the last diff in the transcript, for keyboards only. */
+  toggleLastDiff() {
+    const item = [...this.state.items].reverse().find((i) => i && i.diff);
+    if (!item) {
+      this.toast('no diff in this session');
+      return undefined;
+    }
+    item.expanded = !item.expanded;
+    this.toast(item.expanded ? `diff expanded (${item.diff.rows.length} rows)` : 'diff collapsed');
+    this.invalidate();
+    this.scheduleSave();
+    return undefined;
+  }
+
   /** A list dialog draws group rows too: the selection index must skip them. */
   sessionRowIndex(index) {
     const at = Math.max(0, Math.min(this.sessions.length, index));
@@ -1611,6 +1647,7 @@ class App {
       frame.push(footerFor());
       if (prompt.cursor) cursor = { row: promptStart + prompt.cursor.row, col: prompt.cursor.col };
     } else {
+      const chatMap = [];
       const chat = W2
         .chatLines(t, st.items, {
           width: W - 4,
@@ -1618,6 +1655,7 @@ class App {
           agent: this.agentName(),
           model: this.modelName(),
           details: st.details ? 'full' : false,
+          map: chatMap,
         })
         .map((line) => R.spaces(2) + line);
 
@@ -1625,7 +1663,11 @@ class App {
       const maxScroll = Math.max(0, chat.length - bodyH);
       st.scroll = Math.min(Math.max(0, st.scroll), maxScroll);
       const start = Math.max(0, chat.length - bodyH - st.scroll);
+      // a click comes in screen rows: remember how the visible slice maps onto `chat`
+      this._chatView = { start, pad: 0, map: chatMap };
       const visible = chat.slice(start, start + bodyH);
+      const pad = Math.max(0, bodyH - visible.length);
+      this._chatView.pad = pad;
       while (visible.length < bodyH) visible.unshift('');
       frame.push(...visible);
       frame.push('');
@@ -1862,6 +1904,7 @@ function HELP_ROWS() {
     ['Session', 'ctrl+x n', 'new session'],
     ['Session', 'ctrl+x l', 'switch session'],
     ['Session', '/sessions', 'switch between sessions'],
+    ['Session', 'click / ctrl+x e', 'open or close a diff that was cut short'],
     ['Session', '/queue', 'tasks on the bridge'],
     ['Session', 'ctrl+x a', 'Ask and Proceed / Proceed'],
     ['Session', 'ctrl+x t', 'switch theme'],

package/src/tui/widgets.js

@@ -214,14 +214,22 @@ function diffLines(t, diff, { width = 80, max = 24 } = {}) {
     out.push(`${line}${spaces(Math.max(0, width - R.vlen(head + body)))}${RESET}`);
   }
   if (rows.length > max) {
-    out.push(paint(D.ctx.noBg, D.number, spaces(gutter) + `… ${rows.length - max} more lines`, width));
+    // the last row is the affordance: clicking it expands this very card (see chatLines' map)
+    out.push(paint(D.ctx.noBg, D.number, spaces(gutter) + `⋯ ${rows.length - max} more lines`, width));
+    out.affordance = 'more';
   }
   return out;
 }
 
 function chatLines(t, items, opts = {}) {
-  const { width, frame = 0, agent = 'Build', model = '', details = true } = opts;
+  const { width, frame = 0, agent = 'Build', model = '', details = true, map = null } = opts;
   const out = [];
+  // `map` records, for every emitted line, which item it belongs to: the mouse needs it to
+  // know that the row under the pointer is that card's "more lines" affordance.
+  const mark = (from, item, extra = null) => {
+    if (!map) return;
+    for (let i = from; i < out.length; i += 1) map[i] = { item, ...(i === from ? extra : null) };
+  };
   let prevKind = null;
   // Blocks (a message, a card) get one empty line above and below; single lines
   // (thoughts, notices) stay together, so nothing looks glued to its neighbour.
@@ -284,6 +292,7 @@ function chatLines(t, items, opts = {}) {
         const meta = item.meta ? ` (${item.meta})` : '';
         pushBlank();
         if (item.diff && details && item.diff.rows && item.diff.rows.length) {
+          const from = out.length;
           const bg = bgSeq(t.c.backgroundPanel);
           const bar = `${fgSeq(t.c.background)}┃${RESET}`;
           const inner = width - 3;
@@ -301,8 +310,19 @@ function chatLines(t, items, opts = {}) {
                 width - 1,
               ),
           );
-          for (const line of diffLines(t, item.diff, { width: inner, max: 20 })) {
-            out.push(bar + line + spaces(0));
+          const diffRows = diffLines(t, item.diff, { width: inner, max: item.expanded ? Infinity : 20 });
+          for (const line of diffRows) out.push(bar + line + spaces(0));
+          if (diffRows.affordance === 'more') {
+            mark(from, item);
+            if (map) map[out.length - 1] = { item, affordance: 'more' };
+          } else if (item.expanded) {
+            // expanded: the card ends with a row that closes it again (also clickable)
+            const D = t.diff;
+            out.push(bar + `${bgSeq(D.ctx.noBg)}${fgSeq(D.number)}${spaces(3)}− collapse diff${spaces(Math.max(0, inner - 17))}${RESET}`);
+            mark(from, item);
+            if (map) map[out.length - 1] = { item, affordance: 'less' };
+          } else {
+            mark(from, item);
           }
         } else if (item.detail && details) {
           // block tool: left border, panel background, command then output