@hienlh/ppm 0.21.0 → 0.22.0

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

@@ -17,46 +17,119 @@
  *   `-pix_fmt` request leak into the device negotiation logs a warning per open.
  * - A missing Screen Recording grant does NOT fail the spawn — macOS hands the process black
  *   frames instead; that is surfaced client-side by the "real frame" check, not here.
+ *
+ * X11 (`x11grab`) notes:
+ * - The grabber honours `-framerate` (unlike avfoundation), so it keeps gdigrab's plain filter.
+ * - X11 gives every monitor one root-window coordinate space, so capturing a single monitor is
+ *   a crop: `-video_size WxH -i :0.0+X,Y`. Without the offsets you get the union of all
+ *   monitors, which on a two-screen host is a letterboxed image of both.
+ * - `-draw_mouse` defaults to 1, but it is passed explicitly: it is the one thing that makes a
+ *   remote session usable and it should not silently change with an ffmpeg default. It is also
+ *   the only cursor control there is — the pointer is burned into the frames at *capture* time,
+ *   so turning it off is a respawn, never a client-side decision.
+ * - The spawn needs `DISPLAY`/`XAUTHORITY` in its env — see `remote-desktop-linux-session.ts`
+ *   for why the PPM process usually does not have them itself.
  */
-import { CAPTURE_FRAMERATE } from "./remote-desktop-encoder-args.ts";
+import { DEFAULT_FPS, type QualityPreset } from "./remote-desktop-quality.ts";
+import { VAAPI_UPLOAD_FILTER } from "../media-transcode/ffmpeg-capabilities.ts";
+import { detectLinuxSession, type LinuxSession } from "./remote-desktop-linux-session.ts";
+
+/** The region to grab, in the OS's global coordinate space. null = the backend's whole surface. */
+export interface CaptureRect { x: number; y: number; width: number; height: number }
 
 export type CaptureInput =
   | { kind: "gdigrab" }
-  | { kind: "avfoundation"; screen: string };
+  | { kind: "avfoundation"; screen: string }
+  | { kind: "x11grab"; display: string; rect: CaptureRect | null };
 
 /** avfoundation's name for the N-th display in `CGGetActiveDisplayList` order (0 = main). */
 export function avfoundationScreenName(captureIndex: number): string {
   return `Capture screen ${captureIndex}`;
 }
 
-/** ffmpeg args from `-f <grabber>` through `-i <source>` for the given input. */
-export function captureInputArgs(input: CaptureInput): string[] {
+/** x11grab's source string: `:<display>.<screen>+<x>,<y>`. The screen number is only appended
+ *  when the display string does not already carry one — `DISPLAY` is normally `:0`, but a
+ *  `:0.0` in the environment would otherwise become `:0.0.0` and fail to parse. */
+export function x11GrabSource(display: string, rect: CaptureRect | null): string {
+  const withScreen = display.includes(".") ? display : `${display}.0`;
+  return rect ? `${withScreen}+${rect.x},${rect.y}` : withScreen;
+}
+
+/** ffmpeg args from `-f <grabber>` through `-i <source>` for the given input.
+ *
+ *  `drawMouse` is the host pointer. All three grabbers draw it by default and each spells the
+ *  flag differently — gdigrab and x11grab take `-draw_mouse`, avfoundation `-capture_cursor` —
+ *  so the one place that knows which grabber is in use is the one that has to translate it. */
+export function captureInputArgs(
+  input: CaptureInput,
+  preset: QualityPreset = { fps: DEFAULT_FPS, bitrate: "1M" },
+  drawMouse = true,
+): string[] {
+  const fps = String(preset.fps);
+  const mouse = drawMouse ? "1" : "0";
   switch (input.kind) {
     case "gdigrab":
-      return ["-f", "gdigrab", "-framerate", String(CAPTURE_FRAMERATE), "-i", "desktop"];
+      return ["-f", "gdigrab", "-draw_mouse", mouse, "-framerate", fps, "-i", "desktop"];
     case "avfoundation":
-      // `-capture_cursor 1` draws the pointer into the frame (gdigrab does so by default).
       return ["-use_wallclock_as_timestamps", "1",
-        "-f", "avfoundation", "-capture_cursor", "1", "-pixel_format", "nv12",
-        "-framerate", String(CAPTURE_FRAMERATE), "-i", input.screen];
+        "-f", "avfoundation", "-capture_cursor", mouse, "-pixel_format", "nv12",
+        "-framerate", fps, "-i", input.screen];
+    case "x11grab":
+      return ["-f", "x11grab", "-draw_mouse", mouse, "-framerate", fps,
+        ...(input.rect ? ["-video_size", `${input.rect.width}x${input.rect.height}`] : []),
+        "-i", x11GrabSource(input.display, input.rect)];
   }
 }
 
-/** `-vf` chain for the given input; the scale step is shared, avfoundation adds the rate cap. */
-export function captureVideoFilter(input: CaptureInput): string {
-  const scale = "scale=-2:720";
-  return input.kind === "avfoundation" ? `fps=${CAPTURE_FRAMERATE},${scale}` : scale;
+/** `-vf` chain for the given input; avfoundation adds the rate cap and VAAPI appends the upload
+ *  to GPU memory that its encoder requires. One `-vf` only: a second occurrence would silently
+ *  replace the first rather than combining.
+ *
+ *  There is **no scale step**. A quality rung sets a bitrate ratio and nothing else — RustDesk's
+ *  image quality never touches the resolution, and measured on a 3440x1440 host the downscale
+ *  this used to do bought almost nothing: 720p used 1.17 Mbit/s against 1.26 Mbit/s for native
+ *  at the same cap, because a desktop is mostly static and H.264 spends bits on *change* rather
+ *  than on area. It cost 4.8x the pixels for 7% of the bandwidth. Dropping the filter also
+ *  removes the upscale hazard it existed to guard against: with no scaling at all, a rung cannot
+ *  ask for more pixels than the host has.
+ *
+ *  Returns an empty string when there is nothing to filter, which the caller must treat as
+ *  "omit `-vf` entirely" — ffmpeg rejects an empty filtergraph argument. */
+export function captureVideoFilter(
+  input: CaptureInput,
+  encoder = "libx264",
+  preset: QualityPreset = { fps: DEFAULT_FPS, bitrate: "1M" },
+): string {
+  const parts: string[] = [];
+  // avfoundation ignores `-framerate` and delivers at display refresh with a stuck pts, so the
+  // cadence has to be imposed here; the other grabbers take it at the input.
+  if (input.kind === "avfoundation") parts.push(`fps=${preset.fps}`);
+  if (encoder === "h264_vaapi") parts.push(VAAPI_UPLOAD_FILTER);
+  return parts.join(",");
 }
 
 /** Pick the capture input for this host; null on platforms without a grabber. Whether the
  *  grabber actually works (ffmpeg built without it, no display) surfaces through ffmpeg's
  *  own exit + stderr tail in `startCapture`, the same way gdigrab failures do.
  *  `captureIndex` selects the display on backends that capture one at a time (avfoundation);
- *  gdigrab always grabs the whole virtual desktop. */
-export function captureInputForPlatform(platform: NodeJS.Platform = process.platform, captureIndex = 0): CaptureInput | null {
+ *  gdigrab always grabs the whole virtual desktop, x11grab crops by `rect`.
+ *
+ *  `opts.session` is passed explicitly by tests so this stays a pure function of its
+ *  arguments: it otherwise probes the host, and "is there an X server" is exactly the thing a
+ *  headless CI runner answers differently from a developer's desktop. */
+export function captureInputForPlatform(
+  platform: NodeJS.Platform = process.platform,
+  captureIndex = 0,
+  opts: { session?: LinuxSession | null; rect?: CaptureRect | null } = {},
+): CaptureInput | null {
   switch (platform) {
     case "win32": return { kind: "gdigrab" };
     case "darwin": return { kind: "avfoundation", screen: avfoundationScreenName(captureIndex) };
+    case "linux": {
+      const session = "session" in opts ? opts.session : detectLinuxSession();
+      if (session?.kind !== "x11") return null;
+      return { kind: "x11grab", display: session.display, rect: opts.rect ?? null };
+    }
     default: return null;
   }
 }

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

@@ -10,11 +10,14 @@
  * the in-flight `reader.read()` then resolves with `done: true` and the pump loop exits on
  * its own — it is never cancelled from outside.
  */
-import { getFfmpegCapabilities } from "../media-transcode/ffmpeg-capabilities.ts";
+import { encoderDeviceArgs, getFfmpegCapabilities } from "../media-transcode/ffmpeg-capabilities.ts";
 import { captureEncoderArgs } from "./remote-desktop-encoder-args.ts";
 import {
-  captureInputArgs, captureVideoFilter, captureInputForPlatform, type CaptureInput,
+  captureInputArgs, captureVideoFilter, captureInputForPlatform,
+  type CaptureInput, type CaptureRect,
 } from "./remote-desktop-capture-input.ts";
+import { detectLinuxSession, linuxSessionEnv } from "./remote-desktop-linux-session.ts";
+import { DEFAULT_FPS, type QualityPreset } from "./remote-desktop-quality.ts";
 import { AccessUnitAssembler, type AccessUnit } from "./access-unit-assembler.ts";
 import type { RemoteDisplay } from "./remote-desktop-displays.ts";
 
@@ -34,18 +37,28 @@ export function buildCaptureArgs(
   ffmpeg: string,
   encoder: string = "libx264",
   input: CaptureInput = { kind: "gdigrab" },
+  preset: QualityPreset = { fps: DEFAULT_FPS, bitrate: "1M" },
+  drawMouse = true,
 ): string[] {
   return [
     ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin",
     "-fflags", "nobuffer", "-flags", "low_delay",
-    ...captureInputArgs(input),
-    "-vf", captureVideoFilter(input),
-    ...captureEncoderArgs(encoder),
+    // VAAPI opens its DRM device during input setup, so this has to precede `-i`.
+    ...encoderDeviceArgs(encoder),
+    ...captureInputArgs(input, preset, drawMouse),
+    // Spread rather than a fixed pair: with no scale step a software encoder on x11grab/gdigrab
+    // has nothing left to filter, and ffmpeg rejects `-vf ""` outright rather than ignoring it.
+    ...withVideoFilter(captureVideoFilter(input, encoder, preset)),
+    ...captureEncoderArgs(encoder, preset),
     "-flush_packets", "1",
     "-f", "h264", "pipe:1",
   ];
 }
 
+function withVideoFilter(filter: string): string[] {
+  return filter ? ["-vf", filter] : [];
+}
+
 export interface CaptureHandle {
   /** SPS bytes cached from the stream (for the avc1 codec string), null before the encoder's
    *  first keyframe has been parsed. */
@@ -59,6 +72,15 @@ export interface CaptureHandle {
 export interface StartCaptureOptions {
   /** Which display to grab; null/undefined = the platform default (primary / whole desktop). */
   display?: RemoteDisplay | null;
+  /** Resolution/frame-rate/bitrate rung; defaults to the balanced preset. */
+  preset?: QualityPreset;
+  /** Draw the host pointer into the frames. Defaults to true, and can only be changed by
+   *  respawning: every grabber takes it as a startup flag. */
+  drawMouse?: boolean;
+  /** H.264 encoder to use, overriding the capability probe's first choice. Must be one that
+   *  `workingEncoders()` reported: an encoder this build/GPU cannot run makes ffmpeg exit at
+   *  once, which the session then reports as "Capture failed". */
+  encoder?: string;
   onAccessUnit: (au: AccessUnit) => void;
   /** Called once the process exits, whether via `stop()` or on its own (crash/killed
    *  externally) — lets the session registry clean up without polling. `reason` is a short
@@ -73,13 +95,24 @@ export interface StartCaptureOptions {
 export async function startCapture(opts: StartCaptureOptions): Promise<CaptureHandle> {
   const caps = await getFfmpegCapabilities();
   if (!caps.ffmpeg) throw new CaptureUnavailableError();
-  const input = captureInputForPlatform(process.platform, opts.display?.captureIndex ?? 0);
+  // Linux only: the grabber is chosen by session type, and ffmpeg is handed the session's
+  // DISPLAY/XAUTHORITY because the PPM process very often has neither of its own.
+  const session = process.platform === "linux" ? detectLinuxSession() : null;
+  const d = opts.display;
+  const rect: CaptureRect | null =
+    d && d.width > 0 && d.height > 0 ? { x: d.x, y: d.y, width: d.width, height: d.height } : null;
+  const input = captureInputForPlatform(process.platform, d?.captureIndex ?? 0, { session, rect });
   if (!input) throw new CaptureUnavailableError(`no screen capture input on ${process.platform}`);
 
-  const proc = Bun.spawn(buildCaptureArgs(caps.ffmpeg, caps.encoder ?? "libx264", input), {
+  const argv = buildCaptureArgs(
+    caps.ffmpeg, opts.encoder ?? caps.encoder ?? "libx264", input, opts.preset,
+    opts.drawMouse ?? true,
+  );
+  const proc = Bun.spawn(argv, {
     stdout: "pipe",
     stderr: "pipe",
     stdin: "ignore",
+    ...(session ? { env: { ...process.env, ...linuxSessionEnv(session) } } : {}),
   });
 
   let stopped = false;

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

@@ -0,0 +1,166 @@
+/**
+ * Read and write the *host's* clipboard for the remote-desktop session.
+ *
+ * Shelling out rather than talking X11/Win32 directly, because owning a selection is not a
+ * one-shot call: an X11 clipboard owner has to stay alive answering `SelectionRequest` events
+ * for as long as it holds the selection, which means an event pump for the lifetime of the
+ * copy. `xclip`/`wl-copy` already fork a helper that does exactly that, so the cost of this
+ * choice is one package the host may not have — surfaced as `clipboardTool() === null` and
+ * an install command, never as a silent no-op (this dev host has *none* of xclip/xsel/wl-copy
+ * while running a perfectly good X11 desktop, which is the same trap as `xrandr` the binary).
+ *
+ * Everything is text/plain. Images are deliberately out of scope: they would need a second
+ * transport and the browser half only accepts them in a secure context anyway.
+ */
+import { existsSync } from "node:fs";
+import { detectLinuxSession, linuxSessionEnv, type LinuxSession } from "./remote-desktop-linux-session.ts";
+
+/** A paste is a paste, not a file transfer. 64 KiB is far more than any realistic snippet and
+ *  bounds both the WS message and the argv/stdin handed to a helper process. */
+export const MAX_CLIPBOARD_CHARS = 64 * 1024;
+/** A clipboard helper that hangs (no selection owner, a wedged compositor) must not hang the
+ *  session's message loop, which is awaited per WS message. */
+const CLIPBOARD_TIMEOUT_MS = 2_000;
+
+export interface ClipboardTool {
+  /** Reads text/plain from the clipboard on stdout. */
+  read: string[];
+  /** Writes stdin to the clipboard. */
+  write: string[];
+  /** Both sides are base64 so no console code page can mangle non-ASCII (Windows). */
+  base64: boolean;
+  /** The package to install when this host has no tool at all. */
+  install?: string;
+}
+
+/** PowerShell's `Get-Clipboard`/`Set-Clipboard` go through stdout/stdin, whose encoding follows
+ *  the console code page — so the text is base64'd on both sides rather than trusting it.
+ *  `-Raw` keeps a multi-line clipboard as one string, and the `$null` guard is needed because
+ *  an empty clipboard makes `GetBytes` throw rather than return nothing. */
+const WIN_READ = "$t = Get-Clipboard -Raw; if ($null -eq $t) { '' } else "
+  + "{ [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($t)) }";
+const WIN_WRITE = "Set-Clipboard -Value "
+  + "([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String([Console]::In.ReadToEnd())))";
+
+/** Which helper this host has, or null. Linux is by session type: `wl-copy` talks to the
+ *  compositor and `xclip`/`xsel` to the X server, and on a Wayland session the X pair would
+ *  address XWayland's own clipboard — a different clipboard from the one the user sees. */
+export function clipboardTool(
+  platform: NodeJS.Platform = process.platform,
+  session: LinuxSession | null = platform === "linux" ? detectLinuxSession() : null,
+): ClipboardTool | null {
+  if (platform === "darwin") {
+    return { read: ["pbpaste"], write: ["pbcopy"], base64: false };
+  }
+  if (platform === "win32") {
+    const pwsh = ["powershell", "-NoProfile", "-NonInteractive", "-Command"];
+    return { read: [...pwsh, WIN_READ], write: [...pwsh, WIN_WRITE], base64: true };
+  }
+  if (platform !== "linux" || !session) return null;
+  if (session.kind === "wayland") {
+    return has("wl-copy") && has("wl-paste")
+      ? { read: ["wl-paste", "--no-newline", "--type", "text/plain"], write: ["wl-copy"], base64: false, install: "wl-clipboard" }
+      : { read: [], write: [], base64: false, install: "wl-clipboard" };
+  }
+  if (has("xclip")) {
+    return {
+      read: ["xclip", "-selection", "clipboard", "-o"],
+      write: ["xclip", "-selection", "clipboard", "-i"],
+      base64: false,
+      install: "xclip",
+    };
+  }
+  if (has("xsel")) {
+    return {
+      read: ["xsel", "--clipboard", "--output"],
+      write: ["xsel", "--clipboard", "--input"],
+      base64: false,
+      install: "xsel",
+    };
+  }
+  return { read: [], write: [], base64: false, install: "xclip" };
+}
+
+/** `Bun.which` also finds a shell builtin/alias shape; an explicit PATH walk is enough here and
+ *  keeps the tool list assertable in a test without a real binary. */
+function has(bin: string): boolean {
+  return (process.env.PATH ?? "").split(":").some((dir) => dir && existsSync(`${dir}/${bin}`));
+}
+
+/** True when this host can actually move the clipboard. A tool entry with empty argv means
+ *  "this is the tool you want, it is not installed" — that is what carries `install` to the UI. */
+export function clipboardAvailable(tool: ClipboardTool | null = clipboardTool()): boolean {
+  return !!tool && tool.read.length > 0 && tool.write.length > 0;
+}
+
+/** Env a Linux helper needs to reach the session (a PPM started by its systemd user unit has
+ *  no `DISPLAY`/`WAYLAND_DISPLAY` at all — same reason ffmpeg is spawned with this). */
+function spawnEnv(session: LinuxSession | null): Record<string, string | undefined> {
+  return session ? { ...process.env, ...linuxSessionEnv(session) } : process.env;
+}
+
+/** The host clipboard as text, or null when there is no tool, it failed, or it holds no text
+ *  (an image-only clipboard reads as empty rather than as an error). */
+export async function readHostClipboard(): Promise<string | null> {
+  const session = process.platform === "linux" ? detectLinuxSession() : null;
+  const tool = clipboardTool(process.platform, session);
+  if (!clipboardAvailable(tool)) return null;
+  try {
+    const proc = Bun.spawn(tool!.read, { stdout: "pipe", stderr: "ignore", env: spawnEnv(session) });
+    const out = await withTimeout(new Response(proc.stdout).text(), () => proc.kill());
+    if (out === null) return null;
+    // A non-zero exit is normal for an empty clipboard (`xclip` reports no owner), so the exit
+    // code is not treated as failure — an empty read is simply an empty clipboard.
+    const text = tool!.base64 ? decodeBase64(out.trim()) : out;
+    return text === null || text.length === 0 ? null : text.slice(0, MAX_CLIPBOARD_CHARS);
+  } catch {
+    return null;
+  }
+}
+
+/** Put `text` on the host clipboard. Returns whether it landed. */
+export async function writeHostClipboard(text: string): Promise<boolean> {
+  if (text.length === 0 || text.length > MAX_CLIPBOARD_CHARS) return false;
+  const session = process.platform === "linux" ? detectLinuxSession() : null;
+  const tool = clipboardTool(process.platform, session);
+  if (!clipboardAvailable(tool)) return false;
+  try {
+    const payload = tool!.base64 ? Buffer.from(text, "utf8").toString("base64") : text;
+    const proc = Bun.spawn(tool!.write, {
+      stdin: new TextEncoder().encode(payload),
+      stdout: "ignore",
+      stderr: "ignore",
+      env: spawnEnv(session),
+    });
+    // `xclip -i`/`wl-copy` fork a helper that keeps owning the selection and the parent exits
+    // straight away, so this waits on the parent only — by design, not by accident.
+    const code = await withTimeout(proc.exited, () => proc.kill());
+    return code === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Resolve `p`, or run `onTimeout` and give null, so one wedged helper cannot stall the session. */
+async function withTimeout<T>(p: Promise<T>, onTimeout: () => void): Promise<T | null> {
+  const timeout = Bun.sleep(CLIPBOARD_TIMEOUT_MS).then(() => null);
+  const result = await Promise.race([p, timeout]);
+  if (result === null) { try { onTimeout(); } catch { /* already gone */ } }
+  return result as T | null;
+}
+
+/** The keys to press so the host pastes, as `KeyboardEvent.code`s to press in order (and
+ *  release in reverse).
+ *
+ *  `shift` is not cosmetic: a terminal pastes on Ctrl+**Shift**+V and reads a plain Ctrl+V as
+ *  the literal quoted-insert control code, so answering every paste with Ctrl+V would insert
+ *  `^V` into every remote shell. The client sends what the user actually pressed. */
+export function pasteComboCodes(platform: NodeJS.Platform, shift: boolean): string[] {
+  const mod = platform === "darwin" ? "MetaLeft" : "ControlLeft";
+  return shift ? [mod, "ShiftLeft", "KeyV"] : [mod, "KeyV"];
+}
+
+function decodeBase64(b64: string): string | null {
+  if (b64.length === 0) return "";
+  try { return Buffer.from(b64, "base64").toString("utf8"); } catch { return null; }
+}

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

@@ -11,8 +11,21 @@
  *
  * Windows: gdigrab `desktop` grabs the whole virtual screen and SendInput maps 0..65535 onto
  * that same rectangle, so there is exactly one "display" and no offsets to apply.
+ *
+ * X11: monitors come from RandR 1.5 `XRRGetMonitors` through FFI, NOT from parsing `xrandr`.
+ * The binary is a separate package from the library and is genuinely absent on hosts that have
+ * the library (verified: this dev host has `libXrandr.so.2` and no `xrandr`), so a shell-out
+ * reports "no displays" on a working desktop. X11 puts every monitor in one root-window
+ * coordinate space — the same model as the Windows virtual desktop — so `x`/`y` are real
+ * offsets and a per-monitor capture is a crop of the root window, not a separate device.
+ *
+ * Wayland: deliberately empty. There is no client-side monitor list to offer — the desktop
+ * portal's own dialog is what picks the screen, and its answer arrives as a PipeWire node.
  */
 
+import { detectLinuxSession, type LinuxSession } from "./remote-desktop-linux-session.ts";
+import { asPointer, getX11 } from "./remote-desktop-x11.ts";
+
 export interface RemoteDisplay {
   /** Stable per host session (`CGDirectDisplayID` on macOS, `"desktop"` on Windows). */
   id: string;
@@ -30,6 +43,56 @@ export interface RemoteDisplay {
 const CACHE_MS = 5000;
 let cache: { at: number; displays: RemoteDisplay[] } | null = null;
 
+/** `XRRMonitorInfo` on x86-64: `Atom name` (8), `Bool primary` (4), `Bool automatic` (4),
+ *  `int noutput` (4), `int x, y, width, height` (16), `int mwidth, mheight` (8), then a
+ *  pointer that forces the trailing 4 bytes of padding. Verified against a real 3440x1440
+ *  monitor: reading `primary`/`x`/`y`/`width`/`height` at these offsets returns 1/0/0/3440/1440. */
+const MONITOR_INFO_SIZE = 56;
+const MONITOR_OFF = { name: 0, primary: 8, x: 20, y: 24, width: 28, height: 32 } as const;
+
+async function listX11Displays(session: LinuxSession): Promise<RemoteDisplay[]> {
+  const conn = await getX11(session);
+  if (!conn) return [];
+  const { ffi, x11, xrandr, dpy } = conn;
+
+  /** No libXrandr: one display covering the whole root window, which is what x11grab
+   *  captures by default anyway. */
+  const wholeScreen = (): RemoteDisplay[] => [{
+    id: "screen", label: "Whole screen", primary: true, x: 0, y: 0,
+    width: x11.XDisplayWidth(dpy, conn.screen), height: x11.XDisplayHeight(dpy, conn.screen),
+    captureIndex: 0,
+  }];
+  if (!xrandr) return wholeScreen();
+
+  const countOut = new Int32Array(1);
+  const monitors = xrandr.XRRGetMonitors(dpy, conn.root, 1, ffi.ptr(countOut));
+  const count = countOut[0] ?? 0;
+  if (!monitors || count <= 0) return wholeScreen();
+
+  const displays: RemoteDisplay[] = [];
+  for (let i = 0; i < count; i++) {
+    const base = asPointer(Number(monitors) + i * MONITOR_INFO_SIZE);
+    const namePtr = x11.XGetAtomName(dpy, ffi.read.u64(base, MONITOR_OFF.name));
+    let label = `Display ${i + 1}`;
+    if (namePtr) {
+      label = new ffi.CString(namePtr).toString();
+      x11.XFree(namePtr);
+    }
+    displays.push({
+      id: label,
+      label,
+      primary: ffi.read.i32(base, MONITOR_OFF.primary) !== 0,
+      x: ffi.read.i32(base, MONITOR_OFF.x),
+      y: ffi.read.i32(base, MONITOR_OFF.y),
+      width: ffi.read.i32(base, MONITOR_OFF.width),
+      height: ffi.read.i32(base, MONITOR_OFF.height),
+      captureIndex: i,
+    });
+  }
+  xrandr.XRRFreeMonitors(monitors);
+  return displays.length > 0 ? displays : wholeScreen();
+}
+
 async function listDarwinDisplays(): Promise<RemoteDisplay[]> {
   const { dlopen, FFIType: T, ptr } = await import("bun:ffi");
   const cg = dlopen("/System/Library/Frameworks/CoreGraphics.framework/CoreGraphics", {
@@ -71,10 +134,23 @@ async function listDarwinDisplays(): Promise<RemoteDisplay[]> {
   return displays;
 }
 
-export async function listDisplays(platform: NodeJS.Platform = process.platform): Promise<RemoteDisplay[]> {
+/** `linuxSession` is passed explicitly by tests: it otherwise probes the host, and "is there
+ *  an X server" is exactly what a headless runner answers differently from a desktop. */
+export async function listDisplays(
+  platform: NodeJS.Platform = process.platform,
+  linuxSession = platform === "linux" ? detectLinuxSession() : null,
+): Promise<RemoteDisplay[]> {
   if (platform === "win32") {
     return [{ id: "desktop", label: "All displays", primary: true, x: 0, y: 0, width: 0, height: 0, captureIndex: 0 }];
   }
+  if (platform === "linux") {
+    // Wayland: the portal dialog picks the screen, so there is nothing to list here.
+    if (linuxSession?.kind !== "x11") return [];
+    if (cache && Date.now() - cache.at < CACHE_MS) return cache.displays;
+    const displays = await listX11Displays(linuxSession);
+    cache = { at: Date.now(), displays };
+    return displays;
+  }
   if (platform !== "darwin") return [];
   if (cache && Date.now() - cache.at < CACHE_MS) return cache.displays;
   const displays = await listDarwinDisplays();

package/src/services/remote-desktop/remote-desktop-encoder-args.ts

@@ -10,10 +10,19 @@
  * predictable during development.
  */
 
-/** 30fps + a 1s keyframe interval (30 frames): smoother than 15fps and bounds how long a
- *  dropped/late-joining client waits to resync (see WS backpressure handling). */
-export const CAPTURE_FRAMERATE = 30;
-export const CAPTURE_GOP_FRAMES = 30;
+import { DEFAULT_FPS, type QualityPreset } from "./remote-desktop-quality.ts";
+
+/** Half a second of frames. The GOP is the single lever on "how bad is a hiccup": discarding
+ *  one delta makes every later delta in the GOP undecodable, so the client stares at a frozen
+ *  picture until the next keyframe — measured at 502 ms from a 120 ms backpressure spike while
+ *  this was one full second. Halving it halves that worst case, and costs **no bitrate**:
+ *  measured against a full-motion 3440x1440 source, -0.0% at `balanced`, -0.1% at `high`,
+ *  +0.3% at `tiny`. It is free because the encode is rate-capped (`-b:v` = `-maxrate`), so the
+ *  extra keyframes redistribute the same budget instead of adding to it — the real price is a
+ *  little per-frame quality, which is the right trade for halving a frozen picture. */
+export function gopFrames(preset: QualityPreset): number {
+  return Math.max(1, Math.round(preset.fps / 2));
+}
 
 /** ffmpeg output args for the H.264 encode step (goes after `-i desktop -vf ...`).
  *  Prefers hardware NVENC (verified to work even under an RDP session on this class of GPU) —
@@ -21,8 +30,13 @@ export const CAPTURE_GOP_FRAMES = 30;
  *  a fast/LAN transport. Falls back to a low-latency libx264 profile when no hardware H.264
  *  encoder is available. The avc1 codec string is derived from the real SPS at runtime, so the
  *  encoder's actual profile/level is handled regardless of which branch runs. */
-export function captureEncoderArgs(encoder: string = "libx264"): string[] {
-  const common = ["-b:v", "6M", "-maxrate", "6M", "-g", String(CAPTURE_GOP_FRAMES), "-bf", "0", "-pix_fmt", "yuv420p"];
+export function captureEncoderArgs(
+  encoder: string = "libx264",
+  preset: QualityPreset = { fps: DEFAULT_FPS, bitrate: "1M" },
+): string[] {
+  const rate = ["-b:v", preset.bitrate, "-maxrate", preset.bitrate,
+    "-g", String(gopFrames(preset)), "-bf", "0"];
+  const common = [...rate, "-pix_fmt", "yuv420p"];
   switch (encoder) {
     case "h264_nvenc":
       // p2 + `-tune ll` (low latency), CBR, no frame reordering, minimal output delay/VBV.
@@ -30,6 +44,11 @@ export function captureEncoderArgs(encoder: string = "libx264"): string[] {
         "-zerolatency", "1", "-delay", "0", "-bufsize", "512k", ...common];
     case "h264_qsv":
       return ["-c:v", "h264_qsv", "-preset", "veryfast", "-low_power", "1", "-bufsize", "512k", ...common];
+    case "h264_vaapi":
+      // Linux hardware encode on Intel and AMD. No `-pix_fmt`: the frames arriving here are
+      // already GPU-resident nv12 (see `VAAPI_UPLOAD_FILTER`), and a software pixel format on
+      // the output makes ffmpeg refuse the hardware frame context outright.
+      return ["-c:v", "h264_vaapi", "-rc_mode", "CBR", ...rate];
     case "h264_amf":
       return ["-c:v", "h264_amf", "-quality", "speed", "-rc", "cbr", "-bufsize", "512k", ...common];
     case "h264_videotoolbox":

package/src/services/remote-desktop/remote-desktop-evdev-key-map.ts

@@ -0,0 +1,69 @@
+/**
+ * `KeyboardEvent.code` (physical key, layout-independent) → Linux evdev key code
+ * (`KEY_*` from `linux/input-event-codes.h`). Same contract as `remote-desktop-vk-map.ts`
+ * and `remote-desktop-cg-key-map.ts`: only `code` is accepted, never `key`.
+ *
+ * Evdev codes rather than X11 keysyms, and that choice is what makes this table correct on a
+ * non-US host. `XKeysymToKeycode(XK_a)` answers "which key currently *produces* an a", which
+ * on an AZERTY host is the physical Q key — so a keysym table would silently transpose the
+ * whole keyboard for anyone not on a US layout. An evdev code names the physical switch, which
+ * is exactly what `KeyboardEvent.code` also names, so the mapping is a rename rather than a
+ * lookup through the active layout.
+ *
+ * The same table serves both Linux backends: XTEST wants `evdev + 8` (see `X11_KEYCODE_OFFSET`)
+ * and uinput wants the raw code.
+ */
+
+const CODE_TO_EVDEV: Record<string, number> = {
+  Escape: 1,
+  Digit1: 2, Digit2: 3, Digit3: 4, Digit4: 5, Digit5: 6,
+  Digit6: 7, Digit7: 8, Digit8: 9, Digit9: 10, Digit0: 11,
+  Minus: 12, Equal: 13, Backspace: 14, Tab: 15,
+  KeyQ: 16, KeyW: 17, KeyE: 18, KeyR: 19, KeyT: 20, KeyY: 21,
+  KeyU: 22, KeyI: 23, KeyO: 24, KeyP: 25,
+  BracketLeft: 26, BracketRight: 27, Enter: 28, ControlLeft: 29,
+  KeyA: 30, KeyS: 31, KeyD: 32, KeyF: 33, KeyG: 34,
+  KeyH: 35, KeyJ: 36, KeyK: 37, KeyL: 38,
+  Semicolon: 39, Quote: 40, Backquote: 41, ShiftLeft: 42, Backslash: 43,
+  KeyZ: 44, KeyX: 45, KeyC: 46, KeyV: 47, KeyB: 48, KeyN: 49, KeyM: 50,
+  Comma: 51, Period: 52, Slash: 53, ShiftRight: 54,
+  NumpadMultiply: 55, AltLeft: 56, Space: 57, CapsLock: 58,
+  F1: 59, F2: 60, F3: 61, F4: 62, F5: 63, F6: 64, F7: 65, F8: 66, F9: 67, F10: 68,
+  NumLock: 69, ScrollLock: 70,
+  Numpad7: 71, Numpad8: 72, Numpad9: 73, NumpadSubtract: 74,
+  Numpad4: 75, Numpad5: 76, Numpad6: 77, NumpadAdd: 78,
+  Numpad1: 79, Numpad2: 80, Numpad3: 81, Numpad0: 82, NumpadDecimal: 83,
+  /** The extra key ISO layouts have next to the left Shift (`KEY_102ND`). */
+  IntlBackslash: 86,
+  F11: 87, F12: 88,
+  /** Japanese layouts (`KEY_RO`, `KEY_YEN`). */
+  IntlRo: 89,
+  NumpadEnter: 96, ControlRight: 97, NumpadDivide: 98,
+  PrintScreen: 99, AltRight: 100,
+  Home: 102, ArrowUp: 103, PageUp: 104, ArrowLeft: 105, ArrowRight: 106,
+  End: 107, ArrowDown: 108, PageDown: 109, Insert: 110, Delete: 111,
+  Pause: 119,
+  IntlYen: 124,
+  MetaLeft: 125, MetaRight: 126, ContextMenu: 127,
+  F13: 183, F14: 184, F15: 185, F16: 186, F17: 187, F18: 188,
+  F19: 189, F20: 190, F21: 191, F22: 192, F23: 193, F24: 194,
+};
+
+/** X11 keycodes are evdev codes shifted by 8 — an XFree86 legacy that every Linux X server
+ *  still honours (verified against a live server: `KEY_A` 30 → X keycode 38, `KEY_ESC` 1 → 9,
+ *  `KEY_LEFTMETA` 125 → 133). */
+export const X11_KEYCODE_OFFSET = 8;
+
+/** Every modifier's evdev code — used to force-release stuck modifiers on teardown (a lost
+ *  keyup otherwise leaves e.g. Shift logically held on the host after the WS drops). */
+export const MODIFIER_EVDEV_CODES = [42, 54, 29, 97, 56, 100, 125, 126] as const;
+
+/** Every code this table can emit. A uinput device must declare each key it will ever send
+ *  (`UI_SET_KEYBIT`) before creation — an undeclared key is dropped by the kernel silently. */
+export const ALL_EVDEV_CODES: readonly number[] = [...new Set(Object.values(CODE_TO_EVDEV))].sort((a, b) => a - b);
+
+/** Resolve a `KeyboardEvent.code` to its evdev code; null for anything unmapped (IME
+ *  composition, media keys) rather than guessing and injecting the wrong key. */
+export function codeToEvdev(code: string): number | null {
+  return CODE_TO_EVDEV[code] ?? null;
+}