@hienlh/ppm 0.18.15 → 0.19.0

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

@@ -16,12 +16,16 @@
  * 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.
+ * `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";
+import { RemoteDesktopReadinessGate } from "./remote-desktop-readiness-gate";
 
 const RemoteDesktopMobileView = lazy(() => import("./remote-desktop-mobile-view"));
 
@@ -34,9 +38,13 @@ export function RemoteDesktopMobileSheet() {
 
   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>
+      <RemoteDesktopWarningGate onCancel={close}>
+        <RemoteDesktopReadinessGate onCancel={close}>
+          <Suspense fallback={<div className="flex h-full items-center justify-center text-sm text-text-2">Loading…</div>}>
+            <RemoteDesktopMobileView onClose={close} />
+          </Suspense>
+        </RemoteDesktopReadinessGate>
+      </RemoteDesktopWarningGate>
     </div>,
     portalContainer ?? document.getElementById("root") ?? document.body,
   );

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

@@ -3,12 +3,16 @@
  * 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 { Hand, MousePointer2, Keyboard, ZoomOut, Gauge, Monitor, 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 {
+  /** Current display's name on a multi-monitor host; null hides the button (single display). */
+  displayLabel: string | null;
+  /** Cycle to the next display — one tap per hop beats a dropdown in the thumb zone. */
+  onNextDisplay: () => void;
   mode: RemoteDesktopInputMode;
   onToggleMode: () => void;
   onOpenKeyboard: () => void;
@@ -45,6 +49,8 @@ function ToolbarButton({
 }
 
 export function RemoteDesktopMobileToolbar({
+  displayLabel,
+  onNextDisplay,
   mode,
   onToggleMode,
   onOpenKeyboard,
@@ -68,6 +74,11 @@ export function RemoteDesktopMobileToolbar({
       <ToolbarButton onClick={onResetZoom} label="Reset zoom">
         <ZoomOut className="size-5" />
       </ToolbarButton>
+      {displayLabel !== null && (
+        <ToolbarButton onClick={onNextDisplay} label={displayLabel.length > 10 ? `${displayLabel.slice(0, 9)}…` : displayLabel}>
+          <Monitor className="size-5" />
+        </ToolbarButton>
+      )}
       <ToolbarButton onClick={toggleStats} label="Stats" active={statsVisible}>
         <Gauge className="size-5" />
       </ToolbarButton>

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

@@ -16,6 +16,7 @@ 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";
+import { useRemoteDesktopDisplayChoice } from "./use-remote-desktop-display-choice";
 
 export interface RemoteDesktopMobileViewProps {
   onClose: () => void;
@@ -26,11 +27,12 @@ export default function RemoteDesktopMobileView({ onClose }: RemoteDesktopMobile
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
   const [mode, setMode] = useState<RemoteDesktopInputMode>("mouse");
   const [keyBarOpen, setKeyBarOpen] = useState(false);
+  const display = useRemoteDesktopDisplayChoice();
 
   const {
     connState, errorMessage, decoderStatus, decoderErrorMessage, sendMessage, reconnect,
     getTotalBytes, getFrameCount,
-  } = useRemoteDesktopConnection(canvasRef);
+  } = useRemoteDesktopConnection(canvasRef, { displayId: display.displayId });
   const streaming = connState === "streaming";
 
   const { transform, virtualCursor, resetZoom } = useRemoteDesktopTouch({
@@ -169,6 +171,8 @@ export default function RemoteDesktopMobileView({ onClose }: RemoteDesktopMobile
       >
         {keyBarOpen && <RemoteDesktopMobileKeyBar sendMessage={sendMessage} />}
         <RemoteDesktopMobileToolbar
+          displayLabel={display.displays.length > 1 ? display.current?.label ?? null : null}
+          onNextDisplay={display.next}
           mode={mode}
           onToggleMode={toggleMode}
           onOpenKeyboard={openKeyboard}

package/src/web/components/remote-desktop/remote-desktop-readiness-gate.tsx

@@ -0,0 +1,128 @@
+/**
+ * Second gate after the warning: the host's requirements checklist. Renders `children` (the
+ * viewer) straight away when every requirement is met; otherwise shows one row per item with
+ * its actions and re-polls until they clear. Video requirements block; input requirements only
+ * downgrade the button to "view only" — a screen you can see but not drive is still useful.
+ *
+ * Actions are generic (`terminal` types into a PPM dock terminal — the host's shell, so it works
+ * from a phone; `host` asks the server to prompt/open Settings on the host; `link` opens on the
+ * client). Same dark chrome and ≥44px targets as the warning gate, both surfaces.
+ */
+import { useState, type ReactNode } from "react";
+import { CheckCircle2, Circle, ExternalLink, Loader2, MonitorSmartphone, TerminalSquare } from "lucide-react";
+import { runInTerminal } from "@/lib/run-in-terminal";
+import { useRemoteDesktopReadiness, type RemoteDesktopRequirement, type RequirementAction } from "./use-remote-desktop-readiness";
+
+export interface RemoteDesktopReadinessGateProps {
+  onCancel: () => void;
+  children: ReactNode;
+}
+
+export function RemoteDesktopReadinessGate({ onCancel, children }: RemoteDesktopReadinessGateProps) {
+  const [accepted, setAccepted] = useState(false);
+  const { caps, failed, runHostAction } = useRemoteDesktopReadiness(!accepted);
+
+  if (accepted || (caps?.videoReady && caps.inputReady)) return <>{children}</>;
+
+  const pending = caps?.requirements.filter((r) => !r.ok) ?? [];
+  const viewOnly = !!caps?.videoReady && !caps.inputReady;
+  // The dock terminal opens *under* this surface (the mobile sheet covers the whole viewport),
+  // so hand the command over and get out of the way; the entry stays in the nav to come back to.
+  const onTerminal = (command: string) => { runInTerminal(command); onCancel(); };
+
+  return (
+    <div
+      className="flex h-full w-full items-center justify-center overflow-y-auto bg-black p-4 text-white"
+      data-testid="remote-desktop-readiness-gate"
+    >
+      <div className="flex w-full max-w-sm flex-col gap-4 rounded-xl border border-white/10 bg-white/5 p-5">
+        <div className="flex items-center gap-2">
+          <MonitorSmartphone className="size-5 shrink-0 text-primary" />
+          <h2 className="text-base font-semibold">This host needs a few things</h2>
+        </div>
+
+        {!caps && !failed && (
+          <div className="flex items-center gap-2 text-sm text-white/70"><Loader2 className="size-4 animate-spin" /> Checking the host…</div>
+        )}
+        {failed && <p className="text-sm text-red-300">Could not reach the host&apos;s remote-desktop service.</p>}
+
+        <ul className="flex flex-col gap-3">
+          {caps?.requirements.map((r) => (
+            <RequirementRow key={r.id} req={r} onHostAction={runHostAction} onTerminal={onTerminal} />
+          ))}
+        </ul>
+
+        {pending.length > 0 && (
+          <p className="text-xs text-white/50">Re-checking every few seconds — this updates by itself once fixed.</p>
+        )}
+
+        <div className="flex gap-2">
+          <button type="button" onClick={onCancel} className="min-h-11 flex-1 rounded-md bg-white/10 px-3 text-sm hover:bg-white/20">
+            Cancel
+          </button>
+          <button
+            type="button"
+            disabled={!caps?.videoReady}
+            onClick={() => setAccepted(true)}
+            className="min-h-11 flex-1 rounded-md bg-primary px-3 text-sm font-medium text-primary-foreground hover:bg-primary/90 disabled:cursor-not-allowed disabled:opacity-40"
+            data-testid="remote-desktop-readiness-continue"
+          >
+            {viewOnly ? "Continue (view only)" : "Continue"}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+interface ActionHandlers {
+  onHostAction: (id: string, a: "request" | "open-settings") => Promise<void>;
+  onTerminal: (command: string) => void;
+}
+
+function RequirementRow({ req, ...handlers }: { req: RemoteDesktopRequirement } & ActionHandlers) {
+  return (
+    <li className="flex gap-2" data-testid={`remote-desktop-requirement-${req.id}`} data-ok={req.ok}>
+      {req.ok
+        ? <CheckCircle2 className="mt-0.5 size-4 shrink-0 text-emerald-400" />
+        : <Circle className="mt-0.5 size-4 shrink-0 text-amber-300" />}
+      <div className="flex min-w-0 flex-1 flex-col gap-2">
+        <div className="text-sm font-medium">
+          {req.title}
+          {!req.ok && <span className="ml-2 text-xs font-normal text-white/50">{req.gates === "video" ? "required" : "for mouse & keyboard"}</span>}
+        </div>
+        {!req.ok && (
+          <>
+            <p className="text-sm text-white/70">{req.detail}</p>
+            <div className="flex flex-wrap gap-2">
+              {req.actions.map((a) => <ActionButton key={a.label} action={a} reqId={req.id} {...handlers} />)}
+            </div>
+          </>
+        )}
+      </div>
+    </li>
+  );
+}
+
+function ActionButton({ action, reqId, onHostAction, onTerminal }: { action: RequirementAction; reqId: string } & ActionHandlers) {
+  const cls = "inline-flex min-h-11 items-center gap-1.5 rounded-md bg-white/10 px-3 text-sm hover:bg-white/20";
+  if (action.kind === "terminal") {
+    return (
+      <button type="button" className={cls} onClick={() => onTerminal(action.command)} title={action.command}>
+        <TerminalSquare className="size-4" /> {action.label}
+      </button>
+    );
+  }
+  if (action.kind === "link") {
+    return (
+      <a className={cls} href={action.url} target="_blank" rel="noreferrer">
+        <ExternalLink className="size-4" /> {action.label}
+      </a>
+    );
+  }
+  return (
+    <button type="button" className={cls} onClick={() => void onHostAction(reqId, action.action)}>
+      {action.label}
+    </button>
+  );
+}

package/src/web/components/remote-desktop/remote-desktop-warning-gate.tsx

@@ -0,0 +1,106 @@
+/**
+ * Warning shown before the Remote Desktop viewer connects — wraps both the desktop window body
+ * (`remote-desktop-window-content.tsx`) and the mobile full-screen view
+ * (`remote-desktop-mobile-sheet.tsx`). The viewer is only mounted after the user continues, so
+ * no session nonce is minted and no frame is captured while the warning is up.
+ *
+ * Shown on every open until the user ticks "don't show again", which persists via the shared
+ * `remoteDesktopWarningDismissed` UI pref (server-side, like the stats-overlay toggle) so the
+ * choice follows them across devices. Dark chrome on purpose: it sits where the black canvas
+ * will be, on both surfaces.
+ */
+import { useState, type ReactNode } from "react";
+import { MonitorSmartphone, ShieldAlert } from "lucide-react";
+import { useSettingsStore } from "@/stores/settings-store";
+
+export interface RemoteDesktopWarningGateProps {
+  /** Called when the user backs out instead of continuing — close the window/sheet. */
+  onCancel: () => void;
+  children: ReactNode;
+}
+
+export function RemoteDesktopWarningGate({ onCancel, children }: RemoteDesktopWarningGateProps) {
+  const dismissed = useSettingsStore((s) => s.remoteDesktopWarningDismissed);
+  const setDismissed = useSettingsStore((s) => s.setRemoteDesktopWarningDismissed);
+  const [accepted, setAccepted] = useState(false);
+  const [dontShowAgain, setDontShowAgain] = useState(false);
+
+  if (dismissed || accepted) return <>{children}</>;
+
+  const onContinue = () => {
+    if (dontShowAgain) setDismissed(true);
+    setAccepted(true);
+  };
+
+  return (
+    <div
+      className="flex h-full w-full items-center justify-center overflow-y-auto bg-black p-4 text-white"
+      data-testid="remote-desktop-warning-gate"
+    >
+      <div className="flex w-full max-w-sm flex-col gap-4 rounded-xl border border-white/10 bg-white/5 p-5">
+        <div className="flex items-center gap-2">
+          <MonitorSmartphone className="size-5 shrink-0 text-primary" />
+          <h2 className="text-base font-semibold">Remote Desktop</h2>
+          <span className="ml-auto rounded-full bg-amber-500/20 px-2 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-amber-300">
+            Beta
+          </span>
+        </div>
+
+        <ul className="flex flex-col gap-2 text-sm text-white/80">
+          <li className="flex gap-2">
+            <ShieldAlert className="mt-0.5 size-4 shrink-0 text-amber-300" />
+            <span>
+              This streams the host&apos;s <strong>whole screen</strong> and lets you <strong>move its mouse and type</strong> as if
+              you were sitting at it. Anything you do here happens on the real desktop.
+            </span>
+          </li>
+          <li className="flex gap-2">
+            <ShieldAlert className="mt-0.5 size-4 shrink-0 text-amber-300" />
+            <span>
+              Anyone signed in to this PPM can do the same. Avoid opening it over a public share link you don&apos;t fully
+              trust; a private network (Tailscale, LAN) is safer.
+            </span>
+          </li>
+          <li className="flex gap-2">
+            <ShieldAlert className="mt-0.5 size-4 shrink-0 text-amber-300" />
+            <span>
+              Still beta: the host must be unlocked with an active session, UAC prompts stay hidden, and a person at the
+              host will fight you for the cursor.
+            </span>
+          </li>
+        </ul>
+
+        <label className="flex min-h-11 cursor-pointer items-center gap-2 text-sm text-white/70">
+          <input
+            type="checkbox"
+            checked={dontShowAgain}
+            onChange={(e) => setDontShowAgain(e.target.checked)}
+            className="size-4 accent-primary"
+            data-testid="remote-desktop-warning-dont-show"
+          />
+          Don&apos;t show this again
+        </label>
+
+        {/* Primary action last (thumb zone on mobile); both ≥44px tall. */}
+        <div className="flex gap-2">
+          <button
+            type="button"
+            onClick={onCancel}
+            className="min-h-11 flex-1 rounded-md bg-white/10 px-3 text-sm hover:bg-white/20"
+            data-testid="remote-desktop-warning-cancel"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={onContinue}
+            className="min-h-11 flex-1 rounded-md bg-primary px-3 text-sm font-medium text-primary-foreground hover:bg-primary/90"
+            data-testid="remote-desktop-warning-continue"
+          >
+            Continue
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/web/components/remote-desktop/remote-desktop-window-content.tsx

@@ -1,21 +1,40 @@
 /**
  * Remote Desktop window body: thin wrapper around `useRemoteDesktopConnection` (WS/nonce/ping/
  * decode, shared with the mobile viewer) that renders the canvas, overlay states, and wires
- * pointer/keyboard capture over the connection's `sendMessage`.
+ * pointer/keyboard capture over the connection's `sendMessage`. Sits behind
+ * `RemoteDesktopWarningGate`, so the connection hook (and its session nonce) only runs once the
+ * user has read the warning.
  */
-import { useRef } from "react";
+import { useCallback, useRef } from "react";
 import { RotateCw, MonitorX, Gauge } from "lucide-react";
 import type { WindowContentProps } from "@/components/floating-window/window-content-registry";
+import { useWindowStore } from "@/components/floating-window/window-store";
 import { useSettingsStore } from "@/stores/settings-store";
 import { cn } from "@/lib/utils";
 import { useRemoteDesktopConnection } from "./use-remote-desktop-connection";
 import { useRemoteInputCapture } from "./use-remote-input-capture";
 import { RemoteDesktopStatsOverlay } from "./remote-desktop-stats-overlay";
+import { RemoteDesktopWarningGate } from "./remote-desktop-warning-gate";
+import { RemoteDesktopReadinessGate } from "./remote-desktop-readiness-gate";
+import { useRemoteDesktopDisplayChoice } from "./use-remote-desktop-display-choice";
 
-export default function RemoteDesktopWindowContent(_props: WindowContentProps) {
+export default function RemoteDesktopWindowContent({ id }: WindowContentProps) {
+  const closeWindow = useWindowStore((s) => s.close);
+  const onCancel = useCallback(() => closeWindow(id), [closeWindow, id]);
+  return (
+    <RemoteDesktopWarningGate onCancel={onCancel}>
+      <RemoteDesktopReadinessGate onCancel={onCancel}>
+        <RemoteDesktopViewer />
+      </RemoteDesktopReadinessGate>
+    </RemoteDesktopWarningGate>
+  );
+}
+
+function RemoteDesktopViewer() {
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const display = useRemoteDesktopDisplayChoice();
   const { connState, errorMessage, decoderStatus, decoderErrorMessage, sendMessage, reconnect, getFrameCount, getTotalBytes } =
-    useRemoteDesktopConnection(canvasRef);
+    useRemoteDesktopConnection(canvasRef, { displayId: display.displayId });
   const statsVisible = useSettingsStore((s) => s.remoteDesktopStatsVisible);
   const toggleStats = useSettingsStore((s) => s.toggleRemoteDesktopStatsVisible);
 
@@ -39,6 +58,21 @@ export default function RemoteDesktopWindowContent(_props: WindowContentProps) {
     >
       <canvas ref={canvasRef} data-testid="remote-desktop-canvas" className="max-h-full max-w-full outline-none" />
       <RemoteDesktopStatsOverlay canvasRef={canvasRef} getFrameCount={getFrameCount} getTotalBytes={getTotalBytes} />
+      {/* Multi-monitor hosts: pick which display to stream. Left of the stats toggle, same
+          corner cluster; a single-display host renders nothing here. */}
+      {display.displays.length > 1 && (
+        <select
+          value={display.current?.id ?? ""}
+          onChange={(e) => display.select(e.target.value)}
+          aria-label="Display"
+          className="absolute right-8 top-1 z-40 h-6 max-w-[45%] rounded bg-black/40 px-1.5 text-xs text-white/80 hover:bg-black/60"
+          data-testid="remote-desktop-display-select"
+        >
+          {display.displays.map((d) => (
+            <option key={d.id} value={d.id}>{d.label}{d.primary ? " (main)" : ""} · {d.width}×{d.height}</option>
+          ))}
+        </select>
+      )}
       {/* Small corner toggle for the stats overlay above — top-right so it never collides with
           the overlay itself (top-left) or the window's own title bar/controls above this body. */}
       <button

package/src/web/components/remote-desktop/use-remote-desktop-available.ts

@@ -1,29 +1,12 @@
 /**
- * Fetches remote-desktop capabilities once and reports whether the feature should surface in
- * the UI. Returns `available=false` when the server feature flag is off (the endpoint 404s) or
- * video capture is unavailable, so the nav entry stays hidden unless `REMOTE_DESKTOP_ENABLED`
- * is set and ffmpeg can capture.
+ * Whether the Remote Desktop entry should surface in the UI. Hidden only when the host opted
+ * out (`REMOTE_DESKTOP_ENABLED=0` — the endpoint 404s) or the OS has no capture path at all.
+ * Everything the user can fix in place — ffmpeg missing, a macOS permission not granted — keeps
+ * the entry visible; `RemoteDesktopReadinessGate` walks them through it after the warning.
  */
-import { useEffect, useState } from "react";
-import { api } from "@/lib/api-client";
-
-interface Capabilities {
-  ffmpegAvailable: boolean;
-  videoAvailable: boolean;
-  inputAvailable: boolean;
-  authRequired: boolean;
-}
+import { useRemoteDesktopReadiness } from "./use-remote-desktop-readiness";
 
 export function useRemoteDesktopAvailable(): { available: boolean; authRequired: boolean } {
-  const [caps, setCaps] = useState<Capabilities | null>(null);
-
-  useEffect(() => {
-    let cancelled = false;
-    api.get<Capabilities>("/api/remote-desktop/capabilities")
-      .then((c) => { if (!cancelled) setCaps(c); })
-      .catch(() => { if (!cancelled) setCaps(null); }); // 404 (flag off) or network error — stay hidden
-    return () => { cancelled = true; };
-  }, []);
-
-  return { available: !!caps?.videoAvailable, authRequired: !!caps?.authRequired };
+  const { caps } = useRemoteDesktopReadiness(false);
+  return { available: !!caps?.platformSupported, authRequired: !!caps?.authRequired };
 }

package/src/web/components/remote-desktop/use-remote-desktop-connection.ts

@@ -39,8 +39,15 @@ export interface UseRemoteDesktopConnectionResult {
   getFrameCount: () => number;
 }
 
+export interface UseRemoteDesktopConnectionOptions {
+  /** One of `/capabilities`' `displays[].id`; undefined = the host's primary display. Changing it
+   *  tears the session down and reconnects on the new display — one ffmpeg per display. */
+  displayId?: string;
+}
+
 export function useRemoteDesktopConnection(
   canvasRef: React.RefObject<HTMLCanvasElement | null>,
+  { displayId }: UseRemoteDesktopConnectionOptions = {},
 ): UseRemoteDesktopConnectionResult {
   const wsRef = useRef<WebSocket | null>(null);
   const totalBytesRef = useRef(0);
@@ -82,7 +89,7 @@ export function useRemoteDesktopConnection(
       wsRef.current = ws;
 
       ws.onopen = () => {
-        ws.send(JSON.stringify({ type: "auth", nonce }));
+        ws.send(JSON.stringify({ type: "auth", nonce, ...(displayId ? { displayId } : {}) }));
         pingTimer = setInterval(() => sendMessage({ type: "ping" }), PING_INTERVAL_MS);
       };
       ws.onmessage = (event) => {
@@ -128,8 +135,8 @@ export function useRemoteDesktopConnection(
       wsRef.current = null;
       try { decoder.reset(); } catch { /* tearing down regardless */ }
     };
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- reconnect is driven by `generation`
-  }, [generation]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- reconnect is driven by `generation` + the display pick
+  }, [generation, displayId]);
 
   const reconnect = useCallback(() => setGeneration((g) => g + 1), []);
   const getTotalBytes = useCallback(() => totalBytesRef.current, []);

package/src/web/components/remote-desktop/use-remote-desktop-display-choice.ts

@@ -0,0 +1,30 @@
+/**
+ * Which host display the viewer is on. Reads the list from `/capabilities`, defaults to the
+ * primary, and exposes `next()` for a one-button cycle (mobile toolbar) plus `select()` for a
+ * dropdown (desktop). Hosts with a single display never surface a control — `displays.length`
+ * tells the caller whether to render one.
+ */
+import { useCallback, useState } from "react";
+import { useRemoteDesktopReadiness, type RemoteDisplay } from "./use-remote-desktop-readiness";
+
+export interface RemoteDesktopDisplayChoice {
+  displays: RemoteDisplay[];
+  /** undefined until the list arrives or when the pick is the primary — the server treats both as "primary". */
+  displayId: string | undefined;
+  current: RemoteDisplay | undefined;
+  select: (id: string) => void;
+  next: () => void;
+}
+
+export function useRemoteDesktopDisplayChoice(): RemoteDesktopDisplayChoice {
+  const { caps } = useRemoteDesktopReadiness(false);
+  const displays = caps?.displays ?? [];
+  const [picked, setPicked] = useState<string | undefined>(undefined);
+  const current = displays.find((d) => d.id === picked) ?? displays.find((d) => d.primary) ?? displays[0];
+  const next = useCallback(() => {
+    if (displays.length < 2) return;
+    const i = displays.findIndex((d) => d.id === (current?.id));
+    setPicked(displays[(i + 1) % displays.length]?.id);
+  }, [displays, current]);
+  return { displays, displayId: picked, current, select: setPicked, next };
+}

package/src/web/components/remote-desktop/use-remote-desktop-readiness.ts

@@ -0,0 +1,82 @@
+/**
+ * Client view of `GET /api/remote-desktop/capabilities`: the host's requirements checklist
+ * (ffmpeg, macOS permissions, …) plus the derived `videoReady` / `inputReady` flags.
+ *
+ * Mirrors the server types in `src/services/remote-desktop/remote-desktop-requirements.ts` —
+ * the UI renders whatever items arrive and never branches on the host OS. Polls while `poll`
+ * is on so a permission granted in System Settings (or `brew install ffmpeg` finishing in the
+ * dock terminal) flips the panel without a reload.
+ */
+import { useCallback, useEffect, useState } from "react";
+import { api } from "@/lib/api-client";
+
+export type RequirementAction =
+  | { kind: "terminal"; label: string; command: string }
+  | { kind: "link"; label: string; url: string }
+  | { kind: "host"; label: string; action: "request" | "open-settings" };
+
+export interface RemoteDesktopRequirement {
+  id: string;
+  ok: boolean;
+  gates: "video" | "input";
+  title: string;
+  detail: string;
+  actions: RequirementAction[];
+}
+
+export interface RemoteDisplay {
+  id: string;
+  label: string;
+  primary: boolean;
+  width: number;
+  height: number;
+}
+
+export interface RemoteDesktopCapabilities {
+  displays: RemoteDisplay[];
+  ffmpegAvailable: boolean;
+  videoAvailable: boolean;
+  inputAvailable: boolean;
+  authRequired: boolean;
+  platform: string;
+  platformSupported: boolean;
+  requirements: RemoteDesktopRequirement[];
+  videoReady: boolean;
+  inputReady: boolean;
+}
+
+export const READINESS_POLL_MS = 2000;
+
+export function useRemoteDesktopReadiness(poll: boolean): {
+  caps: RemoteDesktopCapabilities | null;
+  /** 404 (feature flag off) or network failure — treat as "not available". */
+  failed: boolean;
+  refresh: () => void;
+  runHostAction: (id: string, action: "request" | "open-settings") => Promise<void>;
+} {
+  const [caps, setCaps] = useState<RemoteDesktopCapabilities | null>(null);
+  const [failed, setFailed] = useState(false);
+  const [tick, setTick] = useState(0);
+  const refresh = useCallback(() => setTick((t) => t + 1), []);
+
+  useEffect(() => {
+    let cancelled = false;
+    api.get<RemoteDesktopCapabilities>("/api/remote-desktop/capabilities")
+      .then((c) => { if (!cancelled) { setCaps(c); setFailed(false); } })
+      .catch(() => { if (!cancelled) setFailed(true); });
+    return () => { cancelled = true; };
+  }, [tick]);
+
+  useEffect(() => {
+    if (!poll) return;
+    const timer = setInterval(refresh, READINESS_POLL_MS);
+    return () => clearInterval(timer);
+  }, [poll, refresh]);
+
+  const runHostAction = useCallback(async (id: string, action: "request" | "open-settings") => {
+    try { await api.post(`/api/remote-desktop/requirements/${encodeURIComponent(id)}/${action}`); } catch { /* panel shows state on next poll */ }
+    refresh();
+  }, [refresh]);
+
+  return { caps, failed, refresh, runHostAction };
+}