Skip to content

armgit / axuse

Public Imported from GitHub
0

Accessibility-first browser & computer use for AI agents — one MCP server for every harness (Codex, Claude Code, OpenCode, Antigravity). Instruments the DOM/accessibility tree via CDP instead of screenshot loops: diffed snapshots, stable element refs, trusted input, typed errors. Zero dependencies

31.4 KB
Raw Blame
/**
 * axuse — minimal zero-dependency X11 protocol client (Linux desktop driver).
 *
 * Lineage: the Windows driver scripts PowerShell + SendInput, the macOS
 * driver scripts JXA + CoreGraphics. Linux has no comparable "scriptable
 * surface" guaranteed present — xdotool/wmctrl/scrot are extra apt packages
 * — but every X11 server speaks one wire protocol over a Unix socket, and
 * Node ships everything needed to speak it directly:
 *
 *   - connection setup + Xauthority cookie (MIT-MAGIC-COOKIE-1) with an
 *     empty-auth retry (SI:localuser grants local same-user clients)
 *   - core requests: WarpPointer, QueryPointer, GetImage, GetGeometry,
 *     TranslateCoordinates, InternAtom, GetProperty, SendEvent,
 *     GetKeyboardMapping
 *   - XTEST FakeInput — trusted server-side input synthesis, the X
 *     equivalent of SendInput (wire layout per the XTEST 2.2 encoding)
 *   - EWMH properties for the client window list + _NET_ACTIVE_WINDOW
 *
 * Scope notes (v1):
 *   - X11/XWayland only; native Wayland sessions refuse with a typed error.
 *   - The root window of the display's default screen is the coordinate
 *     space. On the standard single-X-screen layout the root spans every
 *     monitor, so warps and captures work across monitors.
 */
import { connect as netConnect } from "node:net";
import { readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { AxError, Codes } from "../core/errors.js";

const NO_WINDOW = 0;

/** X core request opcodes used here. */
export const Op = Object.freeze({
  GetGeometry: 14, QueryTree: 15, InternAtom: 16, GetProperty: 20, SendEvent: 25,
  QueryPointer: 38, TranslateCoordinates: 40, WarpPointer: 41,
  GetImage: 73, QueryExtension: 98, GetKeyboardMapping: 101,
});

/** FAKE_EVENT_TYPE values (same as the core event codes). */
export const FakeEventType = Object.freeze({
  KeyPress: 2, KeyRelease: 3, ButtonPress: 4, ButtonRelease: 5, MotionNotify: 6,
});

/** Parse a display string ":1", ":1.0", "unix:1", "host:1" → parts. */
export function parseDisplay(display = process.env.DISPLAY ?? "") {
  const m = /^([a-zA-Z0-9._-]*):([0-9]+)(?:\.([0-9]+))?$/.exec(String(display).trim());
  if (!m) return null;
  return { host: m[1], display: Number(m[2]), screen: m[3] === undefined ? null : Number(m[3]) };
}

/** Xauthority records (little-endian u16 lengths, no padding between fields):
 *   family(u16) addrLen addr | numLen num | nameLen name | dataLen data */
export function readXauthority(path) {
  let buf;
  try {
    buf = readFileSync(path);
  } catch {
    return [];
  }
  const out = [];
  let o = 0;
  const u16 = () => { const v = buf.readUInt16LE(o); o += 2; return v; };
  const blob = () => { const n = u16(); const b = buf.subarray(o, o + n); o += n; return b; };
  while (o + 2 <= buf.length) {
    const start = o;
    try {
      const family = u16();
      const addr = blob();
      const num = blob();
      const name = blob();
      const data = blob();
      out.push({ family, addr, num: num.toString("latin1"), name: name.toString("latin1"), data });
    } catch {
      o = start;
      break; // truncated record
    }
  }
  return out;
}

/** Best MIT-MAGIC-COOKIE-1 for a display: exact display-number match first,
 *  then a wildcard-family record (FamilyWild=65535, FamilyLocal=256). */
function cookieFor(display) {
  const path = process.env.XAUTHORITY || join(homedir(), ".Xauthority");
  const cookies = readXauthority(path).filter((r) => r.name === "MIT-MAGIC-COOKIE-1");
  return cookies.find((r) => r.num === String(display))
    ?? cookies.find((r) => r.family === 65535 || r.family === 256)
    ?? null;
}

function describeXError(code) {
  const names = {
    1: "BadRequest", 2: "BadValue", 3: "BadWindow", 4: "BadPixmap", 5: "BadAtom",
    6: "BadCursor", 7: "BadFont", 8: "BadMatch", 9: "BadDrawable", 10: "BadAccess",
    11: "BadAlloc", 12: "BadColor", 13: "BadGC", 14: "BadIDChoice", 15: "BadName",
    16: "BadLength", 17: "BadImplementation",
  };
  return names[code] ?? `code ${code}`;
}

/** Static evdev keymap (keysym → [keycode = KEY_* + 8, shift]) for servers
 *  whose core keyboard map is empty (XKB-owned). US-layout punctuation; the
 *  server map wins whenever it is populated. */
const EVDEV_KEYMAP = (() => {
  const rows = [];
  const push = (keysym, keycode, shift) => rows.push([keysym, keycode, shift]);
  // Letters in QWERTY PHYSICAL order (evdev keycodes; X keycode = code + 8):
  // q w e r t y u i o p → 24..33, a s d f g h j k l → 38..46,
  // z x c v b n m → 52..58. Alphabetical order would be wrong — the map is
  // positional, not alphabetical.
  const letterRows = [
    ["qwertyuiop", 24],
    ["asdfghjkl", 38],
    ["zxcvbnm", 52],
  ];
  for (const [letters, base] of letterRows) {
    for (let i = 0; i < letters.length; i++) {
      const c = letters.charCodeAt(i);
      push(c, base + i, false); // lowercase
      push(c - 32, base + i, true); // uppercase (shift)
    }
  }
  // Digits row (KEY_1=2 → keycode 10 … KEY_0=11 → 19)
  const digits = "1234567890";
  const shifted = "!@#$%^&*()";
  for (let i = 0; i < 10; i++) {
    push(digits.charCodeAt(i), 10 + i, false);
    push(shifted.charCodeAt(i), 10 + i, true);
  }
  const named = [
    // [keysym, keycode, shift]
    [0xff0d, 36, false], [0xff09, 23, false], [0xff1b, 9, false], [0xff08, 22, false],
    [0xffff, 119, false], [0xff63, 118, false],
    [0xff52, 111, false], [0xff54, 116, false], [0xff51, 113, false], [0xff53, 114, false],
    [0xff50, 110, false], [0xff57, 115, false], [0xff55, 112, false], [0xff56, 117, false],
    [0x20, 65, false],
    [0xffe1, 50, false], [0xffe2, 62, false], // Shift_L/R
    [0xffe3, 37, false], [0xffe4, 105, false], // Control_L/R
    [0xffe9, 64, false], [0xffea, 108, false], // Alt_L/R
    [0xffeb, 133, false], [0xffec, 134, false], // Super_L/R
    [0xffe5, 66, false], [0xff7f, 77, false], // Caps_Lock, Num_Lock
    // US punctuation (unshifted, shifted)
    [0x2d, 20, false], [0x5f, 20, true], // - _
    [0x3d, 21, false], [0x2b, 21, true], // = +
    [0x5b, 34, false], [0x7b, 34, true], // [ {
    [0x5d, 35, false], [0x7d, 35, true], // ] }
    [0x5c, 51, false], [0x7c, 51, true], // \ |
    [0x3b, 47, false], [0x3a, 47, true], // ; :
    [0x27, 48, false], [0x22, 48, true], // ' "
    [0x60, 49, false], [0x7e, 49, true], // ` ~
    [0x2c, 59, false], [0x3c, 59, true], // , <
    [0x2e, 60, false], [0x3e, 60, true], // . >
    [0x2f, 61, false], [0x3f, 61, true], // / ?
  ];
  rows.push(...named);
  for (let i = 0; i < 12; i++) push(0xffbe + i, 67 + i, false); // F1-F12
  // Numeric keypad: KP_0=90, KP_1=87 … KP_9=81 (evdev + 8).
  const kpDigits = [[0xffb0, 90], [0xffb1, 87], [0xffb2, 88], [0xffb3, 89], [0xffb4, 83],
    [0xffb5, 84], [0xffb6, 85], [0xffb7, 79], [0xffb8, 80], [0xffb9, 81]];
  for (const [keysym, keycode] of kpDigits) push(keysym, keycode, false);
  push(0xffab, 86, false); // KP_Add
  push(0xffad, 82, false); // KP_Subtract
  push(0xaa, 63, false); // KP_Multiply
  push(0xaf, 106, false); // KP_Divide
  push(0xff8b, 104, false); // KP_Enter
  push(0xff9e, 91, false); // KP_Decimal
  return rows;
})();

/**
 * A small synchronous-request-at-a-time X11 client. Desktop input must be
 * strictly ordered anyway (the driver serializes ops like WindowsDriver),
 * so a sequence-keyed pending map is sufficient — no concurrent pipelines.
 */
export class X11Client {
  /** @param {string} [display] */
  constructor(display) {
    this.display = String(display ?? process.env.DISPLAY ?? "");
    this.displaySpec = parseDisplay(this.display);
    this.socket = null;
    this.seq = 0;
    this.pending = new Map(); // seq → {resolve, reject}
    this.buffer = Buffer.alloc(0);
    this.setupWaiters = []; // pre-handshake readers (waitFor)
    this.rootWindow = 0;
    this.rootCandidates = [];
    this.screenWidth = 0;
    this.screenHeight = 0;
    this.minKeycode = 0;
    this.maxKeycode = 0;
    this.imageByteOrder = 0; // 0 LSBFirst, 1 MSBFirst
    this.pixmapFormats = new Map(); // depth → bits-per-pixel
    this.xtestOpcode = 0;
    this.atoms = new Map();
    this.keysymToKey = new Map(); // keysym → {keycode, shift}
    this.dead = false;
  }

  get connected() {
    return !!this.socket && !this.dead;
  }

  /* ----------------------------------------------------------- connection */

  async connect() {
    this.dead = false; // a disposed client may reconnect (driver respawn)
    if (!this.displaySpec) {
      throw new AxError(Codes.DESKTOP_DRIVER_UNAVAILABLE,
        process.env.WAYLAND_DISPLAY
          ? "This looks like a native Wayland session with no usable DISPLAY; the Linux desktop driver speaks X11 (XWayland covers most desktop apps — set DISPLAY, usually :0, :1 or similar)."
          : "DISPLAY is not set; the Linux desktop driver needs an X11 session (run the harness inside the desktop session, or under xvfb-run for a virtual display).",
        { hint: "Desktop control on Linux targets X11/XWayland; browser tools work everywhere.", retry: "never" });
    }
    const { host, display } = this.displaySpec;
    await new Promise((resolve, reject) => {
      const sock = (host === "" || host === "unix")
        ? netConnect(`/tmp/.X11-unix/X${display}`)
        : netConnect({ host, port: 6000 + display });
      const fail = (e) => reject(new AxError(Codes.DESKTOP_DRIVER_UNAVAILABLE,
        `Cannot open X display ${process.env.DISPLAY ?? ""}: ${e.message}`,
        { hint: "Run inside the X session (XAUTHORITY may need to point at the session cookie), or under xvfb-run.", retry: "never" }));
      sock.once("error", fail);
      sock.once("connect", () => {
        sock.off("error", fail);
        this.socket = sock;
        resolve();
      });
    });

    try {
      await this.handshake(cookieFor(display));
    } catch (e) {
      // A mismatched cookie is the common cause; SI:localuser access control
      // admits same-user clients without any cookie — retry cookie-less.
      if (e instanceof AxError && e.code === Codes.DESKTOP_DRIVER_UNAVAILABLE) {
        this.teardownSocket();
        await this.reopenSocket();
        await this.handshake(null);
      } else {
        throw e;
      }
    }
    this.socket.on("data", (d) => this.routeData(d));
    this.socket.on("close", () => this.failAll("X11 connection closed"));
    this.socket.on("error", () => this.failAll("X11 connection error"));

    if (!(await this.resolveRoot())) {
      throw new AxError(Codes.INTERNAL, "No candidate root window answered GetGeometry.");
    }
    this.xtestOpcode = (await this.queryExtension("XTEST")).majorOpcode;
    if (!this.xtestOpcode) {
      throw new AxError(Codes.DESKTOP_DRIVER_UNAVAILABLE,
        "The X server does not support the XTEST extension; trusted input synthesis is unavailable.",
        { retry: "never" });
    }
    await this.loadKeyboardMap();
    return this;
  }

  async reopenSocket() {
    const { host, display } = this.displaySpec;
    await new Promise((resolve, reject) => {
      const sock = (host === "" || host === "unix")
        ? netConnect(`/tmp/.X11-unix/X${display}`)
        : netConnect({ host, port: 6000 + display });
      sock.once("error", reject);
      sock.once("connect", () => { this.socket = sock; resolve(); });
    });
    this.buffer = Buffer.alloc(0);
    this.dead = false;
  }

  teardownSocket() {
    try { this.socket?.destroy(); } catch {}
    this.socket = null;
  }

  /** Send the connection setup with an (optional) auth cookie and parse it. */
  async handshake(cookie) {
    const name = "MIT-MAGIC-COOKIE-1";
    const data = cookie?.data ?? Buffer.alloc(0);
    const pad4 = (n) => (4 - (n % 4)) % 4;
    const head = Buffer.alloc(12);
    head.writeUInt8(0x6c, 0); // 'l' — little-endian
    head.writeUInt8(0, 1);
    head.writeUInt16LE(11, 2); // protocol 11.0
    head.writeUInt16LE(0, 4);
    head.writeUInt16LE(name.length, 6);
    head.writeUInt16LE(data.length, 8);
    head.writeUInt16LE(0, 10);
    this.socket.write(Buffer.concat([
      head,
      Buffer.from(name, "latin1"), Buffer.alloc(pad4(name.length)),
      data, Buffer.alloc(pad4(data.length)),
    ]));

    const first = await this.waitFor(8);
    // The setup length field counts 4-byte units AFTER the 8-byte header,
    // INCLUDING the 32-byte fixed part (release/ids/keycodes…): the whole
    // packet is 8 + length*4 bytes (verified against Xorg 1.21 wire).
    const total = 8 + first.readUInt16LE(6) * 4;
    const full = Buffer.concat([first, await this.waitFor(total - 8)]);
    if (full[0] === 2) {
      // SetupFailed: [2][reasonLen][major][minor][len16][reason…]
      const reason = full.subarray(8).toString("utf8").replace(/\0.*$/s, "").trim();
      throw new AxError(Codes.DESKTOP_DRIVER_UNAVAILABLE,
        `The X server refused the connection${reason ? `: ${reason}` : ""}.`,
        { hint: "Auth mismatch — run inside the X session or point XAUTHORITY at the session cookie.", retry: "never" });
    }
    if (full[0] !== 1) throw new AxError(Codes.INTERNAL, `Unexpected X11 setup reply type ${full[0]}`);
    // Fixed-field layout verified byte-by-byte against Xorg 1.21.1 wire
    // (Ubuntu 22.04–26.04 family; LSB connection):
    //   vlen@24, maxReqLen@26, pad@28, nformats@29, imageByteOrder@30,
    //   bitmapBitOrder@31, scanlineUnit@32, scanlinePad@33, minKey@34,
    //   maxKey@35, [email protected], vendor@40, formats (8·nformats),
    //   then screens. Single-byte fields are junk-guarded (some builds
    //   leave "unused" slots uninitialized).
    this.imageByteOrder = full[30] <= 1 ? full[30] : 0;
    this.minKeycode = full[34];
    this.maxKeycode = full[35];
    if (!(this.minKeycode < this.maxKeycode)) {
      // Fallback: the canonical evdev range every mainstream server uses.
      this.minKeycode = 8;
      this.maxKeycode = 255;
    }
    const vendorLen = full.readUInt16LE(24);
    const afterVendor = 40 + vendorLen + ((4 - (vendorLen % 4)) % 4);
    // Pixmap formats ([depth, bits-per-pixel, scanline-pad, 5 junk] × 8):
    // Xorg maps depth 24 → 32 bpp — GetImage rows must use this, not depth/8.
    this.pixmapFormats = new Map();
    const fmtCount = full[29] >= 1 && full[29] <= 16 ? full[29] : 6;
    for (let i = 0; i < fmtCount && afterVendor + i * 8 + 2 <= full.length; i++) {
      const depth = full[afterVendor + i * 8];
      const bitsPerPixel = full[afterVendor + i * 8 + 1];
      if (depth > 0 && bitsPerPixel > 0) this.pixmapFormats.set(depth, bitsPerPixel);
    }
    // Screen 0 root candidates: the declared pixmap-format count when it
    // parses sanely, else a scan — the true root is confirmed against the
    // live server by GetGeometry in resolveRoot().
    this.rootCandidates = [];
    const nformats = full[29] >= 1 && full[29] <= 16 ? full[29] : null;
    for (const formats of nformats !== null ? [nformats] : [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 14, 16]) {
      const s = afterVendor + formats * 8;
      if (s + 24 > full.length) break;
      const root = full.readUInt32LE(s);
      // Screen record: root(4) colormap(4) white(4) black(4) masks(4)
      // then width/height in pixels at s+20/s+22.
      const w = full.readUInt16LE(s + 20);
      const h = full.readUInt16LE(s + 22);
      if (root !== 0 && w > 0 && h > 0 && w <= 32767 && h <= 32767) {
        this.rootCandidates.push({ root, w, h });
      }
    }
    if (!this.rootCandidates.length) {
      throw new AxError(Codes.INTERNAL, "Could not parse the X11 connection setup screen list.");
    }
  }

  /** Pick the real root window: the candidate whose GetGeometry round-trips
   *  on the live connection (formats/visual bytes can masquerade as screens
   *  to a heuristic, but only a real window answers GetGeometry). */
  async resolveRoot() {
    for (const cand of this.rootCandidates ?? []) {
      try {
        const g = await this.getGeometry(cand.root);
        if (g.w > 0 && g.h > 0) {
          this.rootWindow = cand.root;
          this.screenWidth = g.w;
          this.screenHeight = g.h;
          return true;
        }
      } catch {
        // BadWindow → wrong candidate, keep scanning.
      }
    }
    return false;
  }

  /** Accumulate `n` bytes during setup (sole consumer of socket data). */
  waitFor(n) {
    if (this.buffer.length >= n) {
      const out = this.buffer.subarray(0, n);
      this.buffer = this.buffer.subarray(n);
      return Promise.resolve(out);
    }
    return new Promise((resolve, reject) => {
      const w = { n, resolve, reject };
      this.setupWaiters.push(w);
      const onChunk = (d) => { this.buffer = Buffer.concat([this.buffer, d]); this.pumpSetup(); };
      const onClose = () => {
        this.setupWaiters.splice(this.setupWaiters.indexOf(w), 1);
        reject(new AxError(Codes.DESKTOP_DRIVER_UNAVAILABLE, "X11 connection closed during handshake"));
      };
      this.socket.on("data", onChunk);
      this.socket.once("close", onClose);
      w.cleanup = () => { this.socket.off("data", onChunk); this.socket.off("close", onClose); };
      this.pumpSetup();
    });
  }

  pumpSetup() {
    while (this.setupWaiters.length && this.buffer.length >= this.setupWaiters[0].n) {
      const w = this.setupWaiters.shift();
      const out = this.buffer.subarray(0, w.n);
      this.buffer = this.buffer.subarray(w.n);
      w.cleanup?.();
      w.resolve(out);
    }
  }

  /* ------------------------------------------------------- reply routing */

  routeData(chunk) {
    this.buffer = Buffer.concat([this.buffer, chunk]);
    for (;;) {
      if (this.buffer.length < 32) return;
      const first = this.buffer[0];
      if (first === 0) {
        // X error: [0][code][seq][value(4)][minor(2)][major(1)][pad(21)]
        const code = this.buffer[1];
        const seq = this.buffer.readUInt16LE(2);
        const value = this.buffer.readUInt32LE(4);
        const minor = this.buffer.readUInt16LE(8);
        const major = this.buffer[10];
        this.buffer = this.buffer.subarray(32);
        const p = this.pending.get(seq);
        if (p) {
          this.pending.delete(seq);
          p.reject(new AxError(Codes.DESKTOP_OP_FAILED,
            `X11 ${describeXError(code)} on request ${major}.${minor} (value ${value})`, { retry: "retry" }));
        }
        continue;
      }
      if (first === 1) {
        const seq = this.buffer.readUInt16LE(2);
        const extra = this.buffer.readUInt32LE(4) * 4;
        const total = 32 + extra;
        if (this.buffer.length < total) return;
        const reply = Buffer.from(this.buffer.subarray(0, total)); // copy: buffer window gets sliced
        this.buffer = this.buffer.subarray(total);
        const p = this.pending.get(seq);
        if (p) {
          this.pending.delete(seq);
          p.resolve(reply);
        }
        continue;
      }
      // Event (2..64): v1 routes nothing — skip one 32-byte frame.
      this.buffer = this.buffer.subarray(32);
    }
  }

  failAll(reason) {
    this.dead = true;
    for (const [, p] of this.pending) p.reject(new AxError(Codes.DESKTOP_OP_FAILED, reason));
    this.pending.clear();
  }

  /** Send a fully-assembled request buffer (length slot at bytes 2..4 is
   *  filled in here from the buffer size). Resolves on the reply when
   *  `wantReply`, else immediately after the write. */
  send(buf, wantReply = false) {
    if (!this.socket || this.dead) {
      return Promise.reject(new AxError(Codes.DESKTOP_OP_FAILED, "X11 connection is not open"));
    }
    if (buf.length % 4 !== 0) throw new Error("X11 request must be 4-byte aligned");
    buf.writeUInt16LE(buf.length / 4, 2);
    // The server numbers EVERY request (replies AND no-reply requests);
    // the counter must advance even when we expect nothing back.
    const seq = (this.seq = (this.seq + 1) & 0xffff);
    if (!wantReply) {
      this.socket.write(buf);
      return Promise.resolve();
    }
    return new Promise((resolve, reject) => {
      this.pending.set(seq, { resolve, reject });
      this.socket.write(buf);
    });
  }

  /* ------------------------------------------------------------- requests */

  async queryExtension(name) {
    const n = Buffer.byteLength(name);
    const buf = Buffer.alloc(4 + 4 + n + ((4 - (n % 4)) % 4));
    buf.writeUInt8(Op.QueryExtension, 0);
    buf.writeUInt16LE(2 + (4 + n) / 4, 2);
    buf.writeUInt16LE(n, 4);
    buf.write(name, 8, "latin1");
    const rep = await this.send(buf, true);
    // Field layout verified on the wire (Xorg 1.21 LSB): present BOOL at
    // byte 8, major opcode / first event / first error as single bytes.
    return rep[8] === 1 ? { present: true, majorOpcode: rep[9] } : { present: false, majorOpcode: 0 };
  }

  async internAtom(name) {
    const cached = this.atoms.get(name);
    if (cached) return cached;
    const n = Buffer.byteLength(name);
    const buf = Buffer.alloc(4 + 4 + n + ((4 - (n % 4)) % 4));
    buf.writeUInt8(Op.InternAtom, 0);
    buf.writeUInt8(1, 1); // only if exists
    buf.writeUInt16LE(2 + (4 + n) / 4, 2);
    buf.writeUInt16LE(n, 4);
    buf.write(name, 8, "latin1");
    const rep = await this.send(buf, true);
    const atom = rep.readUInt32LE(8);
    this.atoms.set(name, atom);
    return atom;
  }

  async getProperty(window, name, { longLength = 4096 } = {}) {
    const prop = typeof name === "string" ? await this.internAtom(name) : name;
    if (!prop) {
      // Atom not present (e.g. EWMH atoms without a running window manager):
      // the property cannot exist — report empty rather than BadAtom.
      return { format: 0, typeAtom: 0, bytesAfter: 0, valueLen: 0, value: Buffer.alloc(0) };
    }
    const buf = Buffer.alloc(24);
    buf.writeUInt8(Op.GetProperty, 0);
    buf.writeUInt8(0, 1); // delete = false
    buf.writeUInt16LE(6, 2);
    buf.writeUInt32LE(window, 4);
    buf.writeUInt32LE(prop, 8);
    buf.writeUInt32LE(0, 12); // type = AnyPropertyType
    buf.writeUInt32LE(0, 16); // long-offset
    buf.writeUInt32LE(longLength, 20);
    const rep = await this.send(buf, true);
    return {
      format: rep[1],
      typeAtom: rep.readUInt32LE(8),
      bytesAfter: rep.readUInt32LE(12),
      valueLen: rep.readUInt32LE(16),
      value: rep.subarray(32, 32 + rep.readUInt32LE(16)),
    };
  }

  /** GetProperty value as a CARD32 list (window ids, pids…). */
  async getPropertyU32s(window, name) {
    const { format, value } = await this.getProperty(window, name);
    if (format !== 32) return [];
    const out = [];
    for (let o = 0; o + 4 <= value.length; o += 4) out.push(value.readUInt32LE(o));
    return out;
  }

  async getGeometry(drawable) {
    const buf = Buffer.alloc(8);
    buf.writeUInt8(Op.GetGeometry, 0);
    buf.writeUInt16LE(2, 2);
    buf.writeUInt32LE(drawable, 4);
    const rep = await this.send(buf, true);
    return {
      depth: rep[1],
      root: rep.readUInt32LE(8),
      x: rep.readInt16LE(12),
      y: rep.readInt16LE(14),
      w: rep.readUInt16LE(16),
      h: rep.readUInt16LE(18),
    };
  }

  async queryPointer() {
    const buf = Buffer.alloc(8);
    buf.writeUInt8(Op.QueryPointer, 0);
    buf.writeUInt16LE(2, 2);
    buf.writeUInt32LE(this.rootWindow, 4);
    const rep = await this.send(buf, true);
    return {
      sameScreen: rep[1] === 1,
      child: rep.readUInt32LE(12),
      rootX: rep.readInt16LE(16),
      rootY: rep.readInt16LE(18),
    };
  }

  async warpPointer(x, y) {
    // 24 bytes (length 6): dst-x/dst-y are INT16 per the protocol encoding
    // (verified against Xorg 1.21 — a 28-byte form draws BadLength).
    const buf = Buffer.alloc(24);
    buf.writeUInt8(Op.WarpPointer, 0);
    buf.writeUInt16LE(6, 2);
    buf.writeUInt32LE(NO_WINDOW, 4); // src = None
    buf.writeUInt32LE(this.rootWindow, 8); // dst = root
    buf.writeInt16LE(0, 12); // src x
    buf.writeInt16LE(0, 14); // src y
    buf.writeUInt16LE(0, 16); // src width 0 = whole
    buf.writeUInt16LE(0, 18); // src height
    buf.writeInt16LE(Math.round(x), 20); // dst x
    buf.writeInt16LE(Math.round(y), 22); // dst y
    await this.send(buf);
  }

  /** XTEST FakeInput (36 bytes, length 9): keys use server keycodes, buttons
   *  1-7 (4/5 = wheel up/down, 6/7 = wheel left/right), motion with
   *  detail 0 = absolute rootX/rootY. delay 0 = immediate. */
  async fakeInput({ type, detail = 0, delayMs = 0, x, y } = {}) {
    if (!this.xtestOpcode) throw new AxError(Codes.DESKTOP_OP_FAILED, "XTEST extension not available");
    const buf = Buffer.alloc(36);
    buf.writeUInt8(this.xtestOpcode, 0);
    buf.writeUInt8(2, 1); // FakeInput
    buf.writeUInt8(type, 4);
    buf.writeUInt8(detail, 5);
    buf.writeUInt32LE(delayMs, 8);
    // root (0 = current root) at 12; 8 unused; rootX/rootY at 24/26.
    if (x !== undefined) buf.writeInt16LE(Math.round(x), 24);
    if (y !== undefined) buf.writeInt16LE(Math.round(y), 26);
    await this.send(buf);
  }

  /** ZPixmap grab of the root window (clamped to bounds by the caller).
   *  Returns raw rows + layout facts for the RGB conversion step. */
  async getImage(x, y, w, h) {
    const buf = Buffer.alloc(20); // 5 units: opcode, format, drawable, x/y/w/h, plane-mask
    buf.writeUInt8(Op.GetImage, 0);
    buf.writeUInt8(2, 1); // format = ZPixmap
    buf.writeUInt32LE(this.rootWindow, 4);
    buf.writeInt16LE(Math.round(x), 8);
    buf.writeInt16LE(Math.round(y), 10);
    buf.writeUInt16LE(w, 12);
    buf.writeUInt16LE(h, 14);
    buf.writeUInt32LE(0xffffffff, 16); // plane mask = all
    const rep = await this.send(buf, true);
    const depth = rep[1];
    const data = rep.subarray(32);
    const bitsPerPixel = this.pixmapFormats?.get(depth) ?? (depth >= 24 ? 32 : depth);
    const bytesPerPixel = Math.max(1, bitsPerPixel / 8);
    const stride = Math.ceil((w * bytesPerPixel) / 4) * 4;
    return { depth, bytesPerPixel, stride, w, h, data, byteOrder: this.imageByteOrder };
  }

  /** Fill keysym → {keycode, shift} from the server keyboard map. Servers
   *  whose keyboard is fully owned by XKB (Xvfb, some minimal setups) answer
   *  the core query with an empty map — then fall back to the static evdev
   *  table (X keycode = Linux KEY_* + 8, stable across distros). */
  async loadKeyboardMap() {
    const count = this.maxKeycode - this.minKeycode + 1;
    if (count > 0) {
      const buf = Buffer.alloc(8);
      buf.writeUInt8(Op.GetKeyboardMapping, 0);
      buf.writeUInt8(this.minKeycode, 1);
      buf.writeUInt16LE(2, 2);
      buf.writeUInt8(count, 4);
      const rep = await this.send(buf, true);
      const perKeycode = rep[1] || 2;
      const nKeysyms = rep.readUInt32LE(4); // reply length in CARD32 units
      this.keysymToKey.clear();
      for (let k = 0; k < count; k++) {
        for (let col = 0; col < perKeycode; col++) {
          const idx = k * perKeycode + col;
          if (idx >= nKeysyms) break;
          const keysym = rep.readUInt32LE(32 + idx * 4);
          if (!keysym) continue;
          // Column parity encodes Shift on the primary group; register the
          // first mapping for each keysym (group-2 columns only add).
          if (!this.keysymToKey.has(keysym)) {
            this.keysymToKey.set(keysym, { keycode: this.minKeycode + k, shift: col % 2 === 1 });
          }
        }
      }
      if (this.keysymToKey.size > 0) return this.keysymToKey.size;
    }
    this.applyEvdevMap();
    return this.keysymToKey.size;
  }

  /** The static evdev/XKB fallback map: [keysym, keycode, needsShift]. */
  applyEvdevMap() {
    this.keysymToKey.clear();
    for (const [keysym, keycode, shift] of EVDEV_KEYMAP) {
      this.keysymToKey.set(keysym, { keycode, shift: !!shift });
    }
  }

  keyForKeysym(keysym) {
    return this.keysymToKey.get(keysym) ?? null;
  }

  /** A child window's origin in root coordinates. */
  async translateCoordinates(window) {
    const buf = Buffer.alloc(16);
    buf.writeUInt8(Op.TranslateCoordinates, 0);
    buf.writeUInt16LE(4, 2);
    buf.writeUInt32LE(window, 4);
    buf.writeUInt32LE(this.rootWindow, 8);
    buf.writeInt16LE(0, 12);
    buf.writeInt16LE(0, 14);
    const rep = await this.send(buf, true);
    return { child: rep.readUInt32LE(8), x: rep.readInt16LE(12), y: rep.readInt16LE(14) };
  }

  /** SetInputFocus — the WM-less fallback so XTEST keys have a target. */
  async setInputFocus(window) {
    const buf = Buffer.alloc(12);
    buf.writeUInt8(42, 0); // SetInputFocus
    buf.writeUInt8(1, 1); // revert-to: PointerRoot
    buf.writeUInt16LE(3, 2);
    buf.writeUInt32LE(window, 4);
    buf.writeUInt32LE(0, 8); // CurrentTime
    await this.send(buf);
  }

  /* ------------------------------------------------------------ RandR ---- */

  #randrOpcode = 0;
  #randrConfigTimestamp = 0;

  async randrOpcode() {
    if (this.#randrOpcode === 0) {
      const { present, majorOpcode } = await this.queryExtension("RANDR");
      this.#randrOpcode = present ? majorOpcode : -1;
    }
    return this.#randrOpcode > 0 ? this.#randrOpcode : 0;
  }

  /** Active monitor layout via RandR 1.2 (RRGetScreenResourcesCurrent +
   *  RRGetCrtcInfo + RRGetOutputPrimary). Returns [] without RandR. */
  async getMonitors() {
    const ext = await this.randrOpcode();
    if (!ext) return [];
    try {
      // RRGetScreenResourcesCurrent (minor 25, per randrproto encoding)
      const req = Buffer.alloc(8);
      req.writeUInt8(ext, 0);
      req.writeUInt8(25, 1);
      req.writeUInt16LE(2, 2);
      req.writeUInt32LE(this.rootWindow, 4);
      const res = await this.send(req, true);
      this.#randrConfigTimestamp = res.readUInt32LE(12);
      const numCrtcs = res.readUInt16LE(16);
      const crtcs = [];
      for (let i = 0; i < numCrtcs; i++) {
        crtcs.push(res.readUInt32LE(32 + i * 4));
      }
      // RRGetOutputPrimary (minor 31) → xid
      const pReq = Buffer.alloc(8);
      pReq.writeUInt8(ext, 0);
      pReq.writeUInt8(31, 1);
      pReq.writeUInt16LE(2, 2);
      pReq.writeUInt32LE(this.rootWindow, 4);
      let primary = 0;
      try {
        const p = await this.send(pReq, true);
        primary = p.readUInt32LE(8);
      } catch {}

      const monitors = [];
      for (const crtc of crtcs) {
        // RRGetCrtcInfo (minor 20): reply carries timestamp, x/y/w/h, mode…
        const cReq = Buffer.alloc(12);
        cReq.writeUInt8(ext, 0);
        cReq.writeUInt8(20, 1);
        cReq.writeUInt16LE(3, 2);
        cReq.writeUInt32LE(crtc, 4);
        cReq.writeUInt32LE(this.#randrConfigTimestamp, 8);
        const info = await this.send(cReq, true);
        const mode = info.readUInt32LE(20);
        if (!mode) continue; // disabled crtc
        const numOutputs = info.readUInt16LE(28);
        const firstOutput = numOutputs ? info.readUInt32LE(32) : 0;
        monitors.push({
          x: info.readInt16LE(12),
          y: info.readInt16LE(14),
          w: info.readUInt16LE(16),
          h: info.readUInt16LE(18),
          primary: firstOutput === primary,
        });
      }
      return monitors;
    } catch {
      return []; // RandR shapes vary; the root union stays the source of truth
    }
  }

  /** SendEvent of a format-32 ClientMessage to the root window (EWMH).
   *  44-byte request: SendEvent header (12) + 32-byte event, where the
   *  ClientMessage event packs type(1) format(1) seq(2) window(4)
   *  message-type(4) data.l[5](20) with no pad. */
  async sendClientMessage(window, messageTypeAtom, data = [0, 0, 0, 0, 0]) {
    const buf = Buffer.alloc(44);
    buf.writeUInt8(Op.SendEvent, 0);
    buf.writeUInt8(1, 1); // propagate
    buf.writeUInt16LE(11, 2);
    buf.writeUInt32LE(this.rootWindow, 4); // destination
    buf.writeUInt32LE((1 << 19) | (1 << 20), 8); // SubstructureNotify|SubstructureRedirect
    buf.writeUInt8(33, 12); // ClientMessage
    buf.writeUInt8(32, 13); // format 32
    buf.writeUInt32LE(window, 16);
    buf.writeUInt32LE(messageTypeAtom, 20);
    for (let i = 0; i < 5; i++) buf.writeUInt32LE((data[i] ?? 0) >>> 0, 24 + i * 4);
    await this.send(buf);
  }

  close() {
    this.dead = true;
    this.failAll("X11 client closed");
    this.teardownSocket();
  }
}