@hienlh/ppm 0.18.13 → 0.18.15

package/src/web/components/floating-window/open-tab-in-pip.ts

@@ -0,0 +1,78 @@
+/**
+ * Send a tab straight into picture-in-picture, without the user ever seeing a window.
+ *
+ * A PiP window can only adopt an element that is already in the page, and it needs somewhere
+ * to put it back. The floating window is that element and that home — so one still opens
+ * here, it is simply never shown: the frame keeps a pip-only window off screen, and closing
+ * PiP closes it, which re-docks the tab into the panel it came from.
+ */
+
+import { usePanelStore } from "@/stores/panel-store";
+import { focusPipDocument } from "./pip/pip-focus-target";
+import { attachPipHost } from "./pip/pip-host";
+import { TITLEBAR_HEIGHT } from "./window-chrome-contract";
+import {
+  clearPipOnlyWindow,
+  markPipOnlyWindow,
+  setWindowPip,
+  whenWindowSlot,
+} from "./window-pip-registry";
+import { useWindowStore } from "./window-store";
+
+export type OpenTabInPipResult = "opened" | "window-cap" | "cancelled";
+
+/** Drop the host window; its own teardown hands the tab back to the panel it came from. */
+function discard(windowId: string): void {
+  clearPipOnlyWindow(windowId);
+  useWindowStore.getState().close(windowId);
+}
+
+/**
+ * Detach a tab into a hidden window and adopt it into a PiP window.
+ *
+ * Rejects when the browser refuses the request (no support, or the click's activation was
+ * already spent); the caller reports that. Call it from a click handler with nothing awaited
+ * before it — the one await inside is a React commit, which leaves the activation valid.
+ */
+export async function openTabInPip(tabId: string, panelId: string): Promise<OpenTabInPipResult> {
+  const windowId = usePanelStore.getState().popOutTab(tabId, panelId);
+  if (!windowId) return "window-cap";
+  markPipOnlyWindow(windowId);
+
+  // The window exists in the store, but its body is created by the frame's layout effect —
+  // one commit away.
+  const slot = await whenWindowSlot(windowId);
+  if (!slot) {
+    discard(windowId);
+    return "cancelled";
+  }
+
+  const rect = useWindowStore.getState().windows[windowId]?.rect;
+  let handle;
+  try {
+    handle = await attachPipHost(slot, {
+      // A zero falls through to the host's minimum size rather than a magic default.
+      width: rect?.w ?? 0,
+      height: rect ? rect.h - TITLEBAR_HEIGHT : 0,
+      onDetach: () => {
+        setWindowPip(windowId, null);
+        // Closing PiP means "done with this tab out here", not "give me a window instead":
+        // the tab goes back to its strip.
+        discard(windowId);
+      },
+    });
+  } catch (err) {
+    discard(windowId);
+    throw err;
+  }
+
+  // Null means the window went away while the request was in flight; the host already
+  // restored what it had and called onDetach.
+  if (!handle) return "cancelled";
+
+  setWindowPip(windowId, handle);
+  // A DOM move carries no focus with it: without this the tab is visible in PiP but swallows
+  // nothing until the user clicks it.
+  focusPipDocument(handle.pipWindow.document);
+  return "opened";
+}

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-pip-registry.ts

@@ -24,6 +24,52 @@ const listeners = new Set<() => void>();
 export function publishWindowSlot(windowId: string, el: HTMLElement | null): void {
   if (el) slots.set(windowId, el);
   else slots.delete(windowId);
+  for (const notify of listeners) notify();
+}
+
+/**
+ * Resolve once a window has published its body, or `null` if it never does.
+ *
+ * A window opened to host a picture-in-picture request exists in the store before React has
+ * mounted its frame, so the element the PiP host needs does not exist yet in the click
+ * handler that created it. Waiting is safe: transient activation survives a commit, it is
+ * consuming it twice that the browser refuses.
+ */
+export function whenWindowSlot(windowId: string, timeoutMs = 2000): Promise<HTMLElement | null> {
+  const existing = windowSlot(windowId);
+  if (existing) return Promise.resolve(existing);
+  return new Promise((resolve) => {
+    const settle = (el: HTMLElement | null) => {
+      listeners.delete(check);
+      clearTimeout(timer);
+      resolve(el);
+    };
+    const check = () => {
+      const el = windowSlot(windowId);
+      if (el) settle(el);
+    };
+    const timer = setTimeout(() => settle(null), timeoutMs);
+    listeners.add(check);
+  });
+}
+
+/**
+ * Windows that exist only to carry a tab into picture-in-picture: the frame keeps them off
+ * screen while PiP is up, and closing PiP closes the window, so the tab goes straight back
+ * to its tab strip instead of stranding an empty window the user never asked for.
+ */
+const pipOnly = new Set<string>();
+
+export function markPipOnlyWindow(windowId: string): void {
+  pipOnly.add(windowId);
+}
+
+export function isPipOnlyWindow(windowId: string): boolean {
+  return pipOnly.has(windowId);
+}
+
+export function clearPipOnlyWindow(windowId: string): void {
+  pipOnly.delete(windowId);
 }
 
 /** The body element of a mounted window, or null. */

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/layout/tab-pop-out-menu-item.tsx

@@ -1,12 +1,17 @@
 /**
- * "Open in window" — detaches a tab into a floating window, keeping it live.
+ * "Open in window" / "Open in picture-in-picture" — detaches a tab, keeping it live.
+ *
+ * The PiP route skips the window entirely from the user's point of view: a host window is
+ * opened and hidden, and closing PiP closes it, so the tab lands back in this strip.
  *
  * Desktop only: the window layer renders nothing below the md breakpoint, so on a phone
  * the item would move a tab somewhere the user cannot see (a scaled-down window is never
  * the answer — see the mobile-first UI rules).
  */
-import { ExternalLink } from "lucide-react";
+import { ExternalLink, PictureInPicture2 } from "lucide-react";
 import { toast } from "sonner";
+import { openTabInPip } from "@/components/floating-window/open-tab-in-pip";
+import { isDocumentPipSupported } from "@/components/floating-window/pip/pip-support";
 import { ContextMenuItem, ContextMenuSeparator } from "@/components/ui/context-menu";
 import { useIsMobile } from "@/hooks/use-is-mobile";
 import { usePanelStore } from "@/stores/panel-store";
@@ -36,6 +41,24 @@ export function TabPopOutMenuItem({ tab, panelId }: TabPopOutMenuItemProps) {
         <ExternalLink className="size-3.5 mr-2" />
         Open in window
       </ContextMenuItem>
+      {isDocumentPipSupported() && (
+        <ContextMenuItem
+          onClick={() => {
+            // Nothing awaited before this call: it spends the click's activation on the PiP
+            // request, and the browser grants that only to a live gesture.
+            void openTabInPip(tab.id, panelId)
+              .then((result) => {
+                if (result === "window-cap") toast.error("Too many windows open — close one first");
+              })
+              .catch(() => {
+                toast.error("Could not open the picture-in-picture window");
+              });
+          }}
+        >
+          <PictureInPicture2 className="size-3.5 mr-2" />
+          Open in picture-in-picture
+        </ContextMenuItem>
+      )}
       <ContextMenuSeparator />
     </>
   );

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