@lardexx/arenacode 2.7.0 → 2.9.0

package/src/automation/linux.js

@@ -0,0 +1,809 @@
+'use strict';
+
+// Linux backend: Xlib + XTest through koffi. No xdotool, no wmctrl, no scrot, no
+// ImageMagick: the client talks to the X server itself, which is also what makes it
+// testable (Xvfb gives a real display to move the pointer and read pixels from).
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const zlib = require('node:zlib');
+const { spawn } = require('node:child_process');
+const { lib, fn } = require('./ffi');
+
+const DISPLAY = () => process.env.DISPLAY || ':0';
+
+let dpy = null;
+let screen = 0;
+let rootWindow = 0;
+
+function openDisplay() {
+  if (dpy) return dpy;
+  const display = DISPLAY();
+  if (!/^:?\d|^.*:\d/.test(display)) throw new Error(`no X11 display (DISPLAY=${display})`);
+  const XOpenDisplay = fn('libX11.so.6', 'XOpenDisplay', 'void* XOpenDisplay(const char* name)');
+  if (!XOpenDisplay) throw new Error('libX11 not found');
+  const handle = XOpenDisplay(display);
+  if (!handle) throw new Error(`XOpenDisplay(${display}) failed`);
+  const XDefaultScreen = fn('libX11.so.6', 'XDefaultScreen', 'int XDefaultScreen(void* dpy)');
+  const XRootWindow = fn('libX11.so.6', 'XRootWindow', 'unsigned long XRootWindow(void* dpy, int screen)');
+  dpy = handle;
+  screen = XDefaultScreen(dpy);
+  rootWindow = XRootWindow(dpy, screen);
+  return dpy;
+}
+
+function closeDisplay() {
+  if (!dpy) return;
+  const XCloseDisplay = fn('libX11.so.6', 'XCloseDisplay', 'int XCloseDisplay(void* dpy)');
+  try {
+    if (XCloseDisplay) XCloseDisplay(dpy);
+  } catch {
+    /* ignore */
+  }
+  dpy = null;
+}
+
+const flush = () => {
+  const XFlush = fn('libX11.so.6', 'XFlush', 'int XFlush(void* dpy)');
+  if (XFlush) XFlush(dpy);
+};
+const sync = () => {
+  const XSync = fn('libX11.so.6', 'XSync', 'int XSync(void* dpy, int discard)');
+  if (XSync) XSync(dpy, 0);
+};
+
+function requireX() {
+  openDisplay();
+  const Xtst = lib('libXtst.so.6');
+  if (!Xtst) throw new Error('libXtst not found (install libxtst6): input injection needs XTest');
+}
+
+// --------------------------------------------------------------------- input
+
+const BUTTONS = { left: 1, middle: 2, right: 3 };
+
+function fakeButton(button, down) {
+  const XTestFakeButtonEvent = fn(
+    'libXtst.so.6',
+    'XTestFakeButtonEvent',
+    'int XTestFakeButtonEvent(void* dpy, unsigned int button, bool is_press, unsigned long delay)'
+  );
+  XTestFakeButtonEvent(dpy, button, down, 0);
+  flush();
+}
+
+function moveMouse(x, y) {
+  requireX();
+  const XTestFakeMotionEvent = fn(
+    'libXtst.so.6',
+    'XTestFakeMotionEvent',
+    'int XTestFakeMotionEvent(void* dpy, int screen, int x, int y, unsigned long delay)'
+  );
+  XTestFakeMotionEvent(dpy, screen, Math.round(x), Math.round(y), 0);
+  flush();
+  return { ok: true, x, y };
+}
+
+function click(x, y, { button = 'left', count = 1 } = {}) {
+  requireX();
+  moveMouse(x, y);
+  const b = BUTTONS[button] || 1;
+  for (let i = 0; i < Math.max(1, count); i += 1) {
+    fakeButton(b, true);
+    fakeButton(b, false);
+    if (i + 1 < count) sync();
+  }
+  return { ok: true, x, y, button, count };
+}
+
+function mouseButton(x, y, button, down) {
+  requireX();
+  if (Number.isFinite(x) && Number.isFinite(y)) moveMouse(x, y);
+  fakeButton(BUTTONS[button] || 1, down);
+  return { ok: true, x, y, button };
+}
+
+function drag(x, y, x2, y2) {
+  requireX();
+  moveMouse(x, y);
+  fakeButton(1, true);
+  const steps = 12;
+  for (let i = 1; i <= steps; i += 1) {
+    const nx = Math.round(x + ((x2 - x) * i) / steps);
+    const ny = Math.round(y + ((y2 - y) * i) / steps);
+    const XTestFakeMotionEvent = fn(
+      'libXtst.so.6',
+      'XTestFakeMotionEvent',
+      'int XTestFakeMotionEvent(void* dpy, int screen, int x, int y, unsigned long delay)'
+    );
+    XTestFakeMotionEvent(dpy, screen, nx, ny, 0);
+    flush();
+  }
+  fakeButton(1, false);
+  return { ok: true, from: [x, y], to: [x2, y2] };
+}
+
+function scroll(amount, x = null, y = null) {
+  requireX();
+  if (Number.isFinite(x) && Number.isFinite(y)) moveMouse(x, y);
+  const button = amount > 0 ? 4 : 5;
+  for (let i = 0; i < Math.abs(Math.trunc(amount) || 1); i += 1) {
+    fakeButton(button, true);
+    fakeButton(button, false);
+  }
+  return { ok: true, amount };
+}
+
+// ------------------------------------------------------------------ keyboard
+
+const MOD_KEYSYMS = {
+  ctrl: 'Control_L',
+  control: 'Control_L',
+  alt: 'Alt_L',
+  option: 'Alt_L',
+  shift: 'Shift_L',
+  win: 'Super_L',
+  super: 'Super_L',
+  meta: 'Super_L',
+  cmd: 'Super_L',
+  command: 'Super_L',
+};
+
+const KEY_NAMES = {
+  enter: 'Return',
+  return: 'Return',
+  tab: 'Tab',
+  esc: 'Escape',
+  escape: 'Escape',
+  space: 'space',
+  spacebar: 'space',
+  backspace: 'BackSpace',
+  bs: 'BackSpace',
+  delete: 'Delete',
+  del: 'Delete',
+  insert: 'Insert',
+  ins: 'Insert',
+  home: 'Home',
+  end: 'End',
+  pageup: 'Page_Up',
+  pagedown: 'Page_Down',
+  pgup: 'Page_Up',
+  pgdn: 'Page_Down',
+  up: 'Up',
+  down: 'Down',
+  left: 'Left',
+  right: 'Right',
+  arrowup: 'Up',
+  arrowdown: 'Down',
+  arrowleft: 'Left',
+  arrowright: 'Right',
+  capslock: 'Caps_Lock',
+  numlock: 'Num_Lock',
+  scrolllock: 'Scroll_Lock',
+  printscreen: 'Print',
+  prtsc: 'Print',
+  pause: 'Pause',
+  menu: 'Menu',
+  contextmenu: 'Menu',
+  apps: 'Menu',
+  plus: 'plus',
+  minus: 'minus',
+  comma: 'comma',
+  period: 'period',
+  slash: 'slash',
+  backslash: 'backslash',
+  semicolon: 'semicolon',
+  quote: 'apostrophe',
+  bracketleft: 'bracketleft',
+  bracketright: 'bracketright',
+  backtick: 'grave',
+  equal: 'equal',
+  numpad0: 'KP_0',
+  numpad1: 'KP_1',
+  numpad2: 'KP_2',
+  numpad3: 'KP_3',
+  numpad4: 'KP_4',
+  numpad5: 'KP_5',
+  numpad6: 'KP_6',
+  numpad7: 'KP_7',
+  numpad8: 'KP_8',
+  numpad9: 'KP_9',
+};
+for (let i = 1; i <= 24; i += 1) KEY_NAMES[`f${i}`] = `F${i}`;
+
+const keysymOf = (name) => {
+  const XStringToKeysym = fn('libX11.so.6', 'XStringToKeysym', 'unsigned long XStringToKeysym(const char* name)');
+  return Number(XStringToKeysym(name)) || 0;
+};
+
+const keycodeOf = (keysym) => {
+  const XKeysymToKeycode = fn('libX11.so.6', 'XKeysymToKeycode', 'unsigned char XKeysymToKeycode(void* dpy, unsigned long keysym)');
+  return Number(XKeysymToKeycode(dpy, keysym)) || 0;
+};
+
+function fakeKey(keycode, down) {
+  const XTestFakeKeyEvent = fn(
+    'libXtst.so.6',
+    'XTestFakeKeyEvent',
+    'int XTestFakeKeyEvent(void* dpy, unsigned int keycode, bool is_press, unsigned long delay)'
+  );
+  XTestFakeKeyEvent(dpy, keycode, down, 0);
+  flush();
+}
+
+/** Does this keysym sit in the shifted column of its keycode? */
+function needsShift(keysym, keycode) {
+  const XGetKeyboardMapping = fn(
+    'libX11.so.6',
+    'XGetKeyboardMapping',
+    'unsigned long* XGetKeyboardMapping(void* dpy, unsigned char first_keycode, int keycode_count, int* keysyms_per_keycode)'
+  );
+  const XFree = fn('libX11.so.6', 'XFree', 'int XFree(void* data)');
+  const per = [0];
+  const ptr = XGetKeyboardMapping(dpy, keycode, 1, per);
+  if (!ptr) return false;
+  let shifted = false;
+  try {
+    const count = per[0] || 1;
+    const koffi = require('koffi');
+    const arr = koffi.decode(ptr, koffi.array('unsigned long', count));
+    if (Number(arr[0]) !== keysym && Number(arr[1]) === keysym) shifted = true;
+  } catch {
+    shifted = false;
+  }
+  if (XFree) XFree(ptr);
+  return shifted;
+}
+
+let spareKeycode = 0;
+let restoreTimer = null;
+
+/** Gives the borrowed keycode back to the keymap (NoSymbol). */
+function releaseKeycode() {
+  restoreTimer = null;
+  if (!spareKeycode || !dpy) return;
+  const koffi = require('koffi');
+  const XChangeKeyboardMapping = fn(
+    'libX11.so.6',
+    'XChangeKeyboardMapping',
+    'int XChangeKeyboardMapping(void* dpy, int first_keycode, int keysyms_per_keycode, unsigned long* keysyms, int num_codes)'
+  );
+  const empty = koffi.alloc('unsigned long', 2);
+  koffi.encode(empty, koffi.array('unsigned long', 2), [0, 0]);
+  XChangeKeyboardMapping(dpy, spareKeycode, 2, empty, 1);
+  sync();
+}
+
+function unicodeKeycode(codepoint) {
+  // Borrow an unused keycode, map it to the character, press it, give it back.
+  const koffi = require('koffi');
+  const XDisplayKeycodes = fn('libX11.so.6', 'XDisplayKeycodes', 'int XDisplayKeycodes(void* dpy, _Out_ int* min, _Out_ int* max)');
+  const XChangeKeyboardMapping = fn(
+    'libX11.so.6',
+    'XChangeKeyboardMapping',
+    'int XChangeKeyboardMapping(void* dpy, int first_keycode, int keysyms_per_keycode, unsigned long* keysyms, int num_codes)'
+  );
+  if (!spareKeycode) {
+    const min = [0];
+    const max = [0];
+    XDisplayKeycodes(dpy, min, max);
+    // the last keycodes are normally free
+    spareKeycode = Math.max(min[0] || 8, (max[0] || min[0] + 1) - 1);
+    if (process.env.ARENACODE_DEBUG_X) console.error('keycodes', min[0], max[0], 'spare', spareKeycode);
+  }
+  const syms = koffi.alloc('unsigned long', 2);
+  koffi.encode(syms, koffi.array('unsigned long', 2), [codepoint, codepoint]);
+  if (restoreTimer) {
+    clearTimeout(restoreTimer);
+    restoreTimer = null;
+    releaseKeycode();
+  }
+  XChangeKeyboardMapping(dpy, spareKeycode, 2, syms, 1);
+  sync();
+  fakeKey(spareKeycode, true);
+  fakeKey(spareKeycode, false);
+  sync();
+  // The target translates the event when it receives it, slightly after this request
+  // was queued: keep the character mapped for a moment, then give the keycode back.
+  if (process.env.ARENACODE_KEEP_KEYMAP !== '1') {
+    restoreTimer = setTimeout(releaseKeycode, 60);
+    if (restoreTimer.unref) restoreTimer.unref();
+  }
+  return spareKeycode;
+}
+
+function typeText(text, x = null, y = null) {
+  requireX();
+  if (x !== null && y !== null) {
+    moveMouse(x, y);
+    click(x, y);
+  }
+  const value = String(text || '');
+  let typed = 0;
+  for (const ch of value) {
+    if (ch === '\n' || ch === '\r') {
+      pressKeys('enter');
+      typed += 1;
+      continue;
+    }
+    const code = ch.codePointAt(0);
+    if (code >= 0x100) {
+      unicodeKeycode(code);
+      typed += 1;
+      continue;
+    }
+    const keysym = code;
+    const keycode = keycodeOf(keysym);
+    if (!keycode) {
+      unicodeKeycode(code);
+      typed += 1;
+      continue;
+    }
+    const shift = needsShift(keysym, keycode);
+    const shiftKey = shift ? keycodeOf(keysymOf('Shift_L')) : 0;
+    if (shiftKey) fakeKey(shiftKey, true);
+    fakeKey(keycode, true);
+    fakeKey(keycode, false);
+    if (shiftKey) fakeKey(shiftKey, false);
+    typed += 1;
+  }
+  sync();
+  return { ok: true, chars: value.length, typed };
+}
+
+function pressKeys(combo) {
+  requireX();
+  const parts = String(combo || '')
+    .toLowerCase()
+    .split('+')
+    .map((p) => p.trim())
+    .filter(Boolean);
+  if (!parts.length) return { ok: false, error: `unreadable key combination: ${combo}` };
+  let repeat = 1;
+  const mods = [];
+  const keys = [];
+  for (const part of parts) {
+    if (part === 'repeat') {
+      repeat = 2;
+      continue;
+    }
+    if (/^x\d+$/.test(part)) {
+      repeat = Number(part.slice(1));
+      continue;
+    }
+    const modSym = MOD_KEYSYMS[part];
+    if (modSym) {
+      const kc = keycodeOf(keysymOf(modSym));
+      if (kc) mods.push(kc);
+      continue;
+    }
+    const name = KEY_NAMES[part] || (part.length === 1 ? null : part);
+    const keysym = name ? keysymOf(name) : part.toUpperCase().charCodeAt(0);
+    const kc = keycodeOf(keysym || part.toUpperCase().charCodeAt(0));
+    if (kc) keys.push({ kc, shift: name ? needsShift(keysym, kc) : false });
+  }
+  if (!mods.length && !keys.length) return { ok: false, error: `unreadable key combination: ${combo}` };
+  const shiftKc = keycodeOf(keysymOf('Shift_L'));
+  for (let i = 0; i < Math.min(50, Math.max(1, repeat)); i += 1) {
+    if (!keys.length && mods.length) {
+      const only = mods[mods.length - 1];
+      fakeKey(only, true);
+      fakeKey(only, false);
+      continue;
+    }
+    for (const kc of mods) fakeKey(kc, true);
+    for (const key of keys) {
+      if (key.shift && shiftKc) fakeKey(shiftKc, true);
+      fakeKey(key.kc, true);
+      fakeKey(key.kc, false);
+      if (key.shift && shiftKc) fakeKey(shiftKc, false);
+    }
+    for (const kc of [...mods].reverse()) fakeKey(kc, false);
+  }
+  sync();
+  return { ok: true, keys: combo };
+}
+
+// ------------------------------------------------------------------ windows
+
+function screenSize() {
+  openDisplay();
+  const XDisplayWidth = fn('libX11.so.6', 'XDisplayWidth', 'int XDisplayWidth(void* dpy, int screen)');
+  const XDisplayHeight = fn('libX11.so.6', 'XDisplayHeight', 'int XDisplayHeight(void* dpy, int screen)');
+  return { ok: true, width: XDisplayWidth(dpy, screen), height: XDisplayHeight(dpy, screen) };
+}
+
+function decodeCString(ptr, max = 512, encoding = 'latin1') {
+  const koffi = require('koffi');
+  try {
+    const bytes = koffi.decode(ptr, 'uint8_t', max);
+    return Buffer.from(bytes).toString(encoding).split('\0')[0];
+  } catch {
+    return '';
+  }
+}
+
+function windowName(win) {
+  const XFetchName = fn('libX11.so.6', 'XFetchName', 'int XFetchName(void* dpy, unsigned long win, _Out_ void** name)');
+  const XFree = fn('libX11.so.6', 'XFree', 'int XFree(void* data)');
+  const out = [null];
+  let name = '';
+  if (XFetchName && XFetchName(dpy, win, out) && out[0]) {
+    name = decodeCString(out[0], 512);
+    if (XFree) XFree(out[0]);
+  }
+  if (!name) name = netWmName(win);
+  return name;
+}
+
+function netWmName(win) {
+  const XInternAtom = fn('libX11.so.6', 'XInternAtom', 'unsigned long XInternAtom(void* dpy, const char* name, bool only_if_exists)');
+  const XGetWindowProperty = fn(
+    'libX11.so.6',
+    'XGetWindowProperty',
+    'int XGetWindowProperty(void* dpy, unsigned long win, unsigned long property, long long_offset, long long_length, bool delete, unsigned long req_type, _Out_ unsigned long* actual_type, _Out_ int* actual_format, _Out_ unsigned long* nitems, _Out_ unsigned long* bytes_after, _Out_ void** prop)'
+  );
+  const XFree = fn('libX11.so.6', 'XFree', 'int XFree(void* data)');
+  if (!XGetWindowProperty) return '';
+  const atom = XInternAtom(dpy, '_NET_WM_NAME', false);
+  const utf8 = XInternAtom(dpy, 'UTF8_STRING', false);
+  const type = [0];
+  const format = [0];
+  const nitems = [0];
+  const after = [0];
+  const prop = [null];
+  if (XGetWindowProperty(dpy, win, atom, 0, 1024, false, utf8, type, format, nitems, after, prop) !== 0) return '';
+  if (!prop[0]) return '';
+  const text = decodeCString(prop[0], Math.max(16, Number(nitems[0]) + 1), 'utf8');
+  if (XFree) XFree(prop[0]);
+  return text;
+}
+
+function windows() {
+  openDisplay();
+  const koffi = require('koffi');
+  const XQueryTree = fn(
+    'libX11.so.6',
+    'XQueryTree',
+    'int XQueryTree(void* dpy, unsigned long win, _Out_ unsigned long* root, _Out_ unsigned long* parent, _Out_ void** children, _Out_ unsigned int* nchildren)'
+  );
+  const XGetGeometry = fn(
+    'libX11.so.6',
+    'XGetGeometry',
+    'int XGetGeometry(void* dpy, unsigned long drawable, _Out_ unsigned long* root, _Out_ int* x, _Out_ int* y, _Out_ unsigned int* width, _Out_ unsigned int* height, _Out_ unsigned int* border, _Out_ unsigned int* depth)'
+  );
+  const XTranslateCoordinates = fn(
+    'libX11.so.6',
+    'XTranslateCoordinates',
+    'bool XTranslateCoordinates(void* dpy, unsigned long src, unsigned long dest, int sx, int sy, _Out_ int* dx, _Out_ int* dy, _Out_ unsigned long* child)'
+  );
+  const XFree = fn('libX11.so.6', 'XFree', 'int XFree(void* data)');
+  const wroot = [0];
+  const parent = [0];
+  const children = [null];
+  const count = [0];
+  if (!XQueryTree(dpy, rootWindow, wroot, parent, children, count)) return { ok: true, windows: [] };
+  const list = [];
+  try {
+    const handles = count[0] ? koffi.decode(children[0], koffi.array('unsigned long', count[0])) : [];
+    for (const h of handles) {
+      const win = Number(h);
+      const rr = [0];
+      const gx = [0];
+      const gy = [0];
+      const gw = [0];
+      const gh = [0];
+      const border = [0];
+      const depth = [0];
+      if (!XGetGeometry(dpy, win, rr, gx, gy, gw, gh, border, depth)) continue;
+      if (!gw[0] || !gh[0]) continue;
+      const name = windowName(win);
+      if (!name) continue;
+      const dx = [0];
+      const dy = [0];
+      const child = [0];
+      let x = gx[0];
+      let y = gy[0];
+      if (XTranslateCoordinates(dpy, win, rootWindow, 0, 0, dx, dy, child)) {
+        // XTranslateCoordinates returns the client area: drop the border so the
+        // coordinates match the ones XMoveResizeWindow accepts.
+        x = dx[0] - border[0];
+        y = dy[0] - border[0];
+      }
+      list.push({
+        name,
+        handle: win,
+        hwnd: win,
+        x,
+        y,
+        width: gw[0],
+        height: gh[0],
+        process_id: 0,
+        status: 'normal',
+      });
+    }
+  } finally {
+    if (children[0] && XFree) XFree(children[0]);
+  }
+  return { ok: true, windows: list };
+}
+
+function focusWindow(handle) {
+  openDisplay();
+  const XRaiseWindow = fn('libX11.so.6', 'XRaiseWindow', 'int XRaiseWindow(void* dpy, unsigned long win)');
+  const XSetInputFocus = fn('libX11.so.6', 'XSetInputFocus', 'int XSetInputFocus(void* dpy, unsigned long win, int revert, unsigned long time)');
+  XRaiseWindow(dpy, handle);
+  XSetInputFocus(dpy, handle, 2 /* RevertToParent */, 0 /* CurrentTime */);
+  sync();
+  return { ok: true, name: windowName(handle), handle };
+}
+
+function resizeWindow(handle, x, y, width, height) {
+  openDisplay();
+  const XMoveResizeWindow = fn(
+    'libX11.so.6',
+    'XMoveResizeWindow',
+    'int XMoveResizeWindow(void* dpy, unsigned long win, int x, int y, unsigned int w, unsigned int h)'
+  );
+  XMoveResizeWindow(dpy, handle, x, y, width, height);
+  sync();
+  return { ok: true, name: windowName(handle), x, y, width, height };
+}
+
+// ---------------------------------------------------------------- screenshot
+
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i += 1) {
+    c ^= buf[i];
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  }
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function pngChunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body));
+  return Buffer.concat([len, body, crc]);
+}
+
+function encodePng(rgb, width, height) {
+  const raw = Buffer.alloc((width * 3 + 1) * height);
+  for (let y = 0; y < height; y += 1) {
+    raw[y * (width * 3 + 1)] = 0;
+    rgb.copy(raw, y * (width * 3 + 1) + 1, y * width * 3, (y + 1) * width * 3);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 2;
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    pngChunk('IHDR', ihdr),
+    pngChunk('IDAT', zlib.deflateSync(raw, { level: 6 })),
+    pngChunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+function screenshot(dest) {
+  openDisplay();
+  const XGetImage = fn(
+    'libX11.so.6',
+    'XGetImage',
+    'void* XGetImage(void* dpy, unsigned long drawable, int x, int y, unsigned int width, unsigned int height, unsigned long plane_mask, int format)'
+  );
+  const XGetPixel = fn('libX11.so.6', 'XGetPixel', 'unsigned long XGetPixel(void* image, int x, int y)');
+  const XDestroyImage = fn('libX11.so.6', 'XDestroyImage', 'int XDestroyImage(void* image)');
+  const size = screenSize();
+  const image = XGetImage(dpy, rootWindow, 0, 0, size.width, size.height, 0xffffffff, 2 /* ZPixmap */);
+  if (!image) return { ok: false, error: 'XGetImage failed' };
+  const rgb = Buffer.alloc(size.width * size.height * 3);
+  try {
+    for (let y = 0; y < size.height; y += 1) {
+      for (let x = 0; x < size.width; x += 1) {
+        const pixel = Number(XGetPixel(image, x, y));
+        const o = (y * size.width + x) * 3;
+        rgb[o] = (pixel >> 16) & 0xff;
+        rgb[o + 1] = (pixel >> 8) & 0xff;
+        rgb[o + 2] = pixel & 0xff;
+      }
+    }
+  } finally {
+    if (XDestroyImage) XDestroyImage(image);
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, encodePng(rgb, size.width, size.height));
+  return { ok: true, file: dest, width: size.width, height: size.height, mime: 'image/png' };
+}
+
+// -------------------------------------------------------------------- misc
+
+function pointer() {
+  openDisplay();
+  const koffi = require('koffi');
+  const XQueryPointer = fn(
+    'libX11.so.6',
+    'XQueryPointer',
+    'bool XQueryPointer(void* dpy, unsigned long win, _Out_ unsigned long* root, _Out_ unsigned long* child, _Out_ int* rx, _Out_ int* ry, _Out_ int* wx, _Out_ int* wy, _Out_ unsigned int* mask)'
+  );
+  const r = [0];
+  const c = [0];
+  const rx = [0];
+  const ry = [0];
+  const wx = [0];
+  const wy = [0];
+  const mask = [0];
+  XQueryPointer(dpy, rootWindow, r, c, rx, ry, wx, wy, mask);
+  return { x: rx[0], y: ry[0], mask: mask[0] };
+}
+
+function launchApp(name) {
+  const command = String(name || '');
+  if (!command) return { ok: false, error: 'app name required' };
+  const child = spawn(command, [], { detached: true, stdio: 'ignore', shell: false });
+  child.on('error', () => {});
+  child.unref();
+  return { ok: true, app: command };
+}
+
+function listApps() {
+  const dirs = [
+    '/usr/share/applications',
+    '/usr/local/share/applications',
+    path.join(os.homedir(), '.local/share/applications'),
+  ];
+  const out = [];
+  for (const dir of dirs) {
+    let files = [];
+    try {
+      files = fs.readdirSync(dir).filter((f) => f.endsWith('.desktop'));
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      try {
+        const text = fs.readFileSync(path.join(dir, file), 'utf8');
+        if (/^NoDisplay=true/m.test(text)) continue;
+        const name = /^Name=(.+)$/m.exec(text);
+        if (name) out.push({ name: name[1].trim(), app_id: file.replace(/\.desktop$/, '') });
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return { ok: true, apps: out };
+}
+
+function activeWindow() {
+  openDisplay();
+  const XGetInputFocus = fn(
+    'libX11.so.6',
+    'XGetInputFocus',
+    'int XGetInputFocus(void* dpy, _Out_ unsigned long* focus, _Out_ int* revert)'
+  );
+  const focus = [0];
+  const revert = [0];
+  if (!XGetInputFocus(dpy, focus, revert)) return { ok: true, name: '', handle: null };
+  const handle = Number(focus[0]);
+  if (!handle || handle === 1) return { ok: true, name: '', handle: null }; // None / PointerRoot
+  return { ok: true, name: windowName(handle), handle };
+}
+
+/** The closest thing to windows-use's desktop state that X11 can answer natively. */
+function state(handle = null) {
+  const wins = windows();
+  const size = screenSize();
+  const active = activeWindow();
+  const list = wins.ok ? wins.windows : [];
+  const focused = handle || (active.ok ? active.handle : null);
+  const elements = list
+    .filter((w) => !focused || w.handle === focused)
+    .map((w) => ({
+      name: w.name,
+      control_type: 'Window',
+      kind: 'Window',
+      bounding_box: { left: w.x, top: w.y, right: w.x + w.width, bottom: w.y + w.height },
+      center: { x: w.x + Math.floor(w.width / 2), y: w.y + Math.floor(w.height / 2) },
+      value: '',
+      enabled: true,
+      automation_id: '',
+    }));
+  return {
+    ok: true,
+    windows: list,
+    active_window: active.ok && active.handle ? list.find((w) => w.handle === active.handle) || { name: active.name, handle: active.handle } : null,
+    interactive_elements: elements,
+    scrollable_elements: [],
+    interactive_elements_text: elements
+      .map((e, i) => `${i + 1}. ${e.control_type} '${e.name}' at (${e.center.x}, ${e.center.y})`)
+      .join('\n'),
+    scrollable_elements_text: '',
+    tree_status: 'x11',
+    system: {
+      windows_version: `${process.platform} ${os.release()}`,
+      os_version: os.release(),
+      screen_size: { width: size.width, height: size.height },
+      user_account_type: 'Local Account',
+      default_language: process.env.LANG || 'en',
+      dpi_scaling: 1,
+    },
+    metadata: { depth: 'top-level', kind: 'windows-list', all_desktops: false },
+  };
+}
+
+function available() {
+  try {
+    const size = screenSize();
+    return { ok: true, backend: 'linux', detail: 'X11 via FFI (Xlib + XTest)', screen: size };
+  } catch (err) {
+    return { ok: false, backend: 'linux', error: err.message };
+  }
+}
+
+function sysinfo() {
+  const size = screenSize();
+  return {
+    ok: true,
+    system: {
+      windows_version: `${process.platform} ${os.release()}`,
+      os_version: os.release(),
+      screen_size: { width: size.width, height: size.height },
+      user_account_type: 'Local Account',
+      default_language: process.env.LANG || 'en',
+      dpi_scaling: 1,
+    },
+  };
+}
+
+const backend = {
+  name: 'x11-ffi',
+  available,
+  screenSize,
+  windows,
+  activeWindow,
+  state,
+  moveMouse,
+  click,
+  mouseButton,
+  drag,
+  scroll,
+  typeText,
+  pressKeys,
+  focusWindow,
+  resizeWindow,
+  screenshot,
+  launchApp,
+  listApps,
+  sysinfo,
+};
+
+module.exports = {
+  backend,
+  activeWindow,
+  state,
+  available,
+  sysinfo,
+  openDisplay,
+  closeDisplay,
+  screenSize,
+  moveMouse,
+  click,
+  mouseButton,
+  drag,
+  scroll,
+  typeText,
+  pressKeys,
+  windows,
+  focusWindow,
+  resizeWindow,
+  screenshot,
+  pointer,
+  launchApp,
+  listApps,
+  encodePng,
+};