@hienlh/ppm 0.18.14 → 0.18.16

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

@@ -0,0 +1,48 @@
+/**
+ * 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,
+ * and the lazy chunk itself sits behind `RemoteDesktopWarningGate`, so it isn't even fetched
+ * until the user continues past the warning.
+ */
+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";
+import { RemoteDesktopWarningGate } from "./remote-desktop-warning-gate";
+
+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">
+      <RemoteDesktopWarningGate onCancel={close}>
+        <Suspense fallback={<div className="flex h-full items-center justify-center text-sm text-text-2">Loading…</div>}>
+          <RemoteDesktopMobileView onClose={close} />
+        </Suspense>
+      </RemoteDesktopWarningGate>
+    </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,
+  };
+}

package/src/web/components/remote-desktop/remote-desktop-touch-gesture-tracker.ts

@@ -0,0 +1,195 @@
+/**
+ * Pure(-ish) per-gesture accumulators for `use-remote-desktop-touch.ts` — kept out of the hook
+ * so the DOM-wiring there stays readable and these decision rules live in one place. Each
+ * `track` object is created on touchstart and mutated by the `advance*`/`resolve*` functions as
+ * touchmove/touchend events arrive; nothing here touches the DOM or sends messages directly,
+ * the hook does that with whatever these functions return.
+ */
+import { classifyTwoFingerGesture, isTapGesture, touchDistance, touchMidpoint, type PointerSample } from "./remote-desktop-gesture-classifiers";
+import { fractionFromZoomedPoint, type ZoomPanTransform, type Fraction, type Rect } from "./remote-desktop-coords";
+
+export type RemoteDesktopInputMode = "touch" | "mouse";
+
+export const TAP_MOVE_THRESHOLD_PX = 10;
+export const TAP_MAX_DURATION_MS = 300;
+export const TWO_FINGER_THRESHOLD_PX = 15;
+export const SCALE_MIN = 1;
+export const SCALE_MAX = 4;
+
+function clamp(n: number, min: number, max: number): number {
+  return Math.min(Math.max(n, min), max);
+}
+
+export function clickMessages(xFrac: number, yFrac: number, button: "left" | "right"): Record<string, unknown>[] {
+  return [
+    { type: "pointer", xFrac, yFrac, button, down: true },
+    { type: "pointer", xFrac, yFrac, button, down: false },
+  ];
+}
+
+/* ------------------------------------------------------------------ */
+/*  Single-finger tracking                                             */
+/* ------------------------------------------------------------------ */
+
+export interface SingleTrack {
+  start: PointerSample;
+  last: { x: number; y: number };
+  moved: boolean;
+  /** The displayed video's rect (post letterbox) at gesture start — cached because it does not
+   *  change mid-drag. */
+  rect: Rect;
+}
+
+export function beginSingleTouch(x: number, y: number, rect: Rect): SingleTrack {
+  return { start: { x, y, t: performance.now() }, last: { x, y }, moved: false, rect };
+}
+
+export interface SingleMoveResult {
+  /** Pointer message to send immediately (touch mode: drag-start once, then drag-move). */
+  message?: Record<string, unknown>;
+  /** New virtual-cursor fraction (mouse mode only). */
+  cursor?: Fraction;
+  sendCursorMove?: boolean;
+}
+
+export function advanceSingleTouch(
+  track: SingleTrack,
+  x: number,
+  y: number,
+  mode: RemoteDesktopInputMode,
+  transform: ZoomPanTransform,
+  cursor: Fraction,
+): SingleMoveResult {
+  const dist = Math.hypot(x - track.start.x, y - track.start.y);
+  if (mode === "touch") {
+    if (!track.moved && dist > TAP_MOVE_THRESHOLD_PX) {
+      track.moved = true;
+      const start = fractionFromZoomedPoint(track.start.x, track.start.y, track.rect, transform);
+      track.last = { x, y };
+      return { message: { type: "pointer", xFrac: start.xFrac, yFrac: start.yFrac, button: "left", down: true } };
+    }
+    track.last = { x, y };
+    if (!track.moved) return {};
+    const frac = fractionFromZoomedPoint(x, y, track.rect, transform);
+    return { message: { type: "pointer", xFrac: frac.xFrac, yFrac: frac.yFrac, button: null, down: null } };
+  }
+
+  // Mouse mode: relative drag of the client-side virtual cursor, scaled down by zoom so panning
+  // while zoomed in still moves the cursor the same *host* distance.
+  const dx = (x - track.last.x) / transform.scale;
+  const dy = (y - track.last.y) / transform.scale;
+  if (dist > TAP_MOVE_THRESHOLD_PX) track.moved = true;
+  track.last = { x, y };
+  const next: Fraction = {
+    xFrac: clamp(cursor.xFrac + dx / track.rect.width, 0, 1),
+    yFrac: clamp(cursor.yFrac + dy / track.rect.height, 0, 1),
+  };
+  return { cursor: next, sendCursorMove: true };
+}
+
+export function resolveSingleTouchEnd(
+  track: SingleTrack,
+  x: number,
+  y: number,
+  mode: RemoteDesktopInputMode,
+  transform: ZoomPanTransform,
+  cursor: Fraction,
+): Record<string, unknown>[] {
+  const end: PointerSample = { x, y, t: performance.now() };
+  const tapped = isTapGesture(track.start, end, TAP_MOVE_THRESHOLD_PX, TAP_MAX_DURATION_MS);
+  if (mode === "touch") {
+    const frac = fractionFromZoomedPoint(x, y, track.rect, transform);
+    if (!track.moved && tapped) return clickMessages(frac.xFrac, frac.yFrac, "left");
+    if (track.moved) return [{ type: "pointer", xFrac: frac.xFrac, yFrac: frac.yFrac, button: "left", down: false }];
+    return [];
+  }
+  if (!track.moved && tapped) return clickMessages(cursor.xFrac, cursor.yFrac, "left");
+  return [];
+}
+
+/* ------------------------------------------------------------------ */
+/*  Two-finger tracking                                                 */
+/* ------------------------------------------------------------------ */
+
+export interface TwoFingerTrack {
+  startDistance: number;
+  startMid: { x: number; y: number };
+  lastMid: { x: number; y: number };
+  startScale: number;
+  startTime: number;
+  gesture: "pinch" | "scroll" | null;
+}
+
+export function beginTwoFingerTouch(
+  pa: { x: number; y: number },
+  pb: { x: number; y: number },
+  currentScale: number,
+): TwoFingerTrack {
+  const mid = touchMidpoint(pa, pb);
+  return {
+    startDistance: touchDistance(pa, pb),
+    startMid: mid,
+    lastMid: mid,
+    startScale: currentScale,
+    startTime: performance.now(),
+    gesture: null,
+  };
+}
+
+export interface TwoFingerMoveResult {
+  transform?: ZoomPanTransform;
+  wheelDeltaPx?: number;
+}
+
+/** Locks in "pinch" vs "scroll" the first time either signal (finger spread, or midpoint
+ *  translation) crosses `TWO_FINGER_THRESHOLD_PX`, then keeps applying that gesture for the
+ *  rest of the touch — see `remote-desktop-gesture-classifiers.ts` for why. */
+export function advanceTwoFingerTouch(
+  track: TwoFingerTrack,
+  pa: { x: number; y: number },
+  pb: { x: number; y: number },
+  currentTransform: ZoomPanTransform,
+): TwoFingerMoveResult {
+  const currentDistance = touchDistance(pa, pb);
+  const currentMid = touchMidpoint(pa, pb);
+
+  if (track.gesture === null) {
+    const distDiff = Math.abs(currentDistance - track.startDistance);
+    const midDist = touchDistance(track.startMid, currentMid);
+    if (distDiff > TWO_FINGER_THRESHOLD_PX) {
+      track.gesture = classifyTwoFingerGesture(track.startDistance, currentDistance, TWO_FINGER_THRESHOLD_PX);
+    } else if (midDist > TWO_FINGER_THRESHOLD_PX) {
+      track.gesture = "scroll";
+    } else {
+      track.lastMid = currentMid;
+      return {}; // still ambiguous — wait for more movement before committing
+    }
+  }
+
+  let result: TwoFingerMoveResult;
+  if (track.gesture === "pinch") {
+    const scale = clamp(track.startScale * (currentDistance / track.startDistance), SCALE_MIN, SCALE_MAX);
+    result = { transform: { scale, panX: currentTransform.panX, panY: currentTransform.panY } };
+  } else if (currentTransform.scale > 1.01) {
+    // Panning only makes sense once zoomed in — at scale 1 the same drag scrolls instead.
+    const dx = currentMid.x - track.lastMid.x;
+    const dy = currentMid.y - track.lastMid.y;
+    result = { transform: { scale: currentTransform.scale, panX: currentTransform.panX + dx, panY: currentTransform.panY + dy } };
+  } else {
+    result = { wheelDeltaPx: currentMid.y - track.lastMid.y };
+  }
+  track.lastMid = currentMid;
+  return result;
+}
+
+export function resolveTwoFingerEnd(
+  track: TwoFingerTrack,
+  rect: Rect,
+  transform: ZoomPanTransform,
+): Record<string, unknown>[] {
+  if (track.gesture === null && performance.now() - track.startTime <= TAP_MAX_DURATION_MS) {
+    const frac = fractionFromZoomedPoint(track.lastMid.x, track.lastMid.y, rect, transform);
+    return clickMessages(frac.xFrac, frac.yFrac, "right");
+  }
+  return [];
+}