@hienlh/ppm 0.21.0 → 0.22.0

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

@@ -6,9 +6,16 @@
  * Adding a requirement = push one more item here (and, for `host` actions, handle its id in
  * `runHostAction`). The UI needs no change.
  */
+import { accessSync, constants, existsSync } from "node:fs";
 import { getFfmpegCapabilities } from "../media-transcode/ffmpeg-capabilities.ts";
 import { captureInputForPlatform } from "./remote-desktop-capture-input.ts";
 import { getInputBackend } from "./remote-desktop-input.ts";
+import { clipboardAvailable, clipboardTool } from "./remote-desktop-clipboard.ts";
+import { audioSupport, type AudioSupport } from "./remote-desktop-audio.ts";
+import { privacySupport, type PrivacySupport } from "./remote-desktop-privacy.ts";
+import { listHostResolutions, type HostResolutions } from "./remote-desktop-resolution.ts";
+import { detectLinuxSession, type LinuxSession } from "./remote-desktop-linux-session.ts";
+import { getX11 } from "./remote-desktop-x11.ts";
 import {
   MAC_PERMISSION_SETTINGS_URL,
   macPermissionStatus,
@@ -39,6 +46,15 @@ export interface RemoteDesktopRequirement {
   actions: RequirementAction[];
 }
 
+/** Clipboard sync is an *extra*, not a gate: it blocks neither video nor input, so it cannot
+ *  be a `requirements` row — that checklist is only rendered while video or input is unmet, so a
+ *  row there would be invisible on exactly the working hosts that are missing the tool. */
+export interface ClipboardSupport {
+  available: boolean;
+  /** How to get the tool, when one is missing and this OS needs a package for it. */
+  action: RequirementAction | null;
+}
+
 export interface RemoteDesktopReadiness {
   platform: NodeJS.Platform;
   /** There is a capture path for this OS at all. Gates the UI entry; everything else is a
@@ -49,16 +65,42 @@ export interface RemoteDesktopReadiness {
   videoReady: boolean;
   /** Every `input` requirement is met (and the platform has an injector). */
   inputReady: boolean;
+  clipboard: ClipboardSupport;
+  /** Whether the host can stream its own audio. Not a `requirements` row either, and for the
+   *  same reason as clipboard: that checklist only renders while video or input is unmet, so a
+   *  row here would be invisible on exactly the working hosts that cannot do audio. */
+  audio: AudioSupport;
+  /** Whether local input can be blocked and the host monitor blanked. Informational, like the
+   *  two above — never a gate. */
+  privacy: PrivacySupport;
+  /** The host's own display modes, for the resolution picker. Same non-gating treatment. */
+  resolutions: HostResolutions;
 }
 
 const FFMPEG_INSTALL: Partial<Record<NodeJS.Platform, RequirementAction>> = {
   darwin: { kind: "terminal", label: "Install with Homebrew", command: "brew install ffmpeg" },
   win32: { kind: "terminal", label: "Install with winget", command: "winget install --id Gyan.FFmpeg -e" },
-  linux: { kind: "terminal", label: "Install with apt", command: "sudo apt install ffmpeg" },
 };
 
+/** Distro package managers, in the order a host is checked. `apt` last as the fallback label
+ *  because it is the one most users recognise — but a command that names the wrong package
+ *  manager is worse than none, since the checklist offers to *type it into a real terminal*. */
+const LINUX_PACKAGE_MANAGERS: Array<{ bin: string; label: string; command: string }> = [
+  { bin: "/usr/bin/pacman", label: "Install with pacman", command: "sudo pacman -S --needed ffmpeg" },
+  { bin: "/usr/bin/dnf", label: "Install with dnf", command: "sudo dnf install ffmpeg" },
+  { bin: "/usr/bin/zypper", label: "Install with zypper", command: "sudo zypper install ffmpeg" },
+  { bin: "/usr/bin/apt", label: "Install with apt", command: "sudo apt install ffmpeg" },
+];
+
+/** A `terminal` action installing `pkg` with whichever package manager this host has. */
+function linuxInstallAction(pkg: string): RequirementAction | undefined {
+  const found = LINUX_PACKAGE_MANAGERS.find((p) => existsSync(p.bin));
+  if (!found) return undefined;
+  return { kind: "terminal", label: found.label, command: found.command.replace("ffmpeg", pkg) };
+}
+
 function ffmpegRequirement(platform: NodeJS.Platform, present: boolean): RemoteDesktopRequirement {
-  const install = FFMPEG_INSTALL[platform];
+  const install = platform === "linux" ? linuxInstallAction("ffmpeg") : FFMPEG_INSTALL[platform];
   return {
     id: "ffmpeg",
     ok: present,
@@ -89,8 +131,114 @@ function macPermissionRequirement(id: MacPermissionId, granted: boolean): Remote
   };
 }
 
-export async function remoteDesktopReadiness(platform: NodeJS.Platform = process.platform): Promise<RemoteDesktopReadiness> {
-  const platformSupported = captureInputForPlatform(platform) !== null;
+/** The session-type row. A Wayland host is *not* reported as an unsupported platform: nothing
+ *  about Linux is missing, one specific capture path is — and the user can satisfy it in place
+ *  by choosing X11 at the login screen, which is exactly what a requirement is for. Hiding the
+ *  entry instead would leave them with no explanation at all. */
+function linuxSessionRequirement(session: LinuxSession): RemoteDesktopRequirement {
+  const x11 = session.kind === "x11";
+  return {
+    id: "linux-session",
+    ok: x11,
+    gates: "video",
+    title: "X11 session",
+    detail: "Screen capture currently needs an X11 session. This host is on Wayland, which only "
+      + "shares the screen through the desktop portal — not supported yet. Log out and pick "
+      + "\"Plasma (X11)\" / \"GNOME on Xorg\" at the login screen; mouse and keyboard already work here.",
+    actions: [],
+  };
+}
+
+/** uinput is how a Wayland session receives input, and the device is root-owned by default. */
+function uinputRequirement(): RemoteDesktopRequirement {
+  let writable = false;
+  try { accessSync("/dev/uinput", constants.W_OK); writable = true; } catch { writable = false; }
+  return {
+    id: "uinput",
+    ok: writable,
+    gates: "input",
+    title: "Write access to /dev/uinput",
+    detail: "Wayland has no input-injection protocol, so PPM types through a virtual input "
+      + "device. Add yourself to the `input` group, then log out and back in; until then the "
+      + "view is read-only.",
+    actions: [{ kind: "terminal", label: "Add me to the input group", command: "sudo usermod -aG input $USER" }],
+  };
+}
+
+/** XTEST is a separate package from Xlib on several distros, and without it there is video but
+ *  no input at all. */
+function xtestRequirement(present: boolean): RemoteDesktopRequirement {
+  return {
+    id: "xtest",
+    ok: present,
+    gates: "input",
+    title: "XTEST extension (libXtst)",
+    detail: "Needed to move the mouse and type on an X11 host. Without it the view is read-only.",
+    actions: [linuxInstallAction(xtstPackage())].filter((a): a is RequirementAction => a !== undefined),
+  };
+}
+
+/** libXtst's package name is not the same everywhere: Debian/Ubuntu ship `libxtst6`, Arch
+ *  `libxtst`, Fedora/openSUSE `libXtst`. */
+function xtstPackage(): string {
+  if (existsSync("/usr/bin/pacman")) return "libxtst";
+  if (existsSync("/usr/bin/apt")) return "libxtst6";
+  return "libXtst";
+}
+
+/** No Xlib connection at all — which is a different fault from a missing XTEST extension, and
+ *  used to be reported as one: `getX11()` answering null made the row below say "XTEST
+ *  extension (libXtst)" and offer `apt install libxtst6`, an instruction that cannot help on a
+ *  host whose libX11 is missing or whose server refused the connection. Capture is unaffected
+ *  either way — ffmpeg opens the display itself, in its own process. */
+function xlibRequirement(display: string): RemoteDesktopRequirement {
+  return {
+    id: "xlib",
+    ok: false,
+    gates: "input",
+    title: "A reachable X server (libX11)",
+    detail: `PPM could not open ${display} through Xlib: either libX11 is missing, or the server `
+      + "refused the connection because PPM cannot read its auth cookie. The picture can still "
+      + "arrive while this is unmet — it is mouse, keyboard and privacy mode that need it.",
+    actions: [linuxInstallAction(x11Package())].filter((a): a is RequirementAction => a !== undefined),
+  };
+}
+
+/** Same split as `xtstPackage`: Debian/Ubuntu `libx11-6`, Arch `libx11`, Fedora/openSUSE
+ *  `libX11`. */
+function x11Package(): string {
+  if (existsSync("/usr/bin/pacman")) return "libx11";
+  if (existsSync("/usr/bin/apt")) return "libx11-6";
+  return "libX11";
+}
+
+function clipboardSupport(platform: NodeJS.Platform, session: LinuxSession | null): ClipboardSupport {
+  const tool = clipboardTool(platform, session);
+  if (clipboardAvailable(tool)) return { available: true, action: null };
+  const pkg = tool?.install;
+  return { available: false, action: (pkg && linuxInstallAction(pkg)) || null };
+}
+
+async function linuxRequirements(session: LinuxSession): Promise<RemoteDesktopRequirement[]> {
+  const rows: RemoteDesktopRequirement[] = [linuxSessionRequirement(session)];
+  if (session.kind === "x11") {
+    const conn = await getX11(session);
+    rows.push(conn ? xtestRequirement(conn.hasXTest) : xlibRequirement(session.display));
+  } else {
+    rows.push(uinputRequirement());
+  }
+  return rows;
+}
+
+export async function remoteDesktopReadiness(
+  platform: NodeJS.Platform = process.platform,
+  linuxSession = platform === "linux" ? detectLinuxSession() : null,
+): Promise<RemoteDesktopReadiness> {
+  // On Linux "is this platform supported" means "is there a graphical session to capture" —
+  // the grabber then depends on its type, which is a requirement rather than a hard no.
+  const platformSupported = platform === "linux"
+    ? linuxSession !== null
+    : captureInputForPlatform(platform) !== null;
   const requirements: RemoteDesktopRequirement[] = [];
   if (platformSupported) {
     const caps = await getFfmpegCapabilities();
@@ -100,14 +248,19 @@ export async function remoteDesktopReadiness(platform: NodeJS.Platform = process
       requirements.push(macPermissionRequirement("screen-recording", status["screen-recording"]));
       requirements.push(macPermissionRequirement("accessibility", status.accessibility));
     }
+    if (platform === "linux" && linuxSession) requirements.push(...await linuxRequirements(linuxSession));
   }
-  const inputSupported = getInputBackend(platform) !== null;
+  const inputSupported = getInputBackend(platform, linuxSession) !== null;
   return {
     platform,
     platformSupported,
     requirements,
     videoReady: platformSupported && requirements.filter((r) => r.gates === "video").every((r) => r.ok),
     inputReady: inputSupported && requirements.filter((r) => r.gates === "input").every((r) => r.ok),
+    clipboard: clipboardSupport(platform, linuxSession),
+    audio: await audioSupport(platform),
+    privacy: await privacySupport(platform),
+    resolutions: await listHostResolutions(platform),
   };
 }
 

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

@@ -0,0 +1,302 @@
+/**
+ * Lists and switches the *host's* real display mode — RustDesk's `_ResolutionsMenu`.
+ *
+ * Over FFI rather than by shelling out to `xrandr`, for the reason already documented for the
+ * monitor list: `xrandr` the binary and `libXrandr` the library are different packages, and
+ * this dev host has the library and not the binary. A version that shells out reports "no
+ * resolutions" on a perfectly good desktop.
+ *
+ * Struct offsets are x86-64 and are written out rather than derived, because a wrong one does
+ * not fail — it reads a neighbouring field, so a mode list comes back with plausible-looking
+ * garbage in it. They are checked against an independent oracle in the test: the kernel's own
+ * the `modes` file under `/sys/class/drm/<card>-<connector>`, which lists what the attached display advertises.
+ *
+ *   XRRScreenResources (64):  timestamp 0, configTimestamp 8, ncrtc 16, crtcs 24,
+ *                             noutput 32, outputs 40, nmode 48, modes 56
+ *   XRRModeInfo (80):         id 0, width 8, height 12, dotClock 16, hTotal 32, vTotal 48,
+ *                             name 56, nameLength 64, modeFlags 72
+ *   XRROutputInfo (96):       crtc 8, name 16, nameLen 24, mm_width 32, mm_height 40,
+ *                             connection 48, ncrtc 52, crtcs 56, nmode 80, npreferred 84,
+ *                             modes 88
+ *   XRRCrtcInfo (64):         x 8, y 12, width 16, height 20, mode 24, rotation 32,
+ *                             noutput 36, outputs 40
+ *
+ * Switching is not one call but a *sequence*, because the root window is a container for the
+ * CRTCs and neither may be outside the other. A CRTC cannot be configured past the screen
+ * bounds, so any dimension that grows needs `XRRSetScreenSize` **first**; and a screen smaller
+ * than a still-active CRTC is equally invalid, so trimming it down has to come **last**. A
+ * switch where one dimension grows and the other shrinks (1920x1200 → 2560x1080) needs both,
+ * which is why `planResolutionSwitch` is a pure function with its own test rather than a pair
+ * of branches — getting it wrong leaves the mode applied and the root window the wrong size,
+ * i.e. a desktop with a dead strip down one side, which no error reports.
+ */
+import { detectLinuxSession } from "./remote-desktop-linux-session.ts";
+import { asPointer, getX11, type X11Connection } from "./remote-desktop-x11.ts";
+
+/** `RR_Connected` from `randr.h`. */
+const RR_CONNECTED = 0;
+const RR_ROTATE_0 = 1;
+const CURRENT_TIME = 0n;
+/** `RRSetConfigSuccess`. */
+const SET_CONFIG_SUCCESS = 0;
+/** `RR_Interlace` / `RR_DoubleScan` in `modeFlags`, which change what the timings mean. */
+const RR_INTERLACE = 0x10;
+const RR_DOUBLE_SCAN = 0x20;
+
+const SIZEOF_MODE_INFO = 80;
+
+export interface HostMode {
+  /** `RRMode` XID, the value a switch is requested by. Stringified because it is a 64-bit id
+   *  and it travels over JSON. */
+  id: string;
+  width: number;
+  height: number;
+  /** Vertical refresh, one decimal place. 0 when the timings do not allow computing one. */
+  refresh: number;
+  /** True for the mode the output is on right now. */
+  current: boolean;
+  /** True for the display's preferred (native) mode. */
+  preferred: boolean;
+}
+
+export interface HostResolutions {
+  /** Connector name (`HDMI-2`, `DP-1`), or null when nothing usable was found. */
+  output: string | null;
+  modes: HostMode[];
+  /** Why the list is empty, or null. */
+  reason: string | null;
+}
+
+/** dotClock / (hTotal * vTotal), corrected for interlace and doublescan the way `xrandr` does. */
+export function modeRefresh(dotClock: number, hTotal: number, vTotal: number, flags: number): number {
+  if (hTotal <= 0 || vTotal <= 0 || dotClock <= 0) return 0;
+  let vTotalAdjusted = vTotal;
+  if (flags & RR_DOUBLE_SCAN) vTotalAdjusted *= 2;
+  if (flags & RR_INTERLACE) vTotalAdjusted /= 2;
+  return Math.round((dotClock / (hTotal * vTotalAdjusted)) * 10) / 10;
+}
+
+interface Resources {
+  res: number;
+  view: DataView;
+  modes: Map<string, { width: number; height: number; refresh: number }>;
+}
+
+function readResources(x: X11Connection): Resources | null {
+  const res = x.xrandr!.XRRGetScreenResourcesCurrent(x.dpy, x.root);
+  if (!res) return null;
+  const header = new DataView(x.ffi.toArrayBuffer(asPointer(Number(res)), 0, 64));
+  const nmode = header.getInt32(48, true);
+  const modesPtr = Number(header.getBigUint64(56, true));
+  const modes = new Map<string, { width: number; height: number; refresh: number }>();
+  if (modesPtr && nmode > 0) {
+    const table = new DataView(x.ffi.toArrayBuffer(asPointer(modesPtr), 0, nmode * SIZEOF_MODE_INFO));
+    for (let i = 0; i < nmode; i++) {
+      const at = i * SIZEOF_MODE_INFO;
+      modes.set(String(table.getBigUint64(at, true)), {
+        width: table.getUint32(at + 8, true),
+        height: table.getUint32(at + 12, true),
+        refresh: modeRefresh(
+          Number(table.getBigUint64(at + 16, true)),
+          table.getUint32(at + 32, true),
+          table.getUint32(at + 48, true),
+          Number(table.getBigUint64(at + 72, true)),
+        ),
+      });
+    }
+  }
+  return { res: Number(res), view: header, modes };
+}
+
+/** The first connected output that has a CRTC, plus its info pointer. Multi-head hosts get the
+ *  one the session is actually driving; PPM streams one display at a time anyway. */
+function firstActiveOutput(x: X11Connection, r: Resources): { output: number; info: number } | null {
+  const noutput = r.view.getInt32(32, true);
+  const outputsPtr = Number(r.view.getBigUint64(40, true));
+  if (!outputsPtr || noutput <= 0) return null;
+  const ids = new DataView(x.ffi.toArrayBuffer(asPointer(outputsPtr), 0, noutput * 8));
+  for (let i = 0; i < noutput; i++) {
+    const id = ids.getBigUint64(i * 8, true);
+    const info = Number(x.xrandr!.XRRGetOutputInfo(x.dpy, asPointer(r.res), id));
+    if (!info) continue;
+    const iv = new DataView(x.ffi.toArrayBuffer(asPointer(info), 0, 96));
+    const connected = iv.getUint16(48, true) === RR_CONNECTED;
+    const crtc = iv.getBigUint64(8, true);
+    if (connected && crtc !== 0n) return { output: Number(id), info };
+    x.xrandr!.XRRFreeOutputInfo(asPointer(info));
+  }
+  return null;
+}
+
+function outputName(x: X11Connection, info: number): string {
+  const iv = new DataView(x.ffi.toArrayBuffer(asPointer(info), 0, 96));
+  const ptr = Number(iv.getBigUint64(16, true));
+  const len = iv.getInt32(24, true);
+  if (!ptr || len <= 0) return "";
+  return new TextDecoder().decode(new Uint8Array(x.ffi.toArrayBuffer(asPointer(ptr), 0, len)));
+}
+
+/** Every mode the host's active output supports. */
+export async function listHostResolutions(
+  platform: NodeJS.Platform = process.platform,
+): Promise<HostResolutions> {
+  if (platform !== "linux") {
+    return { output: null, modes: [], reason: "Only implemented on Linux (X11) so far." };
+  }
+  const session = detectLinuxSession();
+  if (session?.kind !== "x11") {
+    return { output: null, modes: [], reason: "Changing the host resolution needs an X11 session." };
+  }
+  const x = await getX11(session);
+  if (!x?.xrandr) {
+    return { output: null, modes: [], reason: "The host has no libXrandr." };
+  }
+  const r = readResources(x);
+  if (!r) return { output: null, modes: [], reason: "The X server returned no screen resources." };
+  try {
+    const active = firstActiveOutput(x, r);
+    if (!active) return { output: null, modes: [], reason: "No connected output with a CRTC." };
+    try {
+      const iv = new DataView(x.ffi.toArrayBuffer(asPointer(active.info), 0, 96));
+      const crtc = iv.getBigUint64(8, true);
+      const nmode = iv.getInt32(80, true);
+      const npreferred = iv.getInt32(84, true);
+      const modesPtr = Number(iv.getBigUint64(88, true));
+
+      // Which mode is live right now comes from the CRTC, not the output.
+      let currentMode = "0";
+      const crtcInfo = Number(x.xrandr.XRRGetCrtcInfo(x.dpy, asPointer(r.res), crtc));
+      if (crtcInfo) {
+        const cv = new DataView(x.ffi.toArrayBuffer(asPointer(crtcInfo), 0, 64));
+        currentMode = String(cv.getBigUint64(24, true));
+        x.xrandr.XRRFreeCrtcInfo(asPointer(crtcInfo));
+      }
+
+      const modes: HostMode[] = [];
+      if (modesPtr && nmode > 0) {
+        const ids = new DataView(x.ffi.toArrayBuffer(asPointer(modesPtr), 0, nmode * 8));
+        for (let i = 0; i < nmode; i++) {
+          const id = String(ids.getBigUint64(i * 8, true));
+          const info = r.modes.get(id);
+          if (!info || info.width === 0 || info.height === 0) continue;
+          modes.push({
+            id,
+            width: info.width,
+            height: info.height,
+            refresh: info.refresh,
+            current: id === currentMode,
+            // `npreferred` is a *count* of preferred modes at the head of the list, not an
+            // index — reading it as an index marks the wrong mode native.
+            preferred: i < npreferred,
+          });
+        }
+      }
+      return { output: outputName(x, active.info) || null, modes, reason: null };
+    } finally {
+      x.xrandr.XRRFreeOutputInfo(asPointer(active.info));
+    }
+  } finally {
+    x.xrandr.XRRFreeScreenResources(asPointer(r.res));
+  }
+}
+
+export interface ResolutionSwitchPlan {
+  /** The mode is already live; make no X calls at all. */
+  noop: boolean;
+  /** Screen size to set *before* reconfiguring the CRTC, or null when nothing grows. */
+  grow: { width: number; height: number } | null;
+  /** Screen size to set *after*. A no-op when `grow` already hit these numbers. */
+  final: { width: number; height: number };
+}
+
+/** The order of `XRRSetScreenSize`/`XRRSetCrtcConfig` calls for one switch. See the header. */
+export function planResolutionSwitch(
+  oldWidth: number, oldHeight: number, newWidth: number, newHeight: number,
+): ResolutionSwitchPlan {
+  const final = { width: newWidth, height: newHeight };
+  if (oldWidth === newWidth && oldHeight === newHeight) return { noop: true, grow: null, final };
+  const grows = newWidth > oldWidth || newHeight > oldHeight;
+  return {
+    noop: false,
+    // Per dimension, not per switch: the shrinking half of a mixed switch still may not clip
+    // the CRTC while it is live, so both dimensions hold their maximum across the reconfigure
+    // and `final` trims whichever one overshot.
+    grow: grows ? { width: Math.max(oldWidth, newWidth), height: Math.max(oldHeight, newHeight) } : null,
+    final,
+  };
+}
+
+export interface SetResolutionResult {
+  ok: boolean;
+  /** The mode that is live afterwards, whether or not the switch was the one asked for. */
+  width: number;
+  height: number;
+  error: string | null;
+}
+
+/**
+ * Put the host's active output on `modeId`. Returns what is actually live afterwards.
+ */
+export async function setHostResolution(
+  modeId: string, platform: NodeJS.Platform = process.platform,
+): Promise<SetResolutionResult> {
+  const fail = (error: string): SetResolutionResult => ({ ok: false, width: 0, height: 0, error });
+  if (platform !== "linux") return fail("Only implemented on Linux (X11) so far.");
+  const session = detectLinuxSession();
+  if (session?.kind !== "x11") return fail("Needs an X11 session.");
+  const x = await getX11(session);
+  if (!x?.xrandr) return fail("The host has no libXrandr.");
+  const r = readResources(x);
+  if (!r) return fail("The X server returned no screen resources.");
+  try {
+    const target = r.modes.get(modeId);
+    if (!target) return fail("That mode is not one this host advertises.");
+    const active = firstActiveOutput(x, r);
+    if (!active) return fail("No connected output with a CRTC.");
+    try {
+      const iv = new DataView(x.ffi.toArrayBuffer(asPointer(active.info), 0, 96));
+      const crtc = iv.getBigUint64(8, true);
+      const mmWidth = Number(iv.getBigUint64(32, true));
+      const mmHeight = Number(iv.getBigUint64(40, true));
+
+      const crtcInfo = Number(x.xrandr.XRRGetCrtcInfo(x.dpy, asPointer(r.res), crtc));
+      if (!crtcInfo) return fail("Could not read the CRTC.");
+      const cv = new DataView(x.ffi.toArrayBuffer(asPointer(crtcInfo), 0, 64));
+      const cx = cv.getInt32(8, true);
+      const cy = cv.getInt32(12, true);
+      const oldWidth = cv.getUint32(16, true);
+      const oldHeight = cv.getUint32(20, true);
+      x.xrandr.XRRFreeCrtcInfo(asPointer(crtcInfo));
+
+      const plan = planResolutionSwitch(oldWidth, oldHeight, target.width, target.height);
+      if (plan.noop) return { ok: true, width: oldWidth, height: oldHeight, error: null };
+
+      const setScreen = (width: number, height: number) => {
+        // The millimetres are the output's real ones, so the desktop's DPI does not move with
+        // the mode. Passing the conventional 96dpi figure instead makes every font on the host
+        // change size when a remote user picks a resolution.
+        x.xrandr!.XRRSetScreenSize(x.dpy, x.root, width, height, mmWidth, mmHeight);
+        x.x11.XSync(x.dpy, 0);
+      };
+
+      if (plan.grow) setScreen(plan.grow.width, plan.grow.height);
+      const outputs = new BigUint64Array([BigInt(active.output)]);
+      const status = x.xrandr.XRRSetCrtcConfig(
+        x.dpy, asPointer(r.res), crtc, CURRENT_TIME, cx, cy,
+        BigInt(modeId), RR_ROTATE_0, x.ffi.ptr(outputs), 1,
+      );
+      x.x11.XSync(x.dpy, 0);
+      if (status !== SET_CONFIG_SUCCESS) {
+        // Put the container back, or the desktop keeps a dead strip the CRTC never filled.
+        if (plan.grow) setScreen(oldWidth, oldHeight);
+        return fail(`The X server refused the mode (status ${status}).`);
+      }
+      setScreen(plan.final.width, plan.final.height);
+      return { ok: true, width: target.width, height: target.height, error: null };
+    } finally {
+      x.xrandr.XRRFreeOutputInfo(asPointer(active.info));
+    }
+  } finally {
+    x.xrandr.XRRFreeScreenResources(asPointer(r.res));
+  }
+}