@hienlh/ppm 0.18.13 → 0.18.15

package/src/web/components/remote-desktop/remote-desktop-mobile-key-bar.tsx

@@ -0,0 +1,131 @@
+/**
+ * Compact function/combo key row shown above the toolbar while the virtual keyboard is open.
+ * Modifiers (Ctrl/Alt/Shift/Win) are STICKY: tap to hold (sends the key-down immediately,
+ * highlights the button), tap again to release (key-down was already sent, so this just sends
+ * the matching key-up) — lets a chord like "Ctrl + tap on the video" be built one tap at a time.
+ * The combo buttons (Ctrl+C etc.) are a shortcut for the same idea: one tap sends the whole
+ * down/up sequence, independent of whatever sticky modifiers happen to be held.
+ *
+ * No server changes needed — every button here is just the existing `{type:"key",code,down}`
+ * protocol `use-remote-input-capture.ts` already speaks; the server's own `heldKeyCodes`
+ * tracking (`remote-desktop-session.ts`) already releases anything sent down:true here too on
+ * disconnect/heartbeat-timeout, the same as a real held key.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { cn } from "@/lib/utils";
+
+export interface RemoteDesktopMobileKeyBarProps {
+  sendMessage: (msg: Record<string, unknown>) => void;
+}
+
+const MODIFIERS = [
+  { label: "Ctrl", code: "ControlLeft" },
+  { label: "Alt", code: "AltLeft" },
+  { label: "Shift", code: "ShiftLeft" },
+  { label: "Win", code: "MetaLeft" },
+] as const;
+
+const FUNCTION_KEYS = [
+  { label: "Esc", code: "Escape" },
+  { label: "Tab", code: "Tab" },
+  { label: "←", code: "ArrowLeft" },
+  { label: "↑", code: "ArrowUp" },
+  { label: "↓", code: "ArrowDown" },
+  { label: "→", code: "ArrowRight" },
+] as const;
+
+const COMBOS: readonly { label: string; codes: readonly string[] }[] = [
+  { label: "Ctrl+C", codes: ["ControlLeft", "KeyC"] },
+  { label: "Ctrl+V", codes: ["ControlLeft", "KeyV"] },
+  { label: "Ctrl+Z", codes: ["ControlLeft", "KeyZ"] },
+  { label: "Ctrl+A", codes: ["ControlLeft", "KeyA"] },
+  { label: "Alt+Tab", codes: ["AltLeft", "Tab"] },
+  // Windows blocks synthetic Ctrl+Alt+Del (the Secure Attention Sequence) from SendInput
+  // regardless of privilege level — this is an OS restriction, not a bug here. The button is
+  // best-effort: harmless to try, and there is no way to detect the block ahead of time.
+  { label: "Ctrl+Alt+Del", codes: ["ControlLeft", "AltLeft", "Delete"] },
+];
+
+function KeyBarButton({
+  onClick,
+  active,
+  className,
+  children,
+}: {
+  onClick: () => void;
+  active?: boolean;
+  className?: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={cn(
+        "min-h-11 min-w-11 shrink-0 whitespace-nowrap rounded-md px-2.5 text-xs font-medium text-white/80",
+        "active:bg-white/15 transition-colors",
+        active && "bg-primary text-primary-foreground",
+        className,
+      )}
+    >
+      {children}
+    </button>
+  );
+}
+
+export function RemoteDesktopMobileKeyBar({ sendMessage }: RemoteDesktopMobileKeyBarProps) {
+  const [held, setHeld] = useState<ReadonlySet<string>>(new Set());
+  const heldRef = useRef(held);
+  heldRef.current = held;
+
+  // Safety net: a modifier left toggled on must not stay logically held on the host once this
+  // bar goes away (keyboard dismissed, sheet closed) — same reasoning as `releaseAll` elsewhere.
+  useEffect(() => {
+    return () => {
+      heldRef.current.forEach((code) => sendMessage({ type: "key", code, down: false }));
+    };
+  }, [sendMessage]);
+
+  const toggleModifier = useCallback((code: string) => {
+    setHeld((prev) => {
+      const isHeld = prev.has(code);
+      sendMessage({ type: "key", code, down: !isHeld });
+      const next = new Set(prev);
+      if (isHeld) next.delete(code); else next.add(code);
+      return next;
+    });
+  }, [sendMessage]);
+
+  const tapKey = useCallback((code: string) => {
+    sendMessage({ type: "key", code, down: true });
+    sendMessage({ type: "key", code, down: false });
+  }, [sendMessage]);
+
+  const sendCombo = useCallback((codes: readonly string[]) => {
+    // Press down in order, release in reverse — mirrors physically pressing then releasing a
+    // chord (last key down first key up would read as a different shortcut on some apps).
+    codes.forEach((code) => sendMessage({ type: "key", code, down: true }));
+    [...codes].reverse().forEach((code) => sendMessage({ type: "key", code, down: false }));
+  }, [sendMessage]);
+
+  return (
+    <div
+      className="flex shrink-0 gap-1 overflow-x-auto border-t border-white/10 bg-black/90 px-2 py-1.5"
+      data-testid="remote-desktop-mobile-key-bar"
+    >
+      {MODIFIERS.map((m) => (
+        <KeyBarButton key={m.code} onClick={() => toggleModifier(m.code)} active={held.has(m.code)}>
+          {m.label}
+        </KeyBarButton>
+      ))}
+      <div className="mx-0.5 w-px shrink-0 bg-white/10" />
+      {FUNCTION_KEYS.map((k) => (
+        <KeyBarButton key={k.code} onClick={() => tapKey(k.code)}>{k.label}</KeyBarButton>
+      ))}
+      <div className="mx-0.5 w-px shrink-0 bg-white/10" />
+      {COMBOS.map((c) => (
+        <KeyBarButton key={c.label} onClick={() => sendCombo(c.codes)}>{c.label}</KeyBarButton>
+      ))}
+    </div>
+  );
+}

package/src/web/components/remote-desktop/remote-desktop-mobile-sheet.tsx

@@ -0,0 +1,43 @@
+/**
+ * Full-screen mobile presentation of the Remote Desktop viewer — `WindowLayer` renders nothing
+ * below `md`, so this is what mobile opens instead of the desktop floating window (see
+ * `open-remote-desktop.ts`). Self-gated singleton, mounted once at the app root beside the
+ * other mobile overlays (`MobileExplorerSheet`, `TeamMemberSheet`) — renders nothing until
+ * `useRemoteDesktopMobileOpenState().open()` is called.
+ *
+ * Deliberately NOT the shared `BottomSheet`: that component tracks `visualViewport` and shrinks
+ * its panel to leave room above the on-screen keyboard (right for a chat input you need visible
+ * next to the keyboard), but this viewer's "keyboard" is just a hidden input forwarding
+ * keystrokes — nothing here needs to stay visible above it, and shrinking the canvas viewport
+ * every time the toolbar's Keyboard button is tapped is exactly the wrong behavior. It also
+ * wires swipe-to-dismiss on touchstart/move/end, which fights the gesture engine's own
+ * `stopPropagation()`-based touch handling. A plain `fixed inset-0` portal sidesteps both —
+ * this stays full-viewport no matter what the keyboard does; `remote-desktop-mobile-view.tsx`
+ * reads `visualViewport` itself and floats just its toolbar/key-bar row above the keyboard.
+ *
+ * The heavy viewer (canvas, WebCodecs decoder, gesture engine) is a nested lazy import, same as
+ * `TeamMemberSheet` does for its content — nothing here loads until the sheet actually opens.
+ */
+import { Suspense, lazy } from "react";
+import { createPortal } from "react-dom";
+import { usePortalContainer } from "@/components/ui/portal-container-context";
+import { useRemoteDesktopMobileOpenState } from "./use-remote-desktop-mobile-open-state";
+
+const RemoteDesktopMobileView = lazy(() => import("./remote-desktop-mobile-view"));
+
+export function RemoteDesktopMobileSheet() {
+  const isOpen = useRemoteDesktopMobileOpenState((s) => s.isOpen);
+  const close = useRemoteDesktopMobileOpenState((s) => s.close);
+  const portalContainer = usePortalContainer();
+
+  if (!isOpen) return null;
+
+  return createPortal(
+    <div className="fixed inset-0 z-[45] bg-black" data-testid="remote-desktop-mobile-sheet">
+      <Suspense fallback={<div className="flex h-full items-center justify-center text-sm text-text-2">Loading…</div>}>
+        <RemoteDesktopMobileView onClose={close} />
+      </Suspense>
+    </div>,
+    portalContainer ?? document.getElementById("root") ?? document.body,
+  );
+}

package/src/web/components/remote-desktop/remote-desktop-mobile-toolbar.tsx

@@ -0,0 +1,79 @@
+/**
+ * Bottom (thumb-zone) toolbar for the mobile remote-desktop viewer: Touch/Mouse mode toggle,
+ * virtual keyboard, zoom reset, close. Every button is a 44px+ touch target per
+ * `docs/design-guidelines.md`'s Mobile-First UI Rules.
+ */
+import { Hand, MousePointer2, Keyboard, ZoomOut, Gauge, X } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { useSettingsStore } from "@/stores/settings-store";
+import type { RemoteDesktopInputMode } from "./use-remote-desktop-touch";
+
+export interface RemoteDesktopMobileToolbarProps {
+  mode: RemoteDesktopInputMode;
+  onToggleMode: () => void;
+  onOpenKeyboard: () => void;
+  onResetZoom: () => void;
+  onClose: () => void;
+}
+
+function ToolbarButton({
+  onClick,
+  label,
+  active,
+  children,
+}: {
+  onClick: () => void;
+  label: string;
+  active?: boolean;
+  children: React.ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label={label}
+      className={cn(
+        "flex min-h-11 min-w-11 flex-1 flex-col items-center justify-center gap-0.5 rounded-lg py-1.5 text-[10px]",
+        "text-white/80 active:bg-white/10 transition-colors",
+        active && "bg-white/15 text-white",
+      )}
+    >
+      {children}
+      <span>{label}</span>
+    </button>
+  );
+}
+
+export function RemoteDesktopMobileToolbar({
+  mode,
+  onToggleMode,
+  onOpenKeyboard,
+  onResetZoom,
+  onClose,
+}: RemoteDesktopMobileToolbarProps) {
+  const statsVisible = useSettingsStore((s) => s.remoteDesktopStatsVisible);
+  const toggleStats = useSettingsStore((s) => s.toggleRemoteDesktopStatsVisible);
+
+  return (
+    <div
+      className="flex shrink-0 items-stretch gap-1 border-t border-white/10 bg-black/90 px-2 pb-[max(0.375rem,env(safe-area-inset-bottom))] pt-1.5"
+      data-testid="remote-desktop-mobile-toolbar"
+    >
+      <ToolbarButton onClick={onToggleMode} label={mode === "mouse" ? "Mouse" : "Touch"} active>
+        {mode === "mouse" ? <MousePointer2 className="size-5" /> : <Hand className="size-5" />}
+      </ToolbarButton>
+      <ToolbarButton onClick={onOpenKeyboard} label="Keyboard">
+        <Keyboard className="size-5" />
+      </ToolbarButton>
+      <ToolbarButton onClick={onResetZoom} label="Reset zoom">
+        <ZoomOut className="size-5" />
+      </ToolbarButton>
+      <ToolbarButton onClick={toggleStats} label="Stats" active={statsVisible}>
+        <Gauge className="size-5" />
+      </ToolbarButton>
+      <ToolbarButton onClick={onClose} label="Close">
+        <X className="size-5" />
+      </ToolbarButton>
+    </div>
+  );
+}

package/src/web/components/remote-desktop/remote-desktop-mobile-view.tsx

@@ -0,0 +1,190 @@
+/**
+ * Mobile full-screen remote-desktop viewer: canvas + pinch-zoom/pan stage, gesture engine
+ * (`use-remote-desktop-touch`), virtual keyboard, and the bottom toolbar — hosted inside
+ * `remote-desktop-mobile-sheet.tsx`'s plain full-viewport portal. Shares the exact WS/nonce/
+ * ping/decode connection logic the desktop floating window uses
+ * (`use-remote-desktop-connection`), so this is presentation + input wiring only, not a
+ * parallel connection implementation.
+ */
+import { useRef, useState, useCallback } from "react";
+import { RotateCw, MonitorX } from "lucide-react";
+import { useVisualViewport } from "@/hooks/use-visual-viewport";
+import { useRemoteDesktopConnection } from "./use-remote-desktop-connection";
+import { useRemoteDesktopTouch, type RemoteDesktopInputMode } from "./use-remote-desktop-touch";
+import { useRemoteDesktopVirtualKeyboard } from "./use-remote-desktop-virtual-keyboard";
+import { RemoteDesktopMobileToolbar } from "./remote-desktop-mobile-toolbar";
+import { RemoteDesktopMobileKeyBar } from "./remote-desktop-mobile-key-bar";
+import { RemoteDesktopStatsOverlay } from "./remote-desktop-stats-overlay";
+import { letterboxedContentRect } from "./remote-desktop-coords";
+
+export interface RemoteDesktopMobileViewProps {
+  onClose: () => void;
+}
+
+export default function RemoteDesktopMobileView({ onClose }: RemoteDesktopMobileViewProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const [mode, setMode] = useState<RemoteDesktopInputMode>("mouse");
+  const [keyBarOpen, setKeyBarOpen] = useState(false);
+
+  const {
+    connState, errorMessage, decoderStatus, decoderErrorMessage, sendMessage, reconnect,
+    getTotalBytes, getFrameCount,
+  } = useRemoteDesktopConnection(canvasRef);
+  const streaming = connState === "streaming";
+
+  const { transform, virtualCursor, resetZoom } = useRemoteDesktopTouch({
+    containerRef,
+    canvasRef,
+    mode,
+    sendMessage,
+    enabled: streaming,
+  });
+  const { inputRef: keyboardInputRef, show: showKeyboard } = useRemoteDesktopVirtualKeyboard(sendMessage, streaming);
+
+  // Lifts the toolbar/key-bar row above the on-screen keyboard instead of the whole sheet
+  // shrinking to make room for it (that was the previous, since-reverted behavior — see
+  // remote-desktop-mobile-sheet.tsx's header comment for why it was wrong here).
+  const viewportInsets = useVisualViewport(true);
+  const keyboardInset = viewportInsets?.keyboardInset ?? 0;
+
+  const toggleMode = useCallback(() => setMode((m) => (m === "mouse" ? "touch" : "mouse")), []);
+  const openKeyboard = useCallback(() => { showKeyboard(); setKeyBarOpen(true); }, [showKeyboard]);
+
+  const overlayMessage = decoderStatus === "unsupported"
+    ? decoderErrorMessage
+    : connState === "error"
+      ? errorMessage
+      : connState === "closed"
+        ? "Disconnected"
+        : connState === "connecting"
+          ? "Connecting…"
+          : null;
+
+  const stageStyle = { transform: `translate(${transform.panX}px, ${transform.panY}px) scale(${transform.scale})` };
+
+  // Positions the virtual-cursor marker (mouse mode) at the video's actual displayed pixel,
+  // not a raw percentage of the stage — the canvas is letterboxed (object-contain) inside the
+  // stage whenever the capture's aspect ratio doesn't match the phone's, so a naive `left:
+  // xFrac*100%` would land inside the letterbox bars instead of on the video. Mirrors exactly
+  // what the gesture engine does for hit-testing (`letterboxedContentRect`), just forward
+  // instead of inverse. Reading layout here (not in an effect) is fine: it only feeds a cosmetic
+  // overlay position, recomputed on every render the cursor itself changes, which already
+  // happens on every drag frame.
+  let cursorLeft = `${(virtualCursor?.xFrac ?? 0.5) * 100}%`;
+  let cursorTop = `${(virtualCursor?.yFrac ?? 0.5) * 100}%`;
+  if (virtualCursor && containerRef.current && canvasRef.current?.width && canvasRef.current.height) {
+    const box = containerRef.current.getBoundingClientRect();
+    const videoRect = letterboxedContentRect({ left: 0, top: 0, width: box.width, height: box.height }, canvasRef.current.width, canvasRef.current.height);
+    cursorLeft = `${videoRect.left + virtualCursor.xFrac * videoRect.width}px`;
+    cursorTop = `${videoRect.top + virtualCursor.yFrac * videoRect.height}px`;
+  }
+
+  return (
+    <div className="relative h-full w-full bg-black" data-testid="remote-desktop-mobile-view" data-conn-state={connState}>
+      {/* Shrinks to the space above the on-screen keyboard (`bottom: keyboardInset`) so the
+          whole desktop stays visible, just smaller — `object-contain` on the canvas then
+          refits the video into whatever's left, same as it does for the bottom toolbar/notch
+          insets on a normal phone. `top:0` + explicit `bottom` (not `inset-0`) is what lets
+          `bottom` do that shrinking; gesture hit-testing already reads this element's own
+          `getBoundingClientRect()` fresh per gesture, so it stays correct as the box resizes. */}
+      <div
+        ref={containerRef}
+        className="absolute inset-x-0 top-0 flex items-center justify-center overflow-hidden"
+        style={{ touchAction: "none", bottom: keyboardInset }}
+        data-testid="remote-desktop-mobile-stage-container"
+      >
+        {/* `h-full w-full` on both this stage and the canvas below is load-bearing: it gives
+            the canvas a definite box to be letterboxed within (`object-contain` needs one), and
+            keeps the CSS transform's default `transform-origin: 50% 50%` exactly at this
+            container's center — the same point `fractionFromZoomedPoint` assumes. `min-h-0
+            min-w-0` on the canvas defeats the flex-item automatic-minimum-size floor (a
+            well-known flexbox gotcha for replaced elements): without it, a flex item's implicit
+            `min-height/width: auto` can hold the canvas at its intrinsic capture resolution
+            despite `height/width: 100%`, which is what made the video render oversized and get
+            clipped instead of actually shrinking to fit. */}
+        <div className="relative flex h-full w-full items-center justify-center" style={stageStyle}>
+          <canvas
+            ref={canvasRef}
+            data-testid="remote-desktop-canvas"
+            className="block h-full w-full min-h-0 min-w-0 object-contain outline-none"
+          />
+          {mode === "mouse" && virtualCursor && streaming && (
+            <div
+              className="pointer-events-none absolute rounded-full border-2 border-white bg-primary shadow-[0_0_0_1px_rgba(0,0,0,0.6)]"
+              style={{
+                left: cursorLeft,
+                top: cursorTop,
+                width: 14,
+                height: 14,
+                // Counter-scale by 1/zoom: this marker lives inside the zoomed stage, so
+                // without this it would grow right along with the video when zoomed in.
+                transform: `translate(-50%, -50%) scale(${1 / transform.scale})`,
+              }}
+              data-testid="remote-desktop-virtual-cursor"
+            />
+          )}
+        </div>
+
+        {overlayMessage && (
+          <div className="absolute inset-0 flex flex-col items-center justify-center gap-3 bg-black/70 text-sm text-white">
+            <MonitorX className="size-6 opacity-70" />
+            <span className="max-w-sm px-4 text-center">{overlayMessage}</span>
+            {(connState === "error" || connState === "closed") && decoderStatus !== "unsupported" && (
+              <button
+                onClick={reconnect}
+                className="flex items-center gap-1.5 rounded-md bg-white/10 px-3 py-1.5 hover:bg-white/20"
+              >
+                <RotateCw className="size-3.5" /> Reconnect
+              </button>
+            )}
+          </div>
+        )}
+
+        {/* Hidden input the toolbar's Keyboard button focuses to bring up the soft keyboard —
+            kept in normal layout flow (not display:none) since a hidden element cannot receive
+            focus, just visually collapsed to nothing. */}
+        <input
+          ref={keyboardInputRef}
+          type="text"
+          autoComplete="off"
+          autoCapitalize="off"
+          autoCorrect="off"
+          spellCheck={false}
+          className="absolute size-px opacity-0"
+          aria-hidden="true"
+          tabIndex={-1}
+          onBlur={() => setKeyBarOpen(false)}
+          data-testid="remote-desktop-virtual-keyboard-input"
+        />
+      </div>
+
+      {/* Floats above the on-screen keyboard via `keyboardInset` instead of the sheet shrinking
+          to make room — `translateY` rather than `bottom` so it animates smoothly and needs no
+          extra reflow. Sits at the true bottom (translateY(0)) once the keyboard is closed. */}
+      <div
+        className="absolute inset-x-0 bottom-0"
+        style={keyboardInset > 0 ? { transform: `translateY(-${keyboardInset}px)` } : undefined}
+        data-testid="remote-desktop-mobile-bottom-bar"
+      >
+        {keyBarOpen && <RemoteDesktopMobileKeyBar sendMessage={sendMessage} />}
+        <RemoteDesktopMobileToolbar
+          mode={mode}
+          onToggleMode={toggleMode}
+          onOpenKeyboard={openKeyboard}
+          onResetZoom={resetZoom}
+          onClose={onClose}
+        />
+      </div>
+
+      {/* Pushed below the app's top-left device-name pill + the notch safe-area (they overlap a
+          plain top-1 position on the phone). */}
+      <RemoteDesktopStatsOverlay
+        canvasRef={canvasRef}
+        getFrameCount={getFrameCount}
+        getTotalBytes={getTotalBytes}
+        positionClassName="left-1 top-[calc(env(safe-area-inset-top,0px)+2.75rem)]"
+      />
+    </div>
+  );
+}

package/src/web/components/remote-desktop/remote-desktop-stats-overlay.tsx

@@ -0,0 +1,54 @@
+/**
+ * Small, unobtrusive fps/KB-per-s/resolution overlay — shared by the desktop floating window
+ * (`remote-desktop-window-content.tsx`) and the mobile full-screen viewer
+ * (`remote-desktop-mobile-view.tsx`). Self-gated on `useSettingsStore().remoteDesktopStatsVisible`
+ * so both call sites just render it unconditionally; the toggle button on either surface flips
+ * that one shared setting.
+ *
+ * Polls the connection/decoder's ref-backed counters at ~2Hz — not a render dependency on every
+ * frame/message, which would defeat the point of keeping them refs.
+ */
+import { useEffect, useRef, useState } from "react";
+import { useSettingsStore } from "@/stores/settings-store";
+import { computeRemoteDesktopStats, type RemoteDesktopStatsSample } from "./remote-desktop-stats";
+
+const POLL_INTERVAL_MS = 500;
+
+export interface RemoteDesktopStatsOverlayProps {
+  canvasRef: React.RefObject<HTMLCanvasElement | null>;
+  getFrameCount: () => number;
+  getTotalBytes: () => number;
+  /** Position utility classes (default top-left). The mobile viewer overrides this to sit below
+   *  the app's top-left device-name pill + the notch safe-area, which otherwise cover it. */
+  positionClassName?: string;
+}
+
+export function RemoteDesktopStatsOverlay({ canvasRef, getFrameCount, getTotalBytes, positionClassName = "left-1 top-1" }: RemoteDesktopStatsOverlayProps) {
+  const visible = useSettingsStore((s) => s.remoteDesktopStatsVisible);
+  const [display, setDisplay] = useState({ fps: 0, kbps: 0, width: 0, height: 0 });
+  const lastSampleRef = useRef<RemoteDesktopStatsSample>({ frameCount: 0, totalBytes: 0, atMs: 0 });
+
+  useEffect(() => {
+    if (!visible) return;
+    lastSampleRef.current = { frameCount: getFrameCount(), totalBytes: getTotalBytes(), atMs: performance.now() };
+    const id = setInterval(() => {
+      const next: RemoteDesktopStatsSample = { frameCount: getFrameCount(), totalBytes: getTotalBytes(), atMs: performance.now() };
+      const { fps, kbps } = computeRemoteDesktopStats(lastSampleRef.current, next);
+      lastSampleRef.current = next;
+      const canvas = canvasRef.current;
+      setDisplay({ fps, kbps, width: canvas?.width ?? 0, height: canvas?.height ?? 0 });
+    }, POLL_INTERVAL_MS);
+    return () => clearInterval(id);
+  }, [visible, canvasRef, getFrameCount, getTotalBytes]);
+
+  if (!visible) return null;
+
+  return (
+    <div
+      className={`pointer-events-none absolute z-40 rounded bg-black/60 px-1.5 py-0.5 font-mono text-[10px] text-white/80 ${positionClassName}`}
+      data-testid="remote-desktop-stats-overlay"
+    >
+      {Math.round(display.fps)} fps · {Math.round(display.kbps)} KB/s · {display.width}×{display.height}
+    </div>
+  );
+}

package/src/web/components/remote-desktop/remote-desktop-stats.ts

@@ -0,0 +1,37 @@
+/**
+ * Pure fps/KB-per-second math for the stats overlay. Both inputs are cumulative, monotonically
+ * increasing counters (decoder frame count, total bytes received) sampled at two points in
+ * time — the overlay polls at ~2Hz and calls this on each tick with the previous and current
+ * sample, giving a rolling ~500ms window without needing a ring buffer of history.
+ */
+export interface RemoteDesktopStatsSample {
+  frameCount: number;
+  totalBytes: number;
+  /** Sample timestamp, e.g. `performance.now()` — any monotonic clock, ms. */
+  atMs: number;
+}
+
+export interface RemoteDesktopStats {
+  fps: number;
+  kbps: number;
+}
+
+const ZERO_STATS: RemoteDesktopStats = { fps: 0, kbps: 0 };
+
+/**
+ * Derives instantaneous fps/KB-per-s from two samples. Returns zeros (rather than dividing by
+ * zero or a negative interval) when `elapsedMs` isn't positive, and clamps a negative frame/byte
+ * delta to zero — the counters reset to 0 on a reconnect, so a sample straddling that moment
+ * would otherwise read as a huge negative rate for one tick.
+ */
+export function computeRemoteDesktopStats(prev: RemoteDesktopStatsSample, next: RemoteDesktopStatsSample): RemoteDesktopStats {
+  const elapsedMs = next.atMs - prev.atMs;
+  if (elapsedMs <= 0) return ZERO_STATS;
+  const elapsedSec = elapsedMs / 1000;
+  const frames = Math.max(0, next.frameCount - prev.frameCount);
+  const bytes = Math.max(0, next.totalBytes - prev.totalBytes);
+  return {
+    fps: frames / elapsedSec,
+    kbps: bytes / 1024 / elapsedSec,
+  };
+}