@hienlh/ppm 0.18.15 → 0.19.0

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;
+}

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

@@ -0,0 +1,90 @@
+/**
+ * Which displays a remote-desktop session can capture, and where each sits in the host's
+ * global coordinate space (input for a non-primary display has to be offset by its origin).
+ *
+ * macOS: `CGGetActiveDisplayList` order is exactly avfoundation's `Capture screen N` numbering
+ * (ffmpeg builds its screen inputs from that same list) — verified: `[1]` 3440×1440 ⇔
+ * "Capture screen 1" 3440×1440. Sizes/main flag come from CoreGraphics via bun:ffi; names and
+ * bounds go through one JXA call because `CGDisplayBounds` returns a struct by value and
+ * `NSScreen.localizedName` is Objective-C — both out of bun:ffi's reach. Cached briefly: the
+ * capabilities route polls every 2 s while the checklist is up.
+ *
+ * Windows: gdigrab `desktop` grabs the whole virtual screen and SendInput maps 0..65535 onto
+ * that same rectangle, so there is exactly one "display" and no offsets to apply.
+ */
+
+export interface RemoteDisplay {
+  /** Stable per host session (`CGDirectDisplayID` on macOS, `"desktop"` on Windows). */
+  id: string;
+  label: string;
+  primary: boolean;
+  /** Origin + size in the OS's global *logical* coordinate space (points on macOS). */
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Position in the capture backend's own numbering (avfoundation `Capture screen N`). */
+  captureIndex: number;
+}
+
+const CACHE_MS = 5000;
+let cache: { at: number; displays: RemoteDisplay[] } | null = null;
+
+async function listDarwinDisplays(): Promise<RemoteDisplay[]> {
+  const { dlopen, FFIType: T, ptr } = await import("bun:ffi");
+  const cg = dlopen("/System/Library/Frameworks/CoreGraphics.framework/CoreGraphics", {
+    CGGetActiveDisplayList: { args: [T.u32, T.ptr, T.ptr], returns: T.i32 },
+    CGDisplayPixelsWide: { args: [T.u32], returns: T.u64 },
+    CGDisplayPixelsHigh: { args: [T.u32], returns: T.u64 },
+    CGDisplayIsMain: { args: [T.u32], returns: T.bool },
+  }).symbols;
+  const ids = new Uint32Array(16), count = new Uint32Array(1);
+  if (cg.CGGetActiveDisplayList(16, ptr(ids), ptr(count)) !== 0) return [];
+
+  // Names + origins in one osascript round trip (~100 ms); tolerate its absence.
+  type Meta = { id: number; name: string; x: number; y: number };
+  let meta: Meta[] = [];
+  try {
+    const proc = Bun.spawnSync(["osascript", "-l", "JavaScript", "-e",
+      'ObjC.import("AppKit"); ObjC.import("CoreGraphics"); JSON.stringify($.NSScreen.screens.js.map(s => { ' +
+      'const id = s.deviceDescription.objectForKey("NSScreenNumber").unsignedIntValue; const b = $.CGDisplayBounds(id); ' +
+      'return { id, name: s.localizedName.js, x: b.origin.x, y: b.origin.y }; }))']);
+    meta = JSON.parse(proc.stdout.toString().trim() || "[]");
+  } catch { /* names fall back to "Display N", origins to 0 — capture still works */ }
+
+  const displays: RemoteDisplay[] = [];
+  const n = count[0] ?? 0;
+  for (let i = 0; i < n; i++) {
+    const id = ids[i] ?? 0;
+    const m = meta.find((x) => x.id === id);
+    displays.push({
+      id: String(id),
+      label: m?.name ?? `Display ${i + 1}`,
+      primary: cg.CGDisplayIsMain(id),
+      x: m?.x ?? 0,
+      y: m?.y ?? 0,
+      width: Number(cg.CGDisplayPixelsWide(id)),
+      height: Number(cg.CGDisplayPixelsHigh(id)),
+      captureIndex: i,
+    });
+  }
+  return displays;
+}
+
+export async function listDisplays(platform: NodeJS.Platform = process.platform): Promise<RemoteDisplay[]> {
+  if (platform === "win32") {
+    return [{ id: "desktop", label: "All displays", primary: true, x: 0, y: 0, width: 0, height: 0, captureIndex: 0 }];
+  }
+  if (platform !== "darwin") return [];
+  if (cache && Date.now() - cache.at < CACHE_MS) return cache.displays;
+  const displays = await listDarwinDisplays();
+  cache = { at: Date.now(), displays };
+  return displays;
+}
+
+/** The display a session should capture: the requested one when it still exists (a monitor
+ *  can be unplugged between the client's pick and connect), else the primary. */
+export async function resolveDisplay(id: string | undefined): Promise<RemoteDisplay | null> {
+  const displays = await listDisplays();
+  return displays.find((d) => d.id === id) ?? displays.find((d) => d.primary) ?? displays[0] ?? null;
+}

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

@@ -32,6 +32,13 @@ export function captureEncoderArgs(encoder: string = "libx264"): string[] {
       return ["-c:v", "h264_qsv", "-preset", "veryfast", "-low_power", "1", "-bufsize", "512k", ...common];
     case "h264_amf":
       return ["-c:v", "h264_amf", "-quality", "speed", "-rc", "cbr", "-bufsize", "512k", ...common];
+    case "h264_videotoolbox":
+      // macOS hardware encode. `-realtime 1` asks VT to hit the deadline over quality,
+      // `-prio_speed 1` likewise; `-allow_sw 1` keeps it working on hosts where the hardware
+      // encoder is busy/unavailable rather than failing the session. Verified on macOS 26:
+      // emits SPS/PPS/SEI before every IDR and one slice per frame, so the AU assembler's
+      // assumptions hold unchanged.
+      return ["-c:v", "h264_videotoolbox", "-realtime", "1", "-prio_speed", "1", "-allow_sw", "1", ...common];
     default:
       // libx264 low-latency. `-tune zerolatency` enables sliced-threads (multi-slice NALs);
       // access-unit-assembler.ts assumes one slice/frame, so force it back with sliced-threads=0.

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

@@ -1,10 +1,12 @@
 /**
- * Feature flag gate. A live video+input channel to the host must never be reachable just
- * because the code shipped — default OFF until phase-07 hardening (host-approval prompt,
- * signed input path) lands. Every entry point (REST routes, WS upgrade) checks this
- * independently rather than trusting a single call site.
+ * Feature switch. Remote desktop is ON by default — the viewer itself shows a warning before
+ * the first frame is streamed (`remote-desktop-warning-gate.tsx`) and every entry point still
+ * sits behind PPM auth. `REMOTE_DESKTOP_ENABLED=0` (or `false`) turns the whole surface off for
+ * hosts that never want a live video+input channel reachable, e.g. one exposed on a public
+ * tunnel. Every entry point (REST routes, WS upgrade) checks this independently rather than
+ * trusting a single call site.
  */
 export function isRemoteDesktopEnabled(): boolean {
-  const v = process.env.REMOTE_DESKTOP_ENABLED;
-  return v === "1" || v === "true";
+  const v = process.env.REMOTE_DESKTOP_ENABLED?.trim().toLowerCase();
+  return !(v === "0" || v === "false");
 }

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

@@ -0,0 +1,36 @@
+/**
+ * Contract every platform input injector implements. `remote-desktop-input.ts` picks one per
+ * `process.platform`; adding an OS = one new module + one registry line there, nothing else
+ * (the session and the routes only ever talk to the facade).
+ *
+ * All coordinates are 0..1 fractions of the captured frame — the backend owns the mapping to
+ * whatever its OS wants (65535-normalised for SendInput, logical points for CoreGraphics).
+ * Keys are KeyboardEvent `code`s (physical, layout-independent); the backend owns the table.
+ */
+
+/** Where the captured frame sits in the OS's global logical coordinates — what a 0..1 fraction
+ *  is a fraction *of*. null = the backend's default surface (primary display / virtual desktop). */
+export interface InputTargetRect { x: number; y: number; width: number; height: number }
+
+export interface RemoteInputBackend {
+  /** Short id for logs/diagnostics (`"win32-sendinput"`, `"darwin-cgevent"`). Whether injection
+   *  would actually work right now (OS permissions) is a *requirement* in
+   *  `remote-desktop-requirements.ts`, not a backend concern. */
+  readonly id: string;
+  pointer(xFrac: number, yFrac: number, button: "left" | "right" | null, down: boolean | null, target: InputTargetRect | null): Promise<void>;
+  /** `deltaY` in wheel-notch units of 120 (positive = away from the user). */
+  wheel(deltaY: number): Promise<void>;
+  /** Returns false for a `code` the backend has no mapping for (caller drops it). */
+  key(code: string, down: boolean): Promise<boolean>;
+  /** Type a string as text, independent of layout. Optional: not every OS has a cheap path. */
+  text?(text: string): Promise<void>;
+  /** Force-release every modifier, regardless of tracked state — backstop for a lost keyup. */
+  releaseAllModifiers(): Promise<void>;
+}
+
+export class RemoteInputUnavailableError extends Error {
+  constructor(msg = `Remote input injection is not available on ${process.platform}`) {
+    super(msg);
+    this.name = "RemoteInputUnavailableError";
+  }
+}

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

@@ -0,0 +1,200 @@
+/**
+ * macOS input backend: Bun FFI straight into CoreGraphics (`CGEventPost` at the HID tap) — no
+ * helper binary, no signing question for the injector. Selected by `remote-desktop-input.ts`
+ * on `darwin` only; `bun:ffi` is `import()`-ed and `dlopen`-ed lazily inside `load()` so
+ * importing this module elsewhere never touches a framework.
+ *
+ * Spike facts this relies on (`plans/reports/spike-260908-remote-desktop-macos.md` §S2):
+ * - `CGPoint` is passed BY VALUE as two consecutive `double` args — matches the arm64 (d0,d1)
+ *   and x86_64 (xmm0,xmm1) ABIs, integer args keep their own registers. Struct *returns* are
+ *   not expressible, so nothing here reads the cursor back.
+ * - Injection needs the Accessibility grant on the `bun` executable (TCC); without it every
+ *   post is a silent no-op — `remote-desktop-macos-permissions.ts` pre-flights that.
+ * - Coordinates are logical points of the main display (`CGDisplayPixelsWide/High` return
+ *   points despite the name); the capture is that same display, so fractions map directly.
+ * - Modifier state is carried on every event as `CGEventFlags`; a modifier keyDown alone is
+ *   not enough, so held modifiers are tracked and OR-ed onto each subsequent event.
+ */
+import { codeToCgKey, CGKEY_MODIFIER_FLAG, MODIFIER_CGKEY_CODES } from "./remote-desktop-cg-key-map.ts";
+import { RemoteInputUnavailableError, type InputTargetRect, type RemoteInputBackend } from "./remote-desktop-input-backend.ts";
+
+const CG = "/System/Library/Frameworks/CoreGraphics.framework/CoreGraphics";
+const CORE_FOUNDATION = "/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation";
+
+// CGEventType
+const LEFT_DOWN = 1, LEFT_UP = 2, RIGHT_DOWN = 3, RIGHT_UP = 4, MOUSE_MOVED = 5;
+const LEFT_DRAGGED = 6, RIGHT_DRAGGED = 7, FLAGS_CHANGED = 12;
+const HID_EVENT_TAP = 0;
+const BUTTON_LEFT = 0, BUTTON_RIGHT = 1;
+const SCROLL_UNIT_LINE = 1;
+/** kCGMouseEventClickState — must be set on synthesized clicks or apps never see a double-click. */
+const FIELD_CLICK_STATE = 1;
+const DOUBLE_CLICK_MS = 500;
+/** One wheel notch (the client's 120-unit) scrolls this many lines, as it does on Windows. */
+const LINES_PER_NOTCH = 3;
+
+type Ptr = number | bigint;
+type Symbols = {
+  CGEventCreateMouseEvent: (src: Ptr | null, type: number, x: number, y: number, button: number) => Ptr;
+  CGEventCreateKeyboardEvent: (src: Ptr | null, keycode: number, down: boolean) => Ptr;
+  CGEventCreateScrollWheelEvent2: (src: Ptr | null, units: number, count: number, w1: number, w2: number, w3: number) => Ptr;
+  CGEventSetFlags: (ev: Ptr, flags: bigint) => void;
+  CGEventSetType: (ev: Ptr, type: number) => void;
+  CGEventSetIntegerValueField: (ev: Ptr, field: number, value: bigint) => void;
+  CGEventKeyboardSetUnicodeString: (ev: Ptr, length: bigint, utf16: Ptr) => void;
+  CGEventPost: (tap: number, ev: Ptr) => void;
+  CGMainDisplayID: () => number;
+  CGDisplayPixelsWide: (display: number) => bigint;
+  CGDisplayPixelsHigh: (display: number) => bigint;
+  CFRelease: (obj: Ptr) => void;
+};
+
+let loaded: { ffi: typeof import("bun:ffi"); lib: Symbols } | null = null;
+
+async function load() {
+  if (process.platform !== "darwin") throw new RemoteInputUnavailableError();
+  if (loaded) return loaded;
+  const ffi = await import("bun:ffi");
+  const { dlopen, FFIType: T } = ffi;
+  const cg = dlopen(CG, {
+    CGEventCreateMouseEvent: { args: [T.ptr, T.u32, T.double, T.double, T.u32], returns: T.ptr },
+    CGEventCreateKeyboardEvent: { args: [T.ptr, T.u16, T.bool], returns: T.ptr },
+    CGEventCreateScrollWheelEvent2: { args: [T.ptr, T.u32, T.u32, T.i32, T.i32, T.i32], returns: T.ptr },
+    CGEventSetFlags: { args: [T.ptr, T.u64], returns: T.void },
+    CGEventSetType: { args: [T.ptr, T.u32], returns: T.void },
+    CGEventSetIntegerValueField: { args: [T.ptr, T.u32, T.i64], returns: T.void },
+    CGEventKeyboardSetUnicodeString: { args: [T.ptr, T.u64, T.ptr], returns: T.void },
+    CGEventPost: { args: [T.u32, T.ptr], returns: T.void },
+    CGMainDisplayID: { args: [], returns: T.u32 },
+    CGDisplayPixelsWide: { args: [T.u32], returns: T.u64 },
+    CGDisplayPixelsHigh: { args: [T.u32], returns: T.u64 },
+  }).symbols;
+  const cf = dlopen(CORE_FOUNDATION, { CFRelease: { args: [T.ptr], returns: T.void } }).symbols;
+  loaded = { ffi, lib: { ...cg, ...cf } as unknown as Symbols };
+  return loaded;
+}
+
+// Per-process injection state. One remote-desktop session at a time drives the real desktop,
+// so module-level state is the right scope (same as the win32 backend's desktop handle).
+let heldButton: "left" | "right" | null = null;
+const heldModifiers = new Set<number>();
+let lastDownAt = 0;
+let lastDownX = -1, lastDownY = -1, clickState = 1;
+
+function modifierFlags(): bigint {
+  let flags = 0;
+  for (const code of heldModifiers) flags |= CGKEY_MODIFIER_FLAG[code] ?? 0;
+  return BigInt(flags);
+}
+
+function post(lib: Symbols, ev: Ptr, type?: number): void {
+  if (type !== undefined) lib.CGEventSetType(ev, type);
+  lib.CGEventSetFlags(ev, modifierFlags());
+  lib.CGEventPost(HID_EVENT_TAP, ev);
+  lib.CFRelease(ev);
+}
+
+/** Fraction → global logical point on the target display (main display when none given),
+ *  clamped so a wild client value stays on that screen. A secondary display's origin can be
+ *  negative in CG's global space (one here sits at −929,−1440). */
+function toPoint(lib: Symbols, xFrac: number, yFrac: number, target: InputTargetRect | null): { x: number; y: number } {
+  const rect = target ?? (() => {
+    const display = lib.CGMainDisplayID();
+    return { x: 0, y: 0, width: Number(lib.CGDisplayPixelsWide(display)), height: Number(lib.CGDisplayPixelsHigh(display)) };
+  })();
+  return {
+    x: rect.x + Math.min(Math.max(xFrac, 0), 1) * rect.width,
+    y: rect.y + Math.min(Math.max(yFrac, 0), 1) * rect.height,
+  };
+}
+
+async function pointer(
+  xFrac: number, yFrac: number, button: "left" | "right" | null, down: boolean | null, target: InputTargetRect | null,
+): Promise<void> {
+  const { lib } = await load();
+  const { x, y } = toPoint(lib, xFrac, yFrac, target);
+  if (button === null || down === null) {
+    // Pure move: a drag while a button is held, else a plain move.
+    const type = heldButton === "left" ? LEFT_DRAGGED : heldButton === "right" ? RIGHT_DRAGGED : MOUSE_MOVED;
+    post(lib, lib.CGEventCreateMouseEvent(null, type, x, y, heldButton === "right" ? BUTTON_RIGHT : BUTTON_LEFT));
+    return;
+  }
+  const cgButton = button === "left" ? BUTTON_LEFT : BUTTON_RIGHT;
+  const type = button === "left" ? (down ? LEFT_DOWN : LEFT_UP) : (down ? RIGHT_DOWN : RIGHT_UP);
+  if (down) {
+    const now = Date.now();
+    const samePlace = Math.abs(x - lastDownX) < 4 && Math.abs(y - lastDownY) < 4;
+    clickState = now - lastDownAt < DOUBLE_CLICK_MS && samePlace ? clickState + 1 : 1;
+    lastDownAt = now; lastDownX = x; lastDownY = y;
+    heldButton = button;
+  } else {
+    heldButton = null;
+  }
+  const ev = lib.CGEventCreateMouseEvent(null, type, x, y, cgButton);
+  lib.CGEventSetIntegerValueField(ev, FIELD_CLICK_STATE, BigInt(clickState));
+  post(lib, ev);
+}
+
+async function wheel(deltaY: number): Promise<void> {
+  const { lib } = await load();
+  const lines = Math.max(-32768, Math.min(32767, Math.round((deltaY / 120) * LINES_PER_NOTCH)));
+  if (lines === 0) return;
+  post(lib, lib.CGEventCreateScrollWheelEvent2(null, SCROLL_UNIT_LINE, 1, lines, 0, 0));
+}
+
+async function key(code: string, down: boolean): Promise<boolean> {
+  const keycode = codeToCgKey(code);
+  if (keycode === null) return false;
+  const { lib } = await load();
+  const isModifier = keycode in CGKEY_MODIFIER_FLAG;
+  if (isModifier) { if (down) heldModifiers.add(keycode); else heldModifiers.delete(keycode); }
+  // Modifier keys travel as FlagsChanged (with the new flag state already applied above), never
+  // as KeyDown/KeyUp — apps ignore a KeyDown for Shift but honour the flags on it.
+  post(lib, lib.CGEventCreateKeyboardEvent(null, keycode, down), isModifier ? FLAGS_CHANGED : undefined);
+  return true;
+}
+
+/** Carrier keycode for Unicode text events. The attached string is what a Cocoa text view
+ *  types, but the keycode still matters to anything hooking events by key:
+ *  - `0` (kVK_ANSI_A, what most tools use) is re-read as a literal "a" by third-party IMEs
+ *    (OpenKey/EVKey Telex turned "日本" into "â" — two keycode-0 events = "aa" → "â");
+ *  - function keys (F13–F19) and unassigned codes (0x7F, 0xFF) produce NO text at all;
+ *  - Space passes through IMEs as a word break and types every tested char, incl. `\t`, `\n`,
+ *    CJK and surrogate-pair emoji.
+ *  Text is still subject to the host's active IME (Telex rewrote "World" → "ửold"); that is
+ *  inherent to injection on any OS, not something the carrier can avoid. */
+const TEXT_CARRIER_KEYCODE = 0x31;
+
+/** Type text as Unicode, one code point per keyDown/keyUp pair. */
+async function text(str: string): Promise<void> {
+  const { ffi, lib } = await load();
+  for (const ch of str) {
+    const utf16 = new Uint16Array(ch.length);
+    for (let i = 0; i < ch.length; i++) utf16[i] = ch.charCodeAt(i);
+    for (const down of [true, false]) {
+      const ev = lib.CGEventCreateKeyboardEvent(null, TEXT_CARRIER_KEYCODE, down);
+      lib.CGEventKeyboardSetUnicodeString(ev, BigInt(utf16.length), ffi.ptr(utf16));
+      post(lib, ev);
+    }
+  }
+}
+
+async function releaseAllModifiers(): Promise<void> {
+  if (process.platform !== "darwin") return;
+  try {
+    const { lib } = await load();
+    heldModifiers.clear();
+    for (const keycode of MODIFIER_CGKEY_CODES) post(lib, lib.CGEventCreateKeyboardEvent(null, keycode, false), FLAGS_CHANGED);
+    if (heldButton) {
+      // A button still down on disconnect would leave the host mid-drag; release it in place.
+      const type = heldButton === "left" ? LEFT_UP : RIGHT_UP;
+      post(lib, lib.CGEventCreateMouseEvent(null, type, lastDownX, lastDownY, heldButton === "left" ? BUTTON_LEFT : BUTTON_RIGHT));
+      heldButton = null;
+    }
+  } catch { /* best-effort */ }
+}
+
+export const darwinInputBackend: RemoteInputBackend = {
+  id: "darwin-cgevent",
+  pointer, wheel, key, text, releaseAllModifiers,
+};

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

@@ -0,0 +1,243 @@
+/**
+ * Windows input backend: Bun FFI straight into `user32.dll` `SendInput` — no separate helper
+ * process (drops the Rust-binary build step + unsigned-exe/SmartScreen risk the phase plan
+ * flagged for a bundled injector; phase 02's SYSTEM-session helper is a different
+ * process/token anyway, so nothing here is meant to be reused as-is).
+ *
+ * Normal desktop only, current interactive session, no SYSTEM/UAC/lock-screen support.
+ *
+ * `bun:ffi` is only ever `import()`-ed and `dlopen`-ed lazily from inside `loadUser32()`, so
+ * merely importing this module (routing, types) on Linux/macOS test runners never touches
+ * `user32.dll`. Selected by `remote-desktop-input.ts` on `win32` only.
+ */
+import { codeToVk, MODIFIER_VK_CODES } from "./remote-desktop-vk-map.ts";
+import { RemoteInputUnavailableError, type RemoteInputBackend } from "./remote-desktop-input-backend.ts";
+
+const INPUT_MOUSE = 0;
+const INPUT_KEYBOARD = 1;
+const MOUSEEVENTF_MOVE = 0x0001;
+const MOUSEEVENTF_LEFTDOWN = 0x0002;
+const MOUSEEVENTF_LEFTUP = 0x0004;
+const MOUSEEVENTF_RIGHTDOWN = 0x0008;
+const MOUSEEVENTF_RIGHTUP = 0x0010;
+const MOUSEEVENTF_ABSOLUTE = 0x8000;
+const MOUSEEVENTF_VIRTUALDESK = 0x4000;
+const MOUSEEVENTF_WHEEL = 0x0800;
+/** One notch of a real mouse wheel — `mouseData` for `MOUSEEVENTF_WHEEL` is a signed multiple
+ *  of this constant, not a raw pixel delta. */
+const WHEEL_DELTA = 120;
+const KEYEVENTF_KEYUP = 0x0002;
+/** `wScan` carries a UTF-16 unit instead of a scan code; `wVk` must be 0. */
+const KEYEVENTF_UNICODE = 0x0004;
+/** `((DPI_AWARENESS_CONTEXT)-4)` — PER_MONITOR_AWARE_V2. Not a real pointer; the x64 ABI
+ *  passes it in the same register/slot as a pointer arg would, bit pattern only. */
+const DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2 = -4n;
+/** Each `INPUT` struct is 40 bytes on x64 (8-byte `type` slot + 32-byte union). */
+const INPUT_STRUCT_SIZE = 40;
+/** Desktop access rights for input injection. `SendInput` silently no-ops when the calling
+ *  thread is not attached to the *input* desktop; attaching needs the READ/WRITE/SWITCH rights
+ *  plus JOURNALPLAYBACK so the desktop accepts injected input. These MUST be the real DESKTOP_*
+ *  bit values — an invalid mask (e.g. an out-of-range bit) makes `OpenInputDesktop` return NULL
+ *  and the attach silently fails, leaving SendInput pointed at the wrong desktop. */
+const DESKTOP_READOBJECTS = 0x0001;
+const DESKTOP_JOURNALPLAYBACK = 0x0020;
+const DESKTOP_WRITEOBJECTS = 0x0080;
+const DESKTOP_SWITCHDESKTOP = 0x0100;
+const INPUT_DESKTOP_ACCESS =
+  DESKTOP_READOBJECTS | DESKTOP_JOURNALPLAYBACK | DESKTOP_WRITEOBJECTS | DESKTOP_SWITCHDESKTOP; // 0x1A1
+
+/** WINSTA_ALL_ACCESS — enough to open the interactive window station and make it this process's
+ *  station so its input desktop becomes reachable. */
+const WINSTA_ALL_ACCESS = 0x37f;
+
+type FfiModule = typeof import("bun:ffi");
+type User32Symbols = {
+  SendInput: (count: number, ptr: number | bigint, size: number) => number;
+  SetProcessDpiAwarenessContext: (ctx: bigint) => boolean;
+  OpenInputDesktop: (flags: number, inherit: boolean, access: number) => number | bigint;
+  SetThreadDesktop: (hdesk: number | bigint) => boolean;
+  CloseDesktop: (hdesk: number | bigint) => boolean;
+  OpenWindowStationW: (name: number | bigint, inherit: boolean, access: number) => number | bigint;
+  SetProcessWindowStation: (hwinsta: number | bigint) => boolean;
+};
+
+let ffiModule: FfiModule | null = null;
+let user32: User32Symbols | null = null;
+let dpiAwarenessAttempted = false;
+
+async function loadUser32(): Promise<{ ffi: FfiModule; lib: User32Symbols }> {
+  if (process.platform !== "win32") throw new RemoteInputUnavailableError();
+  if (!ffiModule) ffiModule = await import("bun:ffi");
+  const { dlopen, FFIType } = ffiModule;
+  if (!user32) {
+    user32 = dlopen("user32.dll", {
+      SendInput: { args: [FFIType.u32, FFIType.ptr, FFIType.i32], returns: FFIType.u32 },
+      SetProcessDpiAwarenessContext: { args: [FFIType.i64], returns: FFIType.bool },
+      OpenInputDesktop: { args: [FFIType.u32, FFIType.bool, FFIType.u32], returns: FFIType.ptr },
+      SetThreadDesktop: { args: [FFIType.ptr], returns: FFIType.bool },
+      CloseDesktop: { args: [FFIType.ptr], returns: FFIType.bool },
+      OpenWindowStationW: { args: [FFIType.ptr, FFIType.bool, FFIType.u32], returns: FFIType.ptr },
+      SetProcessWindowStation: { args: [FFIType.ptr], returns: FFIType.bool },
+    }).symbols as unknown as User32Symbols;
+  }
+  if (!dpiAwarenessAttempted) {
+    dpiAwarenessAttempted = true;
+    // A second call to this in the same process returns E_ACCESSDENIED — swallow it, it just
+    // means something else (or a previous session) already set it.
+    try { user32.SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2); } catch { /* already set */ }
+  }
+  return { ffi: ffiModule, lib: user32 };
+}
+
+function writeMouseInput(dv: DataView, offset: number, xAbs: number, yAbs: number, flags: number, mouseData = 0): void {
+  dv.setUint32(offset, INPUT_MOUSE, true);
+  dv.setInt32(offset + 8, xAbs, true);
+  dv.setInt32(offset + 12, yAbs, true);
+  dv.setInt32(offset + 16, mouseData, true); // wheel delta for MOUSEEVENTF_WHEEL, unused otherwise
+  dv.setUint32(offset + 20, flags >>> 0, true);
+  dv.setUint32(offset + 24, 0, true); // time: 0 lets the system supply it
+}
+
+function writeKeyInput(dv: DataView, offset: number, vk: number, keyUp: boolean): void {
+  dv.setUint32(offset, INPUT_KEYBOARD, true);
+  dv.setUint16(offset + 8, vk, true);
+  dv.setUint16(offset + 10, 0, true); // wScan — unused, we inject by VK not scan code
+  dv.setUint32(offset + 12, keyUp ? KEYEVENTF_KEYUP : 0, true);
+  dv.setUint32(offset + 16, 0, true); // time
+}
+
+function writeUnicodeKeyInput(dv: DataView, offset: number, unit: number, keyUp: boolean): void {
+  dv.setUint32(offset, INPUT_KEYBOARD, true);
+  dv.setUint16(offset + 8, 0, true); // wVk — must be 0 with KEYEVENTF_UNICODE
+  dv.setUint16(offset + 10, unit, true);
+  dv.setUint32(offset + 12, KEYEVENTF_UNICODE | (keyUp ? KEYEVENTF_KEYUP : 0), true);
+  dv.setUint32(offset + 16, 0, true); // time
+}
+
+/** Handle of the desktop this thread is currently attached to, so we can close the previous one
+ *  when the active input desktop changes (lock/unlock/UAC switches it). One handle in flight. */
+let attachedDesktop: number | bigint | null = null;
+
+/** Attach the calling thread to the *current* input desktop before injecting. Re-run every send
+ *  because the input desktop changes on lock/unlock; `CreateProcessAsUser`/process start only
+ *  fixes the initial desktop, not later switches. Best-effort: on failure we still try SendInput
+ *  (it just no-ops), and log once rather than per-event spam. */
+/** Attach the PROCESS to the interactive window station ("winsta0") once, so its input desktop
+ *  is reachable. Without this, a PPM process launched from a non-interactive station (a service,
+ *  or some spawners) can't OpenInputDesktop at all — SendInput then goes nowhere. No-op when the
+ *  process is already on winsta0 (the normal case for PPM started inside the user's session). */
+let stationEnsured = false;
+function ensureInteractiveStation(ffi: FfiModule, lib: User32Symbols): void {
+  if (stationEnsured) return;
+  stationEnsured = true;
+  const name = "winsta0";
+  const wide = new Uint16Array(name.length + 1);
+  for (let i = 0; i < name.length; i++) wide[i] = name.charCodeAt(i);
+  const hwinsta = lib.OpenWindowStationW(ffi.ptr(wide), false, WINSTA_ALL_ACCESS);
+  if (!hwinsta) return; // already on it, or no access — OpenInputDesktop below will tell us
+  lib.SetProcessWindowStation(hwinsta);
+}
+
+function attachToInputDesktop(ffi: FfiModule, lib: User32Symbols): void {
+  ensureInteractiveStation(ffi, lib);
+  const hdesk = lib.OpenInputDesktop(0, false, INPUT_DESKTOP_ACCESS);
+  if (!hdesk) return; // couldn't open the input desktop (e.g. secure/lock desktop); leave thread as-is
+  const ok = lib.SetThreadDesktop(hdesk);
+  if (ok) {
+    if (attachedDesktop && attachedDesktop !== hdesk) {
+      try { lib.CloseDesktop(attachedDesktop); } catch { /* ignore */ }
+    }
+    attachedDesktop = hdesk;
+  } else {
+    // SetThreadDesktop fails if this thread owns windows/hooks — shouldn't for the server thread.
+    try { lib.CloseDesktop(hdesk); } catch { /* ignore */ }
+  }
+}
+
+async function sendRaw(buf: Uint8Array, count: number): Promise<void> {
+  const { ffi, lib } = await loadUser32();
+  attachToInputDesktop(ffi, lib);
+  const sent = lib.SendInput(count, ffi.ptr(buf), INPUT_STRUCT_SIZE);
+  if (sent !== count) console.warn(`[remote-desktop] SendInput accepted ${sent}/${count} events`);
+}
+
+/** Move the cursor and, if this is a click, press/release the button — one absolute move
+ *  per call so the button acts at the position the client actually clicked. `xFrac`/`yFrac`
+ *  are 0..1 fractions of the capture (client already dropped devicePixelRatio; only the
+ *  canvas-relative fraction is meaningful for host coordinates). The target rect is ignored:
+ *  gdigrab captures the whole virtual desktop and `MOUSEEVENTF_VIRTUALDESK` maps onto it. */
+async function injectPointer(
+  xFrac: number,
+  yFrac: number,
+  button: "left" | "right" | null,
+  down: boolean | null,
+): Promise<void> {
+  const xAbs = Math.round(Math.min(Math.max(xFrac, 0), 1) * 65535);
+  const yAbs = Math.round(Math.min(Math.max(yFrac, 0), 1) * 65535);
+  let flags = MOUSEEVENTF_MOVE | MOUSEEVENTF_ABSOLUTE | MOUSEEVENTF_VIRTUALDESK;
+  if (button === "left") flags |= down ? MOUSEEVENTF_LEFTDOWN : MOUSEEVENTF_LEFTUP;
+  else if (button === "right") flags |= down ? MOUSEEVENTF_RIGHTDOWN : MOUSEEVENTF_RIGHTUP;
+
+  const buf = new Uint8Array(INPUT_STRUCT_SIZE);
+  writeMouseInput(new DataView(buf.buffer), 0, xAbs, yAbs, flags);
+  await sendRaw(buf, 1);
+}
+
+/** Scroll the wheel. `deltaY` is in `WHEEL_DELTA` (120) units — positive rotates the wheel
+ *  forward (scrolls up/away from the user), negative rotates backward (scrolls down). The
+ *  client accumulates raw two-finger-drag pixels into this unit before sending, so this layer
+ *  stays a dumb relay: round + clamp to a safe i16 range so a runaway client value can't wrap
+ *  into a huge or negative-looking mouseData field. */
+async function injectWheel(deltaY: number): Promise<void> {
+  const clamped = Math.max(-32768, Math.min(32767, Math.round(deltaY)));
+  if (clamped === 0) return;
+  const buf = new Uint8Array(INPUT_STRUCT_SIZE);
+  writeMouseInput(new DataView(buf.buffer), 0, 0, 0, MOUSEEVENTF_WHEEL, clamped);
+  await sendRaw(buf, 1);
+}
+
+/** Send a keydown/keyup by physical key code. Returns false for an unmapped code (caller
+ *  should just drop it rather than injecting a wrong key). */
+async function injectKey(code: string, down: boolean): Promise<boolean> {
+  const vk = codeToVk(code);
+  if (vk === null) return false;
+  const buf = new Uint8Array(INPUT_STRUCT_SIZE);
+  writeKeyInput(new DataView(buf.buffer), 0, vk, !down);
+  await sendRaw(buf, 1);
+  return true;
+}
+
+/** Force keyup for every modifier VK, regardless of tracked state — the backstop for a lost
+ *  keyup (blur, WS drop) leaving Shift/Ctrl/Alt/Win logically held on the host. */
+async function releaseAllModifiers(): Promise<void> {
+  if (process.platform !== "win32") return;
+  const buf = new Uint8Array(INPUT_STRUCT_SIZE * MODIFIER_VK_CODES.length);
+  const dv = new DataView(buf.buffer);
+  MODIFIER_VK_CODES.forEach((vk, i) => writeKeyInput(dv, i * INPUT_STRUCT_SIZE, vk, true));
+  try { await sendRaw(buf, MODIFIER_VK_CODES.length); } catch { /* best-effort */ }
+}
+
+/** Type text as Unicode via `KEYEVENTF_UNICODE` — one down/up pair per UTF-16 unit (surrogate
+ *  halves are sent as two units, which is what Windows expects), all in a single `SendInput`
+ *  call so nothing interleaves. Written against the documented struct layout on the Mac side of
+ *  the port; exercised by the e2e harness on Windows, not by unit tests. */
+async function injectText(text: string): Promise<void> {
+  if (text.length === 0) return;
+  const buf = new Uint8Array(INPUT_STRUCT_SIZE * text.length * 2);
+  const dv = new DataView(buf.buffer);
+  for (let i = 0; i < text.length; i++) {
+    const unit = text.charCodeAt(i);
+    writeUnicodeKeyInput(dv, (i * 2) * INPUT_STRUCT_SIZE, unit, false);
+    writeUnicodeKeyInput(dv, (i * 2 + 1) * INPUT_STRUCT_SIZE, unit, true);
+  }
+  await sendRaw(buf, text.length * 2);
+}
+
+export const win32InputBackend: RemoteInputBackend = {
+  id: "win32-sendinput",
+  pointer: injectPointer,
+  wheel: injectWheel,
+  key: injectKey,
+  text: injectText,
+  releaseAllModifiers,
+};