@hienlh/ppm 0.21.0 → 0.22.0

package/src/services/remote-desktop/remote-desktop-input-linux.ts

@@ -0,0 +1,253 @@
+/**
+ * X11 input backend: `bun:ffi` into libXtst's XTEST extension — no helper process, matching
+ * `remote-desktop-input-win32.ts` (user32/SendInput) and `-darwin.ts` (CoreGraphics).
+ *
+ * Selected by `remote-desktop-input.ts` on `linux`, and it answers only for an X11 session:
+ * XTEST is an X server extension, so a Wayland compositor has nothing to inject into and this
+ * backend reports unavailable there (`remote-desktop-input-uinput.ts` covers that case).
+ *
+ * Keys go through `remote-desktop-evdev-key-map.ts` + `X11_KEYCODE_OFFSET`, never through
+ * `XKeysymToKeycode` — see that file for why a keysym lookup transposes a non-US keyboard.
+ *
+ * Text is harder than on the other two platforms: X11 has no "type this Unicode string" call
+ * (`KEYEVENTF_UNICODE` / `CGEventKeyboardSetUnicodeString` have no counterpart). So `text()`
+ * has two paths:
+ *  - **Fast path** — the character already exists in the active keymap, which covers all ASCII
+ *    on any ordinary layout. Press its real keycode, with Shift when it sits in the shifted
+ *    slot. No mapping change, no round trip per character.
+ *  - **Slow path** — anything else (`ệ`, `日`, an emoji). A scratch keycode with no keysyms of
+ *    its own is temporarily bound to the character's Unicode keysym, pressed, and unbound
+ *    again. This needs a real delay after the remap, not just `XSync`: the server applies the
+ *    change immediately but the focused *client* only learns about it when it processes the
+ *    `MappingNotify`, and a key pressed before then is interpreted with the old mapping.
+ *
+ * Caveat shared with macOS/Windows: injected keys enter the host's input stack *above* its
+ * IME, so a Telex/ibus input method running on the host will still rewrite what arrives
+ * (typing "World" through a Telex IME lands as "ửold"). That is the host's IME doing its job,
+ * not a bug here.
+ */
+import { asPointer, getX11, type X11Connection } from "./remote-desktop-x11.ts";
+import { detectLinuxSession, type LinuxSession } from "./remote-desktop-linux-session.ts";
+import { codeToEvdev, MODIFIER_EVDEV_CODES, X11_KEYCODE_OFFSET } from "./remote-desktop-evdev-key-map.ts";
+import { RemoteInputUnavailableError, type InputTargetRect, type RemoteInputBackend } from "./remote-desktop-input-backend.ts";
+
+/** X core protocol button numbers. 4/5 are the wheel's two directions — X11 has no scroll
+ *  axis, a notch *is* a button click. */
+const BUTTON_LEFT = 1;
+const BUTTON_RIGHT = 3;
+const BUTTON_WHEEL_UP = 4;
+const BUTTON_WHEEL_DOWN = 5;
+/** One notch, matching `WHEEL_DELTA` on Windows — the client sends in these units. */
+const WHEEL_DELTA = 120;
+/** Above this a runaway client value is clamped rather than turned into thousands of clicks. */
+const MAX_WHEEL_NOTCHES = 64;
+/** ShiftLeft, for reaching the shifted half of the keymap in `text()`. */
+const SHIFT_KEYCODE = 42 + X11_KEYCODE_OFFSET;
+/** How long a client needs to process the `MappingNotify` from a scratch-keycode remap before
+ *  a key pressed on it is read with the new mapping. `xdotool type` uses 12ms for the same
+ *  reason; below ~8ms characters start arriving as the previous mapping on a busy host. */
+const REMAP_SETTLE_MS = 12;
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+/** The X11 keysym for a Unicode code point. Latin-1 is its own keysym range; everything else
+ *  uses the `0x01000000 | codepoint` convention every X server understands. */
+function unicodeKeysym(cp: number): number {
+  return (cp >= 0x20 && cp <= 0x7e) || (cp >= 0xa0 && cp <= 0xff) ? cp : 0x01000000 | cp;
+}
+
+async function connect(): Promise<X11Connection> {
+  const session: LinuxSession | null = detectLinuxSession();
+  if (session?.kind !== "x11") {
+    throw new RemoteInputUnavailableError("remote input needs an X11 session (Wayland uses uinput)");
+  }
+  const conn = await getX11(session);
+  if (!conn?.xtst || !conn.hasXTest) {
+    throw new RemoteInputUnavailableError("the X server has no XTEST extension (install libXtst)");
+  }
+  return conn;
+}
+
+/** Where a 0..1 fraction lands in root-window coordinates. X11 puts every monitor in one root
+ *  coordinate space, so a per-monitor target is just an offset rect inside it. */
+function toRootCoords(
+  conn: X11Connection, xFrac: number, yFrac: number, target: InputTargetRect | null,
+): { x: number; y: number } {
+  const rect = target ?? {
+    x: 0, y: 0,
+    width: conn.x11.XDisplayWidth(conn.dpy, conn.screen),
+    height: conn.x11.XDisplayHeight(conn.dpy, conn.screen),
+  };
+  const clamp = (v: number) => (Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 0);
+  return {
+    x: Math.round(rect.x + clamp(xFrac) * Math.max(0, rect.width - 1)),
+    y: Math.round(rect.y + clamp(yFrac) * Math.max(0, rect.height - 1)),
+  };
+}
+
+async function pointer(
+  xFrac: number, yFrac: number, button: "left" | "right" | null, down: boolean | null,
+  target: InputTargetRect | null,
+): Promise<void> {
+  const conn = await connect();
+  const { x, y } = toRootCoords(conn, xFrac, yFrac, target);
+  conn.xtst!.XTestFakeMotionEvent(conn.dpy, conn.screen, x, y, 0);
+  if (button && down !== null) {
+    conn.xtst!.XTestFakeButtonEvent(conn.dpy, button === "left" ? BUTTON_LEFT : BUTTON_RIGHT, down ? 1 : 0, 0);
+  }
+  conn.x11.XFlush(conn.dpy);
+}
+
+/** `deltaY` in 120-unit notches, positive = away from the user (scroll up), matching the
+ *  Windows/macOS backends. X11 turns each notch into a press+release of button 4 or 5. */
+async function wheel(deltaY: number): Promise<void> {
+  const conn = await connect();
+  const notches = Math.min(MAX_WHEEL_NOTCHES, Math.round(Math.abs(deltaY) / WHEEL_DELTA));
+  if (notches === 0) return;
+  const button = deltaY > 0 ? BUTTON_WHEEL_UP : BUTTON_WHEEL_DOWN;
+  for (let i = 0; i < notches; i++) {
+    conn.xtst!.XTestFakeButtonEvent(conn.dpy, button, 1, 0);
+    conn.xtst!.XTestFakeButtonEvent(conn.dpy, button, 0, 0);
+  }
+  conn.x11.XFlush(conn.dpy);
+}
+
+async function key(code: string, down: boolean): Promise<boolean> {
+  const evdev = codeToEvdev(code);
+  if (evdev === null) return false;
+  const conn = await connect();
+  conn.xtst!.XTestFakeKeyEvent(conn.dpy, evdev + X11_KEYCODE_OFFSET, down ? 1 : 0, 0);
+  conn.x11.XFlush(conn.dpy);
+  return true;
+}
+
+/** keysym → the keycode that produces it and whether Shift is needed. Rebuilt per `text()`
+ *  call rather than cached: a layout switch would otherwise leave a stale index pressing
+ *  keycodes that now produce different characters, which is worse than one round trip. */
+function buildKeysymIndex(conn: X11Connection): Map<number, { keycode: number; shift: boolean }> {
+  const { ffi, x11, dpy } = conn;
+  const index = new Map<number, { keycode: number; shift: boolean }>();
+  const min = new Int32Array(1), max = new Int32Array(1);
+  x11.XDisplayKeycodes(dpy, ffi.ptr(min), ffi.ptr(max));
+  const count = max[0]! - min[0]! + 1;
+  if (count <= 0) return index;
+
+  const perCode = new Int32Array(1);
+  const syms = x11.XGetKeyboardMapping(dpy, min[0]!, count, ffi.ptr(perCode));
+  if (!syms) return index;
+  const base = asPointer(Number(syms));
+  // Only the first two slots: they are the plain and Shift levels. Level 3/4 need AltGr, so a
+  // character living only there is left to the scratch-keycode path instead of guessing.
+  const slots = Math.min(2, perCode[0]!);
+  for (let i = 0; i < count; i++) {
+    for (let slot = 0; slot < slots; slot++) {
+      const keysym = Number(ffi.read.u64(base, (i * perCode[0]! + slot) * 8));
+      if (keysym !== 0 && !index.has(keysym)) {
+        index.set(keysym, { keycode: min[0]! + i, shift: slot === 1 });
+      }
+    }
+  }
+  x11.XFree(syms);
+  return index;
+}
+
+/** A keycode with no keysyms of its own, safe to borrow for one character. null when the
+ *  keymap is full (then non-ASCII text is dropped rather than clobbering a real key). */
+function findScratchKeycode(conn: X11Connection): number | null {
+  const { ffi, x11, dpy } = conn;
+  const min = new Int32Array(1), max = new Int32Array(1);
+  x11.XDisplayKeycodes(dpy, ffi.ptr(min), ffi.ptr(max));
+  const count = max[0]! - min[0]! + 1;
+  if (count <= 0) return null;
+  const perCode = new Int32Array(1);
+  const syms = x11.XGetKeyboardMapping(dpy, min[0]!, count, ffi.ptr(perCode));
+  if (!syms) return null;
+  const base = asPointer(Number(syms));
+  let found: number | null = null;
+  // Search from the top: high keycodes are where a layout is least likely to grow into.
+  for (let i = count - 1; i >= 0 && found === null; i--) {
+    let empty = true;
+    for (let slot = 0; slot < perCode[0]!; slot++) {
+      if (Number(ffi.read.u64(base, (i * perCode[0]! + slot) * 8)) !== 0) { empty = false; break; }
+    }
+    if (empty) found = min[0]! + i;
+  }
+  x11.XFree(syms);
+  return found;
+}
+
+/**
+ * One string at a time.
+ *
+ * The slow path borrows a spare keycode, and `findScratchKeycode` is deterministic — two
+ * overlapping calls pick the *same* one. They then interleave at the two settle sleeps, and
+ * whichever finishes first unbinds the keycode the other is still using, so the loser taps a
+ * key bound to nothing and types silence, or types the winner's character.
+ *
+ * The client makes this ordinary rather than exotic: the virtual keyboard sends one `text`
+ * message per keystroke and another at `compositionend`, and the slow path is exactly the
+ * non-ASCII input — Vietnamese, CJK — where those arrive fastest.
+ */
+let textQueue: Promise<void> = Promise.resolve();
+
+function text(str: string): Promise<void> {
+  const next = textQueue.then(() => injectText(str));
+  // The chain must survive a failed string, or one error would wedge every later one.
+  textQueue = next.catch(() => undefined);
+  return next;
+}
+
+async function injectText(str: string): Promise<void> {
+  const conn = await connect();
+  const { ffi, x11, xtst, dpy } = conn;
+  const index = buildKeysymIndex(conn);
+  let scratch: number | null | undefined;
+  const scratchSyms = new BigUint64Array(1);
+
+  const tap = (keycode: number, shift: boolean) => {
+    if (shift) xtst!.XTestFakeKeyEvent(dpy, SHIFT_KEYCODE, 1, 0);
+    xtst!.XTestFakeKeyEvent(dpy, keycode, 1, 0);
+    xtst!.XTestFakeKeyEvent(dpy, keycode, 0, 0);
+    if (shift) xtst!.XTestFakeKeyEvent(dpy, SHIFT_KEYCODE, 0, 0);
+    x11.XFlush(dpy);
+  };
+
+  try {
+    for (const ch of str) {
+      const cp = ch.codePointAt(0);
+      if (cp === undefined) continue;
+      const hit = index.get(unicodeKeysym(cp));
+      if (hit) { tap(hit.keycode, hit.shift); continue; }
+
+      if (scratch === undefined) scratch = findScratchKeycode(conn);
+      if (scratch === null) continue; // no borrowable keycode — drop rather than clobber a real key
+      scratchSyms[0] = BigInt(unicodeKeysym(cp));
+      x11.XChangeKeyboardMapping(dpy, scratch, 1, ffi.ptr(scratchSyms), 1);
+      x11.XSync(dpy, 0);
+      await sleep(REMAP_SETTLE_MS);
+      tap(scratch, false);
+      await sleep(REMAP_SETTLE_MS);
+    }
+  } finally {
+    // Always hand the scratch keycode back, including after a throw mid-string: leaving a
+    // Unicode keysym bound to it would make that key type a stray character forever.
+    if (typeof scratch === "number") {
+      scratchSyms[0] = 0n;
+      x11.XChangeKeyboardMapping(dpy, scratch, 1, ffi.ptr(scratchSyms), 1);
+      x11.XSync(dpy, 0);
+    }
+  }
+}
+
+async function releaseAllModifiers(): Promise<void> {
+  const conn = await connect();
+  for (const evdev of MODIFIER_EVDEV_CODES) {
+    conn.xtst!.XTestFakeKeyEvent(conn.dpy, evdev + X11_KEYCODE_OFFSET, 0, 0);
+  }
+  conn.x11.XFlush(conn.dpy);
+}
+
+export const x11InputBackend: RemoteInputBackend = {
+  id: "linux-xtest",
+  pointer, wheel, key, text, releaseAllModifiers,
+};

package/src/services/remote-desktop/remote-desktop-input-uinput.ts

@@ -0,0 +1,242 @@
+/**
+ * Wayland input backend: two virtual devices on `/dev/uinput`, driven straight from the
+ * kernel's evdev interface.
+ *
+ * Why not XTEST: XTEST is an X server extension. A Wayland compositor is not an X server, and
+ * the protocol has no input-injection request at all by design — so the only way in is to be
+ * an input *device*. uinput events enter below the compositor, which means they also work on
+ * X11 (useful: it is how this backend is testable on an X11 host) and they are indistinguishable
+ * from a real keyboard/mouse to everything above.
+ *
+ * **Two devices, not one.** libinput classifies a device from the capabilities it declares, and
+ * a single device advertising both a full keyboard and absolute axes gets misread — typically as
+ * a touchpad, which then applies pointer acceleration and treats absolute coordinates as
+ * relative motion, so the pointer drifts instead of landing where it was told. A pointer device
+ * (absolute axes + buttons + wheel, `INPUT_PROP_DIRECT`) and a keyboard device (keys only) are
+ * each unambiguous.
+ *
+ * **No `text()`.** uinput carries key codes, not characters: there is no counterpart to
+ * `KEYEVENTF_UNICODE` (Windows), `CGEventKeyboardSetUnicodeString` (macOS) or even the
+ * scratch-keysym remap the X11 backend uses, because the layout that turns a key code into a
+ * character lives in the compositor. `text` is therefore absent, the facade's `injectText`
+ * returns false, and the client falls back to per-key events. Consequence: a phone soft keyboard
+ * that reports no key codes (most Android IMEs) cannot type on a Wayland host.
+ *
+ * **Absolute coordinates cover the whole desktop.** The kernel knows nothing about monitor
+ * layout, so 0..65535 maps to the compositor's full pointer area. Per-monitor targeting is not
+ * possible here the way it is under X11's single root-window coordinate space.
+ */
+import { closeSync, openSync, writeSync } from "node:fs";
+import { ALL_EVDEV_CODES, codeToEvdev, MODIFIER_EVDEV_CODES } from "./remote-desktop-evdev-key-map.ts";
+import { RemoteInputUnavailableError, type InputTargetRect, type RemoteInputBackend } from "./remote-desktop-input-backend.ts";
+
+/** ioctl request numbers, verified against `linux/uinput.h` on x86-64 rather than derived by
+ *  hand: `_IOW` encodes the struct size, so a wrong `sizeof` yields a silently different
+ *  request number and `ioctl` fails with EINVAL for no visible reason. */
+const UI_DEV_CREATE = 0x5501;
+const UI_DEV_DESTROY = 0x5502;
+const UI_DEV_SETUP = 0x405c5503;   // _IOW('U', 3, struct uinput_setup)      sizeof 92
+const UI_ABS_SETUP = 0x401c5504;   // _IOW('U', 4, struct uinput_abs_setup)  sizeof 28
+const UI_SET_EVBIT = 0x40045564;
+const UI_SET_KEYBIT = 0x40045565;
+const UI_SET_RELBIT = 0x40045566;
+const UI_SET_ABSBIT = 0x40045567;
+const UI_SET_PROPBIT = 0x4004556e;
+
+const EV_SYN = 0, EV_KEY = 1, EV_REL = 2, EV_ABS = 3;
+const SYN_REPORT = 0;
+const ABS_X = 0, ABS_Y = 1;
+const REL_WHEEL = 8;
+const BTN_LEFT = 0x110, BTN_RIGHT = 0x111, BTN_MIDDLE = 0x112;
+const INPUT_PROP_DIRECT = 0x01;
+const BUS_USB = 0x03;
+
+/** Absolute axis range. Matches Windows `SendInput`'s 0..65535 normalisation, so both
+ *  platforms carry the same "fraction of the surface" semantics. */
+const ABS_MAX = 65535;
+/** `struct input_event` on x86-64: 16-byte timeval (kernel fills it when zero) + u16 type +
+ *  u16 code + s32 value. */
+const EVENT_SIZE = 24;
+/** One notch, matching `WHEEL_DELTA` on the other backends. */
+const WHEEL_DELTA = 120;
+const MAX_WHEEL_NOTCHES = 64;
+
+type Ffi = typeof import("bun:ffi");
+/* eslint-disable @typescript-eslint/no-explicit-any -- dlopen symbol types are per-call */
+type Libc = { ioctl: any };
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+interface Devices { pointer: number; keyboard: number }
+
+let ffiModule: Ffi | null = null;
+let libc: Libc | null = null;
+let devices: Devices | null = null;
+let exitHookInstalled = false;
+
+function eventBuf(entries: Array<[type: number, code: number, value: number]>): Uint8Array {
+  const buf = new Uint8Array(EVENT_SIZE * entries.length);
+  const dv = new DataView(buf.buffer);
+  entries.forEach(([type, code, value], i) => {
+    const at = i * EVENT_SIZE;
+    dv.setUint16(at + 16, type, true);
+    dv.setUint16(at + 18, code, true);
+    dv.setInt32(at + 20, value, true);
+  });
+  return buf;
+}
+
+/** `struct uinput_setup`: input_id (bustype/vendor/product/version) + char name[80] + u32. */
+function setupBuf(name: string, product: number): Uint8Array {
+  const buf = new Uint8Array(92);
+  const dv = new DataView(buf.buffer);
+  dv.setUint16(0, BUS_USB, true);
+  dv.setUint16(2, 0x1d6b, true);   // Linux Foundation — a virtual device, not a spoofed vendor
+  dv.setUint16(4, product, true);
+  dv.setUint16(6, 1, true);
+  buf.set(new TextEncoder().encode(name).subarray(0, 79), 8);
+  return buf;
+}
+
+/** `struct uinput_abs_setup`: u16 code + 2 pad + input_absinfo (value/min/max/fuzz/flat/res). */
+function absSetupBuf(code: number, max: number): Uint8Array {
+  const buf = new Uint8Array(28);
+  const dv = new DataView(buf.buffer);
+  dv.setUint16(0, code, true);
+  dv.setInt32(8, 0, true);    // minimum
+  dv.setInt32(12, max, true); // maximum
+  return buf;
+}
+
+async function loadLibc(): Promise<Libc> {
+  if (libc) return libc;
+  if (!ffiModule) ffiModule = await import("bun:ffi");
+  const { dlopen, FFIType } = ffiModule;
+  // `ioctl` is variadic in C, but every request here passes one integer/pointer argument, which
+  // the x86-64 ABI puts in the same register a fixed third parameter would use.
+  libc = dlopen("libc.so.6", {
+    ioctl: { args: [FFIType.i32, FFIType.u64, FFIType.u64], returns: FFIType.i32 },
+  }).symbols as Libc;
+  return libc;
+}
+
+function ioctlOrThrow(lib: Libc, fd: number, request: number, arg: number | bigint, what: string): void {
+  if (lib.ioctl(fd, BigInt(request), typeof arg === "bigint" ? arg : BigInt(arg)) < 0) {
+    throw new RemoteInputUnavailableError(`uinput ${what} failed (is /dev/uinput writable?)`);
+  }
+}
+
+function createPointerDevice(lib: Libc, ffi: Ffi): number {
+  const fd = openSync("/dev/uinput", "w");
+  ioctlOrThrow(lib, fd, UI_SET_EVBIT, EV_KEY, "SET_EVBIT EV_KEY");
+  for (const btn of [BTN_LEFT, BTN_RIGHT, BTN_MIDDLE]) ioctlOrThrow(lib, fd, UI_SET_KEYBIT, btn, "SET_KEYBIT");
+  ioctlOrThrow(lib, fd, UI_SET_EVBIT, EV_REL, "SET_EVBIT EV_REL");
+  ioctlOrThrow(lib, fd, UI_SET_RELBIT, REL_WHEEL, "SET_RELBIT");
+  ioctlOrThrow(lib, fd, UI_SET_EVBIT, EV_ABS, "SET_EVBIT EV_ABS");
+  // `INPUT_PROP_DIRECT` is what stops libinput reading absolute axes as touchpad motion.
+  ioctlOrThrow(lib, fd, UI_SET_PROPBIT, INPUT_PROP_DIRECT, "SET_PROPBIT");
+  for (const axis of [ABS_X, ABS_Y]) {
+    ioctlOrThrow(lib, fd, UI_SET_ABSBIT, axis, "SET_ABSBIT");
+    const abs = absSetupBuf(axis, ABS_MAX);
+    ioctlOrThrow(lib, fd, UI_ABS_SETUP, BigInt(ffi.ptr(abs)), "ABS_SETUP");
+  }
+  const setup = setupBuf("PPM Remote Pointer", 0x0001);
+  ioctlOrThrow(lib, fd, UI_DEV_SETUP, BigInt(ffi.ptr(setup)), "DEV_SETUP");
+  ioctlOrThrow(lib, fd, UI_DEV_CREATE, 0, "DEV_CREATE");
+  return fd;
+}
+
+function createKeyboardDevice(lib: Libc, ffi: Ffi): number {
+  const fd = openSync("/dev/uinput", "w");
+  ioctlOrThrow(lib, fd, UI_SET_EVBIT, EV_KEY, "SET_EVBIT EV_KEY");
+  for (const code of ALL_EVDEV_CODES) ioctlOrThrow(lib, fd, UI_SET_KEYBIT, code, "SET_KEYBIT");
+  const setup = setupBuf("PPM Remote Keyboard", 0x0002);
+  ioctlOrThrow(lib, fd, UI_DEV_SETUP, BigInt(ffi.ptr(setup)), "DEV_SETUP");
+  ioctlOrThrow(lib, fd, UI_DEV_CREATE, 0, "DEV_CREATE");
+  return fd;
+}
+
+/** Create both devices once. The compositor needs a moment to notice a new device before the
+ *  first event will be routed, so creation is awaited rather than raced with the first click. */
+async function ensureDevices(): Promise<Devices> {
+  if (devices) return devices;
+  if (!ffiModule) ffiModule = await import("bun:ffi");
+  const lib = await loadLibc();
+  const created = { pointer: createPointerDevice(lib, ffiModule), keyboard: createKeyboardDevice(lib, ffiModule) };
+  devices = created;
+  if (!exitHookInstalled) {
+    exitHookInstalled = true;
+    // Without DEV_DESTROY the virtual devices outlive the process and pile up in the
+    // compositor's device list on every restart.
+    process.on("exit", destroyDevices);
+  }
+  await new Promise<void>((r) => setTimeout(r, 120));
+  return created;
+}
+
+/** Destroy both virtual devices now, rather than at process exit.
+ *
+ *  They are process-wide, not per session: one Wayland session leaves a "PPM Remote Keyboard"
+ *  and a "PPM Remote Pointer" in the compositor's device list for the life of the server, where
+ *  they show up in system settings and in any tool that enumerates input devices. The next
+ *  session recreates them — including the ~120 ms `ensureDevices` waits for the compositor to
+ *  notice them — so the only cost is on the first event after a reconnect. */
+export function releaseUinputDevices(): void {
+  destroyDevices();
+}
+
+function destroyDevices(): void {
+  if (!devices || !libc) return;
+  for (const fd of [devices.pointer, devices.keyboard]) {
+    try { libc.ioctl(fd, BigInt(UI_DEV_DESTROY), 0n); } catch { /* going away anyway */ }
+    try { closeSync(fd); } catch { /* ditto */ }
+  }
+  devices = null;
+}
+
+function emit(fd: number, entries: Array<[number, number, number]>): void {
+  const buf = eventBuf([...entries, [EV_SYN, SYN_REPORT, 0]]);
+  writeSync(fd, buf, 0, buf.byteLength);
+}
+
+/** `target` is accepted for interface parity but cannot be honoured: the kernel has no monitor
+ *  layout, so absolute axes always span the compositor's whole pointer area. */
+async function pointer(
+  xFrac: number, yFrac: number, button: "left" | "right" | null, down: boolean | null,
+  _target: InputTargetRect | null,
+): Promise<void> {
+  const dev = await ensureDevices();
+  const clamp = (v: number) => (Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 0);
+  const events: Array<[number, number, number]> = [
+    [EV_ABS, ABS_X, Math.round(clamp(xFrac) * ABS_MAX)],
+    [EV_ABS, ABS_Y, Math.round(clamp(yFrac) * ABS_MAX)],
+  ];
+  if (button && down !== null) events.push([EV_KEY, button === "left" ? BTN_LEFT : BTN_RIGHT, down ? 1 : 0]);
+  emit(dev.pointer, events);
+}
+
+async function wheel(deltaY: number): Promise<void> {
+  const dev = await ensureDevices();
+  const notches = Math.round(deltaY / WHEEL_DELTA);
+  const clamped = Math.max(-MAX_WHEEL_NOTCHES, Math.min(MAX_WHEEL_NOTCHES, notches));
+  if (clamped === 0) return;
+  // REL_WHEEL is positive away from the user, the same sign the facade already carries.
+  emit(dev.pointer, [[EV_REL, REL_WHEEL, clamped]]);
+}
+
+async function key(code: string, down: boolean): Promise<boolean> {
+  const evdev = codeToEvdev(code);
+  if (evdev === null) return false;
+  const dev = await ensureDevices();
+  emit(dev.keyboard, [[EV_KEY, evdev, down ? 1 : 0]]);
+  return true;
+}
+
+async function releaseAllModifiers(): Promise<void> {
+  const dev = await ensureDevices();
+  emit(dev.keyboard, MODIFIER_EVDEV_CODES.map((c) => [EV_KEY, c, 0] as [number, number, number]));
+}
+
+export const uinputInputBackend: RemoteInputBackend = {
+  id: "linux-uinput",
+  pointer, wheel, key, releaseAllModifiers,
+};

package/src/services/remote-desktop/remote-desktop-input.ts

@@ -3,11 +3,17 @@
  * from the registry below; the session and routes never import a platform module directly.
  *
  * Every backend module is safe to *import* anywhere (FFI is loaded lazily inside each), so the
- * registry can hold them all statically — only the selected one ever `dlopen`s. Adding Linux =
- * `remote-desktop-input-linux.ts` + one line in `BACKENDS`.
+ * registry can hold them all statically — only the selected one ever `dlopen`s.
+ *
+ * Linux is the one platform whose backend cannot be decided by `process.platform` alone: XTEST
+ * is an X server extension and a Wayland compositor has no equivalent, so the choice is made
+ * per *session* inside `linuxInputBackend`.
  */
 import { win32InputBackend } from "./remote-desktop-input-win32.ts";
 import { darwinInputBackend } from "./remote-desktop-input-darwin.ts";
+import { x11InputBackend } from "./remote-desktop-input-linux.ts";
+import { uinputInputBackend, releaseUinputDevices } from "./remote-desktop-input-uinput.ts";
+import { detectLinuxSession } from "./remote-desktop-linux-session.ts";
 import { RemoteInputUnavailableError, type InputTargetRect, type RemoteInputBackend } from "./remote-desktop-input-backend.ts";
 
 export { RemoteInputUnavailableError, type InputTargetRect, type RemoteInputBackend };
@@ -17,11 +23,34 @@ const BACKENDS: Partial<Record<NodeJS.Platform, RemoteInputBackend>> = {
   darwin: darwinInputBackend,
 };
 
-/** The backend for this host, or null when the platform has none. */
-export function getInputBackend(platform: NodeJS.Platform = process.platform): RemoteInputBackend | null {
+/** Linux picks by session, not by platform: XTEST is an X server extension, so a Wayland
+ *  compositor is driven as a virtual input device through uinput instead. Returns null on a
+ *  host with no graphical session at all (a headless server, a CI container) so
+ *  `isInputAvailable()` stays honest there. */
+function linuxInputBackend(session = detectLinuxSession()): RemoteInputBackend | null {
+  if (!session) return null;
+  return session.kind === "x11" ? x11InputBackend : uinputInputBackend;
+}
+
+/** The backend for this host, or null when the platform has none. `session` is only read on
+ *  Linux and is passed explicitly by tests — it otherwise probes the host, which a headless
+ *  runner answers differently from a desktop. */
+export function getInputBackend(
+  platform: NodeJS.Platform = process.platform,
+  session = platform === "linux" ? detectLinuxSession() : null,
+): RemoteInputBackend | null {
+  if (platform === "linux") return linuxInputBackend(session);
   return BACKENDS[platform] ?? null;
 }
 
+/** Give back anything the injector holds between calls, for when no session needs it.
+ *
+ *  Only uinput holds something: XTEST, `SendInput` and CoreGraphics own nothing between
+ *  events, so this is a no-op everywhere else and is safe to call unconditionally. */
+export function releaseRemoteInput(): void {
+  releaseUinputDevices();
+}
+
 /** Sync, cheap: does this platform have an injector at all? Used on the per-event hot path to
  *  drop input messages early. "Would it actually work" (OS permissions) is answered by
  *  `remote-desktop-requirements.ts`. */
@@ -29,25 +58,28 @@ export function isInputAvailable(): boolean {
   return getInputBackend() !== null;
 }
 
+/** Throws `RemoteInputUnavailableError`. Every caller below is `async` on purpose, so an
+ *  unsupported platform surfaces as a *rejected promise* rather than a synchronous throw —
+ *  the session forwards input from a WS message handler and only ever `await`s these. */
 function required(): RemoteInputBackend {
   const backend = getInputBackend();
   if (!backend) throw new RemoteInputUnavailableError();
   return backend;
 }
 
-export function injectPointer(
+export async function injectPointer(
   xFrac: number, yFrac: number, button: "left" | "right" | null, down: boolean | null, target: InputTargetRect | null = null,
 ): Promise<void> {
   return required().pointer(xFrac, yFrac, button, down, target);
 }
 
-export function injectWheel(deltaY: number): Promise<void> {
+export async function injectWheel(deltaY: number): Promise<void> {
   // A zero delta is a no-op on every OS — settle it here so no backend is even consulted.
-  if (Math.round(deltaY) === 0) return Promise.resolve();
+  if (Math.round(deltaY) === 0) return;
   return required().wheel(deltaY);
 }
 
-export function injectKey(code: string, down: boolean): Promise<boolean> {
+export async function injectKey(code: string, down: boolean): Promise<boolean> {
   return required().key(code, down);
 }