@hienlh/ppm 0.21.0 → 0.22.0

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

@@ -0,0 +1,250 @@
+/**
+ * One shared Xlib connection for the X11 capture/input paths, over `bun:ffi` — no helper
+ * binary, matching `remote-desktop-input-win32.ts` (user32) and `-darwin.ts` (CoreGraphics).
+ *
+ * Two things here exist to keep a desktop problem from becoming a PPM problem:
+ *
+ * 1. **Xlib's default I/O error handler calls `exit()`.** If the X server goes away — a
+ *    logout, a GPU driver reset, `systemctl restart sddm` — libX11 prints `XIO: fatal IO
+ *    error` and terminates the *calling process*, which here is the whole PPM server: every
+ *    project, terminal and chat session dies because someone logged out of the desktop. Both
+ *    handlers are therefore replaced (`XSetIOErrorHandler` returns instead of falling through,
+ *    and libX11 ≥ 1.7's `XSetIOErrorExitHandler` cancels the exit that otherwise happens even
+ *    when the first one returns). Protocol errors (`BadWindow` from a monitor unplugged
+ *    mid-enumeration) go to a no-op `XSetErrorHandler` rather than the default's stderr spew.
+ *    The callbacks are held in module scope: a GC'd `JSCallback` would leave Xlib calling a
+ *    freed trampoline, which is a segfault rather than the crash it was installed to prevent.
+ *
+ *    On libX11 **1.6** that protection is only half there, and the code says so rather than
+ *    assuming otherwise: the third handler does not exist before 1.7 (2021), so an I/O error
+ *    still reaches the `exit()` the second handler returns into. It is loaded from its own
+ *    dlopen table for that reason — `bun:ffi`'s `dlopen` throws on the *first* missing symbol
+ *    and hands back none of the others, so one optional function in the main table would take
+ *    capture, input, privacy mode and monitor enumeration down together on every host older
+ *    than that (Ubuntu 20.04 ships 1.6.9).
+ *
+ * 2. **A connection that took an I/O error is not reusable.** There is no safe call left on it,
+ *    not even `XCloseDisplay`, so it is dropped un-closed (a few KB, once per X server
+ *    lifetime) and the next caller opens a fresh one.
+ *
+ * libXtst and libXrandr are optional: a host can have Xlib but no XTEST extension (input goes
+ * view-only) or no libXrandr (one whole-screen display instead of per-monitor). Neither is a
+ * reason to fail capture, so both load into `null` rather than throwing.
+ */
+import { resetLinuxSession, type LinuxSession } from "./remote-desktop-linux-session.ts";
+
+type Ffi = typeof import("bun:ffi");
+/** Xlib pointer/handle as bun:ffi hands it back. */
+type Ptr = number | bigint;
+
+const X11_SYMBOLS = {
+  XOpenDisplay: { args: ["cstring"], returns: "ptr" },
+  XDefaultRootWindow: { args: ["ptr"], returns: "u64" },
+  XDefaultScreen: { args: ["ptr"], returns: "i32" },
+  XDisplayWidth: { args: ["ptr", "i32"], returns: "i32" },
+  XDisplayHeight: { args: ["ptr", "i32"], returns: "i32" },
+  XFlush: { args: ["ptr"], returns: "i32" },
+  XSync: { args: ["ptr", "i32"], returns: "i32" },
+  XGetAtomName: { args: ["ptr", "u64"], returns: "ptr" },
+  XFree: { args: ["ptr"], returns: "i32" },
+  XStringToKeysym: { args: ["cstring"], returns: "u64" },
+  XKeysymToKeycode: { args: ["ptr", "u64"], returns: "u8" },
+  XDisplayKeycodes: { args: ["ptr", "ptr", "ptr"], returns: "i32" },
+  XGetKeyboardMapping: { args: ["ptr", "u8", "i32", "ptr"], returns: "ptr" },
+  XChangeKeyboardMapping: { args: ["ptr", "i32", "i32", "ptr", "i32"], returns: "i32" },
+  XQueryPointer: { args: ["ptr", "u64", "ptr", "ptr", "ptr", "ptr", "ptr", "ptr", "ptr"], returns: "i32" },
+  // Privacy mode: an X grab with `owner_events = False` routes every local key and button to
+  // the grabbing client, which simply drops them. Paired with `XTestGrabControl` below, which
+  // is what keeps the *remote* session's injected events working through that grab.
+  XGrabKeyboard: { args: ["ptr", "u64", "i32", "i32", "i32", "u64"], returns: "i32" },
+  XGrabPointer: { args: ["ptr", "u64", "i32", "u32", "i32", "i32", "u64", "u64", "u64"], returns: "i32" },
+  XUngrabKeyboard: { args: ["ptr", "u64"], returns: "i32" },
+  XUngrabPointer: { args: ["ptr", "u64"], returns: "i32" },
+  XSetErrorHandler: { args: ["ptr"], returns: "ptr" },
+  XSetIOErrorHandler: { args: ["ptr"], returns: "ptr" },
+} as const;
+
+/** libX11 ≥ 1.7 only, which is why it is a table of its own rather than one more line above.
+ *  Exported so a test can assert the split still holds: moving this key back into
+ *  `X11_SYMBOLS` is a one-line change that costs every pre-1.7 host its input. */
+export const X11_EXIT_SYMBOLS = {
+  XSetIOErrorExitHandler: { args: ["ptr", "ptr", "ptr"], returns: "void" },
+} as const;
+
+const XTST_SYMBOLS = {
+  XTestQueryExtension: { args: ["ptr", "ptr", "ptr", "ptr", "ptr"], returns: "i32" },
+  XTestFakeMotionEvent: { args: ["ptr", "i32", "i32", "i32", "u64"], returns: "i32" },
+  XTestFakeButtonEvent: { args: ["ptr", "u32", "i32", "u64"], returns: "i32" },
+  XTestFakeKeyEvent: { args: ["ptr", "u32", "i32", "u64"], returns: "i32" },
+  /** Makes this client's XTEST events *impervious to grabs* — the one call that lets privacy
+   *  mode hold a keyboard/pointer grab without also blocking the remote session's own input. */
+  XTestGrabControl: { args: ["ptr", "i32"], returns: "i32" },
+} as const;
+
+const XRANDR_SYMBOLS = {
+  XRRGetMonitors: { args: ["ptr", "u64", "i32", "ptr"], returns: "ptr" },
+  XRRFreeMonitors: { args: ["ptr"], returns: "void" },
+  // Resolution switching. `…Current` rather than `XRRGetScreenResources`: the latter re-polls
+  // every output over DDC, which takes tens of milliseconds and can wake a sleeping monitor.
+  XRRGetScreenResourcesCurrent: { args: ["ptr", "u64"], returns: "ptr" },
+  XRRFreeScreenResources: { args: ["ptr"], returns: "void" },
+  XRRGetOutputInfo: { args: ["ptr", "ptr", "u64"], returns: "ptr" },
+  XRRFreeOutputInfo: { args: ["ptr"], returns: "void" },
+  XRRGetCrtcInfo: { args: ["ptr", "ptr", "u64"], returns: "ptr" },
+  XRRFreeCrtcInfo: { args: ["ptr"], returns: "void" },
+  XRRSetCrtcConfig: {
+    args: ["ptr", "ptr", "u64", "u64", "i32", "i32", "u64", "u16", "ptr", "i32"],
+    returns: "i32",
+  },
+  XRRSetScreenSize: { args: ["ptr", "u64", "i32", "i32", "i32", "i32"], returns: "void" },
+} as const;
+
+/** DPMS lives in libXext, not libX11. Used to turn the host's monitor off for privacy mode
+ *  while leaving the framebuffer — and therefore the capture — alone. */
+const DPMS_SYMBOLS = {
+  DPMSQueryExtension: { args: ["ptr", "ptr", "ptr"], returns: "i32" },
+  DPMSCapable: { args: ["ptr"], returns: "i32" },
+  DPMSEnable: { args: ["ptr"], returns: "i32" },
+  DPMSForceLevel: { args: ["ptr", "u16"], returns: "i32" },
+  DPMSInfo: { args: ["ptr", "ptr", "ptr"], returns: "i32" },
+} as const;
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- dlopen's symbol types are per-call */
+type X11Lib = { [K in keyof typeof X11_SYMBOLS]: any };
+type X11ExitLib = { [K in keyof typeof X11_EXIT_SYMBOLS]: any };
+type XtstLib = { [K in keyof typeof XTST_SYMBOLS]: any };
+type XrandrLib = { [K in keyof typeof XRANDR_SYMBOLS]: any };
+type DpmsLib = { [K in keyof typeof DPMS_SYMBOLS]: any };
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+export interface X11Connection {
+  ffi: Ffi;
+  x11: X11Lib;
+  /** null when the host has no libXtst — capture works, input does not. */
+  xtst: XtstLib | null;
+  /** null when the host has no libXrandr — one whole-screen display instead of per-monitor. */
+  xrandr: XrandrLib | null;
+  /** null when the host has no libXext, or its X server has no DPMS extension — privacy mode
+   *  then blocks local input without blanking the monitor. */
+  dpms: DpmsLib | null;
+  dpy: Ptr;
+  root: bigint;
+  screen: number;
+  /** XTEST is present AND usable on this connection. */
+  hasXTest: boolean;
+  /** Which display this was opened against, so a later session change cannot reuse it. */
+  display: string;
+}
+
+let ffiModule: Ffi | null = null;
+let connection: X11Connection | null = null;
+/** Kept forever: Xlib holds raw pointers to these trampolines for the process lifetime. Named
+ *  rather than an array, because the one read outside `installErrorHandlers` used to be
+ *  `liveCallbacks[2]` — a fourth handler would have handed the wrong trampoline to Xlib, with
+ *  a wrong signature, and nothing to say so until it was called. */
+let errorCallbacks: { onError: Trampoline; onIoError: Trampoline; onIoExit: Trampoline } | null = null;
+let connectionLost = false;
+
+/** One `JSCallback`, whose `.ptr` is the address Xlib keeps for the process lifetime. */
+type Trampoline = InstanceType<Ffi["JSCallback"]>;
+
+function tryDlopen<T>(ffi: Ffi, names: string[], symbols: object): T | null {
+  for (const name of names) {
+    try { return ffi.dlopen(name, symbols as never).symbols as T; } catch { /* try the next soname */ }
+  }
+  return null;
+}
+
+/** Replace the three handlers that would otherwise print to stderr or kill the process. */
+function installErrorHandlers(ffi: Ffi, x11: X11Lib): void {
+  if (errorCallbacks) return;
+  const { JSCallback } = ffi;
+
+  // Protocol error (BadWindow/BadMatch): return 0, the same as the default handler minus stderr.
+  const onError = new JSCallback(() => 0, { args: ["ptr", "ptr"], returns: "i32" });
+  // I/O error: server gone. Mark dead and return — libX11 would otherwise fall through to exit.
+  const onIoError = new JSCallback(() => { connectionLost = true; return 0; }, { args: ["ptr"], returns: "i32" });
+  // The exit that happens anyway once the handler above returns. Cancelled by doing nothing.
+  const onIoExit = new JSCallback(() => { connectionLost = true; }, { args: ["ptr", "ptr"], returns: "void" });
+
+  x11.XSetErrorHandler(onError.ptr);
+  x11.XSetIOErrorHandler(onIoError.ptr);
+  // Written last, and this is the whole of the "installed" flag: the old boolean was set
+  // *before* the two calls above, so anything that read it in between was told the process was
+  // protected while the default handlers were still in place.
+  errorCallbacks = { onError, onIoError, onIoExit };
+}
+
+/** The shared connection for `session`, or null when Xlib is missing or the server refuses us
+ *  (no `$DISPLAY` server running, an auth cookie we cannot read). */
+export async function getX11(session: LinuxSession): Promise<X11Connection | null> {
+  if (session.kind !== "x11") return null;
+  if (connectionLost) { connection = null; connectionLost = false; }
+  // Matched on the display, not merely on there being a connection. The session is re-probed
+  // periodically now, so it can name a different display on a still-live server — a second
+  // seat, a nested Xephyr, `:0` becoming `:1`. Handing back the old `Display*` then sends
+  // every keystroke and click into the display nobody is looking at, silently and for good:
+  // nothing errors, because the old server is still there.
+  // Dropped rather than closed, the way `resetX11` and the module header already decide: Xlib's
+  // I/O error handler can `exit()` the server process, so `XCloseDisplay` is never called here.
+  if (connection && connection.display !== session.display) connection = null;
+  if (connection) return connection;
+
+  if (!ffiModule) ffiModule = await import("bun:ffi");
+  const ffi = ffiModule;
+  const x11 = tryDlopen<X11Lib>(ffi, ["libX11.so.6", "libX11.so"], X11_SYMBOLS);
+  if (!x11) return null;
+  // Same library, second `dlopen`: null here means libX11 1.6, not a missing libX11.
+  const x11Exit = tryDlopen<X11ExitLib>(ffi, ["libX11.so.6", "libX11.so"], X11_EXIT_SYMBOLS);
+  installErrorHandlers(ffi, x11);
+
+  const dpy = x11.XOpenDisplay(Buffer.from(`${session.display}\0`));
+  if (!dpy) return null;
+
+  const xtst = tryDlopen<XtstLib>(ffi, ["libXtst.so.6", "libXtst.so"], XTST_SYMBOLS);
+  const xrandr = tryDlopen<XrandrLib>(ffi, ["libXrandr.so.2", "libXrandr.so"], XRANDR_SYMBOLS);
+  const xext = tryDlopen<DpmsLib>(ffi, ["libXext.so.6", "libXext.so"], DPMS_SYMBOLS);
+
+  let hasXTest = false;
+  if (xtst) {
+    const out = new Int32Array(1);
+    hasXTest = xtst.XTestQueryExtension(dpy, ffi.ptr(out), ffi.ptr(out), ffi.ptr(out), ffi.ptr(out)) !== 0;
+  }
+
+  // The exit handler needs the Display, so it is installed after the connection exists — and
+  // only where the symbol resolved. The guard was on whether a *callback* existed, which is
+  // always true and says nothing about whether libX11 has the function to pass it to.
+  if (x11Exit && errorCallbacks) x11Exit.XSetIOErrorExitHandler(dpy, errorCallbacks.onIoExit.ptr, null);
+
+  // libXext being present is not enough: a server can be built without the DPMS extension, and
+  // `DPMSForceLevel` against one of those is a no-op that returns success.
+  let dpms: DpmsLib | null = null;
+  if (xext) {
+    const out = new Int32Array(2);
+    const present = xext.DPMSQueryExtension(dpy, ffi.ptr(out), ffi.ptr(out.subarray(1))) !== 0;
+    if (present && xext.DPMSCapable(dpy) !== 0) dpms = xext;
+  }
+
+  connection = {
+    ffi, x11, xtst, xrandr, dpms, dpy,
+    root: BigInt(x11.XDefaultRootWindow(dpy)),
+    screen: x11.XDefaultScreen(dpy),
+    hasXTest,
+    display: session.display,
+  };
+  return connection;
+}
+
+/** `bun:ffi` types every address as a branded `Pointer`, but walking a C array means doing
+ *  arithmetic on a plain number. One cast, here, instead of at every struct field. */
+export function asPointer(address: number): import("bun:ffi").Pointer {
+  return address as unknown as import("bun:ffi").Pointer;
+}
+
+/** Drop the cached connection (tests, and after a session change) and, with it, the memoized
+ *  session it was opened against. */
+export function resetX11(): void {
+  connection = null;
+  connectionLost = false;
+  resetLinuxSession();
+}

package/src/services/supervisor.ts

@@ -11,6 +11,7 @@ import {
   unlinkSync, statSync,
 } from "node:fs";
 import { getPpmDir } from "./ppm-dir.ts";
+import { stdioIsLogFile, consumeStdioIsLogEnv, rotateIfOversized, MAX_LOG_BYTES, STDIO_IS_LOG_ENV } from "./log-rotate.ts";
 import { isCompiledBinary } from "./autostart-generator.ts";
 import { cleanupStaleBinaryUpgradeArtifacts } from "./binary-upgrade-swap.ts";
 import {
@@ -60,6 +61,7 @@ const DB_BACKUP_STALE_WARN_MS = 21_600_000; // 6h — snapshots stopped happenin
 const SELF_REPLACE_TIMEOUT_MS = 30_000;     // 30s to wait for new supervisor
 const EDGE_PROBE_INTERVAL_MS = 10_000;      // the public port is dark while the edge is down — check often
 const SERVER_PORT_MIRROR_TIMEOUT_MS = 30_000; // how long to wait for the server to publish its port
+const LOG_ROTATE_INTERVAL_MS = 60_000;      // how often ppm.log is checked against its cap
 
 const logFile = () => resolve(getPpmDir(), "ppm.log");
 const restartingFlag = () => resolve(getPpmDir(), ".restarting");
@@ -154,12 +156,51 @@ let cloudConnected = false; // tracks whether we've initiated a cloud WS connect
 let originalArgv: string[] = [];
 
 // ─── Logging ───────────────────────────────────────────────────────────
+
+/**
+ * Whether this process's own stderr already lands in ppm.log.
+ *
+ * Normally it does not — under systemd stderr is the journal, and the
+ * supervisor's lines belong there as well as in the log. But the replacement
+ * supervisor of a self-upgrade is spawned with `stdio: ["ignore", newLogFd,
+ * newLogFd]`, and from then on every line would be written to the file twice.
+ * Resolved once, lazily: fd 2 does not change underneath a running process.
+ */
+let stderrIsLogFile: boolean | null = null;
+
 function log(level: string, msg: string) {
   const ts = new Date().toISOString();
   const line = `[${ts}] [${level}] [supervisor] ${msg}\n`;
   try { appendFileSync(logFile(), line); } catch {}
-  // Always write supervisor logs to stderr so journalctl captures them
-  try { process.stderr.write(line); } catch {}
+  if (stderrIsLogFile === null) {
+    stderrIsLogFile = stdioIsLogFile(2, logFile());
+    consumeStdioIsLogEnv();
+  }
+  // Write supervisor logs to stderr so journalctl captures them — unless
+  // stderr is the log file itself, where that is the same line again.
+  if (!stderrIsLogFile) { try { process.stderr.write(line); } catch {} }
+}
+
+let logRotateTimer: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Keep ppm.log under its cap. Only the supervisor does this.
+ *
+ * It is the long-lived owner of the descriptor every child was handed, and two
+ * processes truncating one file would race. Deliberately *not* run once at
+ * startup: the first rotation of a log that has been left to grow copies the
+ * whole of it, and doing that during boot adds to the one stall this work is
+ * trying to remove. The first tick is a minute away and nothing is worse for
+ * waiting.
+ */
+function startLogRotation() {
+  if (logRotateTimer) return;
+  logRotateTimer = setInterval(() => {
+    if (rotateIfOversized(logFile())) {
+      log("INFO", `Rotated ppm.log at cap ${Math.round(MAX_LOG_BYTES / 1048576)} MB`);
+    }
+  }, LOG_ROTATE_INTERVAL_MS);
+  logRotateTimer.unref?.();
 }
 
 // ─── Backoff calc ──────────────────────────────────────────────────────
@@ -622,7 +663,8 @@ export async function spawnServer(
   serverChild = await withProbeSpawnGate(() => Bun.spawn({
     cmd,
     stdio: ["ignore", logFd, logFd],
-    env: process.env,
+    // The child cannot work out on Windows that fd 1 is already the log, so it is told.
+    env: { ...process.env, [STDIO_IS_LOG_ENV]: "1" },
     // No visible console window. Critical on Windows after an upgrade: the new
     // supervisor is spawned consoleless (detached), so without this its console
     // children — and the Claude SDK grandchildren they spawn — pop blank windows.
@@ -1509,7 +1551,7 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
     const proc = await withProbeSpawnGate(() => nodeSpawn(cmd[0]!, cmd.slice(1), {
       detached: true,
       stdio: ["ignore", newLogFd, newLogFd] as any,
-      env: process.env as NodeJS.ProcessEnv,
+      env: { ...process.env, [STDIO_IS_LOG_ENV]: "1" } as NodeJS.ProcessEnv,
       windowsHide: true,
     }));
     const killNewChild = () => { try { if (proc.pid) process.kill(proc.pid); } catch {} };
@@ -1873,6 +1915,7 @@ export async function runSupervisor(opts: {
   originalArgv = [...process.argv];
 
   const logFd = openSync(logFile(), "a");
+  startLogRotation();
   log("INFO", `Supervisor started (PID: ${process.pid}, port: ${opts.port}, share: ${opts.share})`);
 
   // ── Systemd self-heal: if the unit file is stale (e.g. still has

package/src/shared/remote-desktop-custom-quality.ts

@@ -0,0 +1,117 @@
+/**
+ * RustDesk's "Custom image quality": a bitrate *percentage* and an fps, with the real bitrate
+ * derived from the capture's own resolution. Ported rather than invented, because two parts of
+ * it are counter-intuitive enough that a reasonable guess is wrong:
+ *
+ *  1. **The percentage is not the ratio.** `video_qos.rs:444` reads it back as
+ *     `((q >> 8 & 0xFFF) * 2) / 100.0`, so the ratio is `percent × 2 / 100` — the dialog's
+ *     default **50% means ratio 1.0**, i.e. exactly `base_bitrate`. Reading 50% as ratio 0.5
+ *     (the obvious reading) makes every custom setting half as sharp as the user asked for,
+ *     and nothing reports it: the picture is simply dimmer than the number promises.
+ *  2. **`base_bitrate` is a nearest-preset lookup, not a formula.** `codec.rs:929` finds the
+ *     table row whose *pixel count* is closest to the source's, then scales that row's bitrate
+ *     by the pixel ratio. A plain bits-per-pixel constant does not reproduce it, because the
+ *     table is deliberately non-linear (720p→1000, 1080p→2073, 4K→5000: 4× the pixels of
+ *     1080p for 2.4× the bits).
+ *
+ * The fixed rungs use the same machinery in RustDesk (`Quality::ratio()` → Best 1.5,
+ * Balanced 0.67, Low 0.5); PPM keeps its own absolute-bitrate ladder for those, so only the
+ * custom path needs this.
+ */
+
+/** `RESOLUTION_PRESETS` from `libs/scrap/src/common/codec.rs`, kbps. */
+const RESOLUTION_BITRATE_PRESETS: readonly (readonly [number, number, number])[] = [
+  [640, 480, 400],
+  [800, 600, 500],
+  [1024, 768, 800],
+  [1280, 720, 1000],
+  [1366, 768, 1100],
+  [1440, 900, 1300],
+  [1600, 900, 1500],
+  [1920, 1080, 2073],
+  [2048, 1080, 2200],
+  [2560, 1440, 3000],
+  [3440, 1440, 4000],
+  [3840, 2160, 5000],
+  [7680, 4320, 12000],
+];
+
+/** `kMinQuality` / `kDefaultQuality` / `kMaxQuality` / `kMaxMoreQuality` from `consts.dart`. */
+export const CUSTOM_QUALITY_MIN_PERCENT = 10;
+export const CUSTOM_QUALITY_DEFAULT_PERCENT = 50;
+export const CUSTOM_QUALITY_MAX_PERCENT = 100;
+/** The "More" checkbox raises the ceiling this far — 2000% is ratio 40, which is `BR_MAX`. */
+export const CUSTOM_QUALITY_MAX_MORE_PERCENT = 2000;
+
+/** `kMinFps` / `kDefaultFps` / `kMaxFps`. */
+export const CUSTOM_FPS_MIN = 5;
+export const CUSTOM_FPS_DEFAULT = 30;
+export const CUSTOM_FPS_MAX = 120;
+
+/** `BR_MIN` / `BR_MAX` from `video_qos.rs`. */
+const BR_MIN = 0.2;
+const BR_MAX = 40.0;
+
+/** Nearest-pixel-count preset, scaled by the pixel ratio. See note 2. */
+export function baseBitrateKbps(width: number, height: number): number {
+  const pixels = Math.max(1, Math.round(width) * Math.round(height));
+  let best = RESOLUTION_BITRATE_PRESETS[7]!; // 1080p, the table's own fallback
+  let bestDistance = Infinity;
+  for (const preset of RESOLUTION_BITRATE_PRESETS) {
+    const distance = Math.abs(preset[0] * preset[1] - pixels);
+    if (distance < bestDistance) { bestDistance = distance; best = preset; }
+  }
+  const presetPixels = best[0] * best[1];
+  // Floored at 1: a 0x0 capture (before the first frame) otherwise scales the smallest preset
+  // down to `round(400 / 307200)` = **0**, and ffmpeg refuses a zero bitrate outright rather
+  // than picking something sensible.
+  return Math.max(1, Math.round(best[2] * (pixels / presetPixels)));
+}
+
+/** Percent → bitrate ratio. `percent × 2 / 100`, clamped. See note 1. */
+export function customQualityRatio(percent: number): number {
+  if (!Number.isFinite(percent)) return (CUSTOM_QUALITY_DEFAULT_PERCENT * 2) / 100;
+  return Math.min(Math.max((percent * 2) / 100, BR_MIN), BR_MAX);
+}
+
+/** Clamp any bitrate ratio to RustDesk's own bounds. Named rungs already sit inside them; the
+ *  congestion scaling in `remote-desktop-quality.ts` is what can push one out. */
+export function clampRatio(ratio: number): number {
+  if (!Number.isFinite(ratio)) return BR_MIN;
+  return Math.min(Math.max(ratio, BR_MIN), BR_MAX);
+}
+
+/** The bitrate a ratio really encodes at, for this capture size. Every rung goes through here —
+ *  a named one, a congestion-scaled one and the custom dialog's percentage alike, which is what
+ *  makes "the chosen quality is a ceiling on the ratio" a statement about one number. */
+export function ratioBitrateKbps(ratio: number, width: number, height: number): number {
+  // Floored at 1: the table's smallest row makes `baseBitrateKbps(0, 0)` round to 0, and ffmpeg
+  // refuses a zero bitrate outright.
+  return Math.max(1, Math.round(baseBitrateKbps(width, height) * clampRatio(ratio)));
+}
+
+/** An ffmpeg bitrate string (`-b:v`/`-maxrate`) for a ratio. */
+export function ratioBitrateArg(ratio: number, width: number, height: number): string {
+  return `${ratioBitrateKbps(ratio, width, height)}k`;
+}
+
+/** The bitrate a custom setting really encodes at, for this capture size. */
+export function customBitrateKbps(percent: number, width: number, height: number): number {
+  return ratioBitrateKbps(customQualityRatio(percent), width, height);
+}
+
+/** An ffmpeg bitrate string (`-b:v`/`-maxrate`) for a custom setting. */
+export function customBitrateArg(percent: number, width: number, height: number): string {
+  return `${customBitrateKbps(percent, width, height)}k`;
+}
+
+export function clampCustomQualityPercent(value: unknown, allowMore = false): number {
+  const max = allowMore ? CUSTOM_QUALITY_MAX_MORE_PERCENT : CUSTOM_QUALITY_MAX_PERCENT;
+  if (typeof value !== "number" || !Number.isFinite(value)) return CUSTOM_QUALITY_DEFAULT_PERCENT;
+  return Math.min(Math.max(Math.round(value), CUSTOM_QUALITY_MIN_PERCENT), max);
+}
+
+export function clampCustomFps(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return CUSTOM_FPS_DEFAULT;
+  return Math.min(Math.max(Math.round(value), CUSTOM_FPS_MIN), CUSTOM_FPS_MAX);
+}

package/src/shared/remote-desktop-quality.ts

@@ -0,0 +1,127 @@
+/**
+ * The remote-desktop quality ladder — shared, because both ends need the same table: the
+ * server turns a rung into ffmpeg args, and the client renders the picker and shows which rung
+ * is active. One definition so a label or a rung cannot drift between them.
+ *
+ * This is RustDesk's own set, ported rather than invented: `toolbarImageQuality` in
+ * `flutter/lib/common/widgets/toolbar.dart` builds exactly four radio items — Good image
+ * quality, Balanced, Optimize reaction time, Custom — and `Quality` in
+ * `libs/scrap/src/common/codec.rs` is the matching enum with the three ratios below.
+ *
+ * Two things follow from that, and both are the opposite of what this file used to do:
+ *
+ * 1. **A rung never changes the resolution.** It sets a bitrate ratio, and the stream stays at
+ *    the host's native size. The old ladder capped height per rung (720p on `balanced`), which
+ *    on a 3440x1440 host threw away 4.8x the pixels — and measured, it 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*, not on area. Neither came close to the
+ *    cap it was given, so the downscale was pure loss.
+ * 2. **There is no `auto` rung.** RustDesk has no such menu item because the adaptation is
+ *    always running: the chosen quality is the *maximum* ratio (`video_qos.rs`: "user set image
+ *    quality => update to the maximum ratio of the latest quality") and congestion lowers the
+ *    effective ratio underneath it. A pin that switched adaptation *off* is what made a chosen
+ *    rung flicker forever on a link that could not carry it.
+ *
+ * The *policy* built on top of this (how far the ratio may fall, and when it moves) is server
+ * side only, in `src/services/remote-desktop/remote-desktop-quality.ts`.
+ */
+
+export type QualityPresetId = "best" | "balanced" | "low";
+
+/** One entry of the Image quality menu: a label and the bitrate ratio it asks for. Deliberately
+ *  carries no resolution and no bitrate — the real bitrate depends on the capture size, so it
+ *  can only be resolved once the display is known (`resolveQuality`). */
+export interface QualityRung {
+  id: QualityPresetId;
+  label: string;
+  /** RustDesk's `BR_BEST` / `BR_BALANCED` / `BR_SPEED` from `codec.rs`, unchanged. */
+  ratio: number;
+}
+
+/** What the capture layer needs: a frame rate and an ffmpeg bitrate string. A rung plus a
+ *  capture size resolves to one of these; so does the custom dialog's percentage. */
+export interface QualityPreset {
+  fps: number;
+  /** ffmpeg bitrate string, used for both `-b:v` and `-maxrate`. */
+  bitrate: string;
+}
+
+export const QUALITY_PRESETS: Record<QualityPresetId, QualityRung> = {
+  best: { id: "best", label: "Good image quality", ratio: 1.5 },
+  balanced: { id: "balanced", label: "Balanced", ratio: 0.67 },
+  low: { id: "low", label: "Optimize reaction time", ratio: 0.5 },
+};
+
+/* "Optimize reaction time" is RustDesk's own name for the 0.5 rung and it is now the right one,
+ * where on the old ladder it would have been backwards. There, the low rungs downscaled and the
+ * *high* rungs were the low-latency ones — measured 1440p60 `gap p50=16.6ms` against 720p30
+ * `p50=33.3ms`. With resolution out of the picture the only thing a lower rung changes is how
+ * many bytes have to cross the link per frame, so less really does mean sooner. */
+
+/** RustDesk's menu order, which is best-first — not the worst-to-best order a ladder walks. */
+export const QUALITY_PRESET_ORDER: readonly QualityPresetId[] = ["best", "balanced", "low"];
+
+/** `Quality::default()` in `codec.rs` is `Balanced`. */
+export const DEFAULT_PRESET_ID: QualityPresetId = "balanced";
+
+/** `pub const FPS: u32 = 30` in `video_qos.rs` — what a named rung streams at. Only the custom
+ *  dialog sets a frame rate directly; RustDesk otherwise adapts it, never exposes it. */
+export const DEFAULT_FPS = 30;
+
+/** Coerce whatever came over the wire into a real preset id, or null for garbage.
+ *  `Object.hasOwn`, never `in`: `in` walks the prototype chain, so `"toString"` off the wire
+ *  would pass as a preset id and `QUALITY_PRESETS["toString"]` would hand the capture pipeline
+ *  a *function* where it expected a rung — nonsense ffmpeg args from one client string. */
+export function parsePresetId(value: unknown): QualityPresetId | null {
+  return typeof value === "string" && Object.hasOwn(QUALITY_PRESETS, value)
+    ? value as QualityPresetId
+    : null;
+}
+
+/** What the client can ask for. `custom` only means something together with the two numbers
+ *  from its dialog, which is why it is a separate arm rather than a fourth rung. */
+export type QualityChoice = QualityPresetId | "custom";
+
+/** A custom rung: RustDesk's bitrate percentage + fps, at the host's native resolution — the
+ *  same resolution every named rung uses (see `remote-desktop-custom-quality.ts`). */
+export interface CustomQuality {
+  /** Bitrate percentage; the real bitrate comes from the capture size. */
+  percent: number;
+  fps: number;
+}
+
+/** Coerce a stored/untrusted value into a `QualityChoice`, falling back to the default rung.
+ *  Separate from `parsePresetId` because the persisted device pref may legitimately be
+ *  `"custom"`, and because localStorage is user-writable — a rung read back from it is
+ *  untrusted input exactly like one off the wire, with the same `Object.hasOwn` hazard behind
+ *  it. A pref left over from the old five-rung ladder (`"tiny"`, `"max"`, `"auto"`) parses as
+ *  garbage and lands on the default, which is what should happen to a rung that no longer
+ *  exists. */
+export function parseQualityChoice(value: unknown): QualityChoice {
+  if (value === "custom") return value;
+  return parsePresetId(value) ?? DEFAULT_PRESET_ID;
+}
+
+/** Next value for the mobile toolbar's one-tap-per-hop button, in menu order. A dropdown in the
+ *  thumb zone is worse than a button that cycles.
+ *
+ *  `custom` is deliberately not in the cycle: it only means something together with the two
+ *  numbers from its dialog, so a one-tap button that landed on it would change the stream to
+ *  whatever was last typed there — surprising, and with no visible cause. */
+export function nextQualityChoice(current: QualityChoice): QualityChoice {
+  if (current === "custom") return QUALITY_PRESET_ORDER[0]!;
+  const at = QUALITY_PRESET_ORDER.indexOf(current);
+  return QUALITY_PRESET_ORDER[(at + 1) % QUALITY_PRESET_ORDER.length]!;
+}
+
+/** Compact label for a toolbar button, where the full label does not fit. RustDesk has no such
+ *  button, so these are the shortest thing that still distinguishes the four. */
+const SHORT_LABELS: Record<QualityPresetId, string> = {
+  best: "Good",
+  balanced: "Balanced",
+  low: "Reaction",
+};
+
+export function shortQualityLabel(choice: QualityChoice): string {
+  return choice === "custom" ? "Custom" : SHORT_LABELS[choice];
+}

package/src/types/chat.ts

@@ -50,6 +50,10 @@ export interface AIProvider {
   onToolApproval?: (callback: ToolApprovalHandler) => void;
   abortQuery?(sessionId: string, source?: string): void;
   getMessages?(sessionId: string): Promise<ChatMessage[]>;
+  /** Every message in the transcript, including the segments before each compaction.
+   *  `getMessages` answers with the resumable *conversation*; this answers with the
+   *  whole history. Only the search index asks for it — see `indexSession`. */
+  getFullMessages?(sessionId: string): Promise<ChatMessage[]>;
   listSessionsByDir?(dir: string, opts?: { limit?: number; offset?: number }): Promise<SessionInfo[]>;
   ensureProjectPath?(sessionId: string, path: string): void;
   setForkSource?(sessionId: string, sourceSessionId: string): void;

package/src/types/git.ts

@@ -59,6 +59,24 @@ export interface GitDiffFile {
   content: string;
 }
 
+/**
+ * Both sides of a single-file diff, as whole files.
+ *
+ * `binary` is decided from the bytes, and when it is true both sides come back
+ * **empty**: decoded, a PNG is megabytes of U+FFFD that no one can read and that
+ * JSON has to escape. The viewer asks again with `text=1` ("Open Anyway") when
+ * the user wants them anyway. A null size means the file does not exist on that
+ * side, which is how the binary view tells an added or deleted file from a
+ * changed one.
+ */
+export interface FileFullDiff {
+  original: string;
+  modified: string;
+  binary: boolean;
+  originalSize: number | null;
+  modifiedSize: number | null;
+}
+
 export interface GitWorktree {
   /** Absolute path to the worktree directory */
   path: string;
@@ -79,3 +97,37 @@ export interface GitWorktree {
   /** True if this worktree can be pruned (directory missing/stale) */
   prunable: boolean;
 }
+
+/**
+ * A whole branch's changes against a base, as one list.
+ *
+ * `mergeBase` is the commit every per-file diff has to be opened against — in
+ * three-dot mode it is where the two refs diverged, not `base` itself.
+ */
+export interface BranchDiff {
+  base: string;
+  head: string;
+  mode: "three-dot" | "two-dot";
+  mergeBase: string;
+  /**
+   * `head` resolved to a commit, which is what a file must be opened against.
+   * `head` itself is a ref name and moves: a commit landing between the list
+   * fetch and a file being opened would show the new tip beside counts and a
+   * blob id describing the old one.
+   */
+  headCommit: string;
+  /** Files omitted from `files` because the list hit its cap; 0 when complete. */
+  omitted: number;
+  files: BranchDiffFile[];
+}
+
+export interface BranchDiffFile {
+  path: string;
+  oldPath?: string;
+  status: "A" | "M" | "D" | "R" | "C" | "T";
+  additions: number;
+  deletions: number;
+  binary: boolean;
+  /** Head-side blob id; what a "reviewed" flag is remembered against. */
+  blob: string;
+}