@hienlh/ppm 0.18.16 → 0.19.1

package/src/services/edge-forwarder.ts

@@ -1,191 +1,191 @@
-/**
- * Edge forwarder — owns the public port and pipes raw TCP to the server's
- * current loopback port.
- *
- * ─── CRITICAL INVARIANT: THIS PROCESS MUST NEVER SPAWN A CHILD ───
- *
- * On Windows a child spawned with fd stdio inherits every inheritable handle,
- * including a listening socket. When such a descendant is orphaned it keeps the
- * socket open, so the port stays in LISTEN under a dead PID and can never be
- * rebound — a "zombie port". The server hits this constantly because it spawns
- * chat/tool/MCP subprocesses; those inherit its listener and wedge its port.
- *
- * The edge exists precisely because it spawns nothing, so its socket cannot be
- * inherited and its port cannot zombie. cloudflared can therefore stay pinned
- * to it forever and the public URL stops rotating. Adding any child-process
- * call to this file reintroduces the exact bug the edge was built to remove.
- *
- * Raw TCP, never HTTP: WebSocket upgrades and SSE streams pass through
- * untouched, and forwarded requests keep the headers cloudflared set.
- */
-import net from "node:net";
-import { resolveTargetPort, _resetTargetCache } from "./edge-target-resolver.ts";
-
-/** Delay between attempts while waiting for the server to come back. */
-const CONNECT_RETRY_MS = 250;
-/**
- * How long a client connection waits for a reachable server before giving up.
- * During an upgrade the server is briefly absent; refusing instantly would
- * surface as a broken page rather than a slow one.
- */
-const CONNECT_WINDOW_MS = 5000;
-
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-
-/** Resolve once the socket is connected; reject on the first connect error. */
-function connectUpstream(port: number): Promise<net.Socket> {
-  return new Promise((resolvePromise, reject) => {
-    const upstream = net.connect({
-      port,
-      host: "127.0.0.1", // never taken from status.json — loopback only
-      allowHalfOpen: true,
-    });
-    const onError = (err: Error) => {
-      upstream.destroy();
-      reject(err);
-    };
-    upstream.once("error", onError);
-    upstream.once("connect", () => {
-      upstream.removeListener("error", onError);
-      resolvePromise(upstream);
-    });
-  });
-}
-
-/**
- * Largest amount of client data held while waiting for the server. Bounds the
- * memory a slow upload can pin during an upgrade window.
- */
-const MAX_PENDING_BYTES = 8 * 1024 * 1024;
-
-/**
- * Pipe one client connection to the server.
- *
- * Resolving the upstream is async, so the first bytes usually arrive before
- * there is anywhere to send them. They must be captured by a `data` listener
- * attached synchronously on this very tick and replayed once the upstream
- * exists.
- *
- * `socket.pause()` is NOT a substitute — verified against Bun 1.3.13: bytes
- * that arrive while paused are lost, and a later `pipe()`/`resume()` does not
- * bring them back. A socket with no `data` listener drops them outright too.
- * Both variants silently swallowed the first request in testing.
- */
-async function handleConnection(
-  client: net.Socket,
-  connectWindowMs: number,
-): Promise<void> {
-  const pending: Buffer[] = [];
-  let pendingBytes = 0;
-  let clientEnded = false;
-  const onEarlyData = (chunk: Buffer) => {
-    pendingBytes += chunk.length;
-    if (pendingBytes > MAX_PENDING_BYTES) {
-      client.destroy();
-      return;
-    }
-    pending.push(chunk);
-  };
-  client.on("data", onEarlyData);
-  client.once("end", () => { clientEnded = true; });
-
-  let upstream: net.Socket | null = null;
-  let clientGone = false;
-
-  // A socket error with no listener is an unhandled 'error' event, which would
-  // take the whole edge process — and the public port — down with it.
-  const teardown = () => {
-    upstream?.destroy();
-    client.destroy();
-  };
-  client.on("error", teardown);
-  client.once("close", () => { clientGone = true; });
-
-  const deadline = Date.now() + connectWindowMs;
-  while (!clientGone && Date.now() < deadline) {
-    const port = resolveTargetPort();
-    if (port !== null) {
-      try {
-        upstream = await connectUpstream(port);
-        break;
-      } catch {
-        // Server not up yet (or moved mid-restart) — re-resolve and retry.
-        _resetTargetCache();
-      }
-    }
-    await sleep(CONNECT_RETRY_MS);
-  }
-
-  if (clientGone) return;
-  if (!upstream) {
-    client.destroy();
-    return;
-  }
-
-  upstream.on("error", teardown);
-
-  // Replay what arrived during the connect, then hand both directions to the
-  // stream machinery. Removing the listener and piping happen in the same tick,
-  // so no chunk can slip through the gap.
-  client.off("data", onEarlyData);
-  for (const chunk of pending) upstream.write(chunk);
-  pending.length = 0;
-
-  client.pipe(upstream);
-  upstream.pipe(client);
-
-  // The client may have half-closed while we were still connecting.
-  if (clientEnded) upstream.end();
-}
-
-export interface EdgeForwarderOptions {
-  publicPort: number;
-  host?: string;
-  /** How long a client waits for a reachable server. Defaults to 5s. */
-  connectWindowMs?: number;
-}
-
-/**
- * Bind the public port and start forwarding. Resolves once listening so the
- * caller can fail fast when the port is unavailable.
- */
-export function startEdgeForwarder(
-  opts: EdgeForwarderOptions,
-): Promise<net.Server> {
-  const host = opts.host ?? "0.0.0.0";
-  const connectWindowMs = opts.connectWindowMs ?? CONNECT_WINDOW_MS;
-  return new Promise((resolvePromise, reject) => {
-    // allowHalfOpen keeps the other direction alive when one side sends FIN —
-    // long-lived chat WS and SSE streams depend on it.
-    const server = net.createServer({ allowHalfOpen: true }, (client) => {
-      void handleConnection(client, connectWindowMs);
-    });
-    server.once("error", reject);
-    server.listen(opts.publicPort, host, () => {
-      server.removeListener("error", reject);
-      resolvePromise(server);
-    });
-  });
-}
-
-// ─── Process entry ─────────────────────────────────────────────────────
-// Mirrors the `__serve__` guard in src/server/index.ts: the supervisor
-// re-invokes the binary as `<bin> __edge__ <publicPort> <host>`.
-if (process.argv.includes("__edge__")) {
-  const idx = process.argv.indexOf("__edge__");
-  const publicPort = parseInt(process.argv[idx + 1] ?? "", 10);
-  const host = process.argv[idx + 2] ?? "0.0.0.0";
-
-  if (!Number.isInteger(publicPort) || publicPort <= 0 || publicPort > 65535) {
-    process.stderr.write(`[edge] Invalid public port: ${process.argv[idx + 1]}\n`);
-    process.exit(2);
-  }
-
-  try {
-    await startEdgeForwarder({ publicPort, host });
-    process.stderr.write(`[edge] Listening on ${host}:${publicPort}\n`);
-  } catch (err) {
-    process.stderr.write(`[edge] Failed to bind ${host}:${publicPort}: ${err}\n`);
-    process.exit(1);
-  }
-}
+/**
+ * Edge forwarder — owns the public port and pipes raw TCP to the server's
+ * current loopback port.
+ *
+ * ─── CRITICAL INVARIANT: THIS PROCESS MUST NEVER SPAWN A CHILD ───
+ *
+ * On Windows a child spawned with fd stdio inherits every inheritable handle,
+ * including a listening socket. When such a descendant is orphaned it keeps the
+ * socket open, so the port stays in LISTEN under a dead PID and can never be
+ * rebound — a "zombie port". The server hits this constantly because it spawns
+ * chat/tool/MCP subprocesses; those inherit its listener and wedge its port.
+ *
+ * The edge exists precisely because it spawns nothing, so its socket cannot be
+ * inherited and its port cannot zombie. cloudflared can therefore stay pinned
+ * to it forever and the public URL stops rotating. Adding any child-process
+ * call to this file reintroduces the exact bug the edge was built to remove.
+ *
+ * Raw TCP, never HTTP: WebSocket upgrades and SSE streams pass through
+ * untouched, and forwarded requests keep the headers cloudflared set.
+ */
+import net from "node:net";
+import { resolveTargetPort, _resetTargetCache } from "./edge-target-resolver.ts";
+
+/** Delay between attempts while waiting for the server to come back. */
+const CONNECT_RETRY_MS = 250;
+/**
+ * How long a client connection waits for a reachable server before giving up.
+ * During an upgrade the server is briefly absent; refusing instantly would
+ * surface as a broken page rather than a slow one.
+ */
+const CONNECT_WINDOW_MS = 5000;
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/** Resolve once the socket is connected; reject on the first connect error. */
+function connectUpstream(port: number): Promise<net.Socket> {
+  return new Promise((resolvePromise, reject) => {
+    const upstream = net.connect({
+      port,
+      host: "127.0.0.1", // never taken from status.json — loopback only
+      allowHalfOpen: true,
+    });
+    const onError = (err: Error) => {
+      upstream.destroy();
+      reject(err);
+    };
+    upstream.once("error", onError);
+    upstream.once("connect", () => {
+      upstream.removeListener("error", onError);
+      resolvePromise(upstream);
+    });
+  });
+}
+
+/**
+ * Largest amount of client data held while waiting for the server. Bounds the
+ * memory a slow upload can pin during an upgrade window.
+ */
+const MAX_PENDING_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Pipe one client connection to the server.
+ *
+ * Resolving the upstream is async, so the first bytes usually arrive before
+ * there is anywhere to send them. They must be captured by a `data` listener
+ * attached synchronously on this very tick and replayed once the upstream
+ * exists.
+ *
+ * `socket.pause()` is NOT a substitute — verified against Bun 1.3.13: bytes
+ * that arrive while paused are lost, and a later `pipe()`/`resume()` does not
+ * bring them back. A socket with no `data` listener drops them outright too.
+ * Both variants silently swallowed the first request in testing.
+ */
+async function handleConnection(
+  client: net.Socket,
+  connectWindowMs: number,
+): Promise<void> {
+  const pending: Buffer[] = [];
+  let pendingBytes = 0;
+  let clientEnded = false;
+  const onEarlyData = (chunk: Buffer) => {
+    pendingBytes += chunk.length;
+    if (pendingBytes > MAX_PENDING_BYTES) {
+      client.destroy();
+      return;
+    }
+    pending.push(chunk);
+  };
+  client.on("data", onEarlyData);
+  client.once("end", () => { clientEnded = true; });
+
+  let upstream: net.Socket | null = null;
+  let clientGone = false;
+
+  // A socket error with no listener is an unhandled 'error' event, which would
+  // take the whole edge process — and the public port — down with it.
+  const teardown = () => {
+    upstream?.destroy();
+    client.destroy();
+  };
+  client.on("error", teardown);
+  client.once("close", () => { clientGone = true; });
+
+  const deadline = Date.now() + connectWindowMs;
+  while (!clientGone && Date.now() < deadline) {
+    const port = resolveTargetPort();
+    if (port !== null) {
+      try {
+        upstream = await connectUpstream(port);
+        break;
+      } catch {
+        // Server not up yet (or moved mid-restart) — re-resolve and retry.
+        _resetTargetCache();
+      }
+    }
+    await sleep(CONNECT_RETRY_MS);
+  }
+
+  if (clientGone) return;
+  if (!upstream) {
+    client.destroy();
+    return;
+  }
+
+  upstream.on("error", teardown);
+
+  // Replay what arrived during the connect, then hand both directions to the
+  // stream machinery. Removing the listener and piping happen in the same tick,
+  // so no chunk can slip through the gap.
+  client.off("data", onEarlyData);
+  for (const chunk of pending) upstream.write(chunk);
+  pending.length = 0;
+
+  client.pipe(upstream);
+  upstream.pipe(client);
+
+  // The client may have half-closed while we were still connecting.
+  if (clientEnded) upstream.end();
+}
+
+export interface EdgeForwarderOptions {
+  publicPort: number;
+  host?: string;
+  /** How long a client waits for a reachable server. Defaults to 5s. */
+  connectWindowMs?: number;
+}
+
+/**
+ * Bind the public port and start forwarding. Resolves once listening so the
+ * caller can fail fast when the port is unavailable.
+ */
+export function startEdgeForwarder(
+  opts: EdgeForwarderOptions,
+): Promise<net.Server> {
+  const host = opts.host ?? "0.0.0.0";
+  const connectWindowMs = opts.connectWindowMs ?? CONNECT_WINDOW_MS;
+  return new Promise((resolvePromise, reject) => {
+    // allowHalfOpen keeps the other direction alive when one side sends FIN —
+    // long-lived chat WS and SSE streams depend on it.
+    const server = net.createServer({ allowHalfOpen: true }, (client) => {
+      void handleConnection(client, connectWindowMs);
+    });
+    server.once("error", reject);
+    server.listen(opts.publicPort, host, () => {
+      server.removeListener("error", reject);
+      resolvePromise(server);
+    });
+  });
+}
+
+// ─── Process entry ─────────────────────────────────────────────────────
+// Mirrors the `__serve__` guard in src/server/index.ts: the supervisor
+// re-invokes the binary as `<bin> __edge__ <publicPort> <host>`.
+if (process.argv.includes("__edge__")) {
+  const idx = process.argv.indexOf("__edge__");
+  const publicPort = parseInt(process.argv[idx + 1] ?? "", 10);
+  const host = process.argv[idx + 2] ?? "0.0.0.0";
+
+  if (!Number.isInteger(publicPort) || publicPort <= 0 || publicPort > 65535) {
+    process.stderr.write(`[edge] Invalid public port: ${process.argv[idx + 1]}\n`);
+    process.exit(2);
+  }
+
+  try {
+    await startEdgeForwarder({ publicPort, host });
+    process.stderr.write(`[edge] Listening on ${host}:${publicPort}\n`);
+  } catch (err) {
+    process.stderr.write(`[edge] Failed to bind ${host}:${publicPort}: ${err}\n`);
+    process.exit(1);
+  }
+}

package/src/services/media-transcode/ffmpeg-capabilities.ts

@@ -2,9 +2,15 @@
  * Discover ffmpeg/ffprobe on this machine and pick the fastest working H.264 encoder.
  *
  * ffmpeg is an *optional* dependency: without it PPM still plays browser-native
- * media (mp4/webm) via Range requests, it just cannot transcode AVI/MKV. The
- * result is cached for the process lifetime — the binary does not appear
- * mid-session, and probing hardware encoders costs a real encode each.
+ * media (mp4/webm) via Range requests, it just cannot transcode AVI/MKV. A
+ * positive result is cached for the process lifetime — probing hardware encoders
+ * costs a real encode each. A *negative* result is not: the remote-desktop
+ * checklist tells the user to install ffmpeg and promises to notice, so "not
+ * found" is re-checked on every call (one `which` + a few `stat`s).
+ *
+ * `PATH` alone is not enough to find it. A daemon started by launchd inherits
+ * `/usr/bin:/bin:/usr/sbin:/sbin` — Homebrew's `/opt/homebrew/bin` is not on it —
+ * so the well-known install directories are probed after `Bun.which`.
  *
  * Hardware encoders are verified by encoding a few synthetic frames rather than by
  * grepping `ffmpeg -encoders`: the list only says the build was compiled with
@@ -60,11 +66,42 @@ async function encoderWorks(ffmpeg: string, encoder: string): Promise<boolean> {
   }
 }
 
+/** Where package managers put ffmpeg when it is not on the daemon's PATH. */
+function wellKnownBinDirs(): string[] {
+  switch (process.platform) {
+    case "darwin": return ["/opt/homebrew/bin", "/usr/local/bin", "/opt/local/bin"];
+    case "win32": {
+      const local = process.env.LOCALAPPDATA;
+      return [
+        ...(local ? [`${local}\\Microsoft\\WinGet\\Links`] : []),
+        "C:\\ProgramData\\chocolatey\\bin", "C:\\ffmpeg\\bin",
+      ];
+    }
+    default: return ["/usr/local/bin", "/usr/bin", "/snap/bin", `${process.env.HOME ?? ""}/.local/bin`];
+  }
+}
+
+/** `Bun.which` on `searchPath` (the process PATH by default) first, then the well-known
+ *  directories. Exported for tests. */
+export function findFfmpegBinary(
+  name: "ffmpeg" | "ffprobe",
+  dirs: string[] = wellKnownBinDirs(),
+  searchPath: string | undefined = process.env.PATH,
+): string | null {
+  const onPath = Bun.which(name, searchPath ? { PATH: searchPath } : undefined);
+  if (onPath) return onPath;
+  for (const dir of dirs) {
+    const found = Bun.which(name, { PATH: dir });
+    if (found) return found;
+  }
+  return null;
+}
+
 let cached: Promise<FfmpegCapabilities> | null = null;
 
 async function detect(): Promise<FfmpegCapabilities> {
-  const ffmpeg = Bun.which("ffmpeg");
-  const ffprobe = Bun.which("ffprobe");
+  const ffmpeg = findFfmpegBinary("ffmpeg");
+  const ffprobe = findFfmpegBinary("ffprobe");
   if (!ffmpeg) return { ffmpeg: null, ffprobe, encoder: null };
   for (const candidate of encoderCandidates()) {
     if (await encoderWorks(ffmpeg, candidate)) return { ffmpeg, ffprobe, encoder: candidate };
@@ -72,10 +109,14 @@ async function detect(): Promise<FfmpegCapabilities> {
   return { ffmpeg, ffprobe, encoder: null };
 }
 
-/** Cached capability lookup; the first call pays for the encoder probes. */
+/** Cached capability lookup; the first call that finds ffmpeg pays for the encoder probes.
+ *  "Not installed" is never cached — the user may be running `brew install ffmpeg` right now. */
 export function getFfmpegCapabilities(): Promise<FfmpegCapabilities> {
   if (!cached) {
-    cached = detect().catch((e) => {
+    cached = detect().then((caps) => {
+      if (!caps.ffmpeg) cached = null;
+      return caps;
+    }).catch((e) => {
       cached = null; // let a later call retry after an unexpected failure
       throw e;
     });

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

@@ -0,0 +1,62 @@
+/**
+ * Per-platform ffmpeg *input* side of the capture pipeline. The shared low-latency flags and
+ * the encoder live in `remote-desktop-capture.ts` / `remote-desktop-encoder-args.ts`; this file
+ * only answers "which grabber, pointed at what, filtered how".
+ *
+ * macOS (`avfoundation`) lessons, measured on macOS 26 / ffmpeg 7.1.1:
+ * - Devices are addressed by NAME, never by index. avfoundation lists cameras before screens
+ *   and the list changes at runtime (an iPhone Continuity Camera joining/leaving moved
+ *   "Capture screen 0" from index 5 to 3 and back within a minute) — an index captured at
+ *   detect time pointed at the phone camera by spawn time. Addressing by name also removes
+ *   the `-list_devices` pre-flight, which cost 0.4–1 s per session start.
+ * - `-framerate 30` is ignored: the screen input delivers at display refresh (120–165 fps on
+ *   ProMotion) with a pts that never advances. `-use_wallclock_as_timestamps 1` restores pts
+ *   and an `fps=30` filter drops back to the target rate (measured 29 fps steady, ~1.3 s to
+ *   first frame). Without it the encoder spends 6 Mbit/s and a 30-frame GOP on 160 fps.
+ * - `-pixel_format nv12` on the input side: the device has no yuv420p, and letting the output
+ *   `-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.
+ */
+import { CAPTURE_FRAMERATE } from "./remote-desktop-encoder-args.ts";
+
+export type CaptureInput =
+  | { kind: "gdigrab" }
+  | { kind: "avfoundation"; screen: string };
+
+/** 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[] {
+  switch (input.kind) {
+    case "gdigrab":
+      return ["-f", "gdigrab", "-framerate", String(CAPTURE_FRAMERATE), "-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];
+  }
+}
+
+/** `-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;
+}
+
+/** 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 {
+  switch (platform) {
+    case "win32": return { kind: "gdigrab" };
+    case "darwin": return { kind: "avfoundation", screen: avfoundationScreenName(captureIndex) };
+    default: return null;
+  }
+}

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

@@ -1,5 +1,5 @@
 /**
- * Spawn ffmpeg (`gdigrab` → H.264 Annex-B on `pipe:1`) and turn its stdout into access units.
+ * Spawn ffmpeg (platform grabber → H.264 Annex-B on `pipe:1`) and turn its stdout into access units.
  *
  * Teardown is `proc.kill()` only — never `reader.cancel()`, never `for await (chunk of
  * proc.stdout) { ... break }`. Both of those cancel the underlying stream reader, which
@@ -11,27 +11,35 @@
  * its own — it is never cancelled from outside.
  */
 import { getFfmpegCapabilities } from "../media-transcode/ffmpeg-capabilities.ts";
-import { captureEncoderArgs, CAPTURE_FRAMERATE } from "./remote-desktop-encoder-args.ts";
+import { captureEncoderArgs } from "./remote-desktop-encoder-args.ts";
+import {
+  captureInputArgs, captureVideoFilter, captureInputForPlatform, type CaptureInput,
+} from "./remote-desktop-capture-input.ts";
 import { AccessUnitAssembler, type AccessUnit } from "./access-unit-assembler.ts";
+import type { RemoteDisplay } from "./remote-desktop-displays.ts";
 
 export class CaptureUnavailableError extends Error {
-  constructor(msg = "ffmpeg is not installed (gdigrab capture requires it)") {
+  constructor(msg = "ffmpeg is not installed (screen capture requires it)") {
     super(msg);
     this.name = "CaptureUnavailableError";
   }
 }
 
-/** Build the gdigrab argv; pure so it can be asserted on without spawning a process.
+/** Build the capture argv; pure so it can be asserted on without spawning a process.
  *  `-fflags nobuffer -flags low_delay` + `-flush_packets 1` stop ffmpeg from holding frames in
  *  its demux/mux buffers before emitting — on a fast/LAN transport that buffering is a big slice
- *  of the felt lag. `encoder` selects the H.264 encoder args (hardware NVENC/QSV/AMF when the
- *  capability probe found one, else libx264). */
-export function buildCaptureArgs(ffmpeg: string, encoder: string = "libx264"): string[] {
+ *  of the felt lag. `encoder` selects the H.264 encoder args (hardware NVENC/QSV/AMF/VideoToolbox
+ *  when the capability probe found one, else libx264); `input` selects the platform grabber. */
+export function buildCaptureArgs(
+  ffmpeg: string,
+  encoder: string = "libx264",
+  input: CaptureInput = { kind: "gdigrab" },
+): string[] {
   return [
     ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin",
     "-fflags", "nobuffer", "-flags", "low_delay",
-    "-f", "gdigrab", "-framerate", String(CAPTURE_FRAMERATE), "-i", "desktop",
-    "-vf", "scale=-2:720",
+    ...captureInputArgs(input),
+    "-vf", captureVideoFilter(input),
     ...captureEncoderArgs(encoder),
     "-flush_packets", "1",
     "-f", "h264", "pipe:1",
@@ -49,6 +57,8 @@ export interface CaptureHandle {
 }
 
 export interface StartCaptureOptions {
+  /** Which display to grab; null/undefined = the platform default (primary / whole desktop). */
+  display?: RemoteDisplay | null;
   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
@@ -58,12 +68,15 @@ export interface StartCaptureOptions {
   onExit?: (code: number | null, reason?: string) => void;
 }
 
-/** Start gdigrab capture. Rejects immediately if ffmpeg is not on PATH. */
+/** Start screen capture. Rejects immediately if ffmpeg is not on PATH or the platform has
+ *  no supported grabber. */
 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);
+  if (!input) throw new CaptureUnavailableError(`no screen capture input on ${process.platform}`);
 
-  const proc = Bun.spawn(buildCaptureArgs(caps.ffmpeg, caps.encoder ?? "libx264"), {
+  const proc = Bun.spawn(buildCaptureArgs(caps.ffmpeg, caps.encoder ?? "libx264", input), {
     stdout: "pipe",
     stderr: "pipe",
     stdin: "ignore",
@@ -73,7 +86,11 @@ export async function startCapture(opts: StartCaptureOptions): Promise<CaptureHa
   const stop = () => {
     if (stopped) return;
     stopped = true;
-    if (!proc.killed) proc.kill();
+    // SIGKILL, not the default SIGTERM: ffmpeg's avfoundation input hangs on SIGTERM/SIGINT
+    // during capture-session teardown (verified on macOS 26 — the process stayed alive for
+    // minutes after both) and would leak one screen-capture ffmpeg per remote-desktop session.
+    // On Windows Bun's kill is TerminateProcess either way, so the semantics are unchanged.
+    if (!proc.killed) proc.kill("SIGKILL");
   };
 
   // Drain stderr so ffmpeg never blocks on a full pipe; keep a short tail for diagnostics.

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

@@ -0,0 +1,45 @@
+/**
+ * `KeyboardEvent.code` (physical key, layout-independent) → macOS virtual keycode (CGKeyCode,
+ * the `kVK_*` constants from HIToolbox/Events.h, ANSI layout). Same contract as
+ * `remote-desktop-vk-map.ts`: only `code` is accepted, never `key`.
+ *
+ * Web `MetaLeft/MetaRight` = Command, `AltLeft/AltRight` = Option. `ContextMenu` has no Mac
+ * key and stays unmapped on purpose.
+ */
+const CODE_TO_CGKEY: Record<string, number> = {
+  KeyA: 0x00, KeyS: 0x01, KeyD: 0x02, KeyF: 0x03, KeyH: 0x04, KeyG: 0x05, KeyZ: 0x06, KeyX: 0x07,
+  KeyC: 0x08, KeyV: 0x09, KeyB: 0x0b, KeyQ: 0x0c, KeyW: 0x0d, KeyE: 0x0e, KeyR: 0x0f, KeyY: 0x10,
+  KeyT: 0x11, Digit1: 0x12, Digit2: 0x13, Digit3: 0x14, Digit4: 0x15, Digit6: 0x16, Digit5: 0x17,
+  Equal: 0x18, Digit9: 0x19, Digit7: 0x1a, Minus: 0x1b, Digit8: 0x1c, Digit0: 0x1d,
+  BracketRight: 0x1e, KeyO: 0x1f, KeyU: 0x20, BracketLeft: 0x21, KeyI: 0x22, KeyP: 0x23,
+  Enter: 0x24, KeyL: 0x25, KeyJ: 0x26, Quote: 0x27, KeyK: 0x28, Semicolon: 0x29, Backslash: 0x2a,
+  Comma: 0x2b, Slash: 0x2c, KeyN: 0x2d, KeyM: 0x2e, Period: 0x2f, Tab: 0x30, Space: 0x31,
+  Backquote: 0x32, Backspace: 0x33, Escape: 0x35,
+  MetaRight: 0x36, MetaLeft: 0x37, ShiftLeft: 0x38, CapsLock: 0x39, AltLeft: 0x3a, ControlLeft: 0x3b,
+  ShiftRight: 0x3c, AltRight: 0x3d, ControlRight: 0x3e,
+  NumpadDecimal: 0x41, NumpadMultiply: 0x43, NumpadAdd: 0x45, NumLock: 0x47, NumpadDivide: 0x4b,
+  NumpadEnter: 0x4c, NumpadSubtract: 0x4e, NumpadEqual: 0x51,
+  Numpad0: 0x52, Numpad1: 0x53, Numpad2: 0x54, Numpad3: 0x55, Numpad4: 0x56, Numpad5: 0x57,
+  Numpad6: 0x58, Numpad7: 0x59, Numpad8: 0x5b, Numpad9: 0x5c,
+  F5: 0x60, F6: 0x61, F7: 0x62, F3: 0x63, F8: 0x64, F9: 0x65, F11: 0x67, F13: 0x69, F14: 0x6b,
+  F10: 0x6d, F12: 0x6f, F15: 0x71, Insert: 0x72 /* Help/Insert */, Home: 0x73, PageUp: 0x74,
+  Delete: 0x75 /* forward delete */, F4: 0x76, End: 0x77, F2: 0x78, PageDown: 0x79, F1: 0x7a,
+  ArrowLeft: 0x7b, ArrowRight: 0x7c, ArrowDown: 0x7d, ArrowUp: 0x7e,
+};
+
+/** CGEventFlags bit for each modifier keycode — macOS carries modifier *state* on every event
+ *  rather than inferring it from prior key events, so the backend must OR these in itself. */
+export const CGKEY_MODIFIER_FLAG: Record<number, number> = {
+  0x38: 0x00020000, 0x3c: 0x00020000, // Shift        → kCGEventFlagMaskShift
+  0x3b: 0x00040000, 0x3e: 0x00040000, // Control      → kCGEventFlagMaskControl
+  0x3a: 0x00080000, 0x3d: 0x00080000, // Option (Alt) → kCGEventFlagMaskAlternate
+  0x37: 0x00100000, 0x36: 0x00100000, // Command      → kCGEventFlagMaskCommand
+};
+
+/** All modifier keycodes — force-released on teardown (mirror of `MODIFIER_VK_CODES`). */
+export const MODIFIER_CGKEY_CODES = [0x38, 0x3c, 0x3b, 0x3e, 0x3a, 0x3d, 0x37, 0x36] as const;
+
+/** Resolve a `KeyboardEvent.code` to its CGKeyCode; null for anything unmapped. */
+export function codeToCgKey(code: string): number | null {
+  return CODE_TO_CGKEY[code] ?? null;
+}