@hienlh/ppm 0.18.14 → 0.18.16

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

@@ -0,0 +1,217 @@
+/**
+ * Mouse/keyboard injection via 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`.
+ */
+import { codeToVk, MODIFIER_VK_CODES } from "./remote-desktop-vk-map.ts";
+
+export class RemoteInputUnavailableError extends Error {
+  constructor(msg = "Remote input injection is only available on Windows") {
+    super(msg);
+    this.name = "RemoteInputUnavailableError";
+  }
+}
+
+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;
+/** `((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
+}
+
+/** 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). */
+export 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. */
+export 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). */
+export 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. */
+export 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 */ }
+}
+
+export function isInputAvailable(): boolean {
+  return process.platform === "win32";
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Single-use, short-TTL connection nonce — mirrors `download-token.service.ts`'s
+ * consume-once pattern.
+ *
+ * The PPM static bearer token already travels as `?token=` on every WS upgrade
+ * (`isWsUpgradeAuthorized`, `src/server/index.ts`) and proves nothing beyond "holds the one
+ * reusable app token" — it is not a real per-session grant. `POST /api/remote-desktop/session`
+ * mints one of these after re-checking `auth.enabled`; the client then presents it via the WS
+ * subprotocol header (never the query string) and it is consumed exactly once, at upgrade
+ * time, in `src/server/index.ts`.
+ */
+import { randomUUIDv7 } from "bun";
+
+const TTL_MS = 30_000;
+const nonces = new Map<string, number>();
+
+/** Mint a nonce; caller must have already verified auth is enabled + a valid request. */
+export function mintRemoteDesktopNonce(): string {
+  const token = randomUUIDv7();
+  nonces.set(token, Date.now());
+  cleanup();
+  return token;
+}
+
+/** Validate + consume. Returns false for missing/expired/already-used nonces. */
+export function consumeRemoteDesktopNonce(token: string): boolean {
+  const mintedAt = nonces.get(token);
+  if (mintedAt === undefined) return false;
+  nonces.delete(token);
+  return Date.now() - mintedAt <= TTL_MS;
+}
+
+function cleanup(): void {
+  const now = Date.now();
+  for (const [token, mintedAt] of nonces) {
+    if (now - mintedAt > TTL_MS) nonces.delete(token);
+  }
+}

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

@@ -0,0 +1,189 @@
+/**
+ * Owns one remote-desktop connection end to end: capture lifecycle, WS backpressure,
+ * heartbeat/TTL teardown, and forwarding input to the injector. "One active session per
+ * host" — a new connection evicts (and awaits) any previous one before starting its own
+ * capture so two `gdigrab` processes never contend for the same display.
+ */
+import { startCapture, type CaptureHandle } from "./remote-desktop-capture.ts";
+import { avc1CodecString } from "./avc1-codec-string.ts";
+import type { AccessUnit } from "./access-unit-assembler.ts";
+import { injectPointer, injectKey, injectWheel, releaseAllModifiers, isInputAvailable } from "./remote-desktop-input.ts";
+
+/** Minimal socket surface this module needs — matches Bun's `ServerWebSocket` shape closely
+ *  enough to be faked in a unit test without a real connection. */
+export interface RemoteDesktopSocket {
+  send(data: string | Uint8Array): number;
+  getBufferedAmount?(): number;
+  close(code?: number, reason?: string): void;
+}
+
+/** App-level heartbeat, independent of Bun's 960s socket `idleTimeout` — a dead tunnel or a
+ * sleeping laptop must not leave ffmpeg + input access live for minutes unattended. */
+const HEARTBEAT_INTERVAL_MS = 5_000;
+// 30s (6 missed 5s pings): tolerant of brief network jitter and of a client whose ping timer
+// is throttled while its tab is briefly backgrounded, without leaving an unattended session
+// (ffmpeg + input access) live for long. The client also re-pings the moment its tab is visible.
+const HEARTBEAT_TIMEOUT_MS = 30_000;
+/** Above this many buffered bytes, drop delta AUs until the next keyframe rather than
+ *  queueing forever — a slow WAN/tunnel link must degrade to "waits ~2s for a keyframe",
+ *  never to unbounded memory growth or an ever-growing latency queue. */
+const BACKPRESSURE_THRESHOLD_BYTES = 512 * 1024;
+
+export class RemoteDesktopSession {
+  private capture: CaptureHandle | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private lastPingAt = Date.now();
+  private droppingUntilKey = false;
+  private sentConfig = false;
+  private closed = false;
+  private readonly heldKeyCodes = new Set<string>();
+  private exitResolve: (() => void) | null = null;
+  /** Resolves once the underlying ffmpeg process has actually exited (not merely asked to). */
+  readonly exited: Promise<void>;
+
+  constructor(private readonly ws: RemoteDesktopSocket) {
+    this.exited = new Promise((resolve) => { this.exitResolve = resolve; });
+  }
+
+  async start(): Promise<void> {
+    this.capture = await startCapture({
+      onAccessUnit: (au) => this.handleAccessUnit(au),
+      // `reason` is only set when ffmpeg died on its own (crash, access denied, etc) — tell
+      // the client *why* before closing instead of leaving it to guess from a bare
+      // disconnect (this is exactly what happens today for e.g. gdigrab failing against a
+      // disconnected Windows session: "Failed to capture image (error 5)").
+      onExit: (_code, reason) => {
+        this.exitResolve?.();
+        if (!this.closed) {
+          if (reason) {
+            try { this.ws.send(JSON.stringify({ type: "error", message: `Capture failed: ${reason}` })); } catch { /* closing anyway */ }
+          }
+          this.close();
+        }
+      },
+    });
+    this.heartbeatTimer = setInterval(() => this.checkHeartbeat(), HEARTBEAT_INTERVAL_MS);
+  }
+
+  noteClientAlive(): void {
+    this.lastPingAt = Date.now();
+  }
+
+  async handleClientMessage(raw: string): Promise<void> {
+    let msg: Record<string, unknown>;
+    try { msg = JSON.parse(raw); } catch { return; }
+    if (msg.type === "ping") { this.noteClientAlive(); return; }
+    if (msg.type === "stop") { this.close(); return; }
+    if (!isInputAvailable()) return; // part 1b unsupported on this OS — silently ignore
+
+    if (msg.type === "pointer") {
+      const { xFrac, yFrac, button, down } = msg as { xFrac?: unknown; yFrac?: unknown; button?: unknown; down?: unknown };
+      if (typeof xFrac === "number" && typeof yFrac === "number") {
+        const btn = button === "left" || button === "right" ? button : null;
+        await injectPointer(xFrac, yFrac, btn, typeof down === "boolean" ? down : null);
+      }
+      return;
+    }
+    if (msg.type === "wheel") {
+      const { dy } = msg as { dy?: unknown };
+      if (typeof dy === "number" && Number.isFinite(dy)) await injectWheel(dy);
+      return;
+    }
+    if (msg.type === "key") {
+      const { code, down } = msg as { code?: unknown; down?: unknown };
+      if (typeof code === "string" && typeof down === "boolean") {
+        if (down) this.heldKeyCodes.add(code); else this.heldKeyCodes.delete(code);
+        await injectKey(code, down);
+      }
+      return;
+    }
+    if (msg.type === "releaseAll") {
+      await this.releaseHeldKeys();
+    }
+  }
+
+  /** Force a keyup for every key this session has tracked as held, then run the modifier
+   *  backstop too — `heldKeyCodes` covers whatever the client actually pressed (letters,
+   *  digits, etc, not just modifiers); `releaseAllModifiers()` is a second backstop for a
+   *  modifier that raced a disconnect before its keydown was ever tracked. Previously this
+   *  only ran the modifier backstop and *cleared* `heldKeyCodes` without releasing them,
+   *  so a held non-modifier key (e.g. a letter) stayed logically down on the host. */
+  private async releaseHeldKeys(): Promise<void> {
+    const codes = [...this.heldKeyCodes];
+    this.heldKeyCodes.clear();
+    await Promise.all(codes.map((code) => injectKey(code, false).catch(() => {})));
+    await releaseAllModifiers();
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.capture?.stop();
+    activeSessions.delete(this);
+    if (this.heldKeyCodes.size > 0) {
+      this.releaseHeldKeys().catch(() => {});
+    }
+    try { this.ws.close(); } catch { /* already closing */ }
+  }
+
+  private checkHeartbeat(): void {
+    if (Date.now() - this.lastPingAt > HEARTBEAT_TIMEOUT_MS) {
+      console.warn("[remote-desktop] heartbeat timeout — tearing down session");
+      this.close();
+    }
+  }
+
+  private handleAccessUnit(au: AccessUnit): void {
+    if (this.closed) return;
+    if (!this.sentConfig) {
+      const sps = this.capture?.cachedSps();
+      if (!sps) return; // nothing decodable yet — wait for the encoder's first SPS
+      const codec = avc1CodecString(sps);
+      if (!codec) return;
+      this.ws.send(JSON.stringify({ type: "config", codec }));
+      this.sentConfig = true;
+    }
+
+    const buffered = this.ws.getBufferedAmount?.() ?? 0;
+    if (buffered > BACKPRESSURE_THRESHOLD_BYTES && !au.isKey) {
+      this.droppingUntilKey = true;
+      return;
+    }
+    if (this.droppingUntilKey && !au.isKey) return;
+    if (au.isKey) this.droppingUntilKey = false;
+
+    const framed = new Uint8Array(1 + au.bytes.length);
+    framed[0] = au.isKey ? 1 : 0;
+    framed.set(au.bytes, 1);
+    this.ws.send(framed);
+  }
+}
+
+const activeSessions = new Set<RemoteDesktopSession>();
+
+/** Evict any previous session (awaiting its ffmpeg exit, capped so a wedged process can't
+ *  hang a reconnect) before starting the new one. */
+export async function createRemoteDesktopSession(ws: RemoteDesktopSocket): Promise<RemoteDesktopSession> {
+  for (const existing of [...activeSessions]) {
+    existing.close();
+    await Promise.race([existing.exited, Bun.sleep(2000)]);
+  }
+  const session = new RemoteDesktopSession(ws);
+  await session.start();
+  activeSessions.add(session);
+  return session;
+}
+
+/** Process-exit sweep so ffmpeg never outlives a server crash/exit — a clean WS close or an
+ *  idle heartbeat timeout is handled by the session itself; this covers everything else
+ *  (SIGINT/SIGTERM, uncaught crash unwind). */
+let sweepRegistered = false;
+export function registerRemoteDesktopExitSweep(): void {
+  if (sweepRegistered) return;
+  sweepRegistered = true;
+  const sweep = () => { for (const s of [...activeSessions]) s.close(); };
+  process.on("exit", sweep);
+  process.on("SIGINT", sweep);
+  process.on("SIGTERM", sweep);
+}

package/src/services/remote-desktop/remote-desktop-vk-map.ts

@@ -0,0 +1,41 @@
+/**
+ * `KeyboardEvent.code` (physical key, layout-independent) → Win32 virtual-key code.
+ * Only `code` is accepted from the client — `key` depends on the browser's active layout
+ * and would map wrong the moment host and client disagree on layout.
+ */
+const CODE_TO_VK: Record<string, number> = {
+  Backspace: 0x08, Tab: 0x09, Enter: 0x0d, ShiftLeft: 0xa0, ShiftRight: 0xa1,
+  ControlLeft: 0xa2, ControlRight: 0xa3, AltLeft: 0xa4, AltRight: 0xa5,
+  Pause: 0x13, CapsLock: 0x14, Escape: 0x1b, Space: 0x20,
+  PageUp: 0x21, PageDown: 0x22, End: 0x23, Home: 0x24,
+  ArrowLeft: 0x25, ArrowUp: 0x26, ArrowRight: 0x27, ArrowDown: 0x28,
+  Insert: 0x2d, Delete: 0x2e,
+  Digit0: 0x30, Digit1: 0x31, Digit2: 0x32, Digit3: 0x33, Digit4: 0x34,
+  Digit5: 0x35, Digit6: 0x36, Digit7: 0x37, Digit8: 0x38, Digit9: 0x39,
+  KeyA: 0x41, KeyB: 0x42, KeyC: 0x43, KeyD: 0x44, KeyE: 0x45, KeyF: 0x46,
+  KeyG: 0x47, KeyH: 0x48, KeyI: 0x49, KeyJ: 0x4a, KeyK: 0x4b, KeyL: 0x4c,
+  KeyM: 0x4d, KeyN: 0x4e, KeyO: 0x4f, KeyP: 0x50, KeyQ: 0x51, KeyR: 0x52,
+  KeyS: 0x53, KeyT: 0x54, KeyU: 0x55, KeyV: 0x56, KeyW: 0x57, KeyX: 0x58,
+  KeyY: 0x59, KeyZ: 0x5a,
+  MetaLeft: 0x5b, MetaRight: 0x5c, ContextMenu: 0x5d,
+  Numpad0: 0x60, Numpad1: 0x61, Numpad2: 0x62, Numpad3: 0x63, Numpad4: 0x64,
+  Numpad5: 0x65, Numpad6: 0x66, Numpad7: 0x67, Numpad8: 0x68, Numpad9: 0x69,
+  NumpadMultiply: 0x6a, NumpadAdd: 0x6b, NumpadSubtract: 0x6d,
+  NumpadDecimal: 0x6e, NumpadDivide: 0x6f,
+  F1: 0x70, F2: 0x71, F3: 0x72, F4: 0x73, F5: 0x74, F6: 0x75,
+  F7: 0x76, F8: 0x77, F9: 0x78, F10: 0x79, F11: 0x7a, F12: 0x7b,
+  NumLock: 0x90, ScrollLock: 0x91,
+  Semicolon: 0xba, Equal: 0xbb, Comma: 0xbc, Minus: 0xbd, Period: 0xbe,
+  Slash: 0xbf, Backquote: 0xc0, BracketLeft: 0xdb, Backslash: 0xdc,
+  BracketRight: 0xdd, Quote: 0xde,
+};
+
+/** All modifier VK codes — used to force-release stuck modifiers on teardown (a lost keyup
+ *  otherwise leaves e.g. Shift logically held on the host after the WS drops). */
+export const MODIFIER_VK_CODES = [0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0x5b, 0x5c] as const;
+
+/** Resolve a `KeyboardEvent.code` to its VK; null for anything unmapped (IME composition,
+ *  unusual layouts) rather than guessing and injecting the wrong key. */
+export function codeToVk(code: string): number | null {
+  return CODE_TO_VK[code] ?? null;
+}