@hienlh/ppm 0.18.16 → 0.19.0

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

@@ -25,6 +25,7 @@ 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"));
 
@@ -38,9 +39,11 @@ export function RemoteDesktopMobileSheet() {
   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>
+        <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-window-content.tsx

@@ -15,21 +15,26 @@ 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({ id }: WindowContentProps) {
   const closeWindow = useWindowStore((s) => s.close);
   const onCancel = useCallback(() => closeWindow(id), [closeWindow, id]);
   return (
     <RemoteDesktopWarningGate onCancel={onCancel}>
-      <RemoteDesktopViewer />
+      <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);
 
@@ -53,6 +58,21 @@ function RemoteDesktopViewer() {
     >
       <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 host opted out (`REMOTE_DESKTOP_ENABLED=0` — the
- * endpoint 404s) or video capture is unavailable (no ffmpeg), so the nav entry stays hidden on
- * hosts that can't or won't stream.
+ * 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 };
+}

package/src/web/components/remote-desktop/use-remote-desktop-virtual-keyboard.ts

@@ -1,8 +1,17 @@
 /**
- * Forwards keydown/keyup from a hidden `<input>` to the shared connection, so a toolbar
- * "Keyboard" button can bring up the phone's soft keyboard without a physical keyboard ever
- * being attached. Mirrors `use-remote-input-capture.ts`'s key handling exactly: `code`
- * (physical key, layout-independent) is sent, never `key` — the host maps `code` → VK.
+ * Forwards typing from a hidden `<input>` to the shared connection, so a toolbar "Keyboard"
+ * button can bring up the phone's soft keyboard without a physical keyboard ever being attached.
+ *
+ * Two paths, because soft keyboards are not keyboards:
+ * - A keydown with a real `code` (hardware keyboard, iOS for many keys) is forwarded as a
+ *   layout-independent `key` message and `preventDefault`-ed, exactly like
+ *   `use-remote-input-capture.ts` — that also suppresses the `beforeinput` that would follow.
+ * - Android soft keyboards send keydown with `code === ""` / keyCode 229 and put the actual
+ *   characters in `beforeinput` (`insertText`) or, for predictive/IME entry, in a composition
+ *   that only settles at `compositionend`. Those go up as `{ type: "text" }`, which the host
+ *   types as Unicode — accents and CJK survive, no `code` mapping involved. Backspace/Enter
+ *   arrive as `deleteContentBackward` / `insertLineBreak` and are mapped back to `key` events
+ *   so a host without a text path still handles them.
  */
 import { useEffect, useRef, useCallback } from "react";
 
@@ -12,10 +21,32 @@ export interface UseRemoteDesktopVirtualKeyboardResult {
   show: () => void;
 }
 
-export function useRemoteDesktopVirtualKeyboard(
-  sendMessage: (msg: Record<string, unknown>) => void,
-  enabled: boolean,
-): UseRemoteDesktopVirtualKeyboardResult {
+type Send = (msg: Record<string, unknown>) => void;
+
+/** `beforeinput` → messages. Exported for unit tests; returns whether the event was consumed. */
+export function forwardBeforeInput(inputType: string, data: string | null, send: Send): boolean {
+  const tap = (code: string) => { send({ type: "key", code, down: true }); send({ type: "key", code, down: false }); };
+  switch (inputType) {
+    case "insertText":
+      if (data) send({ type: "text", text: data });
+      return true;
+    case "insertLineBreak":
+    case "insertParagraph":
+      tap("Enter");
+      return true;
+    case "deleteContentBackward":
+      tap("Backspace");
+      return true;
+    case "deleteContentForward":
+      tap("Delete");
+      return true;
+    default:
+      // insertCompositionText & friends: let the composition run; compositionend sends it.
+      return false;
+  }
+}
+
+export function useRemoteDesktopVirtualKeyboard(sendMessage: Send, enabled: boolean): UseRemoteDesktopVirtualKeyboardResult {
   const inputRef = useRef<HTMLInputElement | null>(null);
 
   useEffect(() => {
@@ -25,19 +56,39 @@ export function useRemoteDesktopVirtualKeyboard(
     // A lost keyup (blur, tab hidden, WS drop) must not leave a modifier logically held on the
     // host — force a release on every path that could lose the matching keyup.
     const releaseAll = () => sendMessage({ type: "releaseAll" });
-    const onKeyDown = (e: KeyboardEvent) => { e.preventDefault(); sendMessage({ type: "key", code: e.code, down: true }); };
-    const onKeyUp = (e: KeyboardEvent) => { e.preventDefault(); sendMessage({ type: "key", code: e.code, down: false }); };
+    const hasCode = (e: KeyboardEvent) => e.code !== "" && e.key !== "Unidentified";
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (!hasCode(e)) return; // soft keyboard: the character comes via beforeinput
+      e.preventDefault();
+      sendMessage({ type: "key", code: e.code, down: true });
+    };
+    const onKeyUp = (e: KeyboardEvent) => {
+      if (!hasCode(e)) return;
+      e.preventDefault();
+      sendMessage({ type: "key", code: e.code, down: false });
+    };
+    const onBeforeInput = (e: InputEvent) => {
+      if (forwardBeforeInput(e.inputType, e.data, sendMessage)) e.preventDefault();
+    };
+    const onCompositionEnd = (e: CompositionEvent) => {
+      if (e.data) sendMessage({ type: "text", text: e.data });
+      input.value = ""; // the composed text landed in the input; the host already has it
+    };
     const onBlur = () => releaseAll();
     const onVisibilityChange = () => { if (document.hidden) releaseAll(); };
 
     input.addEventListener("keydown", onKeyDown);
     input.addEventListener("keyup", onKeyUp);
+    input.addEventListener("beforeinput", onBeforeInput);
+    input.addEventListener("compositionend", onCompositionEnd);
     input.addEventListener("blur", onBlur);
     document.addEventListener("visibilitychange", onVisibilityChange);
 
     return () => {
       input.removeEventListener("keydown", onKeyDown);
       input.removeEventListener("keyup", onKeyUp);
+      input.removeEventListener("beforeinput", onBeforeInput);
+      input.removeEventListener("compositionend", onCompositionEnd);
       input.removeEventListener("blur", onBlur);
       document.removeEventListener("visibilitychange", onVisibilityChange);
       releaseAll();

package/dist/web/assets/api-client-D1CePgQ4.js

@@ -1 +0,0 @@
-import"./vendor-markdown-Ls5AcU91.js";import"./vendor-ui-CaeeFO0B.js";import{i as e,n as t}from"./api-client-BzWM7XPR.js";export{t as api,e as projectUrl};

package/dist/web/assets/api-settings-CNtKkHqW.js

@@ -1 +0,0 @@
-import"./vendor-markdown-Ls5AcU91.js";import"./vendor-ui-CaeeFO0B.js";import"./api-client-BzWM7XPR.js";import{v as e}from"./api-settings-Cubuqjsu.js";export{e as updateDeviceName};