@hienlh/ppm 0.21.0 → 0.22.0

package/src/services/remote-desktop/remote-desktop-linux-session.ts

@@ -0,0 +1,146 @@
+/**
+ * Which graphical session this Linux host is running, and how to reach it.
+ *
+ * The PPM process very often has NO `DISPLAY` / `WAYLAND_DISPLAY` of its own: started by a
+ * systemd user unit (`autostart-register.ts`), by an ssh login, or from a tmux pane detached
+ * long ago, it inherits a bare environment while a full desktop session is running two feet
+ * away. Reading only the env would report "no graphical session" on a machine that plainly has
+ * one, so every lookup falls back to probing the sockets the session itself created.
+ *
+ * Wayland is checked BEFORE X11 and that order is load-bearing: a Wayland session almost
+ * always also runs XWayland, which sets `DISPLAY` and answers `x11grab` — with a view of
+ * XWayland clients only, i.e. a black or half-empty screen rather than an error. Preferring
+ * X11 whenever it answers would therefore silently capture the wrong thing on every modern
+ * GNOME/KDE-Wayland host.
+ *
+ * `homedir()` here is a real home path on purpose (`~/.Xauthority`), like
+ * `autostart-generator.ts` — it has nothing to do with the PPM directory and must not go
+ * through `getPpmDir()`.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type LinuxSession =
+  /** `display` is an X display string (`":0"`); `xauthority` is best-effort — capture and XTEST
+   *  both work without it when PPM runs as the session's own user, which is the normal case. */
+  | { kind: "x11"; display: string; xauthority: string | null }
+  | { kind: "wayland"; display: string; runtimeDir: string };
+
+/** `$XDG_RUNTIME_DIR`, or the path systemd would have used for this uid. */
+function runtimeDir(env: NodeJS.ProcessEnv): string {
+  const fromEnv = env.XDG_RUNTIME_DIR?.trim();
+  if (fromEnv) return fromEnv;
+  return `/run/user/${typeof process.getuid === "function" ? process.getuid() : 1000}`;
+}
+
+/** Entries of `dir` matching `re`, or [] when the directory cannot be read (absent, not ours). */
+function socketsIn(dir: string, re: RegExp): string[] {
+  try {
+    return readdirSync(dir).filter((name) => re.test(name)).sort();
+  } catch {
+    return [];
+  }
+}
+
+/** The Wayland display name (`"wayland-0"`) for this host, or null. */
+function findWaylandDisplay(env: NodeJS.ProcessEnv): string | null {
+  const fromEnv = env.WAYLAND_DISPLAY?.trim();
+  if (fromEnv) return fromEnv;
+  // `wayland-0.lock` sits next to the socket — match the socket only.
+  return socketsIn(runtimeDir(env), /^wayland-\d+$/)[0] ?? null;
+}
+
+/** The X display string (`":0"`) for this host, or null. */
+function findX11Display(env: NodeJS.ProcessEnv): string | null {
+  const fromEnv = env.DISPLAY?.trim();
+  if (fromEnv) return fromEnv;
+  const socket = socketsIn("/tmp/.X11-unix", /^X\d+$/)[0];
+  return socket ? `:${socket.slice(1)}` : null;
+}
+
+/** The X authority file, or null when none is found (X still accepts the owning user locally). */
+function findXauthority(env: NodeJS.ProcessEnv): string | null {
+  const fromEnv = env.XAUTHORITY?.trim();
+  if (fromEnv && existsSync(fromEnv)) return fromEnv;
+  // What Xorg is actually started with on a modern seat: `-auth /run/user/1000/xauth_XXXXXX`.
+  const dir = runtimeDir(env);
+  const runtimeAuth = socketsIn(dir, /^xauth_/)[0];
+  if (runtimeAuth) return join(dir, runtimeAuth);
+  const legacy = join(homedir(), ".Xauthority");
+  return existsSync(legacy) ? legacy : null;
+}
+
+/**
+ * How long a probe result is reused before the filesystem is asked again.
+ *
+ * Short enough that the answer follows the host, long enough that the saving is the whole
+ * point: pointer input arrives at roughly 120 probes a second, so five seconds removes about
+ * 99.6% of them and still lets a session that appears — or changes kind — be seen within one.
+ */
+const SESSION_TTL_MS = 5_000;
+
+/** Memoized answer for `process.env`. See `detectLinuxSession`. */
+let cached: { session: LinuxSession | null; at: number } | null = null;
+
+/**
+ * The graphical session on this host, or null when there is none to capture (a headless
+ * server, a CI container). Pure w.r.t. `env` so callers can pin it in tests.
+ *
+ * The answer for the *ambient* environment is memoized, because this sits on the injected-input
+ * path: `remote-desktop-input.ts` picks a backend and `remote-desktop-input-linux.ts` resolves
+ * the display, so every pointer event detected twice. The client coalesces pointer moves to one
+ * per animation frame, so on the host this code exists for — PPM under a systemd user unit, no
+ * `DISPLAY` in its environment, every probe hitting the filesystem — that was ~240 blocking
+ * `readdirSync`/`existsSync` calls a second on the event loop the rest of this release spends
+ * effort keeping free.
+ *
+ * The memo expires, and the negative answer is the reason. PPM can easily start before the
+ * graphical session — a boot-time systemd unit, an ssh start, a login screen — and a null
+ * cached for the life of the process would report Remote Desktop unsupported on a host that
+ * has a desktop by the time anyone asks. The same expiry is what lets an X11 → Wayland
+ * re-login stop routing input at a display that is gone. `resetX11()` still drops it eagerly
+ * alongside the connection it belongs to, but nothing depends on that being called.
+ *
+ * A caller that passes its own `env` is pinning a scenario and neither reads nor fills the cache.
+ */
+export function detectLinuxSession(env: NodeJS.ProcessEnv = process.env): LinuxSession | null {
+  if (env !== process.env) return probeLinuxSession(env);
+  const now = Date.now();
+  if (cached && now - cached.at < SESSION_TTL_MS) return cached.session;
+  cached = { session: probeLinuxSession(env), at: now };
+  return cached.session;
+}
+
+/** Forget the memoized session. Called by `resetX11()`, which is the other half of the same
+ *  state: a session that changed invalidates the connection opened against it. */
+export function resetLinuxSession(): void {
+  cached = null;
+}
+
+function probeLinuxSession(env: NodeJS.ProcessEnv): LinuxSession | null {
+  // `XDG_SESSION_TYPE` is authoritative when present and stops an XWayland `DISPLAY` from
+  // outvoting a Wayland session; when absent, socket order below encodes the same preference.
+  const declared = env.XDG_SESSION_TYPE?.trim().toLowerCase();
+
+  if (declared !== "x11") {
+    const wayland = findWaylandDisplay(env);
+    if (wayland) return { kind: "wayland", display: wayland, runtimeDir: runtimeDir(env) };
+  }
+  if (declared !== "wayland") {
+    const display = findX11Display(env);
+    if (display) return { kind: "x11", display, xauthority: findXauthority(env) };
+  }
+  return null;
+}
+
+/** Env additions a child process (ffmpeg) needs to reach the session. Spread over
+ *  `process.env`, never used alone — ffmpeg still needs `PATH`. */
+export function linuxSessionEnv(session: LinuxSession): Record<string, string> {
+  if (session.kind === "wayland") {
+    return { WAYLAND_DISPLAY: session.display, XDG_RUNTIME_DIR: session.runtimeDir };
+  }
+  return session.xauthority
+    ? { DISPLAY: session.display, XAUTHORITY: session.xauthority }
+    : { DISPLAY: session.display };
+}

package/src/services/remote-desktop/remote-desktop-ogg-opus.ts

@@ -0,0 +1,144 @@
+/**
+ * Pulls Opus packets out of the Ogg stream ffmpeg writes, so the browser gets framed packets it
+ * can hand straight to `AudioDecoder` instead of a container it would have to demux itself.
+ *
+ * Server-side for the same reason `access-unit-assembler.ts` is: the bytes arrive as arbitrary
+ * stdout chunks with no relation to packet boundaries, and the code that finds those boundaries
+ * is a pure function worth testing once rather than a second implementation in the client.
+ *
+ * Two things about the Ogg muxer are worth knowing before touching this. It buffers a whole
+ * **`page_duration`** before writing a page, and that option defaults to **one second** — the
+ * capture spawns with `-page_duration 20000` because the default measured 2000 ms between
+ * writes, i.e. two seconds of audio latency on a stream whose video arrives in 20 ms. And a
+ * packet may be *split across pages* (the lacing table's 255 means "continues"), which for
+ * 96 kbit/s Opus is rare enough to never show up in a short test and certain to show up
+ * eventually — a demuxer that ignores continuation emits a truncated packet, which
+ * `AudioDecoder` reports as a decode error rather than as a click.
+ *
+ * Ogg page layout (little-endian): `OggS`, version, header flags, 8-byte granule, 4-byte
+ * serial, 4-byte sequence, 4-byte CRC, segment count, then that many lacing bytes, then the
+ * payload. The CRC is deliberately **not** verified: this is a pipe from a child process on the
+ * same machine, not a network, and the one failure it could catch (a partial write) is already
+ * handled by waiting for the full page.
+ */
+
+const OGG_MAGIC = [0x4f, 0x67, 0x67, 0x53]; // "OggS"
+const HEADER_BYTES = 27;
+/** `OpusHead` is 19 bytes; anything shorter is not one. */
+const OPUS_HEAD_MIN = 19;
+
+export interface OpusStreamInfo {
+  channels: number;
+  /** Samples the decoder should discard at the start (Opus encoder warm-up). */
+  preSkip: number;
+  /** The rate the *source* was at. Opus always decodes at 48 kHz regardless. */
+  inputSampleRate: number;
+}
+
+/** Parse an `OpusHead` identification header, or null when these bytes are not one. */
+export function parseOpusHead(bytes: Uint8Array): OpusStreamInfo | null {
+  if (bytes.length < OPUS_HEAD_MIN) return null;
+  const magic = String.fromCharCode(...bytes.subarray(0, 8));
+  if (magic !== "OpusHead") return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return {
+    channels: bytes[9]!,
+    preSkip: view.getUint16(10, true),
+    inputSampleRate: view.getUint32(12, true),
+  };
+}
+
+/** Feed stdout chunks, get whole Opus audio packets. The two header packets (`OpusHead`,
+ *  `OpusTags`) are consumed rather than emitted — the first becomes `info`. */
+export class OggOpusDemuxer {
+  private buffer = new Uint8Array(0);
+  /** Bytes of a packet that ran past the end of its page, awaiting the continuation. */
+  private partial: Uint8Array[] = [];
+  private streamInfo: OpusStreamInfo | null = null;
+  private sawTags = false;
+
+  get info(): OpusStreamInfo | null {
+    return this.streamInfo;
+  }
+
+  push(chunk: Uint8Array): Uint8Array[] {
+    this.buffer = concat([this.buffer, chunk]);
+    const out: Uint8Array[] = [];
+    let offset = 0;
+
+    for (;;) {
+      const start = findMagic(this.buffer, offset);
+      if (start < 0) break;
+      if (this.buffer.length < start + HEADER_BYTES) break;
+      const segmentCount = this.buffer[start + HEADER_BYTES - 1]!;
+      const tableEnd = start + HEADER_BYTES + segmentCount;
+      if (this.buffer.length < tableEnd) break;
+      const table = this.buffer.subarray(start + HEADER_BYTES, tableEnd);
+      let payloadLength = 0;
+      for (const n of table) payloadLength += n;
+      const pageEnd = tableEnd + payloadLength;
+      if (this.buffer.length < pageEnd) break; // page still arriving
+
+      // A page whose first packet continues one from the previous page: `partial` already holds
+      // its head. Dropping `partial` on a page that is *not* a continuation is deliberate — it
+      // means bytes were lost, and half a packet decodes to noise.
+      const continued = (this.buffer[start + 5]! & 0x01) !== 0;
+      if (!continued) this.partial = [];
+
+      let cursor = tableEnd;
+      let pending: Uint8Array[] = this.partial;
+      for (const size of table) {
+        pending.push(this.buffer.subarray(cursor, cursor + size));
+        cursor += size;
+        if (size === 255) continue; // packet continues in the next lacing value
+        const packet = concat(pending);
+        pending = [];
+        this.classify(packet, out);
+      }
+      // Anything still pending ran off the end of this page; 255 as the last lacing value is
+      // exactly how Ogg says "continues on the next page".
+      this.partial = pending;
+      offset = pageEnd;
+    }
+
+    this.buffer = offset > 0 ? this.buffer.slice(offset) : this.buffer;
+    return out;
+  }
+
+  /** Header packets set up the stream; everything else is audio. Recognised by content rather
+   *  than by position, because a stream can be re-announced mid-pipe (ffmpeg restarted). */
+  private classify(packet: Uint8Array, out: Uint8Array[]): void {
+    if (packet.length === 0) return;
+    const head = parseOpusHead(packet);
+    if (head) { this.streamInfo = head; this.sawTags = false; return; }
+    if (!this.sawTags && startsWith(packet, "OpusTags")) { this.sawTags = true; return; }
+    out.push(packet);
+  }
+}
+
+function startsWith(bytes: Uint8Array, ascii: string): boolean {
+  if (bytes.length < ascii.length) return false;
+  for (let i = 0; i < ascii.length; i++) if (bytes[i] !== ascii.charCodeAt(i)) return false;
+  return true;
+}
+
+function findMagic(bytes: Uint8Array, from: number): number {
+  for (let i = from; i + 4 <= bytes.length; i++) {
+    if (bytes[i] === OGG_MAGIC[0] && bytes[i + 1] === OGG_MAGIC[1]
+      && bytes[i + 2] === OGG_MAGIC[2] && bytes[i + 3] === OGG_MAGIC[3]) return i;
+  }
+  // Keep the last 3 bytes: they may be the start of a magic split across chunks.
+  return -1;
+}
+
+/** Always copies, even for a single part. The parts are `subarray` views into the receive
+ *  buffer, so returning one would hand the session a window onto a buffer this demuxer goes on
+ *  to replace — and would pin the whole old chunk alive for the life of one 240-byte packet. */
+function concat(parts: readonly Uint8Array[]): Uint8Array<ArrayBuffer> {
+  let total = 0;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const p of parts) { out.set(p, at); at += p.length; }
+  return out;
+}

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

@@ -0,0 +1,163 @@
+/**
+ * Privacy mode: stop the person sitting at the host from using it, and turn their monitor off,
+ * while the remote session keeps working. RustDesk's `toolbarPrivacyMode` plus its separate
+ * "block user input", which on Linux are the same two mechanisms and so are one switch here.
+ *
+ * **Blocking local input is an X grab, not `EVIOCGRAB`.** The evdev route reads like the right
+ * layer — grab the device and the kernel stops delivering its events to X at all — and it is
+ * the one that does not work on a real desktop: an evdev grab is *exclusive*, and keyboard
+ * remappers hold one on every keyboard for exactly this reason. Measured on this host, with
+ * `toshy` running: `EVIOCGRAB` returned **EBUSY on 3 of 4 devices** (both keyboards and the
+ * wireless receiver) and succeeded only on the mouse — which is the worst possible outcome,
+ * because "privacy mode on" would have been reported while the local keyboard still typed.
+ * kmonad, keyd and xremap all take the same grab.
+ *
+ * `XGrabKeyboard` + `XGrabPointer` with `owner_events = False` sit above all of that: whatever
+ * a remapper re-emits still enters X, and X routes it to the grabbing client, which drops it.
+ * The catch that makes this look impossible at first is that a grab would swallow the remote
+ * session's *own* injected events too — and the fix is one call, `XTestGrabControl(dpy, True)`,
+ * whose entire purpose is to make a client's XTEST events impervious to grabs. Verified rather
+ * than assumed: an `XTestFakeMotionEvent` issued while both grabs were held moved the real
+ * pointer to the requested coordinate.
+ *
+ * That also gives the safety property this feature needs: the grabs belong to the X
+ * *connection*, so they are released by `XUngrab*`, by the connection closing, and by the PPM
+ * process exiting. The worst case for a bug here is `pkill ppm`, never a reboot.
+ *
+ * **Blanking is DPMS, not a black window.** x11grab captures the root window, so a fullscreen
+ * black override-redirect window would be captured too — the remote would see the black screen
+ * and nothing else. `DPMSForceLevel(DPMSModeOff)` turns the *output* off and leaves the
+ * framebuffer alone, so the capture is unaffected. It needs re-asserting on a timer: injected
+ * XTEST events reset the server's idle timer exactly as real ones do, so the monitor would
+ * otherwise come back on the first remote keystroke.
+ */
+import { detectLinuxSession } from "./remote-desktop-linux-session.ts";
+import { getX11, type X11Connection } from "./remote-desktop-x11.ts";
+
+/** `XGrabKeyboard`/`XGrabPointer` return codes we care about. */
+const GRAB_SUCCESS = 0;
+const GRAB_MODE_ASYNC = 1;
+const CURRENT_TIME = 0n;
+const NONE = 0n;
+/** Pointer events the grab claims. Every button and motion bit — the point is that nothing
+ *  reaches another client, so the mask is deliberately everything rather than a subset. */
+const POINTER_EVENT_MASK = 0xffff;
+
+/** DPMS power levels from `dpms.h`. */
+const DPMS_MODE_ON = 0;
+const DPMS_MODE_OFF = 3;
+/** The idle timer is reset by our own injected input, so the level has to be re-forced. Two
+ *  seconds is short enough that a monitor never visibly comes back and long enough to be free. */
+const BLANK_REASSERT_MS = 2_000;
+
+export interface PrivacySupport {
+  available: boolean;
+  /** Why not, and what to do about it. Null when privacy mode works. */
+  reason: string | null;
+  /** Whether the monitor can also be blanked. False means input blocking works on its own —
+   *  useful, so it is offered rather than withheld. */
+  canBlank: boolean;
+}
+
+export async function privacySupport(platform: NodeJS.Platform = process.platform): Promise<PrivacySupport> {
+  if (platform !== "linux") {
+    return { available: false, reason: "Only implemented on Linux (X11) so far.", canBlank: false };
+  }
+  const session = detectLinuxSession();
+  if (session?.kind !== "x11") {
+    return { available: false, reason: "Needs an X11 session.", canBlank: false };
+  }
+  const x11 = await getX11(session);
+  if (!x11) return { available: false, reason: "Cannot reach the host's X server.", canBlank: false };
+  // XTEST is what makes the grab survivable: without it the grab would block the remote
+  // session's input along with the local user's.
+  if (!x11.hasXTest) {
+    return {
+      available: false,
+      reason: "The host's X server has no XTEST extension, so a grab would block remote input too.",
+      canBlank: false,
+    };
+  }
+  return { available: true, reason: null, canBlank: x11.dpms !== null };
+}
+
+/** One engaged privacy mode. `release()` is idempotent and runs on every teardown path. */
+export interface PrivacyHandle {
+  release(): void;
+  /** True when local keyboard *and* pointer are both held. A partial grab is never returned —
+   *  see `engagePrivacy`. */
+  inputBlocked: boolean;
+  /** False when the monitor could not be blanked but input *is* blocked. */
+  blanked: boolean;
+}
+
+/** Take both grabs, or neither. A keyboard grab without a pointer grab (or the reverse) reports
+ *  privacy mode as on while half the host is still usable, which is worse than refusing. */
+function grabInput(x11: X11Connection): boolean {
+  const kb = x11.x11.XGrabKeyboard(x11.dpy, x11.root, 0, GRAB_MODE_ASYNC, GRAB_MODE_ASYNC, CURRENT_TIME);
+  if (kb !== GRAB_SUCCESS) return false;
+  const pt = x11.x11.XGrabPointer(
+    x11.dpy, x11.root, 0, POINTER_EVENT_MASK, GRAB_MODE_ASYNC, GRAB_MODE_ASYNC, NONE, NONE, CURRENT_TIME,
+  );
+  if (pt !== GRAB_SUCCESS) {
+    x11.x11.XUngrabKeyboard(x11.dpy, CURRENT_TIME);
+    x11.x11.XFlush(x11.dpy);
+    return false;
+  }
+  // Without this the injected events below would be delivered to *us* (the grabbing client)
+  // rather than to the focused window, i.e. the remote session would go dead on engage.
+  x11.xtst?.XTestGrabControl(x11.dpy, 1);
+  x11.x11.XSync(x11.dpy, 0);
+  return true;
+}
+
+/**
+ * Engage privacy mode, or return null when this host cannot (see `privacySupport`) or when
+ * another client already holds a grab — a screen locker or an open menu both do, and
+ * `AlreadyGrabbed` is a real, temporary condition rather than a broken host.
+ *
+ * Never throws: a session must not die because privacy mode failed.
+ */
+export async function engagePrivacy(): Promise<PrivacyHandle | null> {
+  if (process.platform !== "linux") return null;
+  const session = detectLinuxSession();
+  if (session?.kind !== "x11") return null;
+  const x11 = await getX11(session);
+  if (!x11?.hasXTest) return null;
+
+  if (!grabInput(x11)) return null;
+
+  let blankTimer: ReturnType<typeof setInterval> | null = null;
+  let blanked = false;
+  const force = (level: number): boolean => {
+    if (!x11.dpms) return false;
+    try {
+      x11.dpms.DPMSEnable(x11.dpy);
+      x11.dpms.DPMSForceLevel(x11.dpy, level);
+      x11.x11.XFlush(x11.dpy);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  blanked = force(DPMS_MODE_OFF);
+  if (blanked) blankTimer = setInterval(() => force(DPMS_MODE_OFF), BLANK_REASSERT_MS);
+
+  let released = false;
+  return {
+    inputBlocked: true,
+    blanked,
+    release: () => {
+      if (released) return;
+      released = true;
+      if (blankTimer) clearInterval(blankTimer);
+      if (blanked) force(DPMS_MODE_ON);
+      try {
+        x11.xtst?.XTestGrabControl(x11.dpy, 0);
+        x11.x11.XUngrabKeyboard(x11.dpy, CURRENT_TIME);
+        x11.x11.XUngrabPointer(x11.dpy, CURRENT_TIME);
+        x11.x11.XFlush(x11.dpy);
+      } catch { /* the server may already be gone; the grabs died with the connection */ }
+    },
+  };
+}

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

@@ -0,0 +1,138 @@
+/**
+ * The *policy* over the quality ladder: how far a congested link may pull the bitrate below the
+ * rung the user chose, and when it moves. The ladder itself (labels and ratios) is in
+ * `src/shared/remote-desktop-quality.ts`, because the client renders it too.
+ *
+ * The shape of this is RustDesk's, and replacing what was here fixed a reported flicker — but
+ * not by the mechanism it first looked like, which is worth writing down because the wrong
+ * diagnosis is the plausible one.
+ *
+ * What the old ladder did was cap *resolution* per rung and hand the top rung a flat 25 Mbit/s
+ * at 1440p60. Over a wifi link that cannot carry that, the capture pipe backs up and **ffmpeg
+ * throttles itself**: measured at 4 Mbit/s, 22.9 of 60 fps arrived with inter-frame gaps to
+ * **181 ms** — bursts and stalls rather than a steady cadence, which at 3440x1440 is exactly
+ * what reads as continuous flicker. The same rung on an unthrottled link measured 60.0 fps at
+ * `gap p50=16.5 p95=22.8 max=35.7 ms`, so the rung was never the problem; asking for a rate the
+ * link could not carry was.
+ *
+ * The tempting explanation was the frame-dropping path — discarding one delta makes every later
+ * delta in its GOP undecodable, so dropping under congestion really would break the picture up
+ * continuously. It was **not** what happened: `congestionState` never fired in any of those
+ * runs, because `ws.getBufferedAmount()` is Bun's *userspace* queue and it drains into the
+ * kernel socket buffer, so it never reached `BACKPRESSURE_THRESHOLD_BYTES`. The keyframe rate
+ * gives it away — 0.75/s against a 30-frame GOP is ffmpeg encoding at 22 fps, not a server
+ * discarding two thirds of what it encoded.
+ *
+ * So the measured fix is the ladder: a rung now sets only a bitrate *ratio* against
+ * `base_bitrate(w, h)`, which for a 3440x1440 display makes the top rung 6 Mbit/s rather than
+ * 25, and the stream holds **30.0 fps with a 42 ms maximum gap over both a 5 Mbit/s and a
+ * 2 Mbit/s link**.
+ *
+ * What is here regardless is RustDesk's own rule, because the old code had a real defect even if
+ * it was not the one being reported: choosing a rung used to set `autoQuality = false`, which
+ * turned the adaptation off entirely and left frame-dropping as the only remaining response.
+ * `video_qos.rs` is explicit that the choice is a *maximum* — "user set image quality => update
+ * to the **maximum** ratio of the latest quality" — with the adaptation always running
+ * underneath it, and encoded frames never thrown away. It reduces the bitrate ratio first and
+ * only then the frame rate, because "bitrate-targeted encoders do not send fewer bytes at fewer
+ * frames".
+ *
+ * Two caveats on `nextRatioScale`, stated rather than implied. It nudges where RustDesk nudges
+ * every three seconds: ours cannot, because every bitrate change respawns ffmpeg for ~400 ms, so
+ * the same idea is applied in coarse steps behind `CHANGE_COOLDOWN_MS`. And it is **unit-tested
+ * only** — no end-to-end run has exercised it, because the detector it hangs off did not fire
+ * even at 0.4 Mbit/s with a relay applying real TCP backpressure. If congestion needs to be
+ * acted on in practice, the thing to fix first is the *signal*, not this policy.
+ */
+
+export {
+  DEFAULT_FPS, DEFAULT_PRESET_ID, QUALITY_PRESETS, QUALITY_PRESET_ORDER, parsePresetId,
+  type QualityPreset, type QualityPresetId, type QualityRung,
+} from "../../shared/remote-desktop-quality.ts";
+
+/** Backpressure events within `DEGRADE_WINDOW_MS` that mean "this link is not keeping up".
+ *  One event is a hiccup — a scroll, a video frame, a tunnel reconnect. */
+export const DEGRADE_EVENT_THRESHOLD = 3;
+export const DEGRADE_WINDOW_MS = 5_000;
+/** Quiet stretch before climbing back toward the chosen rung. Long, because the cost of
+ *  guessing wrong is a stall and then a second respawn to undo it. */
+export const UPGRADE_QUIET_MS = 20_000;
+/** Floor between two changes, whichever direction — bounds the respawn hitch to at worst one
+ *  per this interval no matter how the link behaves. */
+export const CHANGE_COOLDOWN_MS = 10_000;
+
+/** Each reduction multiplies the ratio by this; each recovery divides by it. 0.6 is a third of
+ *  the way down per step, so three steps reach the floor — few enough that a genuinely bad link
+ *  settles inside a minute, coarse enough that each step is worth a respawn. */
+export const CONGESTION_STEP = 0.6;
+/** How far below the chosen rung congestion may go. At `balanced` (ratio 0.67) this bottoms out
+ *  at 0.13, which `clampRatio` then lifts to RustDesk's own `BR_MIN` of 0.2. */
+export const CONGESTION_MIN_SCALE = 0.2;
+
+/** Bytes buffered on the socket above which the link is considered behind. */
+export const BACKPRESSURE_THRESHOLD_BYTES = 512 * 1024;
+/** How long it must *stay* above that before frames are discarded — see `congestionState`. */
+export const BACKPRESSURE_SUSTAIN_MS = 250;
+
+/**
+ * Whether the socket is genuinely congested, given how long it has been backed up.
+ *
+ * Reacting to the first over-threshold frame is strictly counterproductive, and measurably so:
+ * discarding one delta makes every later delta in that GOP undecodable, so the client freezes
+ * until the next keyframe. A **120 ms** spike bought a **502 ms** frozen picture that way. A
+ * spike that short is a client GC pause or a single wifi retransmit — it drains on its own, and
+ * riding it out costs only the few hundred KB that keep flowing meanwhile.
+ *
+ * `since` is the caller's previous value, threaded back in so this stays pure.
+ */
+export function congestionState(
+  since: number | null, buffered: number, now: number,
+): { since: number | null; congested: boolean } {
+  if (buffered <= BACKPRESSURE_THRESHOLD_BYTES) return { since: null, congested: false };
+  const startedAt = since ?? now;
+  return { since: startedAt, congested: now - startedAt >= BACKPRESSURE_SUSTAIN_MS };
+}
+
+export interface AdaptiveState {
+  /** Timestamps of recent backpressure events, pruned to `DEGRADE_WINDOW_MS`. */
+  events: number[];
+  /** When the bitrate last changed, so a flapping link cannot respawn ffmpeg repeatedly. */
+  lastChangeAt: number;
+}
+
+export function initialAdaptiveState(now: number): AdaptiveState {
+  return { events: [], lastChangeAt: now };
+}
+
+/** Record a backpressure event, dropping any older than the window. */
+export function noteBackpressure(state: AdaptiveState, now: number): AdaptiveState {
+  const events = [...state.events, now].filter((t) => now - t <= DEGRADE_WINDOW_MS);
+  return { ...state, events };
+}
+
+/**
+ * The scale the effective bitrate ratio should be at, or null to stay put. Pure so the whole
+ * policy is testable without a socket: `current` is the scale in force (1 = the chosen rung's
+ * own ratio, nothing held back), `state` is the session's backpressure history.
+ *
+ * Never returns above 1: the rung the user picked is the ceiling, and a quiet link is not a
+ * reason to spend more than they asked for.
+ */
+export function nextRatioScale(
+  current: number, state: AdaptiveState, now: number,
+): number | null {
+  if (now - state.lastChangeAt < CHANGE_COOLDOWN_MS) return null;
+
+  const recent = state.events.filter((t) => now - t <= DEGRADE_WINDOW_MS);
+  if (recent.length >= DEGRADE_EVENT_THRESHOLD) {
+    if (current <= CONGESTION_MIN_SCALE) return null; // already as low as this goes
+    return Math.max(CONGESTION_MIN_SCALE, current * CONGESTION_STEP);
+  }
+
+  const lastEvent = state.events.length > 0 ? Math.max(...state.events) : null;
+  const quietFor = lastEvent === null ? now - state.lastChangeAt : now - lastEvent;
+  if (quietFor >= UPGRADE_QUIET_MS && current < 1) {
+    return Math.min(1, current / CONGESTION_STEP);
+  }
+  return null;
+}