@hienlh/ppm 0.18.14 → 0.18.16

package/src/types/chat.ts

@@ -49,6 +49,8 @@ export interface AIProvider {
   getUsage?(): Promise<UsageInfo>;
   /** True when a live streaming subprocess exists for this session */
   hasStreamingSession?(sessionId: string): boolean;
+  /** Prompt-cache lifetime for this session, in ms — how long holding its subprocess pays. */
+  promptCacheTtlMs?(sessionId: string): number;
 }
 
 export interface ModelOption {

package/src/web/app.tsx

@@ -48,6 +48,9 @@ const MobileExplorerSheet = lazy(() =>
 const TeamMemberSheet = lazy(() =>
   import("@/components/chat/team-member-sheet").then((m) => ({ default: m.TeamMemberSheet })),
 );
+const RemoteDesktopMobileSheet = lazy(() =>
+  import("@/components/remote-desktop/remote-desktop-mobile-sheet").then((m) => ({ default: m.RemoteDesktopMobileSheet })),
+);
 
 type AuthState = "checking" | "authenticated" | "unauthenticated";
 
@@ -357,6 +360,11 @@ export function App() {
           <TeamMemberSheet />
         </Suspense>
 
+        {/* Mobile full-screen remote-desktop viewer — same reason as TeamMemberSheet above */}
+        <Suspense fallback={null}>
+          <RemoteDesktopMobileSheet />
+        </Suspense>
+
         {/* Global bug report popup */}
         <BugReportPopup />
 

package/src/web/components/chat/account-dialogs.tsx

@@ -70,9 +70,14 @@ export function AddAccountDialog({ open, onOpenChange, onSuccess }: AddAccountDi
     try {
       let code = oauthCode.trim();
       if (code.includes("#")) code = code.split("#")[0] ?? code;
-      await exchangeOAuthCode(code, oauthState);
+      const acc = await exchangeOAuthCode(code, oauthState);
       handleClose();
-      onSuccess("Account connected via OAuth!");
+      // Signing in again on an account this machine parked carries the token in but
+      // deliberately leaves it out of the rotation. A flat success over a toggle that is
+      // still off reads as a bug, and this is the only place the user finds out otherwise.
+      onSuccess(acc?.status === "disabled"
+        ? "Signed in. This account is still disabled — enable it to use it."
+        : "Account connected via OAuth!");
     } catch (e) {
       setAddError((e as Error).message);
     }
@@ -84,9 +89,11 @@ export function AddAccountDialog({ open, onOpenChange, onSuccess }: AddAccountDi
     setAdding(true);
     setAddError(null);
     try {
-      await addAccount({ apiKey: newToken.trim(), label: newLabel.trim() || undefined });
+      const acc = await addAccount({ apiKey: newToken.trim(), label: newLabel.trim() || undefined });
       handleClose();
-      onSuccess("Account added!");
+      onSuccess(acc?.status === "disabled"
+        ? "Token updated. This account is still disabled — enable it to use it."
+        : "Account added!");
     } catch (e) {
       setAddError((e as Error).message);
     }

package/src/web/components/chat/question-card.tsx

@@ -90,7 +90,11 @@ function useQuestionKeyboard(config: {
   useEffect(() => {
     if (!config.enabled) return;
     const handleKeyDown = (e: KeyboardEvent) => {
-      const isTyping = document.activeElement === config.customInputRef.current;
+      // Resolve focus from the input's OWN document: this card can be rendered inside a
+      // picture-in-picture window, and the module-global `document` is always the main one —
+      // there the input is never active, so every printable key would be treated as a shortcut.
+      const input = config.customInputRef.current;
+      const isTyping = !!input && input.ownerDocument.activeElement === input;
 
       // Number keys 1-9
       if (!isTyping && e.key >= "1" && e.key <= "9") {
@@ -132,7 +136,10 @@ function useQuestionKeyboard(config: {
     if (el) {
       el.addEventListener("keydown", handleKeyDown);
       el.setAttribute("tabindex", "0");
-      if (!el.contains(document.activeElement)) el.focus();
+      // Same reason: asking the main document whether focus is already inside the card answers
+      // "no" for a card living in another document, and this effect re-runs on every render —
+      // which would yank focus out of the custom input after each keystroke.
+      if (!el.contains(el.ownerDocument.activeElement)) el.focus();
     }
     return () => { el?.removeEventListener("keydown", handleKeyDown); };
   }, [config, focusedOption]);

package/src/web/components/chat/usage-badge.tsx

@@ -154,11 +154,12 @@ function formatLastUpdated(ts: number | null | undefined): string | null {
   return `${days}d ago`;
 }
 
-function AccountUsageCard({ entry, isActive, accountInfo, onToggle, onDelete, onExport, onViewProfile, flash, fullscreen }: {
+function AccountUsageCard({ entry, isActive, accountInfo, onToggle, toggling, onDelete, onExport, onViewProfile, flash, fullscreen }: {
   entry: AccountUsageEntry;
   isActive: boolean;
   accountInfo?: AccountInfo;
   onToggle?: (id: string, status: string) => void;
+  toggling?: boolean;
   onDelete?: (id: string, display: string) => void;
   onExport?: (id: string) => void;
   onViewProfile?: (profile: OAuthProfileData, accountId: string) => void;
@@ -207,7 +208,7 @@ function AccountUsageCard({ entry, isActive, accountInfo, onToggle, onDelete, on
             <Switch
               checked={status !== "disabled"}
               onCheckedChange={() => onToggle(entry.accountId, status)}
-              disabled={status === "cooldown"}
+              disabled={toggling || status === "cooldown"}
               className="scale-[0.6] cursor-pointer"
             />
           )}
@@ -269,6 +270,7 @@ export function UsageDetailPanel({ usage, visible, onClose, onReload, loading, l
   const [exportPreselect, setExportPreselect] = useState<string | null>(null);
   const [isFullscreen, setIsFullscreen] = useState(false);
   const [message, setMessage] = useState<string | null>(null);
+  const [togglingId, setTogglingId] = useState<string | null>(null);
   const msgTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
   const prevUsagesRef = useRef<AccountUsageEntry[]>([]);
 
@@ -345,7 +347,18 @@ export function UsageDetailPanel({ usage, visible, onClose, onReload, loading, l
   const fsRows = Math.ceil(fsCount / fsCols);
 
   async function handleToggle(id: string, status: string) {
-    await patchAccount(id, { status: status === "disabled" ? "active" : "disabled" });
+    // Enabling a parked account proves its token server-side first, which is a network
+    // round trip that can come back 400 — and patchAccount throws on that. Without the
+    // catch the message the server takes care to write reaches nobody: unhandled
+    // rejection, no toast, no reload, and the Switch silently snaps back. The pending
+    // flag is because that round trip can take most of a minute in the worst case.
+    setTogglingId(id);
+    try {
+      await patchAccount(id, { status: status === "disabled" ? "active" : "disabled" });
+    } catch (e) {
+      showMessage((e as Error).message);
+    }
+    setTogglingId(null);
     loadAll();
     onReload?.();
   }
@@ -440,6 +453,7 @@ export function UsageDetailPanel({ usage, visible, onClose, onReload, loading, l
                 isActive={entry.accountId === (activeAccountId ?? usage.activeAccountId)}
                 accountInfo={accountMap.get(entry.accountId)}
                 onToggle={handleToggle}
+                toggling={togglingId === entry.accountId}
                 onDelete={(id, display) => setDeleteTarget({ id, display })}
                 onExport={(id) => { setExportPreselect(id); setShowExportDialog(true); }}
                 onViewProfile={(profile, accountId) => setProfileView({ profile, accountId })}

package/src/web/components/floating-window/window-content-registry.ts

@@ -22,6 +22,7 @@ export const WINDOW_CONTENT: Record<WindowKind, LazyExoticComponent<ComponentTyp
   "team-member": lazy(() => import("@/components/chat/team-member-window-content")),
   "system-monitor": lazy(() => import("@/components/system/system-monitor-window-content")),
   "tab-host": lazy(() => import("./tab-host-window-content")),
+  "remote-desktop": lazy(() => import("@/components/remote-desktop/remote-desktop-window-content")),
 };
 
 /** Titlebar text for a window. Falls back to the kind's generic name. */
@@ -33,6 +34,7 @@ export function windowTitle(kind: WindowKind, payload?: Record<string, unknown>)
     return typeof member === "string" && member ? `Session — ${member}` : "Team member";
   }
   if (kind === "system-monitor") return "System Monitor";
+  if (kind === "remote-desktop") return "Remote Desktop";
   // A detached tab carries its title in the payload; the generic name only shows for a
   // window whose tab has not been resolved yet (restore before the layout is loaded).
   if (kind === "tab-host") return "Tab";

package/src/web/components/floating-window/window-store-types.ts

@@ -7,7 +7,7 @@ import type { Rect } from "./window-geometry";
  * Single source of truth: the persistence layer filters this list instead of repeating it,
  * so a new kind can never be silently dropped on reload.
  */
-export const WINDOW_KINDS = ["explorer", "team-member", "system-monitor", "tab-host"] as const;
+export const WINDOW_KINDS = ["explorer", "team-member", "system-monitor", "tab-host", "remote-desktop"] as const;
 
 export type WindowKind = (typeof WINDOW_KINDS)[number];
 

package/src/web/components/layout/mobile-drawer.tsx

@@ -1,5 +1,5 @@
 import { useState, useCallback, useEffect, useMemo } from "react";
-import { X, Bug as BugIcon, Cloud, FolderTree } from "lucide-react";
+import { X, Bug as BugIcon, Cloud, FolderTree, MonitorSmartphone } from "lucide-react";
 import { useShallow } from "zustand/react/shallow";
 import { useProjectStore } from "@/stores/project-store";
 import { useSettingsStore, type SidebarActiveTab } from "@/stores/settings-store";
@@ -23,7 +23,10 @@ import { CloudSharePopover } from "@/components/layout/cloud-share-popover";
 import { BottomSheet } from "@/components/ui/mobile-bottom-sheet";
 import { isMobileDevice } from "@/hooks/use-is-mobile";
 import { openExplorer } from "@/components/os-explorer/open-explorer";
+import { useOpenRemoteDesktop } from "@/components/remote-desktop/open-remote-desktop";
+import { useRemoteDesktopAvailable } from "@/components/remote-desktop/use-remote-desktop-available";
 import { FeatureBadge } from "@/components/ui/feature-badge";
+import type { FeatureBadgeId } from "@/lib/feature-badges";
 import { cn } from "@/lib/utils";
 
 // Tab ids the mobile drawer can render content for. `search` is desktop-only for now;
@@ -33,6 +36,24 @@ const MOBILE_SUPPORTED = new Set<string>([
 ]);
 const isMobileSupported = (id: SidebarActiveTab) => MOBILE_SUPPORTED.has(id) || id.startsWith("ext:");
 
+/** One utility tile in the drawer footer grid — icon over a short single-line label, with an
+ *  optional corner feature badge. Uniform size so the grid wraps cleanly as tiles are added,
+ *  instead of a single cramped row where long labels ("Cloud & Share") wrapped and overflowed. */
+function FooterTile({ icon: Icon, label, badge, onClick }: {
+  icon: React.ElementType; label: string; badge?: FeatureBadgeId; onClick: () => void;
+}) {
+  return (
+    <button
+      onClick={onClick}
+      className="group relative flex flex-col items-center justify-center gap-1 rounded-lg py-2.5 text-text-subtle hover:bg-surface-elevated hover:text-text-secondary transition-colors"
+    >
+      <Icon className="size-4" />
+      <span className="text-[10px] leading-none">{label}</span>
+      <FeatureBadge id={badge} variant="corner" />
+    </button>
+  );
+}
+
 interface MobileDrawerProps {
   isOpen: boolean;
   onClose: () => void;
@@ -47,6 +68,8 @@ export function MobileDrawer({ isOpen, onClose, initialTab }: MobileDrawerProps)
   const sidebarTabOrder = useSettingsStore((s) => s.sidebarTabOrder);
   const setSidebarTabOrder = useSettingsStore((s) => s.setSidebarTabOrder);
   const contributions = useExtensionStore((s) => s.contributions);
+  const { available: remoteDesktopAvailable } = useRemoteDesktopAvailable();
+  const openRemoteDesktop = useOpenRemoteDesktop();
   const [activeTab, setActiveTab] = useState<SidebarActiveTab>(initialTab ?? "explorer");
   const [cloudOpen, setCloudOpen] = useState(false);
 
@@ -138,33 +161,21 @@ export function MobileDrawer({ isOpen, onClose, initialTab }: MobileDrawerProps)
             onReorder={setSidebarTabOrder}
           />
 
-          {/* Files (OS explorer) + Report Bug + Cloud & Share + Version / Upgrade */}
-          <div className="flex items-center justify-between px-4 py-2 border-t border-border text-[11px]">
-            <UpgradeButton align="left" />
-            <div className="flex items-center gap-3">
+          {/* Footer: version/upgrade on its own line, then a uniform wrapping grid of utility
+              tiles (opens explorer/remote/cloud, report bug) — scales cleanly as tiles are added. */}
+          <div className="border-t border-border px-3 py-2">
+            <div className="grid grid-cols-4 gap-1">
               {/* Not a sidebar tab — the explorer opens as its own full-screen sheet. */}
-              <button
-                onClick={() => { onClose(); void openExplorer(); }}
-                className="flex items-center gap-1 text-[10px] text-text-subtle hover:text-text-secondary transition-colors"
-              >
-                <FolderTree className="size-3" />
-                <span>Files</span>
-                <FeatureBadge id="os-explorer" className="text-[7px] px-1" />
-              </button>
-              <button
-                onClick={() => setCloudOpen(true)}
-                className="flex items-center gap-1 text-[10px] text-text-subtle hover:text-text-secondary transition-colors"
-              >
-                <Cloud className="size-3" />
-                <span>Cloud &amp; Share</span>
-              </button>
-              <button
-                onClick={handleReportBug}
-                className="flex items-center gap-1 text-[10px] text-text-subtle hover:text-text-secondary transition-colors"
-              >
-                <BugIcon className="size-3" />
-                <span>Report Bug</span>
-              </button>
+              <FooterTile icon={FolderTree} label="Files" badge="os-explorer" onClick={() => { onClose(); void openExplorer(); }} />
+              {remoteDesktopAvailable && (
+                <FooterTile icon={MonitorSmartphone} label="Remote" badge="remote-desktop" onClick={() => { onClose(); openRemoteDesktop(); }} />
+              )}
+              <FooterTile icon={Cloud} label="Cloud" onClick={() => setCloudOpen(true)} />
+              <FooterTile icon={BugIcon} label="Bug" onClick={handleReportBug} />
+            </div>
+            {/* Version / upgrade pinned at the very bottom, under a divider. */}
+            <div className="mt-2 pt-2 border-t border-border px-1 text-[11px]">
+              <UpgradeButton align="left" />
             </div>
           </div>
         </div>

package/src/web/components/layout/nav-section-rail.tsx

@@ -1,7 +1,9 @@
 import { useState, useRef, useEffect, useMemo, memo } from "react";
 import { createPortal } from "react-dom";
-import { Settings, Bug, Cloud, FolderTree } from "lucide-react";
+import { Settings, Bug, Cloud, FolderTree, MonitorSmartphone } from "lucide-react";
 import { openExplorer } from "@/components/os-explorer/open-explorer";
+import { useOpenRemoteDesktop } from "@/components/remote-desktop/open-remote-desktop";
+import { useRemoteDesktopAvailable } from "@/components/remote-desktop/use-remote-desktop-available";
 import { FeatureBadge } from "@/components/ui/feature-badge";
 import type { FeatureBadgeId } from "@/lib/feature-badges";
 import { useSettingsStore, type SidebarActiveTab } from "@/stores/settings-store";
@@ -147,6 +149,9 @@ export const NavSectionRail = memo(function NavSectionRail({ className }: { clas
     return () => window.removeEventListener("open-cloud-share", open);
   }, []);
 
+  const openRemoteDesktop = useOpenRemoteDesktop();
+  const { available: remoteDesktopAvailable } = useRemoteDesktopAvailable();
+
   const handleReportBug = () => openBugReportPopup(version);
 
   // Rail tab click: collapsed → open on any tab; open → clicking the active tab closes it.
@@ -209,8 +214,11 @@ export const NavSectionRail = memo(function NavSectionRail({ className }: { clas
           </>,
           document.body,
         )}
-        {/* Not a sidebar tab — the explorer lives in its own floating window. */}
+        {/* Not sidebar tabs — these open their own floating windows. */}
         <FooterUtil icon={FolderTree} label="File Explorer" featureBadge="os-explorer" onClick={() => void openExplorer()} />
+        {remoteDesktopAvailable && (
+          <FooterUtil icon={MonitorSmartphone} label="Remote Desktop" featureBadge="remote-desktop" onClick={openRemoteDesktop} />
+        )}
         <FooterUtil icon={Bug} label="Report Bug" onClick={handleReportBug} />
         <FooterUtil icon={Settings} label="Settings" active={sidebarActiveTab === "settings"} onClick={() => handleTabClick("settings")} />
       </div>

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

@@ -0,0 +1,26 @@
+/**
+ * Opens the Remote Desktop viewer: a floating window on desktop, the full-screen mobile sheet
+ * below `md` (`WindowLayer` renders nothing there — same split `open-explorer.ts` makes for the
+ * file explorer). There is one host to control, so a second call on desktop focuses the
+ * existing window instead of opening another; on mobile the sheet is a singleton already.
+ */
+import { useCallback } from "react";
+import { useWindowStore } from "@/components/floating-window/window-store";
+import { isMobileDevice } from "@/hooks/use-is-mobile";
+import { useRemoteDesktopMobileOpenState } from "./use-remote-desktop-mobile-open-state";
+
+export function useOpenRemoteDesktop(): () => void {
+  const openWindow = useWindowStore((s) => s.open);
+  const focusWindow = useWindowStore((s) => s.focus);
+  const openMobileSheet = useRemoteDesktopMobileOpenState((s) => s.open);
+
+  return useCallback(() => {
+    if (isMobileDevice()) {
+      openMobileSheet();
+      return;
+    }
+    const existing = Object.values(useWindowStore.getState().windows).find((w) => w.kind === "remote-desktop");
+    if (existing) focusWindow(existing.id);
+    else openWindow("remote-desktop");
+  }, [openWindow, focusWindow, openMobileSheet]);
+}

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

@@ -0,0 +1,98 @@
+/**
+ * Client → host coordinate mapping. Only the canvas's CSS-pixel bounding rect matters —
+ * `devicePixelRatio` describes the *viewer's* screen (irrelevant to host pixels, and would
+ * double-scale/misplace the cursor if folded in), so it is deliberately never read here.
+ */
+export interface Fraction {
+  xFrac: number;
+  yFrac: number;
+}
+
+/** Plain bounding-box shape every function here accepts — deliberately not `DOMRect` so pure
+ *  computed rects (e.g. `letterboxedContentRect`'s output) satisfy it without faking DOM-only
+ *  members (`right`, `bottom`, `toJSON`, …) that nothing here ever reads. */
+export interface Rect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+function clamp01(n: number): number {
+  return Math.min(Math.max(n, 0), 1);
+}
+
+/** `rect` is the canvas element's `getBoundingClientRect()`. Fractions are clamped to 0..1 so
+ *  a pointer that slips just outside the element (fast drag) still maps to an edge, not a
+ *  wildly out-of-range host coordinate. */
+export function fractionFromPoint(clientX: number, clientY: number, rect: Rect): Fraction {
+  const xFrac = rect.width > 0 ? (clientX - rect.left) / rect.width : 0;
+  const yFrac = rect.height > 0 ? (clientY - rect.top) / rect.height : 0;
+  return { xFrac: clamp01(xFrac), yFrac: clamp01(yFrac) };
+}
+
+/** A CSS `transform: translate(panX, panY) scale(scale)` applied around the transformed
+ *  element's own center (the mobile viewer's default `transform-origin`). */
+export interface ZoomPanTransform {
+  scale: number;
+  panX: number;
+  panY: number;
+}
+
+/**
+ * Reverse-maps a screen point through an active pinch-zoom/pan transform back to a 0..1
+ * fraction of the capture — used by the mobile touch viewer, which zooms/pans the canvas with
+ * a CSS transform instead of re-rendering at a different resolution.
+ *
+ * `rect` MUST be the bounding rect of the never-transformed container the canvas fills at
+ * `scale=1, pan=0` (not the live, possibly-transformed canvas rect) — that container is the
+ * stable reference frame this function projects screen points back into. Deliberately pure
+ * arithmetic rather than reading the live (transformed) element's `getBoundingClientRect()`:
+ * jsdom does not compute CSS transforms into that rect at all, so this stays unit-testable,
+ * and it avoids relying on `transform-origin` math the browser applies opaquely.
+ */
+export function fractionFromZoomedPoint(
+  clientX: number,
+  clientY: number,
+  rect: Rect,
+  transform: ZoomPanTransform,
+): Fraction {
+  const scale = transform.scale || 1;
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+  const baseX = cx + (clientX - cx - transform.panX) / scale;
+  const baseY = cy + (clientY - cy - transform.panY) / scale;
+  return fractionFromPoint(baseX, baseY, rect);
+}
+
+/**
+ * The on-screen sub-rectangle a canvas actually paints its content into under `object-fit:
+ * contain` (or the equivalent CSS2.1 replaced-element max-width/max-height algorithm) — the
+ * canvas ELEMENT's own box does not shrink to the letterboxed video; only the pixels drawn
+ * inside it do. `box` is that element's box at rest (`scale=1, pan=0` — never the live,
+ * zoomed/panned rect: see `fractionFromZoomedPoint`'s doc comment for why), `contentWidth`/
+ * `contentHeight` are the canvas's drawing-buffer dimensions (its `.width`/`.height`
+ * attributes, i.e. the real capture resolution, NOT its CSS size).
+ *
+ * `object-fit: contain` centers the letterboxed content within `box` by default
+ * (`object-position: 50% 50%`), so this rect's own center always coincides with `box`'s
+ * center — that is what keeps `fractionFromZoomedPoint`'s transform-origin math (which derives
+ * `cx,cy` from whatever rect it's given) correct when this rect is passed to it instead of the
+ * raw container box.
+ *
+ * Falls back to `box` unchanged if the content has no size yet (e.g. before the first decoded
+ * frame sets `canvas.width`/`canvas.height`).
+ */
+export function letterboxedContentRect(box: Rect, contentWidth: number, contentHeight: number): Rect {
+  if (contentWidth <= 0 || contentHeight <= 0 || box.width <= 0 || box.height <= 0) return box;
+  const boxAspect = box.width / box.height;
+  const contentAspect = contentWidth / contentHeight;
+  if (contentAspect > boxAspect) {
+    // Content is relatively WIDER than the box -> width-constrained, letterboxed top/bottom.
+    const height = box.width / contentAspect;
+    return { left: box.left, top: box.top + (box.height - height) / 2, width: box.width, height };
+  }
+  // Content is relatively TALLER/narrower than the box -> height-constrained, letterboxed sides.
+  const width = box.height * contentAspect;
+  return { left: box.left + (box.width - width) / 2, top: box.top, width, height: box.height };
+}

package/src/web/components/remote-desktop/remote-desktop-frame-timestamp.ts

@@ -0,0 +1,21 @@
+/**
+ * Strictly-increasing microsecond timestamps for `EncodedVideoChunk`.
+ *
+ * The decoder previously used `performance.now() * 1000` per chunk. Some decoders — especially
+ * mobile hardware H.264 decoders — reject a chunk whose timestamp does not strictly increase
+ * from the previous one; two chunks landing in the same millisecond (easy at 30fps under normal
+ * network/encode jitter) get equal timestamps and can trip that check.
+ *
+ * This is decode-only playback (no A/V sync, nothing ever reads the timestamp back to schedule
+ * presentation), so the value only has to satisfy "strictly greater than the last one" — a
+ * frame-index-based synthetic clock does that unconditionally, independent of wall-clock
+ * resolution or jitter.
+ */
+const DEFAULT_FPS = 30;
+
+/** `frameIndex` is a 0-based, ever-incrementing counter of chunks decoded by ONE decoder
+ *  instance — reset it to 0 whenever a new `VideoDecoder` is created (a fresh instance has no
+ *  timestamp history to stay monotonic against). */
+export function frameTimestampMicros(frameIndex: number, fps: number = DEFAULT_FPS): number {
+  return Math.round((frameIndex * 1_000_000) / fps);
+}

package/src/web/components/remote-desktop/remote-desktop-gesture-classifiers.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure classifiers the mobile touch viewer's gesture engine uses to tell "tap" apart from
+ * "drag", and "pinch-zoom" apart from "two-finger scroll". Kept dependency-free (no DOM,
+ * no React) so they can be unit-tested without a browser.
+ */
+
+/** One sampled point in a gesture: client-space coordinates + a timestamp (ms, any monotonic
+ *  clock — `performance.now()` in the real hook). */
+export interface PointerSample {
+  x: number;
+  y: number;
+  t: number;
+}
+
+/** A tap is a touch that ends close to where it started, quickly — anything else (moved
+ *  further, or held longer) is a drag/long-press instead. Both thresholds must pass; a fast
+ *  but far swipe is a drag, and a slow-but-still finger is a long-press, not a tap. */
+export function isTapGesture(
+  start: PointerSample,
+  end: PointerSample,
+  moveThresholdPx = 10,
+  maxDurationMs = 300,
+): boolean {
+  const dist = Math.hypot(end.x - start.x, end.y - start.y);
+  const duration = end.t - start.t;
+  return dist <= moveThresholdPx && duration <= maxDurationMs;
+}
+
+export type TwoFingerGesture = "pinch" | "scroll";
+
+/**
+ * Two-finger gestures start ambiguous — pinch-zoom and two-finger-scroll both begin as "two
+ * fingers moved a little". They are told apart by which signal crosses its threshold first:
+ * the distance *between* the fingers changing (pinch) vs. their midpoint translating while
+ * staying roughly the same distance apart (scroll). Once a gesture is classified, the caller
+ * should keep calling this with the *same* `startDistance` for the rest of the gesture and
+ * lock in the first non-null-equivalent result — see `use-remote-desktop-touch.ts`.
+ */
+export function classifyTwoFingerGesture(
+  startDistance: number,
+  currentDistance: number,
+  distanceThresholdPx = 15,
+): TwoFingerGesture {
+  return Math.abs(currentDistance - startDistance) > distanceThresholdPx ? "pinch" : "scroll";
+}
+
+/** Euclidean distance between two touch points — shared helper so the hook and its tests
+ *  compute "finger spread" identically. */
+export function touchDistance(a: { x: number; y: number }, b: { x: number; y: number }): number {
+  return Math.hypot(b.x - a.x, b.y - a.y);
+}
+
+/** Midpoint between two touch points. */
+export function touchMidpoint(a: { x: number; y: number }, b: { x: number; y: number }): { x: number; y: number } {
+  return { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
+}

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